#include <sys/kdebug_kernel.h>

sys/kdebug_kernel.h Kernel.framework

includes: Kernel/mach/boolean.h, Kernel/mach/clock_types.h, Kernel/stdbool.h, Kernel/stdint.h, Kernel/stddef.h, sys/cdefs.h

28 macros · 14 functions · 5 typedefs · 3 enums · 1 struct · 1 variable

macroBSD_SYS_KDEBUG_KERNEL_H

#define BSD_SYS_KDEBUG_KERNEL_H

macroKDBG

Traced on debug and development (and release macOS) kernels.

#define KDBG(x, ...) KDBG_(, x, ## __VA_ARGS__, 4, 3, 2, 1, 0)

macroKDBG_FILTERED

Traced on debug and development (and release macOS) kernels if explicitly requested. Omitted from tracing without a typefilter.

#define KDBG_FILTERED(x, ...) KDBG_(_FILTERED, x, ## __VA_ARGS__, 4, 3, 2, 1, 0)

macroKDBG_RELEASE

Traced on debug, development, and release kernels. Only use this tracepoint if the events are required for a shipping trace tool.

#define KDBG_RELEASE(x, ...) KDBG_(_RELEASE, x, ## __VA_ARGS__, 4, 3, 2, 1, 0)

macroKDBG_DEBUG

Traced only on debug kernels.

#define KDBG_DEBUG(x, ...) KDBG_(_DEBUG, x, ## __VA_ARGS__, 4, 3, 2, 1, 0)

functionkdebug_using_continuous_time

bool kdebug_using_continuous_time(void)

Returns true if kdebug is using continuous time for its events, and false otherwise.

functionkdebug_timestamp_from_absolute

extern uint64_t kdebug_timestamp_from_absolute(uint64_t abstime)

Convert an absolute time to a kdebug timestamp.

functionkdebug_timestamp_from_continuous

extern uint64_t kdebug_timestamp_from_continuous(uint64_t conttime)

Convert a continuous time to a kdebug timestamp.

functionkdebug_timestamp

extern uint64_t kdebug_timestamp(void)

Capture a kdebug timestamp for the current time.

functionkdebug_debugid_enabled

bool kdebug_debugid_enabled(uint32_t debugid)

Returns true if kdebug will log an event with the provided debugid, and false otherwise.

functionkdebug_debugid_explicitly_enabled

bool kdebug_debugid_explicitly_enabled(uint32_t debugid)

Returns true only if the debugid is explicitly enabled by filters. Returns false otherwise, including when no filters are active.

functionkdebug_commpage_state

uint32_t kdebug_commpage_state(void)

▾

claude-fable-5, 2026-08-23 · not from Apple sources · verified against xnu bsd/kern/kdebug.c

Returns the kdebug state word that is published to the commpage: 0 when tracing is disabled, otherwise KDEBUG_COMMPAGE_ENABLE_TRACE, or'd with KDEBUG_COMMPAGE_ENABLE_TYPEFILTER when a typefilter is in effect and KDEBUG_COMMPAGE_CONTINUOUS when events are timestamped with continuous time.

enumkd_callback_type

underlying type unsigned int

KD_CALLBACK_KDEBUG_ENABLED	0	Trace is now enabled.
KD_CALLBACK_KDEBUG_DISABLED	1	Trace is being disabled, but events are still accepted for the duration of the callback.
KD_CALLBACK_SYNC_FLUSH	2	Request the latest events from the IOP and block until complete. Any events that occur prior to this callback being called may be dropped by the trace system.
KD_CALLBACK_TYPEFILTER_CHANGED	3	The typefilter is being used. A read-only pointer to the typefilter is provided as the argument, valid only in the callback.
KD_CALLBACK_SNAPSHOT_STATE	4	The coprocessor should emit data that snapshots the current state of the system.

typedefkd_callback_type

typedef enum kd_callback_type kd_callback_type;

enumkdebug_coproc_flags_t

