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 #define KERNEL_DEBUG_EARLY(x, a, b, c, d)                                 \
 303         do {                                                                  \
 304                 kernel_debug_early((uint32_t)(x), (uintptr_t)(a), (uintptr_t)(b), \
 305                         (uintptr_t)(c), (uintptr_t)(d));                              \
 306         } while (0)
 307 #else /* (KDEBUG_LEVEL >= KDEBUG_LEVEL_STANDARD) */
 308 #define KERNEL_DEBUG_CONSTANT(x, a, b, c, d, e) do {} while (0)
 309 #define KERNEL_DEBUG_CONSTANT1(x, a, b, c, d, e) do {} while (0)
 310 #define KERNEL_DEBUG_EARLY(x, a, b, c, d) do {} while (0)
 311 #endif /* (KDEBUG_LEVEL >= KDEBUG_LEVEL_STANDARD) */
 312
 313 /*
 314  * KERNEL_DEBUG_CONSTANT_IST (in-system trace) events provide an audited subset
 315  * of tracepoints for userland system tracing tools.  This tracing level was
 316  * created by 8857227 to protect fairplayd and other PT_DENY_ATTACH processes.
 317  * It has two effects: only KERNEL_DEBUG_CONSTANT_IST() traces are emitted and
 318  * any PT_DENY_ATTACH processes will only emit basic traces as defined by the
 319  * kernel_debug_filter() routine.
 320  */
 321 #define KERNEL_DEBUG_CONSTANT_RELEASE(x, a, b, c, d, e) \
 322         KERNEL_DEBUG_CONSTANT_IST(~KDEBUG_ENABLE_PPT, x, a, b, c, d, 0)
 323
 324 #if (KDEBUG_LEVEL >= KDEBUG_LEVEL_IST)
 325 #define KERNEL_DEBUG_CONSTANT_IST(type, x, a, b, c, d, e)                     \
 326         do {                                                                      \
 327                 if (KDBG_IMPROBABLE(kdebug_enable & (type))) {                        \
 328                         kernel_debug((x), (uintptr_t)(a), (uintptr_t)(b), (uintptr_t)(c), \
 329                                 (uintptr_t)(d), 0);                                           \
 330                 }                                                                     \
 331         } while (0)
 332 #define KERNEL_DEBUG_CONSTANT_IST1(x, a, b, c, d, e)                     \
 333         do {                                                                       \
 334                 if (KDBG_IMPROBABLE(kdebug_enable)) {                         \
 335                         kernel_debug1((x), (uintptr_t)(a), (uintptr_t)(b), (uintptr_t)(c), \
 336                                 (uintptr_t)(d), (uintptr_t)(e));                               \
 337                 }                                                                      \
 338         } while (0)
 339 #else /* (KDEBUG_LEVEL >= KDEBUG_LEVEL_IST) */
 340 #define KERNEL_DEBUG_CONSTANT_IST(type, x, a, b, c, d, e) do {} while (0)
 341 #define KERNEL_DEBUG_CONSTANT_IST1(x, a, b, c, d, e) do {} while (0)
 342 #endif /* (KDEBUG_LEVEL >= KDEBUG_LEVEL_IST) */
 343
 344 #if NO_KDEBUG
 345 #define __kdebug_constant_only __unused
 346 #endif
 347
 348 /*
 349  * KERNEL_DEBUG events are only traced for DEBUG kernels.
 350  */
 351 #define KERNEL_DEBUG_CONSTANT_DEBUG(x, a, b, c, d, e) \
 352         KERNEL_DEBUG(x, a, b, c, d, e)
 353
 354 #if (KDEBUG_LEVEL >= KDEBUG_LEVEL_FULL)
 355 #define __kdebug_only
 356
 357 #undef KERNEL_DEBUG
 358 #define KERNEL_DEBUG(x, a, b, c, d, e)                                  \
 359         do {                                                                \
 360                 if (KDBG_IMPROBABLE(kdebug_enable & ~KDEBUG_ENABLE_PPT)) {      \
 361                         kernel_debug((uint32_t)(x), (uintptr_t)(a), (uintptr_t)(b), \
 362                                 (uintptr_t)(c), (uintptr_t)(d), (uintptr_t)(e));        \
 363                 }                                                               \
 364         } while (0)
 365
 366 /*
 367  * DO NOT USE THIS MACRO -- see warning above for KERNEL_DEBUG_CONSTANT1.
 368  */
 369 #define KERNEL_DEBUG1(x, a, b, c, d, e)                                  \
 370         do {                                                                 \
 371                 if (KDBG_IMPROBABLE(kdebug_enable & ~KDEBUG_ENABLE_PPT)) {       \
 372                         kernel_debug1((uint32_t)(x), (uintptr_t)(a), (uintptr_t)(b), \
 373                                 (uintptr_t)(c), (uintptr_t)(d), (uintptr_t)(e));         \
 374                 }                                                                \
 375         } while (0)
 376
 377 #else /* (KDEBUG_LEVEL >= KDEBUG_LEVEL_FULL) */
 378 #define __kdebug_only __unused
 379
 380 #undef KERNEL_DEBUG
 381 #define KERNEL_DEBUG(x, a, b, c, d, e) do {} while (0)
 382 #define KERNEL_DEBUG1(x, a, b, c, d, e) do {} while (0)
 383 #endif /* (KDEBUG_LEVEL >= KDEBUG_LEVEL_FULL) */
 384
 385 void kernel_debug(uint32_t debugid, uintptr_t arg1, uintptr_t arg2,
 386     uintptr_t arg3, uintptr_t arg4, uintptr_t arg5);
 387
 388 void kernel_debug1(uint32_t debugid, uintptr_t arg1, uintptr_t arg2,
 389     uintptr_t arg3, uintptr_t arg4, uintptr_t arg5);
 390
 391 #define KDBG_FLAG_FILTERED 0x01
 392 #define KDBG_FLAG_NOPROCFILT 0x02
 393
 394 void kernel_debug_flags(uint32_t debugid, uintptr_t arg1, uintptr_t arg2,
 395     uintptr_t arg3, uintptr_t arg4, uint64_t flags);
 396
 397 void kernel_debug_filtered(uint32_t debugid, uintptr_t arg1, uintptr_t arg2,
 398     uintptr_t arg3, uintptr_t arg4);
 399
 400 #pragma mark - xnu API
 401
 402 #ifdef XNU_KERNEL_PRIVATE
 403 /* Used in early boot to log events. */
 404 void kernel_debug_early(uint32_t  debugid, uintptr_t arg1, uintptr_t arg2,
 405     uintptr_t arg3, uintptr_t arg4);
 406 /* Used in early boot to log strings spanning only a single tracepoint. */
 407 void kernel_debug_string_early(const char *message);
 408 /* Used to trace strings within kdebug tracepoints on arbitrary eventids. */
 409 void kernel_debug_string_simple(uint32_t eventid, const char *str);
 410 /* Only used by ktrace to reset kdebug.  ktrace_lock must be held. */
 411 extern void kdebug_reset(void);
 412
 413 void kdbg_dump_trace_to_file(const char *);
 414 void kdebug_init(unsigned int n_events, char *filterdesc, bool wrapping);
 415 void kdebug_trace_start(unsigned int n_events, const char *filterdesc,
 416     bool wrapping, bool at_wake);
 417 void kdebug_free_early_buf(void);
 418 void release_storage_unit(int cpu, uint32_t storage_unit);
 419 bool allocate_storage_unit(int cpu);
 420
 421 struct proc;
 422 void kdbg_trace_data(struct proc *proc, long *arg_pid, long *arg_uniqueid);
 423 void kdbg_trace_string(struct proc *proc, long *arg1, long *arg2, long *arg3,
 424     long *arg4);
 425
 426 #define KDBG_VFS_LOOKUP_FLAG_LOOKUP 0x01
 427 #define KDBG_VFS_LOOKUP_FLAG_NOPROCFILT 0x02
 428 void kdebug_vfs_lookup(long *dbg_parms, int dbg_namelen, void *dp,
 429     uint32_t flags);
 430
 431 #endif /* XNU_KERNEL_PRIVATE */
 432
 433 #ifdef KERNEL_PRIVATE
 434
 435 #define NUMPARMS 23
 436 void kdebug_lookup_gen_events(long *dbg_parms, int dbg_namelen, void *dp,
 437     bool lookup);
 438
 439 #pragma mark - EnergyTracing
 440
 441 #define KERNEL_DBG_IST_SANE KDBG_RELEASE
 442 #define ENTR_KDTRACEFUNC KDBG_RELEASE
 443
 444 // value is int64_t, quality is uint32_t
 445 #define KERNEL_ENERGYTRACE(opcode, lifespan, id, quality, value)        \
 446             ENTR_KDTRACE(kEnTrCompKernel, opcode, lifespan, id,         \
 447                          quality, value)
 448 #define KERNEL_ENTR_ASSOCIATE(par_opcode, par_act_id, sub_opcode, sub_act_id) \
 449             ENTR_KDASSOCIATE(kEnTrCompKernel, par_opcode, par_act_id,   \
 450                              kEnTrCompKernel, sub_opcode, sub_act_id)
 451
 452 #endif /* KERNEL_PRIVATE */
 453
 454 #endif /* KERNEL */
 455
 456 __END_DECLS
 457
 458 #endif /* !defined(BSD_SYS_KDEBUG_KERNEL_H) */