bsd/sys/kdebug_kernel.h

   1 /*
   2  * Copyright (c) 2000-2018 Apple Inc. All rights reserved.
   3  *
   4  * @APPLE_OSREFERENCE_LICENSE_HEADER_START@
   5  *
   6  * This file contains Original Code and/or Modifications of Original Code
   7  * as defined in and that are subject to the Apple Public Source License
   8  * Version 2.0 (the 'License'). You may not use this file except in
   9  * compliance with the License. The rights granted to you under the License
  10  * may not be used to create, or enable the creation or redistribution of,
  11  * unlawful or unlicensed copies of an Apple operating system, or to
  12  * circumvent, violate, or enable the circumvention or violation of, any
  13  * terms of an Apple operating system software license agreement.
  14  *
  15  * Please obtain a copy of the License at
  16  * http://www.opensource.apple.com/apsl/ and read it before using this file.
  17  *
  18  * The Original Code and all software distributed under the License are
  19  * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  20  * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  21  * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  22  * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
  23  * Please see the License for the specific language governing rights and
  24  * limitations under the License.
  25  *
  26  * @APPLE_OSREFERENCE_LICENSE_HEADER_END@
  27  */
  28
  29 #ifndef BSD_SYS_KDEBUG_KERNEL_H
  30 #define BSD_SYS_KDEBUG_KERNEL_H
  31
  32 #include <mach/boolean.h>
  33 #include <mach/clock_types.h>
  34 #include <stdbool.h>
  35 #include <stdint.h>
  36 #include <sys/cdefs.h>
  37
  38 __BEGIN_DECLS
  39
  40 #ifdef KERNEL
  41
  42 /*
  43  * To use kdebug in the kernel:
  44  *
  45  * #include <sys/kdebug_kernel.h>
  46  *
  47  * #define DBG_NETIPINIT NETDBG_CODE(DBG_NETIP, 1)
  48  *
  49  * void
  50  * ip_init(void)
  51  * {
  52  *     KDBG(DBG_NETIPINIT | DBG_FUNC_START, 1, 2, 3, 4);
  53  *     ...
  54  *     KDBG(DBG_NETIPINIT);
  55  *     ...
  56  *     KDBG(DBG_NETIPINIT | DBG_FUNC_END);
  57  * }
  58  */
  59
  60 #pragma mark - kernel tracepoints
  61
  62 /*
  63  * The KDBG{,_DEBUG,_RELEASE,_FILTERED} macros are the preferred method of
  64  * making tracepoints.
  65  *
  66  * Kernel pointers must be unslid or permuted using VM_KERNEL_UNSLIDE_OR_PERM.
  67  * Do not trace any sensitive data.
  68  */
  69
  70 /*
  71  * Traced on debug and development (and release macOS) kernels.
  72  */
  73 #define KDBG(x, ...) KDBG_(, x, ## __VA_ARGS__, 4, 3, 2, 1, 0)
  74
  75 /*
  76  * Traced on debug and development (and release macOS) kernels if explicitly
  77  * requested.  Omitted from tracing without a typefilter.
  78  */
  79 #define KDBG_FILTERED(x, ...) KDBG_(_FILTERED, x, ## __VA_ARGS__, 4, 3, 2, 1, 0)
  80
  81 #ifdef KERNEL_PRIVATE
  82
  83 /*
  84  * Traced on debug and development (and release macOS) kernels, even if the
  85  * process filter would reject it.
  86  */
  87 #define KDBG_RELEASE_NOPROCFILT(x, ...) \
  88                 KDBG_(_RELEASE_NOPROCFILT, x, ## __VA_ARGS__, 4, 3, 2, 1, 0)
  89
  90 #endif /* KERNEL_PRIVATE */
  91
  92 /*
  93  * Traced on debug, development, and release kernels.
  94  *
  95  * Only use this tracepoint if the events are required for a shipping trace
  96  * tool.
  97  */
  98 #define KDBG_RELEASE(x, ...) KDBG_(_RELEASE, x, ## __VA_ARGS__, 4, 3, 2, 1, 0)
  99
 100 /*
 101  * Traced only on debug kernels.
 102  */
 103 #define KDBG_DEBUG(x, ...) KDBG_(_DEBUG, x, ## __VA_ARGS__, 4, 3, 2, 1, 0)
 104
 105 #pragma mark - kernel API
 106
 107 #ifdef KERNEL_PRIVATE
 108
 109 /*
 110  * kernel_debug_string provides the same functionality as the
 111  * kdebug_trace_string syscall as a KPI.  str_id is an in/out
 112  * parameter that, if it's pointing to a string ID of 0, will
 113  * receive a generated ID.  If it provides a value in str_id,
 114  * then that will be used, instead.
 115  *
 116  * Returns an errno indicating the type of failure.
 117  */
 118 int kernel_debug_string(uint32_t debugid, uint64_t *str_id, const char *str);
 119
 120 /*
 121  * kernel_debug_disable disables event logging, but leaves any buffers
 122  * intact.
 123  */
 124 void kernel_debug_disable(void);
 125
 126 #endif /* KERNEL_PRIVATE */
 127
 128 /*
 129  * Returns true if kdebug is using continuous time for its events, and false
 130  * otherwise.
 131  */
 132 bool kdebug_using_continuous_time(void);
 133
 134 /*
 135  * Returns true if kdebug will log an event with the provided debugid, and
 136  * false otherwise.
 137  */
 138 bool kdebug_debugid_enabled(uint32_t debugid);
 139
 140 /*
 141  * Returns true only if the debugid is explicitly enabled by filters.  Returns
 142  * false otherwise, including when no filters are active.
 143  */
 144 bool kdebug_debugid_explicitly_enabled(uint32_t debugid);
 145
 146 uint32_t kdebug_commpage_state(void);
 147
 148 #pragma mark - IOP tracing
 149
 150 /*
 151  * Definitions to support IOP tracing.
 152  */
 153
 154 typedef enum {
 155         /* Trace is now enabled; no arguments.  */
 156         KD_CALLBACK_KDEBUG_ENABLED,
 157         /* Trace is now disabled; no arguments.  */
 158         KD_CALLBACK_KDEBUG_DISABLED,
 159         /*
 160          * Request the latest entries from the IOP and block until complete; no
 161          * arguments.
 162          */
 163         KD_CALLBACK_SYNC_FLUSH,
 164         /*
 165          * The typefilter is enabled; a read-only pointer to the typefilter is
 166          * provided, valid only while in the callback.
 167          */
 168         KD_CALLBACK_TYPEFILTER_CHANGED,
 169 } kd_callback_type;
 170
 171 typedef void (*kd_callback_fn) (void *context, kd_callback_type reason,
 172     void *arg);
 173
 174 struct kd_callback {
 175         kd_callback_fn func;
 176         void *context;
 177         /* name of IOP, NUL-terminated */
 178         char iop_name[8];
 179 };
 180
 181 typedef struct kd_callback kd_callback_t;
 182
 183 /*
 184  * Registers an IOP for participation in tracing.
 185  *
 186  * The registered callback function will be called with the
 187  * supplied context as the first argument, followed by a
 188  * kd_callback_type and an associated void* argument.
 189  *
 190  * The return value is a nonzero coreid that shall be used in
 191  * kernel_debug_enter() to refer to your IOP. If the allocation
 192  * failed, then 0 will be returned.
 193  *
 194  * Caveats:
 195  * Note that not all callback calls will indicate a change in
 196  * state (e.g. disabling trace twice would send two disable
 197  * notifications).
 198  */
 199 int kernel_debug_register_callback(kd_callback_t callback);
 200
 201 void kernel_debug_enter(uint32_t coreid, uint32_t debugid, uint64_t timestamp,
 202     uintptr_t arg1, uintptr_t arg2, uintptr_t arg3, uintptr_t arg4,
 203     uintptr_t threadid);
 204
 205 #pragma mark - internals
 206
 207 #define KDBG_(f, x, a, b, c, d, n, ...) KDBG##n(f, x, a, b, c, d)
 208 #define KDBG0(f, x, a, b, c, d) KERNEL_DEBUG_CONSTANT##f(x, 0, 0, 0, 0, 0)
 209 #define KDBG1(f, x, a, b, c, d) KERNEL_DEBUG_CONSTANT##f(x, a, 0, 0, 0, 0)
 210 #define KDBG2(f, x, a, b, c, d) KERNEL_DEBUG_CONSTANT##f(x, a, b, 0, 0, 0)
 211 #define KDBG3(f, x, a, b, c, d) KERNEL_DEBUG_CONSTANT##f(x, a, b, c, 0, 0)
 212 #define KDBG4(f, x, a, b, c, d) KERNEL_DEBUG_CONSTANT##f(x, a, b, c, d, 0)
 213
 214 #ifdef XNU_KERNEL_PRIVATE
 215 #define KDBG_IMPROBABLE __improbable
 216 #else
 217 #define KDBG_IMPROBABLE
 218 #endif
 219
 220 extern unsigned int kdebug_enable;
 221
 222 /*
 223  * The kernel debug configuration level.  These values control which events are
 224  * compiled in under different build configurations.
 225  *
 226  * Infer the supported kernel debug event level from config option.  Use
 227  * (KDEBUG_LEVEL >= KDEBUG_LEVEL_STANDARD) as a guard to protect unaudited debug
 228  * code.
 229  */
 230 #define KDEBUG_LEVEL_NONE     0
 231 #define KDEBUG_LEVEL_IST      1
 232 #define KDEBUG_LEVEL_STANDARD 2
 233 #define KDEBUG_LEVEL_FULL     3
 234
 235 #if NO_KDEBUG
 236 #define KDEBUG_LEVEL KDEBUG_LEVEL_NONE
 237 #elif IST_KDEBUG
 238 #define KDEBUG_LEVEL KDEBUG_LEVEL_IST
 239 #elif KDEBUG
 240 #define KDEBUG_LEVEL KDEBUG_LEVEL_FULL
 241 #else
 242 #define KDEBUG_LEVEL KDEBUG_LEVEL_STANDARD
 243 /*
 244  * Currently, all other kernel configurations (development, etc) build with
 245  * KDEBUG_LEVEL_STANDARD.
 246  */
 247 #endif
 248
 249 /*
 250  * KERNEL_DEBUG_CONSTANT_FILTERED events are omitted from tracing unless they
 251  * are explicitly requested in the typefilter.  They are not emitted when
 252  * tracing without a typefilter.
 253  */
 254 #if (KDEBUG_LEVEL >= KDEBUG_LEVEL_STANDARD)
 255 #define KERNEL_DEBUG_CONSTANT_FILTERED(x, a, b, c, d, ...)           \
 256         do {                                                             \
 257                 if (KDBG_IMPROBABLE(kdebug_enable & ~KDEBUG_ENABLE_PPT)) {   \
 258                         kernel_debug_filtered((x), (uintptr_t)(a), (uintptr_t)(b),  \
 259                                 (uintptr_t)(c), (uintptr_t)(d)); \
 260                 }                                                            \
 261         } while (0)
 262 #else /* (KDEBUG_LEVEL >= KDEBUG_LEVEL_STANDARD) */
 263 #define KERNEL_DEBUG_CONSTANT_FILTERED(type, x, a, b, c, d, ...) do {} while (0)
 264 #endif /* (KDEBUG_LEVEL >= KDEBUG_LEVEL_STANDARD) */
 265
 266 #if (KDEBUG_LEVEL >= KDEBUG_LEVEL_IST)
 267 #define KERNEL_DEBUG_CONSTANT_RELEASE_NOPROCFILT(x, a, b, c, d, ...)   \
 268         do {                                                               \
 269                 if (KDBG_IMPROBABLE(kdebug_enable & ~KDEBUG_ENABLE_PPT)) {     \
 270                         kernel_debug_flags((x), (uintptr_t)(a), (uintptr_t)(b),    \
 271                                 (uintptr_t)(c), (uintptr_t)(d), KDBG_FLAG_NOPROCFILT); \
 272                 }                                                              \
 273         } while (0)
 274 #else /* (KDEBUG_LEVEL >= KDEBUG_LEVEL_IST) */
 275 #define KERNEL_DEBUG_CONSTANT_RELEASE_NOPROCFILT(x, a, b, c, d, ...) \
 276         do { } while (0)
 277 #endif /* (KDEBUG_LEVEL >= KDEBUG_LEVEL_IST) */
 278
 279
 280 #if (KDEBUG_LEVEL >= KDEBUG_LEVEL_STANDARD)
 281 #define KERNEL_DEBUG_CONSTANT(x, a, b, c, d, e)                               \
 282         do {                                                                      \
 283                 if (KDBG_IMPROBABLE(kdebug_enable & ~KDEBUG_ENABLE_PPT)) {            \
 284                         kernel_debug((x), (uintptr_t)(a), (uintptr_t)(b), (uintptr_t)(c), \
 285                                 (uintptr_t)(d),(uintptr_t)(e));                               \
 286                 }                                                                     \
 287         } while (0)
 288
 289 /*
 290  * DO NOT USE THIS MACRO -- it breaks fundamental assumptions about ktrace and
 291  * is only meant to be used by the pthread kext and other points in the kernel
 292  * where the thread ID must be provided explicitly.
 293  */
 294 #define KERNEL_DEBUG_CONSTANT1(x, a, b, c, d, e)                               \
 295         do {                                                                       \
 296                 if (KDBG_IMPROBABLE(kdebug_enable & ~KDEBUG_ENABLE_PPT)) {             \
 297                         kernel_debug1((x), (uintptr_t)(a), (uintptr_t)(b), (uintptr_t)(c), \
 298                         (uintptr_t)(d), (uintptr_t)(e));                                   \
 299                 }                                                                      \
 300         } while (0)
 301
 302 #else /* (KDEBUG_LEVEL >= KDEBUG_LEVEL_STANDARD) */
 303 #define KERNEL_DEBUG_CONSTANT(x, a, b, c, d, e) do {} while (0)
 304 #define KERNEL_DEBUG_CONSTANT1(x, a, b, c, d, e) do {} while (0)
 305 #endif /* (KDEBUG_LEVEL >= KDEBUG_LEVEL_STANDARD) */
 306
 307 /*
 308  * KERNEL_DEBUG_CONSTANT_IST (in-system trace) events provide an audited subset
 309  * of tracepoints for userland system tracing tools.  This tracing level was
 310  * created by 8857227 to protect fairplayd and other PT_DENY_ATTACH processes.
 311  * It has two effects: only KERNEL_DEBUG_CONSTANT_IST() traces are emitted and
 312  * any PT_DENY_ATTACH processes will only emit basic traces as defined by the
 313  * kernel_debug_filter() routine.
 314  */
 315 #define KERNEL_DEBUG_CONSTANT_RELEASE(x, a, b, c, d, e) \
 316         KERNEL_DEBUG_CONSTANT_IST(~KDEBUG_ENABLE_PPT, x, a, b, c, d, 0)
 317
 318 #if (KDEBUG_LEVEL >= KDEBUG_LEVEL_IST)
 319 #define KERNEL_DEBUG_CONSTANT_IST(type, x, a, b, c, d, e)                     \
 320         do {                                                                      \
 321                 if (KDBG_IMPROBABLE(kdebug_enable & (type))) {                        \
 322                         kernel_debug((x), (uintptr_t)(a), (uintptr_t)(b), (uintptr_t)(c), \
 323                                 (uintptr_t)(d), 0);                                           \
 324                 }                                                                     \
 325         } while (0)
 326
 327 #define KERNEL_DEBUG_CONSTANT_IST1(x, a, b, c, d, e)                     \
 328         do {                                                                       \
 329                 if (KDBG_IMPROBABLE(kdebug_enable)) {                         \
 330                         kernel_debug1((x), (uintptr_t)(a), (uintptr_t)(b), (uintptr_t)(c), \
 331                                 (uintptr_t)(d), (uintptr_t)(e));                               \
 332                 }                                                                      \
 333         } while (0)
 334
 335 #define KERNEL_DEBUG_EARLY(x, a, b, c, d)                                 \
 336         do {                                                                  \
 337                 kernel_debug_early((uint32_t)(x), (uintptr_t)(a), (uintptr_t)(b), \
 338                         (uintptr_t)(c), (uintptr_t)(d));                              \
 339         } while (0)
 340
 341 #else /* (KDEBUG_LEVEL >= KDEBUG_LEVEL_IST) */
 342 #define KERNEL_DEBUG_CONSTANT_IST(type, x, a, b, c, d, e) do {} while (0)
 343 #define KERNEL_DEBUG_CONSTANT_IST1(x, a, b, c, d, e) do {} while (0)
 344 #define KERNEL_DEBUG_EARLY(x, a, b, c, d) do {} while (0)
 345 #endif /* (KDEBUG_LEVEL >= KDEBUG_LEVEL_IST) */
 346
 347 #if NO_KDEBUG
 348 #define __kdebug_constant_only __unused
 349 #endif
 350
 351 /*
 352  * KERNEL_DEBUG events are only traced for DEBUG kernels.
 353  */
 354 #define KERNEL_DEBUG_CONSTANT_DEBUG(x, a, b, c, d, e) \
 355         KERNEL_DEBUG(x, a, b, c, d, e)
 356
 357 #if (KDEBUG_LEVEL >= KDEBUG_LEVEL_FULL)
 358 #define __kdebug_only
 359
 360 #undef KERNEL_DEBUG
 361 #define KERNEL_DEBUG(x, a, b, c, d, e)                                  \
 362         do {                                                                \
 363                 if (KDBG_IMPROBABLE(kdebug_enable & ~KDEBUG_ENABLE_PPT)) {      \
 364                         kernel_debug((uint32_t)(x), (uintptr_t)(a), (uintptr_t)(b), \
 365                                 (uintptr_t)(c), (uintptr_t)(d), (uintptr_t)(e));        \
 366                 }                                                               \
 367         } while (0)
 368
 369 /*
 370  * DO NOT USE THIS MACRO -- see warning above for KERNEL_DEBUG_CONSTANT1.
 371  */
 372 #define KERNEL_DEBUG1(x, a, b, c, d, e)                                  \
 373         do {                                                                 \
 374                 if (KDBG_IMPROBABLE(kdebug_enable & ~KDEBUG_ENABLE_PPT)) {       \
 375                         kernel_debug1((uint32_t)(x), (uintptr_t)(a), (uintptr_t)(b), \
 376                                 (uintptr_t)(c), (uintptr_t)(d), (uintptr_t)(e));         \
 377                 }                                                                \
 378         } while (0)
 379
 380 #else /* (KDEBUG_LEVEL >= KDEBUG_LEVEL_FULL) */
 381 #define __kdebug_only __unused
 382
 383 #undef KERNEL_DEBUG
 384 #define KERNEL_DEBUG(x, a, b, c, d, e) do {} while (0)
 385 #define KERNEL_DEBUG1(x, a, b, c, d, e) do {} while (0)
 386 #endif /* (KDEBUG_LEVEL >= KDEBUG_LEVEL_FULL) */
 387
 388 void kernel_debug(uint32_t debugid, uintptr_t arg1, uintptr_t arg2,
 389     uintptr_t arg3, uintptr_t arg4, uintptr_t arg5);
 390
 391 void kernel_debug1(uint32_t debugid, uintptr_t arg1, uintptr_t arg2,
 392     uintptr_t arg3, uintptr_t arg4, uintptr_t arg5);
 393
 394 #define KDBG_FLAG_FILTERED 0x01
 395 #define KDBG_FLAG_NOPROCFILT 0x02
 396
 397 void kernel_debug_flags(uint32_t debugid, uintptr_t arg1, uintptr_t arg2,
 398     uintptr_t arg3, uintptr_t arg4, uint64_t flags);
 399
 400 void kernel_debug_filtered(uint32_t debugid, uintptr_t arg1, uintptr_t arg2,
 401     uintptr_t arg3, uintptr_t arg4);
 402
 403 #pragma mark - xnu API
 404
 405 #ifdef XNU_KERNEL_PRIVATE
 406
 407 /* Used in early boot to log events. */
 408 void kernel_debug_early(uint32_t  debugid, uintptr_t arg1, uintptr_t arg2,
 409     uintptr_t arg3, uintptr_t arg4);
 410 /* Used in early boot to log strings spanning only a single tracepoint. */
 411 void kernel_debug_string_early(const char *message);
 412 /* Used to trace strings within kdebug tracepoints on arbitrary eventids. */
 413 void kernel_debug_string_simple(uint32_t eventid, const char *str);
 414 /* Only used by ktrace to reset kdebug.  ktrace_lock must be held. */
 415 extern void kdebug_reset(void);
 416
 417 void kdbg_dump_trace_to_file(const char *);
 418
 419 enum kdebug_opts {
 420         KDOPT_WRAPPING = 0x1,
 421         KDOPT_ATBOOT = 0x2,
 422 };
 423
 424 void kdebug_init(unsigned int n_events, char *filterdesc,
 425     enum kdebug_opts opts);
 426 void kdebug_trace_start(unsigned int n_events, const char *filterdesc,
 427     enum kdebug_opts opts);
 428 uint64_t kdebug_wake(void);
 429 void kdebug_free_early_buf(void);
 430 void release_storage_unit(int cpu, uint32_t storage_unit);
 431 bool allocate_storage_unit(int cpu);
 432
 433 struct proc;
 434 void kdbg_trace_data(struct proc *proc, long *arg_pid, long *arg_uniqueid);
 435 void kdbg_trace_string(struct proc *proc, long *arg1, long *arg2, long *arg3,
 436     long *arg4);
 437
 438 #define KDBG_VFS_LOOKUP_FLAG_LOOKUP 0x01
 439 #define KDBG_VFS_LOOKUP_FLAG_NOPROCFILT 0x02
 440 void kdebug_vfs_lookup(unsigned long *path_words, int path_len, void *vnp,
 441     uint32_t flags);
 442
 443 #endif /* XNU_KERNEL_PRIVATE */
 444
 445 #ifdef KERNEL_PRIVATE
 446
 447 #define NUMPARMS 23
 448 void kdebug_lookup_gen_events(long *path_words, int path_len, void *vnp,
 449     bool lookup);
 450
 451 #pragma mark - EnergyTracing
 452
 453 #define KERNEL_DBG_IST_SANE KDBG_RELEASE
 454 #define ENTR_KDTRACEFUNC KDBG_RELEASE
 455
 456 // value is int64_t, quality is uint32_t
 457 #define KERNEL_ENERGYTRACE(opcode, lifespan, id, quality, value)        \
 458             ENTR_KDTRACE(kEnTrCompKernel, opcode, lifespan, id,         \
 459                          quality, value)
 460 #define KERNEL_ENTR_ASSOCIATE(par_opcode, par_act_id, sub_opcode, sub_act_id) \
 461             ENTR_KDASSOCIATE(kEnTrCompKernel, par_opcode, par_act_id,   \
 462                              kEnTrCompKernel, sub_opcode, sub_act_id)
 463
 464 #endif /* KERNEL_PRIVATE */
 465
 466 #endif /* KERNEL */
 467
 468 __END_DECLS
 469
 470 #endif /* !defined(BSD_SYS_KDEBUG_KERNEL_H) */