underlying type uint32_t

KDCP_CONTINUOUS_TIME

typedefkdebug_coproc_flags_t

typedef enum kdebug_coproc_flags_t kdebug_coproc_flags_t;

typedefkd_callback_fn

typedef void (*)(void *, kd_callback_type, void *) kd_callback_fn;

functionkdebug_register_coproc

int kdebug_register_coproc(
	const char *name,
	kdebug_coproc_flags_t flags,
	kd_callback_fn callback,
	void *context
)

Register a coprocessor for participation in tracing. The `callback` function will be called with the provided `context` when necessary, according to the `kd_callback_type`s. The positive core ID is returned on success, or -1 on failure.

functionkernel_debug_enter

void kernel_debug_enter(
	uint32_t coreid,
	uint32_t debugid,
	uint64_t timestamp,
	uintptr_t arg1,
	uintptr_t arg2,
	uintptr_t arg3,
	uintptr_t arg4,
	uintptr_t threadid
)

▾

claude-fable-5, 2026-08-23 · not from Apple sources · verified against xnu bsd/kern/kdebug.c

Emits a trace event on behalf of a coprocessor (IOP). coreid is the core ID returned by kdebug_register_coproc (or the legacy kernel_debug_register_callback); timestamp and threadid are supplied by the caller rather than sampled from the current CPU and thread. The event is dropped if tracing is disabled, coprocessor events are disabled (KDBG_DISABLE_COPROCS), coreid is out of range, or debugid is rejected by the current filters.

structkd_callback

size 24, align 8

kd_callback_fn	func
void *	context
char[8]	iop_name	name of IOP, NUL-terminated

typedefkd_callback_t

typedef struct kd_callback kd_callback_t

functionkernel_debug_register_callback

__kpi_deprecated("use kdebug_register_coproc instead")
int kernel_debug_register_callback(kd_callback_t callback)

deprecated

▾

claude-fable-5, 2026-08-23 · not from Apple sources · verified against xnu bsd/kern/kdebug.c

Deprecated; use kdebug_register_coproc instead. Registers a legacy coprocessor (IOP) tracing callback described by a kd_callback_t (function, context, and up to 8-character iop_name); an unusable name is replaced with "IOP-???". The callback is invoked with KD_CALLBACK_* reasons (trace enabled or disabled, sync flush, typefilter changed). Returns the core ID to pass to kernel_debug_enter.

macroKDBG_

#define KDBG_(f, x, a, b, c, d, n, ...) KDBG##n(f, x, a, b, c, d)

macroKDBG0

#define KDBG0(f, x, a, b, c, d) KERNEL_DEBUG_CONSTANT##f(x, 0, 0, 0, 0, 0)

macroKDBG1

#define KDBG1(f, x, a, b, c, d) KERNEL_DEBUG_CONSTANT##f(x, a, 0, 0, 0, 0)

macroKDBG2

#define KDBG2(f, x, a, b, c, d) KERNEL_DEBUG_CONSTANT##f(x, a, b, 0, 0, 0)

macroKDBG3

#define KDBG3(f, x, a, b, c, d) KERNEL_DEBUG_CONSTANT##f(x, a, b, c, 0, 0)

macroKDBG4

#define KDBG4(f, x, a, b, c, d) KERNEL_DEBUG_CONSTANT##f(x, a, b, c, d, 0)

macroKDBG_IMPROBABLE

#define KDBG_IMPROBABLE

variablekdebug_enable

extern unsigned int kdebug_enable

macroKDEBUG_LEVEL_NONE

The kernel debug configuration level. These values control which events are compiled in under different build configurations. Infer the supported kernel debug event level from config option. Use (KDEBUG_LEVEL >= KDEBUG_LEVEL_STANDARD) as a guard to protect unaudited debug code.

#define KDEBUG_LEVEL_NONE 0

macroKDEBUG_LEVEL_IST

#define KDEBUG_LEVEL_IST 1

