]> git.saurik.com Git - apple/xnu.git/blob - bsd/sys_private/kdebug_private.h
xnu-6153.121.1.tar.gz
[apple/xnu.git] / bsd / sys_private / kdebug_private.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_KDEBUG_PRIVATE_H
30 #define BSD_KDEBUG_PRIVATE_H
31
32 #include <stdint.h>
33 #include <stdbool.h>
34 #include <sys/cdefs.h>
35 #include <sys/kdebug.h>
36
37 __BEGIN_DECLS
38
39 #if !KERNEL
40
41 #include <Availability.h>
42
43 #pragma mark - user space SPI
44
45 /*
46 * OS components can use the full precision of the "code" field
47 * (Class, SubClass, Code) to inject events using kdebug_trace() by
48 * using:
49 *
50 * kdebug_trace(KDBG_CODE(DBG_XPC, 15, 1) | DBG_FUNC_NONE, 1, 2, 3, 4);
51 *
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).
57 *
58 * Classes can be reserved by filing a Radar in xnu | ktrace.
59 *
60 * 64-bit arguments may be truncated if the system is using a 32-bit
61 * kernel.
62 *
63 * On error, -1 will be returned and errno will indicate the error.
64 */
65 int kdebug_trace(uint32_t code, uint64_t arg1, uint64_t arg2, uint64_t arg3,
66 uint64_t arg4)
67 __OSX_AVAILABLE(10.10) __IOS_AVAILABLE(8.2);
68
69 /*!
70 * @function kdebug_trace_string
71 *
72 * @discussion
73 * This function emits strings to kdebug trace along with an ID and allows
74 * for previously-traced strings to be overwritten and invalidated.
75 *
76 * To start tracing a string and generate an ID to use to refer to it:
77 *
78 * string_id = kdebug_trace_string(debugid, 0, "string");
79 *
80 * To replace a string previously traced:
81 *
82 * string_id = kdebug_trace_string(debugid, string_id, "new string");
83 *
84 * To invalidate a string ID:
85 *
86 * string_id = kdebug_trace_string(debugid, string_id, NULL);
87 *
88 * To check for errors:
89 *
90 * if ((int64_t)string_id == -1) { perror("string error") }
91 *
92 * @param debugid
93 * The `debugid` to check if its enabled before tracing and include as
94 * an argument in the event containing the string.
95 *
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`.
99 *
100 * @param str_id
101 * When 0, a new ID will be generated and returned if tracing is
102 * enabled.
103 *
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`.
108 *
109 * @param str
110 * A NUL-terminated 'C' string containing the characters that should be
111 * traced alongside `str_id`.
112 *
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.
116 *
117 * @return
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.
122 *
123 * The errors that can occur are:
124 *
125 * EINVAL
126 * There are function qualifiers on `debugid`, `str` is empty, or
127 * `str_id` was not generated by this function.
128 * EPERM
129 * The `debugid`'s class or subclass is reserved for internal use.
130 * EFAULT
131 * `str` is an invalid address or NULL when `str_id` is 0.
132 */
133 extern uint64_t kdebug_trace_string(uint32_t debugid, uint64_t str_id,
134 const char *str)
135 __OSX_AVAILABLE(10.11) __IOS_AVAILABLE(9.0);
136
137 /*
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:
142 *
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);
147 * }
148 *
149 * If tracing is enabled for the code at the time of the check, 1
150 * will be returned. Otherwise, 0 will be returned.
151 */
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);
155
156 /*
157 * Returns a pointer to the userspace typefilter, if one is available.
158 * May return NULL.
159 */
160 extern void *kdebug_typefilter(void)
161 __OSX_AVAILABLE(10.12) __IOS_AVAILABLE(10.0)
162 __WATCHOS_AVAILABLE(3.0) __TVOS_AVAILABLE(10.0);
163
164 /*
165 * Returns true if kdebug is using continuous time for its events, and false
166 * otherwise.
167 */
168 extern bool kdebug_using_continuous_time(void)
169 __API_AVAILABLE(macos(10.15), ios(13), tvos(13), watchos(6));
170
171 #endif /* !KERNEL */
172
173 #pragma mark - private debugids
174
175 #define DBG_PPT 36
176 #define DBG_PERFCTRL 39
177 #define DBG_CLPC 50
178 #define DBG_MUSE 52
179
180 /* **** 128 to 139 are reserved for IOP tracing **** */
181 #define DBG_ANS 128
182 #define DBG_SIO 129
183 #define DBG_SEP 130
184 #define DBG_ISP 131
185 #define DBG_OSCAR 132
186 #define DBG_EMBEDDEDGFX 133
187 #define DBG_PMP 134
188 #define DBG_RTKIT 135
189
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 */
197
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
202
203 #define PPT_TEST 0x01
204 #define PPT_JETSAM_HIWAT 0x02
205 #define PPT_JETSAM_TOPPROC 0x03
206
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)
210
211 #if !defined(DRIVERKIT)
212
213 extern unsigned int kdebug_enable;
214
215 /*
216 * Bits used by kdebug_enable. These control which events are traced at
217 * runtime.
218 */
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 */
224
225 /*
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.
229 */
230 #define KDEBUG_ENABLE_CONT_TIME 0x20
231
232 #define KDEBUG_TRACE (KDEBUG_ENABLE_TRACE)
233
234 /*
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.
237 */
238 #define KDEBUG_PPT (KDEBUG_ENABLE_PPT)
239 #define KDEBUG_COMMON (KDEBUG_ENABLE_TRACE | KDEBUG_ENABLE_PPT)
240
241 /*
242 * The kernel debug configuration level. These values control which events are
243 * compiled in under different build configurations.
244 *
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
247 * code.
248 */
249 #define KDEBUG_LEVEL_NONE 0
250 #define KDEBUG_LEVEL_IST 1
251 #define KDEBUG_LEVEL_STANDARD 2
252 #define KDEBUG_LEVEL_FULL 3
253
254 #if NO_KDEBUG
255 #define KDEBUG_LEVEL KDEBUG_LEVEL_NONE
256 #elif IST_KDEBUG
257 #define KDEBUG_LEVEL KDEBUG_LEVEL_IST
258 #elif KDEBUG
259 #define KDEBUG_LEVEL KDEBUG_LEVEL_FULL
260 #else
261 #define KDEBUG_LEVEL KDEBUG_LEVEL_STANDARD
262 /*
263 * Currently, all other kernel configurations (development, etc) build with
264 * KDEBUG_LEVEL_STANDARD.
265 */
266 #endif
267
268 /*
269 * Some Apple internal clients try to use the kernel macros in user space.
270 */
271 #ifndef KERNEL_DEBUG
272 #define KERNEL_DEBUG(...) do { } while (0)
273 #endif /* !defined(KERNEL_DEBUG) */
274
275 #pragma mark - private definitions
276
277 /*
278 * Ensure that both LP32 and LP64 variants of arm64 use the same kd_buf
279 * structure.
280 */
281 #if defined(__arm64__)
282 typedef uint64_t kd_buf_argtype;
283 #else
284 typedef uintptr_t kd_buf_argtype;
285 #endif
286
287 typedef struct {
288 uint64_t timestamp;
289 kd_buf_argtype arg1;
290 kd_buf_argtype arg2;
291 kd_buf_argtype arg3;
292 kd_buf_argtype arg4;
293 kd_buf_argtype arg5; /* the thread ID */
294 uint32_t debugid;
295 /*
296 * Ensure that both LP32 and LP64 variants of arm64 use the same kd_buf
297 * structure.
298 */
299 #if defined(__LP64__) || defined(__arm64__)
300 uint32_t cpuid;
301 kd_buf_argtype unused;
302 #endif
303 } kd_buf;
304
305 #if defined(__LP64__) || defined(__arm64__)
306 #define KDBG_TIMESTAMP_MASK 0xffffffffffffffffULL
307 static inline void
308 kdbg_set_cpu(kd_buf *kp, int cpu)
309 {
310 kp->cpuid = (unsigned int)cpu;
311 }
312 static inline int
313 kdbg_get_cpu(kd_buf *kp)
314 {
315 return (int)kp->cpuid;
316 }
317 static inline void
318 kdbg_set_timestamp(kd_buf *kp, uint64_t thetime)
319 {
320 kp->timestamp = thetime;
321 }
322 static inline uint64_t
323 kdbg_get_timestamp(kd_buf *kp)
324 {
325 return kp->timestamp;
326 }
327 static inline void
328 kdbg_set_timestamp_and_cpu(kd_buf *kp, uint64_t thetime, int cpu)
329 {
330 kdbg_set_timestamp(kp, thetime);
331 kdbg_set_cpu(kp, cpu);
332 }
333 #else
334 #define KDBG_TIMESTAMP_MASK 0x00ffffffffffffffULL
335 #define KDBG_CPU_MASK 0xff00000000000000ULL
336 #define KDBG_CPU_SHIFT 56
337 static inline void
338 kdbg_set_cpu(kd_buf *kp, int cpu)
339 {
340 kp->timestamp = (kp->timestamp & KDBG_TIMESTAMP_MASK) |
341 (((uint64_t) cpu) << KDBG_CPU_SHIFT);
342 }
343 static inline int
344 kdbg_get_cpu(kd_buf *kp)
345 {
346 return (int) (((kp)->timestamp & KDBG_CPU_MASK) >> KDBG_CPU_SHIFT);
347 }
348 static inline void
349 kdbg_set_timestamp(kd_buf *kp, uint64_t thetime)
350 {
351 kp->timestamp = thetime & KDBG_TIMESTAMP_MASK;
352 }
353 static inline uint64_t
354 kdbg_get_timestamp(kd_buf *kp)
355 {
356 return kp->timestamp & KDBG_TIMESTAMP_MASK;
357 }
358 static inline void
359 kdbg_set_timestamp_and_cpu(kd_buf *kp, uint64_t thetime, int cpu)
360 {
361 kp->timestamp = (thetime & KDBG_TIMESTAMP_MASK) |
362 (((uint64_t) cpu) << KDBG_CPU_SHIFT);
363 }
364 #endif
365
366 /*
367 * 2^16 bits (8 kilobytes), one for each possible class/subclass combination
368 */
369 #define KDBG_TYPEFILTER_BITMAP_SIZE ((256 * 256) / 8)
370
371 /*
372 * Bits for kd_ctrl_page.flags, KERN_KD{D,E}FLAGS.
373 */
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)
392
393 /* bits for kd_ctrl_page.flags and kbufinfo_t.flags */
394
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
403
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
410
411 typedef struct {
412 unsigned int type;
413 unsigned int value1;
414 unsigned int value2;
415 unsigned int value3;
416 unsigned int value4;
417 } kd_regtype;
418
419 typedef struct {
420 /* number of events that can fit in the buffers */
421 int nkdbufs;
422 /* set if trace is disabled */
423 int nolog;
424 /* kd_ctrl_page.flags */
425 unsigned int flags;
426 /* number of threads in thread map */
427 int nkdthreads;
428 /* the owning pid */
429 int bufid;
430 } kbufinfo_t;
431
432 typedef struct {
433 /* the thread ID */
434 #if defined(__arm64__)
435 uint64_t thread;
436 #else
437 uintptr_t thread;
438 #endif
439 /* 0 for invalid, otherwise the PID (or 1 for kernel_task) */
440 int valid;
441 /* the name of the process owning the thread */
442 char command[20];
443 } kd_threadmap;
444
445 typedef struct {
446 uint32_t version_no;
447 uint32_t cpu_count;
448 } kd_cpumap_header;
449
450 /* cpumap flags */
451 #define KDBG_CPUMAP_IS_IOP 0x1
452
453 typedef struct {
454 uint32_t cpu_id;
455 uint32_t flags;
456 char name[8];
457 } kd_cpumap;
458
459 typedef struct {
460 int version_no;
461 int thread_count;
462 uint64_t TOD_secs;
463 uint32_t TOD_usecs;
464 } RAW_header;
465
466 #define RAW_VERSION0 0x55aa0000
467 #define RAW_VERSION1 0x55aa0101
468 #define RAW_VERSION2 0x55aa0200 /* Only used by kperf and Instruments */
469
470 /*
471 * Bits set in the comm page for kdebug.
472 */
473 #define KDEBUG_COMMPAGE_ENABLE_TRACE 0x1
474 #define KDEBUG_COMMPAGE_ENABLE_TYPEFILTER 0x2 /* Forced to false if ENABLE_TRACE is 0 */
475
476 #pragma mark - EnergyTracing
477
478 /* for EnergyTracing user space & clients */
479 #define kEnTrCompKernel 2
480
481 /*
482 * EnergyTracing opcodes
483 *
484 * Activations use DBG_FUNC_START/END.
485 * Events are DBG_FUNC_NONE.
486 */
487
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.
492 */
493 #define kEnTrActKernSocket 1
494 #define kEnTrActKernSockRead 2
495 #define kEnTrActKernSockWrite 3
496
497 #define kEnTrActKernPoll 10
498 #define kEnTrActKernSelect 11
499 #define kEnTrActKernKQWait 12
500
501 // events
502 #define kEnTrEvUnblocked 256
503
504 // EnergyTracing flags (the low-order 16 bits of 'quality')
505 #define kEnTrFlagNonBlocking 1 << 0
506 #define kEnTrFlagNoWork 1 << 1
507
508 /*
509 * EnergyTracing macros.
510 */
511
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) \
518 do { \
519 uint32_t kdcode__; \
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__); \
525 } while(0)
526
527 /*
528 * Trace the association of two existing activations.
529 *
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
535 * activation ID.
536 *
537 * arg2 arg3 arg4
538 +-----------------+ +~+----+----+--------+ +----------+
539 |kEnTrModAssociate| | | | | | | |
540 +-----------------+ +~+----+----+--------+ +----------+
541 * 8-bits unused sub-activation ID
542 * 8-bit sub-component
543 * 16-bit sub-opcode
544 *
545 */
546 #define kEnTrModAssociate (1 << 28)
547 #define ENTR_KDASSOCIATE(par_comp, par_opcode, par_act_id, \
548 sub_comp, sub_opcode, sub_act_id) \
549 do { \
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, \
553 sub_act_id); \
554 } while(0)
555
556 #else /* (KDEBUG_LEVEL >= KDEBUG_LEVEL_IST) */
557
558 #define ENTR_SHOULDTRACE FALSE
559 #define ENTR_KDTRACE(component, opcode, lifespan, id, quality, value) \
560 do {} while (0)
561 #define ENTR_KDASSOCIATE(par_comp, par_opcode, par_act_id, \
562 sub_comp, sub_opcode, sub_act_id) \
563 do {} while (0)
564
565 #endif /* (KDEBUG_LEVEL >= KDEBUG_LEVEL_IST) */
566
567 #endif /* !defined(DRIVERKIT) */
568
569 __END_DECLS
570
571 #endif /* !defined(BSD_KDEBUG_PRIVATE_H) */