]>
git.saurik.com Git - apple/xnu.git/blob - bsd/sys_private/kdebug_private.h
2 * Copyright (c) 2000-2018 Apple Inc. All rights reserved.
4 * @APPLE_OSREFERENCE_LICENSE_HEADER_START@
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.
15 * Please obtain a copy of the License at
16 * http://www.opensource.apple.com/apsl/ and read it before using this file.
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.
26 * @APPLE_OSREFERENCE_LICENSE_HEADER_END@
29 #ifndef BSD_KDEBUG_PRIVATE_H
30 #define BSD_KDEBUG_PRIVATE_H
34 #include <sys/cdefs.h>
35 #include <sys/kdebug.h>
41 #include <Availability.h>
43 #pragma mark - user space SPI
46 * OS components can use the full precision of the "code" field
47 * (Class, SubClass, Code) to inject events using kdebug_trace() by
50 * kdebug_trace(KDBG_CODE(DBG_XPC, 15, 1) | DBG_FUNC_NONE, 1, 2, 3, 4);
52 * These trace points can be included in production code, since they
53 * use reserved, non-overlapping ranges. The performance impact when
54 * kernel tracing is not enabled is minimal. However, when tracing is enabled,
55 * each tracepoint becomes a syscall. For this reason, os_signpost(3) is
56 * recommended instead of kdebug_trace(2).
58 * Classes can be reserved by filing a Radar in xnu | ktrace.
60 * 64-bit arguments may be truncated if the system is using a 32-bit
63 * On error, -1 will be returned and errno will indicate the error.
65 int kdebug_trace(uint32_t code
, uint64_t arg1
, uint64_t arg2
, uint64_t arg3
,
67 __OSX_AVAILABLE(10.10) __IOS_AVAILABLE(8.2);
70 * @function kdebug_trace_string
73 * This function emits strings to kdebug trace along with an ID and allows
74 * for previously-traced strings to be overwritten and invalidated.
76 * To start tracing a string and generate an ID to use to refer to it:
78 * string_id = kdebug_trace_string(debugid, 0, "string");
80 * To replace a string previously traced:
82 * string_id = kdebug_trace_string(debugid, string_id, "new string");
84 * To invalidate a string ID:
86 * string_id = kdebug_trace_string(debugid, string_id, NULL);
88 * To check for errors:
90 * if ((int64_t)string_id == -1) { perror("string error") }
93 * The `debugid` to check if its enabled before tracing and include as
94 * an argument in the event containing the string.
96 * Some classes or subclasses are reserved for specific uses and are not
97 * allowed to be used with this function. No function qualifiers are
98 * allowed on `debugid`.
101 * When 0, a new ID will be generated and returned if tracing is
104 * Otherwise `str_id` must contain an ID that was previously generated
105 * with this function. Clents should pass NULL in `str` if `str_id`
106 * is no longer in use. Otherwise, the string previously mapped to
107 * `str_id` will be overwritten with the contents of `str`.
110 * A NUL-terminated 'C' string containing the characters that should be
111 * traced alongside `str_id`.
113 * If necessary, the string will be truncated at an
114 * implementation-defined length. The string must not be the empty
115 * string, but can be NULL if a valid `str_id` is provided.
118 * 0 if tracing is disabled or `debugid` is being filtered out of trace.
119 * It can also return (int64_t)-1 if an error occured. Otherwise,
120 * it returns the ID to use to refer to the string in future
121 * kdebug_trace(2) calls.
123 * The errors that can occur are:
126 * There are function qualifiers on `debugid`, `str` is empty, or
127 * `str_id` was not generated by this function.
129 * The `debugid`'s class or subclass is reserved for internal use.
131 * `str` is an invalid address or NULL when `str_id` is 0.
133 extern uint64_t kdebug_trace_string(uint32_t debugid
, uint64_t str_id
,
135 __OSX_AVAILABLE(10.11) __IOS_AVAILABLE(9.0);
138 * Although the performance impact of kdebug_trace() when kernel
139 * tracing is not enabled is minimal, it may require the caller to
140 * perform an expensive calculation/summarization. This cost can be
141 * skipped by checking the kdebug_is_enabled() predicate:
143 * if (kdebug_is_enabled(KDBG_CODE(DBG_XPC, 15, 1))) {
144 * uint64_t arg1 = ...;
145 * uint64_t arg2 = ...;
146 * kdebug_trace(KDBG_CODE(DBG_XPC, 15, 1) | DBG_FUNC_NONE, arg1, arg2, 0, 0);
149 * If tracing is enabled for the code at the time of the check, 1
150 * will be returned. Otherwise, 0 will be returned.
152 extern bool kdebug_is_enabled(uint32_t code
)
153 __OSX_AVAILABLE(10.12) __IOS_AVAILABLE(10.0)
154 __WATCHOS_AVAILABLE(3.0) __TVOS_AVAILABLE(10.0);
157 * Returns a pointer to the userspace typefilter, if one is available.
160 extern void *kdebug_typefilter(void)
161 __OSX_AVAILABLE(10.12) __IOS_AVAILABLE(10.0)
162 __WATCHOS_AVAILABLE(3.0) __TVOS_AVAILABLE(10.0);
165 * Returns true if kdebug is using continuous time for its events, and false
168 extern bool kdebug_using_continuous_time(void)
169 __API_AVAILABLE(macos(10.15), ios(13), tvos(13), watchos(6));
173 #pragma mark - private debugids
176 #define DBG_PERFCTRL 39
180 /* **** 128 to 139 are reserved for IOP tracing **** */
185 #define DBG_OSCAR 132
186 #define DBG_EMBEDDEDGFX 133
188 #define DBG_RTKIT 135
190 #define MACH_BRIDGE_RCV_TS 0x1 /* receive timestamp pair from interrupt handler */
191 #define MACH_BRIDGE_REMOTE_TIME 0x2 /* calculate remote timestamp */
192 #define MACH_BRIDGE_RESET_TS 0x3 /* reset timestamp conversion parameters */
193 #define MACH_BRIDGE_TS_PARAMS 0x4 /* recompute timestamp conversion parameters */
194 #define MACH_BRIDGE_SKIP_TS 0x5 /* skip timestamp */
195 #define MACH_BRIDGE_TS_MISMATCH 0x6 /* mismatch between predicted and received remote timestamp */
196 #define MACH_BRIDGE_OBSV_RATE 0x7 /* out of range observed rates */
198 /* DBG_SKYWALK has same toplevel code as DBG_DLIL, so don't reuse subcodes */
199 #define DBG_SKYWALK_FLOWSWITCH 0x11
200 #define DBG_SKYWALK_NETIF 0x12
201 #define DBG_SKYWALK_CHANNEL 0x13
203 #define PPT_TEST 0x01
204 #define PPT_JETSAM_HIWAT 0x02
205 #define PPT_JETSAM_TOPPROC 0x03
207 #define SKYWALKDBG_CODE(SubClass, code) KDBG_CODE(DBG_DLIL, SubClass, code)
208 #define PPTDBG_CODE(SubClass, code) KDBG_CODE(DBG_PPT, SubClass, code)
209 #define PERFCTRL_CODE(SubClass, code) KDBG_CODE(DBG_PERFCTRL, SubClass, code)
211 #if !defined(DRIVERKIT)
213 extern unsigned int kdebug_enable
;
216 * Bits used by kdebug_enable. These control which events are traced at
219 #define KDEBUG_ENABLE_TRACE (1U << 0)
220 #define KDEBUG_ENABLE_ENTROPY (1U << 1) /* obsolete */
221 #define KDEBUG_ENABLE_CHUD (1U << 2) /* obsolete */
222 #define KDEBUG_ENABLE_PPT (1U << 3) /* obsolete */
223 #define KDEBUG_ENABLE_SERIAL (1U << 4) /* obsolete */
226 * If set, the timestamps in events are expected to be continuous times.
227 * Otherwise, the timestamps are absolute times. IOPs should observe this bit
228 * in order to log events that can be merged cleanly with other event streams.
230 #define KDEBUG_ENABLE_CONT_TIME 0x20
232 #define KDEBUG_TRACE (KDEBUG_ENABLE_TRACE)
235 * Specify KDEBUG_PPT to indicate that the event belongs to the limited PPT set.
236 * PPT is deprecated -- use a typefilter and the PPTDBG class instead.
238 #define KDEBUG_PPT (KDEBUG_ENABLE_PPT)
239 #define KDEBUG_COMMON (KDEBUG_ENABLE_TRACE | KDEBUG_ENABLE_PPT)
242 * The kernel debug configuration level. These values control which events are
243 * compiled in under different build configurations.
245 * Infer the supported kernel debug event level from config option. Use
246 * (KDEBUG_LEVEL >= KDEBUG_LEVEL_STANDARD) as a guard to protect unaudited debug
249 #define KDEBUG_LEVEL_NONE 0
250 #define KDEBUG_LEVEL_IST 1
251 #define KDEBUG_LEVEL_STANDARD 2
252 #define KDEBUG_LEVEL_FULL 3
255 #define KDEBUG_LEVEL KDEBUG_LEVEL_NONE
257 #define KDEBUG_LEVEL KDEBUG_LEVEL_IST
259 #define KDEBUG_LEVEL KDEBUG_LEVEL_FULL
261 #define KDEBUG_LEVEL KDEBUG_LEVEL_STANDARD
263 * Currently, all other kernel configurations (development, etc) build with
264 * KDEBUG_LEVEL_STANDARD.
269 * Some Apple internal clients try to use the kernel macros in user space.
272 #define KERNEL_DEBUG(...) do { } while (0)
273 #endif /* !defined(KERNEL_DEBUG) */
275 #pragma mark - private definitions
278 * Ensure that both LP32 and LP64 variants of arm64 use the same kd_buf
281 #if defined(__arm64__)
282 typedef uint64_t kd_buf_argtype
;
284 typedef uintptr_t kd_buf_argtype
;
293 kd_buf_argtype arg5
; /* the thread ID */
296 * Ensure that both LP32 and LP64 variants of arm64 use the same kd_buf
299 #if defined(__LP64__) || defined(__arm64__)
301 kd_buf_argtype unused
;
305 #if defined(__LP64__) || defined(__arm64__)
306 #define KDBG_TIMESTAMP_MASK 0xffffffffffffffffULL
308 kdbg_set_cpu(kd_buf
*kp
, int cpu
)
310 kp
->cpuid
= (unsigned int)cpu
;
313 kdbg_get_cpu(kd_buf
*kp
)
315 return (int)kp
->cpuid
;
318 kdbg_set_timestamp(kd_buf
*kp
, uint64_t thetime
)
320 kp
->timestamp
= thetime
;
322 static inline uint64_t
323 kdbg_get_timestamp(kd_buf
*kp
)
325 return kp
->timestamp
;
328 kdbg_set_timestamp_and_cpu(kd_buf
*kp
, uint64_t thetime
, int cpu
)
330 kdbg_set_timestamp(kp
, thetime
);
331 kdbg_set_cpu(kp
, cpu
);
334 #define KDBG_TIMESTAMP_MASK 0x00ffffffffffffffULL
335 #define KDBG_CPU_MASK 0xff00000000000000ULL
336 #define KDBG_CPU_SHIFT 56
338 kdbg_set_cpu(kd_buf
*kp
, int cpu
)
340 kp
->timestamp
= (kp
->timestamp
& KDBG_TIMESTAMP_MASK
) |
341 (((uint64_t) cpu
) << KDBG_CPU_SHIFT
);
344 kdbg_get_cpu(kd_buf
*kp
)
346 return (int) (((kp
)->timestamp
& KDBG_CPU_MASK
) >> KDBG_CPU_SHIFT
);
349 kdbg_set_timestamp(kd_buf
*kp
, uint64_t thetime
)
351 kp
->timestamp
= thetime
& KDBG_TIMESTAMP_MASK
;
353 static inline uint64_t
354 kdbg_get_timestamp(kd_buf
*kp
)
356 return kp
->timestamp
& KDBG_TIMESTAMP_MASK
;
359 kdbg_set_timestamp_and_cpu(kd_buf
*kp
, uint64_t thetime
, int cpu
)
361 kp
->timestamp
= (thetime
& KDBG_TIMESTAMP_MASK
) |
362 (((uint64_t) cpu
) << KDBG_CPU_SHIFT
);
367 * 2^16 bits (8 kilobytes), one for each possible class/subclass combination
369 #define KDBG_TYPEFILTER_BITMAP_SIZE ((256 * 256) / 8)
372 * Bits for kd_ctrl_page.flags, KERN_KD{D,E}FLAGS.
374 #define KDBG_INIT (1U << 0) /* obsolete */
375 /* disable tracing when buffers are full */
376 #define KDBG_NOWRAP (1U << 1)
377 #define KDBG_FREERUN (1U << 2) /* obsolete */
378 /* buffer has wrapped */
379 #define KDBG_WRAPPED (1U << 3)
380 /* flags that are allowed to be set by user space */
381 #define KDBG_USERFLAGS (KDBG_FREERUN | KDBG_NOWRAP | KDBG_INIT)
382 /* only include processes with kdebug bit set in proc */
383 #define KDBG_PIDCHECK (1U << 4)
384 /* thread map is initialized */
385 #define KDBG_MAPINIT (1U << 5)
386 /* exclude processes based on kdebug bit in proc */
387 #define KDBG_PIDEXCLUDE (1U << 6)
388 /* whether the kdebug locks are intialized */
389 #define KDBG_LOCKINIT (1U << 7)
390 /* word size of the kernel */
391 #define KDBG_LP64 (1U << 8)
393 /* bits for kd_ctrl_page.flags and kbufinfo_t.flags */
395 /* only trace events within a range */
396 #define KDBG_RANGECHECK 0x00100000U
397 /* only trace at most 4 types of events, at the code granularity */
398 #define KDBG_VALCHECK 0x00200000U
399 /* check class and subclass against the typefilter */
400 #define KDBG_TYPEFILTER_CHECK 0x00400000U
401 /* kdebug trace buffers are initialized */
402 #define KDBG_BUFINIT 0x80000000U
404 /* bits for the type field of kd_regtype */
405 #define KDBG_CLASSTYPE 0x10000
406 #define KDBG_SUBCLSTYPE 0x20000
407 #define KDBG_RANGETYPE 0x40000
408 #define KDBG_TYPENONE 0x80000
409 #define KDBG_CKTYPES 0xF0000
420 /* number of events that can fit in the buffers */
422 /* set if trace is disabled */
424 /* kd_ctrl_page.flags */
426 /* number of threads in thread map */
434 #if defined(__arm64__)
439 /* 0 for invalid, otherwise the PID (or 1 for kernel_task) */
441 /* the name of the process owning the thread */
451 #define KDBG_CPUMAP_IS_IOP 0x1
466 #define RAW_VERSION0 0x55aa0000
467 #define RAW_VERSION1 0x55aa0101
468 #define RAW_VERSION2 0x55aa0200 /* Only used by kperf and Instruments */
471 * Bits set in the comm page for kdebug.
473 #define KDEBUG_COMMPAGE_ENABLE_TRACE 0x1
474 #define KDEBUG_COMMPAGE_ENABLE_TYPEFILTER 0x2 /* Forced to false if ENABLE_TRACE is 0 */
476 #pragma mark - EnergyTracing
478 /* for EnergyTracing user space & clients */
479 #define kEnTrCompKernel 2
482 * EnergyTracing opcodes
484 * Activations use DBG_FUNC_START/END.
485 * Events are DBG_FUNC_NONE.
488 /* Socket reads and writes are uniquely identified by the (sanitized)
489 * pointer to the socket struct in question. To associate this address
490 * with the user space file descriptor, we have a socket activation with
491 * the FD as its identifier and the socket struct pointer as its value.
493 #define kEnTrActKernSocket 1
494 #define kEnTrActKernSockRead 2
495 #define kEnTrActKernSockWrite 3
497 #define kEnTrActKernPoll 10
498 #define kEnTrActKernSelect 11
499 #define kEnTrActKernKQWait 12
502 #define kEnTrEvUnblocked 256
504 // EnergyTracing flags (the low-order 16 bits of 'quality')
505 #define kEnTrFlagNonBlocking 1 << 0
506 #define kEnTrFlagNoWork 1 << 1
509 * EnergyTracing macros.
512 #if (KDEBUG_LEVEL >= KDEBUG_LEVEL_IST)
513 // whether to bother calculating EnergyTracing inputs
514 // could change in future to see if DBG_ENERGYTRACE is active
515 #define ENTR_SHOULDTRACE kdebug_enable
516 // encode logical EnergyTracing into 32/64 KDebug trace
517 #define ENTR_KDTRACE(component, opcode, lifespan, id, quality, value) \
520 uintptr_t highval__, lowval__, mask__ = 0xffffffff; \
521 kdcode__ = KDBG_CODE(DBG_ENERGYTRACE,component,opcode)|(lifespan); \
522 highval__ = ((value) >> 32) & mask__; \
523 lowval__ = (value) & mask__; \
524 ENTR_KDTRACEFUNC(kdcode__, id, quality, highval__, lowval__); \
528 * Trace the association of two existing activations.
530 * An association is traced as a modification to the parent activation.
531 * In order to fit the sub-activation's component, activation code, and
532 * activation ID into a kdebug tracepoint, the arguments that would hold
533 * the value are left separate, and one stores the component and opcode
534 * of the sub-activation, while the other stores the pointer-sized
538 +-----------------+ +~+----+----+--------+ +----------+
539 |kEnTrModAssociate| | | | | | | |
540 +-----------------+ +~+----+----+--------+ +----------+
541 * 8-bits unused sub-activation ID
542 * 8-bit sub-component
546 #define kEnTrModAssociate (1 << 28)
547 #define ENTR_KDASSOCIATE(par_comp, par_opcode, par_act_id, \
548 sub_comp, sub_opcode, sub_act_id) \
550 unsigned sub_compcode = ((unsigned)sub_comp << 16) | sub_opcode; \
551 ENTR_KDTRACEFUNC(KDBG_CODE(DBG_ENERGYTRACE,par_comp,par_opcode), \
552 par_act_id, kEnTrModAssociate, sub_compcode, \
556 #else /* (KDEBUG_LEVEL >= KDEBUG_LEVEL_IST) */
558 #define ENTR_SHOULDTRACE FALSE
559 #define ENTR_KDTRACE(component, opcode, lifespan, id, quality, value) \
561 #define ENTR_KDASSOCIATE(par_comp, par_opcode, par_act_id, \
562 sub_comp, sub_opcode, sub_act_id) \
565 #endif /* (KDEBUG_LEVEL >= KDEBUG_LEVEL_IST) */
567 #endif /* !defined(DRIVERKIT) */
571 #endif /* !defined(BSD_KDEBUG_PRIVATE_H) */