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) */