macroKDEBUG_LEVEL_STANDARD

#define KDEBUG_LEVEL_STANDARD 2

macroKDEBUG_LEVEL_FULL

#define KDEBUG_LEVEL_FULL 3

macroKDEBUG_LEVEL

#define KDEBUG_LEVEL KDEBUG_LEVEL_STANDARD

macroKERNEL_DEBUG_CONSTANT_FILTERED

KERNEL_DEBUG_CONSTANT_FILTERED events are omitted from tracing unless they are explicitly requested in the typefilter. They are not emitted when tracing without a typefilter.

#define KERNEL_DEBUG_CONSTANT_FILTERED(x, a, b, c, d, ...) do {
	        if (KDBG_IMPROBABLE(kdebug_enable & ~KDEBUG_ENABLE_PPT)) {
	                kernel_debug_filtered((x), (uintptr_t)(a), (uintptr_t)(b),
	                        (uintptr_t)(c), (uintptr_t)(d));
	        }
	} while (0)

macroKERNEL_DEBUG_CONSTANT_RELEASE_NOPROCFILT

#define KERNEL_DEBUG_CONSTANT_RELEASE_NOPROCFILT(x, a, b, c, d, ...) do {
	        if (KDBG_IMPROBABLE(kdebug_enable & ~KDEBUG_ENABLE_PPT)) {
	                kernel_debug_flags((x), (uintptr_t)(a), (uintptr_t)(b),
	                        (uintptr_t)(c), (uintptr_t)(d), KDBG_NON_PROCESS);
	        }
	} while (0)

macroKERNEL_DEBUG_CONSTANT

#define KERNEL_DEBUG_CONSTANT(x, a, b, c, d, e) do {
	        if (KDBG_IMPROBABLE(kdebug_enable & ~KDEBUG_ENABLE_PPT)) {
	                kernel_debug((x), (uintptr_t)(a), (uintptr_t)(b), (uintptr_t)(c),
	                        (uintptr_t)(d),(uintptr_t)(e));
	        }
	} while (0)

macroKERNEL_DEBUG_CONSTANT1

DO NOT USE THIS MACRO -- it breaks fundamental assumptions about ktrace and is only meant to be used by the pthread kext and other points in the kernel where the thread ID must be provided explicitly.

#define KERNEL_DEBUG_CONSTANT1(x, a, b, c, d, e) do {
	        if (KDBG_IMPROBABLE(kdebug_enable & ~KDEBUG_ENABLE_PPT)) {
	                kernel_debug1((x), (uintptr_t)(a), (uintptr_t)(b), (uintptr_t)(c),
	                (uintptr_t)(d), (uintptr_t)(e));
	        }
	} while (0)

macroKERNEL_DEBUG_CONSTANT_RELEASE

KERNEL_DEBUG_CONSTANT_IST (in-system trace) events provide an audited subset of tracepoints for userland system tracing tools. This tracing level was created by 8857227 to protect fairplayd and other PT_DENY_ATTACH processes. It has two effects: only KERNEL_DEBUG_CONSTANT_IST() traces are emitted and any PT_DENY_ATTACH processes will only emit basic traces as defined by the kernel_debug_filter() routine.

#define KERNEL_DEBUG_CONSTANT_RELEASE(x, a, b, c, d, e) KERNEL_DEBUG_CONSTANT_IST(~KDEBUG_ENABLE_PPT, x, a, b, c, d, 0)

macroKERNEL_DEBUG_CONSTANT_IST

#define KERNEL_DEBUG_CONSTANT_IST(type, x, a, b, c, d, e) do {
	        if (KDBG_IMPROBABLE(kdebug_enable & (type))) {
	                kernel_debug((x), (uintptr_t)(a), (uintptr_t)(b), (uintptr_t)(c),
	                        (uintptr_t)(d), 0);
	        }
	} while (0)

macroKERNEL_DEBUG_CONSTANT_IST1

