1 /*
2 * Copyright (c) 2000-2021 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 <os/base.h>
33 #include <stdint.h>
34 #include <stdbool.h>
35 #include <sys/cdefs.h>
36 #include <sys/kdebug.h>
37
38 __BEGIN_DECLS
39
40 #if !KERNEL
41
42 #include <Availability.h>
43
44 #pragma mark - User space SPI
45
46 // Internal software can trace events into kdebug, but the os_signpost(3)
47 // interfaces in `<os/signpost.h>` are recommended.
48 //
49 // kdebug_trace(KDBG_EVENTID(DBG_XPC, 15, 1), 1, 2, 3, 4);
50 //
51 // The performance impact when kernel tracing is not enabled is minimal.
52 // However, when tracing is enabled, each event requires a syscall.
53 //
54 // Classes can be reserved by filing a Radar in xnu | ktrace.
55 //
56 // 64-bit arguments may be truncated if the system is using a 32-bit kernel.
57 //
58 // On error, -1 will be returned and errno will indicate the error.
59 int kdebug_trace(uint32_t debugid, uint64_t arg1, uint64_t arg2, uint64_t arg3,
60 uint64_t arg4)
61 __API_AVAILABLE(macos(10.0), ios(8), tvos(8), watchos(1));
62
63 // Although the performance impact of kdebug_trace() when tracing is disabled is
64 // minimal, it may require the caller to perform an expensive calculation or
65 // summarization. This cost can be skipped by checking the kdebug_is_enabled()
66 // predicate:
67 //
68 // if (kdebug_is_enabled(KDBG_CODE(DBG_XPC, 15, 1))) {
69 // uint64_t arg1 = ...;
70 // uint64_t arg2 = ...;
71 // kdebug_trace(KDBG_EVENTID(DBG_XPC, 15, 1), arg1, arg2, 0, 0);
72 // }
73 //
74 // true is returned iff tracing is enabled for the debug ID at the time of the
75 // check.
76 extern bool kdebug_is_enabled(uint32_t debugid)
77 __API_AVAILABLE(macos(10.12), ios(10), watchos(3), tvos(10));
78
79 // Returns true if kdebug is using continuous time for its events, and false
80 // otherwise.
81 extern bool kdebug_using_continuous_time(void)
82 __API_AVAILABLE(macos(10.15), ios(13), tvos(13), watchos(6));
83
84 // Convert an absolute time to a kdebug timestamp.
85 extern uint64_t kdebug_timestamp_from_absolute(uint64_t abstime)
86 __API_AVAILABLE(macos(12), ios(15), tvos(15), watchos(8));
87
88 // Convert a continuous time to a kdebug timestamp.
89 extern uint64_t kdebug_timestamp_from_continuous(uint64_t conttime)
90 __API_AVAILABLE(macos(12), ios(15), tvos(15), watchos(8));
91
92 // Capture a kdebug timestamp for the current time.
93 extern uint64_t kdebug_timestamp(void)
94 __API_AVAILABLE(macos(12), ios(15), tvos(15), watchos(8));
95
96 /// @function kdebug_trace_string
97 ///
98 /// @discussion
99 /// This function emits strings to kdebug trace along with an ID and allows
100 /// for previously-traced strings to be overwritten and invalidated.
101 ///
102 /// To start tracing a string and generate an ID to use to refer to it:
103 ///
104 /// string_id = kdebug_trace_string(debugid, 0, "string");
105 ///
106 /// To replace a string previously traced:
107 ///
108 /// string_id = kdebug_trace_string(debugid, string_id, "new string");
109 ///
110 /// To invalidate a string ID:
111 ///
112 /// string_id = kdebug_trace_string(debugid, string_id, NULL);
113 ///
114 /// To check for errors:
115 ///
116 /// if ((int64_t)string_id == -1) { perror("string error") }
117 ///
118 /// @param debugid
119 /// The `debugid` to check if its enabled before tracing and include as
120 /// an argument in the event containing the string.
121 ///
122 /// Some classes or subclasses are reserved for specific uses and are not
123 /// allowed to be used with this function. No function qualifiers are
124 /// allowed on `debugid`.
125 ///
126 /// @param str_id
127 /// When 0, a new ID will be generated and returned if tracing is
128 /// enabled.
129 ///
130 /// Otherwise `str_id` must contain an ID that was previously generated
131 /// with this function. Clents should pass NULL in `str` if `str_id`
132 /// is no longer in use. Otherwise, the string previously mapped to
133 /// `str_id` will be overwritten with the contents of `str`.
134 ///
135 /// @param str
136 /// A NUL-terminated 'C' string containing the characters that should be
137 /// traced alongside `str_id`.
138 ///
139 /// If necessary, the string will be truncated at an
140 /// implementation-defined length of at least PATH_MAX characters. The string
141 /// must not be the empty string, but can be NULL if a valid `str_id` is
142 /// provided.
143 ///
144 /// @return
145 /// 0 if tracing is disabled or `debugid` is being filtered out of trace.
146 /// It can also return (int64_t)-1 if an error occured. Otherwise,
147 /// it returns the ID to use to refer to the string in future
148 /// kdebug_trace(2) calls.
149 ///
150 /// The errors that can occur are:
151 ///
152 /// EINVAL
153 /// There are function qualifiers on `debugid`, `str` is empty, or
154 /// `str_id` was not generated by this function.
155 /// EPERM
156 /// The `debugid`'s class or subclass is reserved for internal use.
157 /// EFAULT
158 /// `str` is an invalid address or NULL when `str_id` is 0.
159 extern uint64_t kdebug_trace_string(uint32_t debugid, uint64_t str_id,
160 const char *str)
161 __API_AVAILABLE(macos(10.11), ios(9), watchos(2), tvos(9));
162
163 // Returns a pointer to the userspace typefilter, if one is available.
164 // May return NULL.
165 extern void *kdebug_typefilter(void)
166 __API_AVAILABLE(macos(10.12), ios(10), watchos(3), tvos(10));
167
168 #endif /* !KERNEL */
169
170 #pragma mark - Private debug IDs
171
172 #define DBG_PPT 36
173 #define DBG_PERFCTRL 39
174 #define DBG_CLPC 50
175 #define DBG_MUSE 52
176
177 #define DBG_ANS 128
178 #define DBG_SIO 129
179 #define DBG_SEP 130
180 #define DBG_ISP 131
181 #define DBG_OSCAR 132
182 #define DBG_EMBEDDEDGFX 133
183 #define DBG_PMP 134
184 #define DBG_RTKIT 135
185 #define DBG_DCP 136
186 #define DBG_KMP 137
187
188 // DBG_SKYWALK is the same as DBG_DLIL, so don't reuse subclasses
189 #define DBG_SKYWALK_ALWAYSON 0x10
190 #define DBG_SKYWALK_FLOWSWITCH 0x11
191 #define DBG_SKYWALK_NETIF 0x12
192 #define DBG_SKYWALK_CHANNEL 0x13
193 #define DBG_SKYWALK_PACKET 0x14
194
195 // DBG_AQM is the same as DBG_DLIL and DBG_SKYWALK, so don't reuse subclasses
196 #define DBG_AQM_ALWAYSON 0x30
197 #define DBG_AQM_STATS 0x31
198
199 // DBG_IFNET is the same as DBG_DLIL, DBG_AQM and DBG_SKYWALK, so don't reuse subclasses
200 #define DBG_IFNET 0x40
201
202 #define PPT_TEST 0x01
203 #define PPT_JETSAM_HIWAT 0x02
204 #define PPT_JETSAM_TOPPROC 0x03
205
206 // DBG_SECURITY private subclasses
207 #define DBG_SEC_SSMA 0x02
208
209 #define SKYWALKDBG_CODE(SubClass, code) KDBG_CODE(DBG_DLIL, SubClass, code)
210 #define PPTDBG_CODE(SubClass, code) KDBG_CODE(DBG_PPT, SubClass, code)
211 #define PERFCTRL_CODE(SubClass, code) KDBG_CODE(DBG_PERFCTRL, SubClass, code)
212 #define AQMDBG_CODE(SubClass, code) KDBG_CODE(DBG_DLIL, SubClass, code)
213 #define IFNETDBG_CODE(SubClass, code) KDBG_CODE(DBG_DLIL, SubClass, code)
214
215 #if !defined(DRIVERKIT)
216
217 extern unsigned int kdebug_enable;
218
219 // Options for `kdebug_enable`.
220
221 // Enable tracing.
222 #define KDEBUG_ENABLE_TRACE 0x001U
223 // Whether timestamps are continuous times or absolute times.
224 #define KDEBUG_ENABLE_CONT_TIME 0x020U
225
226 #define KDEBUG_TRACE (KDEBUG_ENABLE_TRACE)
227
228 // Control which kernel events are compiled in under different build
229 // configurations.
230
231 // No kdebug events are emitted with the macros.
232 #define KDEBUG_LEVEL_NONE 0
233 // In-System Tracing exposes a limited set of events for release kernels.
234 #define KDEBUG_LEVEL_IST 1
235 // The default for development kernels.
236 #define KDEBUG_LEVEL_STANDARD 2
237 // Truly verbose, debug-level logging, only set manually.
238 #define KDEBUG_LEVEL_FULL 3
239
240 // Use configuration options to set the kdebug level.
241 #if NO_KDEBUG
242 #define KDEBUG_LEVEL KDEBUG_LEVEL_NONE
243 #elif IST_KDEBUG
244 #define KDEBUG_LEVEL KDEBUG_LEVEL_IST
245 #elif KDEBUG
246 #define KDEBUG_LEVEL KDEBUG_LEVEL_FULL
247 #else // !NO_KDEBUG && !IST_KDEBUG && !KDEBUG
248 #define KDEBUG_LEVEL KDEBUG_LEVEL_STANDARD
249 #endif // !NO_KDEBUG && !IST_KDEBUG && !KDEBUG
250
251 #pragma mark - Implementation details
252
253 // Ensure that LP32 and LP64 variants of arm64 use the same kd_buf structure.
254 #if defined(__arm64__)
255 typedef uint64_t kd_buf_argtype;
256 #else // defined(__arm64__)
257 typedef uintptr_t kd_buf_argtype;
258 #endif // !defined(__arm64__)
259
260 // The main event ABI as recorded in the kernel.
261
262 typedef struct {
263 uint64_t timestamp;
264 kd_buf_argtype arg1;
265 kd_buf_argtype arg2;
266 kd_buf_argtype arg3;
267 kd_buf_argtype arg4;
268 kd_buf_argtype arg5; // Always the thread ID.
269 uint32_t debugid;
270 // Ensure that LP32 and LP64 variants of arm64 use the same kd_buf structure.
271 #if defined(__LP64__) || defined(__arm64__)
272 uint32_t cpuid;
273 kd_buf_argtype unused;
274 #endif // defined(__LP64__) || defined(__arm64__)
275 } kd_buf;
276
277 #if defined(__LP64__) || defined(__arm64__)
278
279 #define KDBG_TIMESTAMP_MASK 0xffffffffffffffffULL
280 static inline void
kdbg_set_cpu(kd_buf * kp,int cpu)281 kdbg_set_cpu(kd_buf *kp, int cpu)
282 {
283 kp->cpuid = (unsigned int)cpu;
284 }
285 static inline int
kdbg_get_cpu(kd_buf * kp)286 kdbg_get_cpu(kd_buf *kp)
287 {
288 return (int)kp->cpuid;
289 }
290 static inline void
kdbg_set_timestamp(kd_buf * kp,uint64_t thetime)291 kdbg_set_timestamp(kd_buf *kp, uint64_t thetime)
292 {
293 kp->timestamp = thetime;
294 }
295 static inline uint64_t
kdbg_get_timestamp(kd_buf * kp)296 kdbg_get_timestamp(kd_buf *kp)
297 {
298 return kp->timestamp;
299 }
300 static inline void
kdbg_set_timestamp_and_cpu(kd_buf * kp,uint64_t thetime,int cpu)301 kdbg_set_timestamp_and_cpu(kd_buf *kp, uint64_t thetime, int cpu)
302 {
303 kdbg_set_timestamp(kp, thetime);
304 kdbg_set_cpu(kp, cpu);
305 }
306 #else // defined(__LP64__) || defined(__arm64__)
307 #define KDBG_TIMESTAMP_MASK 0x00ffffffffffffffULL
308 #define KDBG_CPU_MASK 0xff00000000000000ULL
309 #define KDBG_CPU_SHIFT 56
310 static inline void
kdbg_set_cpu(kd_buf * kp,int cpu)311 kdbg_set_cpu(kd_buf *kp, int cpu)
312 {
313 kp->timestamp = (kp->timestamp & KDBG_TIMESTAMP_MASK) |
314 (((uint64_t) cpu) << KDBG_CPU_SHIFT);
315 }
316 static inline int
kdbg_get_cpu(kd_buf * kp)317 kdbg_get_cpu(kd_buf *kp)
318 {
319 return (int) (((kp)->timestamp & KDBG_CPU_MASK) >> KDBG_CPU_SHIFT);
320 }
321 static inline void
kdbg_set_timestamp(kd_buf * kp,uint64_t thetime)322 kdbg_set_timestamp(kd_buf *kp, uint64_t thetime)
323 {
324 kp->timestamp = thetime & KDBG_TIMESTAMP_MASK;
325 }
326 static inline uint64_t
kdbg_get_timestamp(kd_buf * kp)327 kdbg_get_timestamp(kd_buf *kp)
328 {
329 return kp->timestamp & KDBG_TIMESTAMP_MASK;
330 }
331 static inline void
kdbg_set_timestamp_and_cpu(kd_buf * kp,uint64_t thetime,int cpu)332 kdbg_set_timestamp_and_cpu(kd_buf *kp, uint64_t thetime, int cpu)
333 {
334 kp->timestamp = (thetime & KDBG_TIMESTAMP_MASK) |
335 (((uint64_t) cpu) << KDBG_CPU_SHIFT);
336 }
337 #endif // !defined(__LP64__) && !defined(__arm64__)
338
339 // 8KB, one bit for each possible class/subclass combination.
340 #define KDBG_TYPEFILTER_BITMAP_SIZE ((256 * 256) / 8)
341
342 // Settings that may need to be changed while tracing, protected by the storage
343 // lock or the ktrace lock if tracing is disabled.
344 //
345 // These flags must not overlap with `kdebug_flags_t`.
346 __options_decl(kdebug_live_flags_t, uint32_t, {
347 // Disable tracing when events wrap. Set while reading events.
348 KDBG_NOWRAP = 0x0002,
349 // Events have wrapped.
350 KDBG_WRAPPED = 0x0008,
351 });
352
353 // Mostly configuration options, protected by the ktrace lock.
354 __options_decl(kdebug_flags_t, uint32_t, {
355 // Only trace processes with the kdebug bit set.
356 KDBG_PIDCHECK = 0x0010,
357 // Thread map pointer is valid.
358 KDBG_MAPINIT = 0x0020,
359 // Exclude events from processes with the kdebug bit set.
360 KDBG_PIDEXCLUDE = 0x0040,
361 // Events are 64-bit, only for `kbufinfo_t`.
362 KDBG_LP64 = 0x0100,
363 // Timestamps are continuous time, instead of absolute time.
364 KDBG_CONTINUOUS_TIME = 0x0200,
365 // Exclude events from coprocessors (IOPs).
366 KDBG_DISABLE_COPROCS = 0x0400,
367 // Disable tracing on event match.
368 KDBG_MATCH_DISABLE = 0x0800,
369 // Check the typefilter.
370 KDBG_TYPEFILTER_CHECK = 0x00400000,
371 // 64-bit debug ID present in arg4 (triage-only).
372 KDBG_DEBUGID_64 = 0x00800000,
373 // Event storage buffers are initialized.
374 KDBG_BUFINIT = 0x80000000U,
375 });
376
377 // Obsolete flags.
378 #define KDBG_INIT 0x01
379 #define KDBG_FREERUN 0x04
380
381 // Flags in `kdebug_live_flags_t` and `kdebug_flags_t` that can be modified by
382 // user space.
383 #define KDBG_USERFLAGS (KDBG_NOWRAP | KDBG_CONTINUOUS_TIME | \
384 KDBG_DISABLE_COPROCS | KDBG_MATCH_DISABLE)
385
386 // Information about kdebug for user space consumption.
387 typedef struct {
388 // Size of buffers in number of events (kd_bufs).
389 int nkdbufs;
390 // True is tracing is disabled, false otherwise.
391 int nolog;
392 // Combined `kdebug_live_flags_t` and `kdebug_state_t`.
393 unsigned int flags;
394 // Number of threads in the thread map.
395 int nkdthreads;
396 // Owning process PID.
397 int bufid;
398 } kbufinfo_t;
399
400 // Header for CPU mapping list.
401 typedef struct {
402 uint32_t version_no;
403 uint32_t cpu_count;
404 } kd_cpumap_header;
405
406 // CPU map entry flags.
407 #define KDBG_CPUMAP_IS_IOP 0x1
408
409 // CPU map entries to map `cpuid` from events to names.
410 typedef struct {
411 uint32_t cpu_id;
412 uint32_t flags;
413 char name[32];
414 } kd_cpumap_ext;
415
416 // Match structured data from events.
417 typedef struct {
418 uint32_t kem_debugid;
419 uint32_t kem_padding;
420 uint64_t kem_args[4];
421 } kd_event_matcher;
422
423 // Options for `kdebug_enable` in the comm-page.
424 #define KDEBUG_COMMPAGE_ENABLE_TRACE 0x1
425 #define KDEBUG_COMMPAGE_ENABLE_TYPEFILTER 0x2
426 #define KDEBUG_COMMPAGE_CONTINUOUS 0x4
427
428 #pragma mark - Tests
429
430 // Test scenarios.
431 __enum_decl(kdebug_test_t, uint32_t, {
432 KDTEST_KERNEL_MACROS = 1,
433 KDTEST_OLD_TIMESTAMP,
434 KDTEST_FUTURE_TIMESTAMP,
435 KDTEST_SETUP_IOP,
436 KDTEST_SETUP_COPROCESSOR,
437 KDTEST_CONTINUOUS_TIMESTAMP,
438 KDTEST_ABSOLUTE_TIMESTAMP,
439 KDTEST_PAST_EVENT,
440 });
441
442 #pragma mark - Obsolete interfaces
443
444 // Some Apple-internal clients try to use the kernel macros in user space.
445 #ifndef KERNEL_DEBUG
446 #define KERNEL_DEBUG(...) do { } while (0)
447 #endif // !defined(KERNEL_DEBUG)
448
449 // Obsolete options for `kdebug_enable`.
450 #define KDEBUG_ENABLE_ENTROPY 0x002U
451 #define KDEBUG_ENABLE_CHUD 0x004U
452 #define KDEBUG_ENABLE_PPT 0x008U
453 #define KDEBUG_ENABLE_SERIAL 0x010U
454 #define KDEBUG_PPT (KDEBUG_ENABLE_PPT)
455 #define KDEBUG_COMMON (KDEBUG_ENABLE_TRACE | KDEBUG_ENABLE_PPT)
456
457 // Obsolete flags.
458 #define KDBG_LOCKINIT 0x0080
459 #define KDBG_RANGECHECK 0x00100000U
460 #define KDBG_VALCHECK 0x00200000U
461
462 // Type values for `kd_regtype`.
463 #define KDBG_CLASSTYPE 0x10000
464 #define KDBG_SUBCLSTYPE 0x20000
465 #define KDBG_RANGETYPE 0x40000
466 #define KDBG_TYPENONE 0x80000
467 #define KDBG_CKTYPES 0xF0000
468
469 typedef struct {
470 unsigned int type;
471 unsigned int value1;
472 unsigned int value2;
473 unsigned int value3;
474 unsigned int value4;
475 } kd_regtype;
476
477 // Entry for the legacy thread map system (replaced by stackshot).
478 typedef struct {
479 // A thread's unique ID.
480 #if defined(__arm64__)
481 uint64_t thread;
482 #else
483 uintptr_t thread __kernel_data_semantics;
484 #endif
485 // The process ID (or 1 for `kernproc`).
486 int valid;
487 // The name of the process owning this thread.
488 char command[20];
489 } kd_threadmap;
490
491 // Legacy CPU map entry.
492 typedef struct {
493 uint32_t cpu_id;
494 uint32_t flags;
495 char name[8];
496 } kd_cpumap;
497
498 // File header for legacy trace files.
499 typedef struct {
500 int version_no;
501 int thread_count;
502 uint64_t TOD_secs;
503 uint32_t TOD_usecs;
504 } RAW_header;
505
506 // Obsolete `version_no` for legacy trace files.
507 #define RAW_VERSION0 0x55aa0000
508 #define RAW_VERSION1 0x55aa0101
509 #define RAW_VERSION2 0x55aa0200
510
511 // Obsolete EnergyTracing definitions.
512
513 #define kEnTrCompKernel 2
514 #define kEnTrActKernSocket 1
515 #define kEnTrActKernSockRead 2
516 #define kEnTrActKernSockWrite 3
517 #define kEnTrActKernPoll 10
518 #define kEnTrActKernSelect 11
519 #define kEnTrActKernKQWait 12
520 #define kEnTrEvUnblocked 256
521 #define kEnTrFlagNonBlocking 0x1
522 #define kEnTrFlagNoWork 0x2
523
524 #if (KDEBUG_LEVEL >= KDEBUG_LEVEL_IST)
525 #define ENTR_SHOULDTRACE kdebug_enable
526 #define ENTR_KDTRACE(component, opcode, lifespan, id, quality, value) \
527 do { \
528 uint32_t kdcode__; \
529 uintptr_t highval__, lowval__, mask__ = 0xffffffff; \
530 kdcode__ = KDBG_CODE(DBG_ENERGYTRACE,component,opcode)|(lifespan); \
531 highval__ = ((value) >> 32) & mask__; \
532 lowval__ = (value) & mask__; \
533 ENTR_KDTRACEFUNC(kdcode__, id, quality, highval__, lowval__); \
534 } while(0)
535
536 #define kEnTrModAssociate (1 << 28)
537 #define ENTR_KDASSOCIATE(par_comp, par_opcode, par_act_id, \
538 sub_comp, sub_opcode, sub_act_id) \
539 do { \
540 unsigned sub_compcode = ((unsigned)sub_comp << 16) | sub_opcode; \
541 ENTR_KDTRACEFUNC(KDBG_CODE(DBG_ENERGYTRACE,par_comp,par_opcode), \
542 par_act_id, kEnTrModAssociate, sub_compcode, \
543 sub_act_id); \
544 } while(0)
545
546 #else // (KDEBUG_LEVEL >= KDEBUG_LEVEL_IST)
547
548 #define ENTR_SHOULDTRACE 0
549 #define ENTR_KDTRACE(component, opcode, lifespan, id, quality, value) do {} while (0)
550 #define ENTR_KDASSOCIATE(par_comp, par_opcode, par_act_id, sub_comp, sub_opcode, sub_act_id) do {} while (0)
551
552 #endif // (KDEBUG_LEVEL >= KDEBUG_LEVEL_IST)
553
554 #endif // !defined(DRIVERKIT)
555
556 __END_DECLS
557
558 #endif // !defined(BSD_KDEBUG_PRIVATE_H)
559