#define KERNEL_DEBUG_CONSTANT_IST1(x, a, b, c, d, e) do {
	        if (KDBG_IMPROBABLE(kdebug_enable)) {
	                kernel_debug1((x), (uintptr_t)(a), (uintptr_t)(b), (uintptr_t)(c),
	                        (uintptr_t)(d), (uintptr_t)(e));
	        }
	} while (0)

macroKERNEL_DEBUG_EARLY

#define KERNEL_DEBUG_EARLY(x, a, b, c, d) do {
	        kernel_debug_early((uint32_t)(x), (uintptr_t)(a), (uintptr_t)(b),
	                (uintptr_t)(c), (uintptr_t)(d));
	} while (0)

macroKERNEL_DEBUG_CONSTANT_DEBUG

KERNEL_DEBUG events are only traced for DEBUG kernels.

#define KERNEL_DEBUG_CONSTANT_DEBUG(x, a, b, c, d, e) KERNEL_DEBUG(x, a, b, c, d, e)

macroKERNEL_DEBUG

#define KERNEL_DEBUG(x, a, b, c, d, e) do {} while (0)

macroKERNEL_DEBUG1

#define KERNEL_DEBUG1(x, a, b, c, d, e) do {} while (0)

functionkernel_debug

void kernel_debug(
	uint32_t debugid,
	uintptr_t arg1,
	uintptr_t arg2,
	uintptr_t arg3,
	uintptr_t arg4,
	uintptr_t arg5
)

▾

claude-fable-5, 2026-08-23 · not from Apple sources · verified against xnu bsd/kern/kdebug.c

Records a kdebug trace event. debugid identifies the tracepoint (class, subclass, code, and function qualifier); arg1 through arg4 are the event payload; the fifth recorded value is the current thread's ID, and arg5 is ignored. The event is dropped unless kdebug tracing is enabled and debugid passes the current filters. Backs the KERNEL_DEBUG and KDBG family of macros, which compile out at lower trace levels and are normally used instead of calling this directly.

functionkernel_debug1

void kernel_debug1(
	uint32_t debugid,
	uintptr_t arg1,
	uintptr_t arg2,
	uintptr_t arg3,
	uintptr_t arg4,
	uintptr_t arg5
)

▾

claude-fable-5, 2026-08-23 · not from Apple sources · verified against xnu bsd/kern/kdebug.c

As kernel_debug, but records the caller-supplied arg5 as the event's fifth value instead of the current thread's ID. Backs the KERNEL_DEBUG1 macro.

enumkdebug_emit_flags_t

underlying type uint64_t

KDBG_FILTER_ONLY	1
KDBG_NON_PROCESS	2

typedefkdebug_emit_flags_t

typedef enum kdebug_emit_flags_t kdebug_emit_flags_t;

functionkernel_debug_flags

void kernel_debug_flags(
	uint32_t debugid,
	uintptr_t arg1,
	uintptr_t arg2,
	uintptr_t arg3,
	uintptr_t arg4,
	kdebug_emit_flags_t flags
)

▾

claude-fable-5, 2026-08-23 · not from Apple sources · verified against xnu bsd/kern/kdebug.c

As kernel_debug (the current thread's ID is recorded as the fifth value), with emit flags controlling filtering: KDBG_FILTER_ONLY drop the event when tracing without a typefilter KDBG_NON_PROCESS do not subject the event to the per-process filter

functionkernel_debug_filtered

void kernel_debug_filtered(
	uint32_t debugid,
	uintptr_t arg1,
	uintptr_t arg2,
	uintptr_t arg3,
	uintptr_t arg4
)

▾

claude-fable-5, 2026-08-23 · not from Apple sources · verified against xnu bsd/kern/kdebug.c

Equivalent to kernel_debug_flags with KDBG_FILTER_ONLY: the event is recorded only when a typefilter is in effect and enables debugid, and is omitted from unfiltered traces. Intended for high-rate events; corresponds to the KDBG_FILTERED macro.