xref: /xnu-12377.61.12/bsd/sys/kdebug_kernel.h (revision 4d495c6e23c53686cf65f45067f79024cf5dcee8)

/*
 * Copyright (c) 2000-2018 Apple Inc. All rights reserved.
 *
 * @APPLE_OSREFERENCE_LICENSE_HEADER_START@
 *
 * This file contains Original Code and/or Modifications of Original Code
 * as defined in and that are subject to the Apple Public Source License
 * Version 2.0 (the 'License'). You may not use this file except in
 * compliance with the License. The rights granted to you under the License
 * may not be used to create, or enable the creation or redistribution of,
 * unlawful or unlicensed copies of an Apple operating system, or to
 * circumvent, violate, or enable the circumvention or violation of, any
 * terms of an Apple operating system software license agreement.
 *
 * Please obtain a copy of the License at
 * http://www.opensource.apple.com/apsl/ and read it before using this file.
 *
 * The Original Code and all software distributed under the License are
 * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
 * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
 * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
 * Please see the License for the specific language governing rights and
 * limitations under the License.
 *
 * @APPLE_OSREFERENCE_LICENSE_HEADER_END@
 */

#ifndef BSD_SYS_KDEBUG_KERNEL_H
#define BSD_SYS_KDEBUG_KERNEL_H

#include <mach/boolean.h>
#include <mach/clock_types.h>
#include <stdbool.h>
#include <stdint.h>
#include <stddef.h>
#include <sys/cdefs.h>

__BEGIN_DECLS

#ifdef KERNEL

/*
 * To use kdebug in the kernel:
 *
 * #include <sys/kdebug_kernel.h>
 *
 * #define DBG_NETIPINIT NETDBG_CODE(DBG_NETIP, 1)
 *
 * void
 * ip_init(void)
 * {
 *     KDBG(DBG_NETIPINIT | DBG_FUNC_START, 1, 2, 3, 4);
 *     ...
 *     KDBG(DBG_NETIPINIT);
 *     ...
 *     KDBG(DBG_NETIPINIT | DBG_FUNC_END);
 * }
 */

#pragma mark - kernel tracepoints

/*
 * The KDBG{,_DEBUG,_RELEASE,_FILTERED} macros are the preferred method of
 * making tracepoints.
 *
 * Kernel pointers must be unslid or permuted using VM_KERNEL_UNSLIDE_OR_PERM.
 * Do not trace any sensitive data.
 */

/*
 * Traced on debug and development (and release macOS) kernels.
 */
#define KDBG(x, ...) KDBG_(, x, ## __VA_ARGS__, 4, 3, 2, 1, 0)

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

#ifdef KERNEL_PRIVATE

/*
 * Traced on debug and development (and release macOS) kernels, even if the
 * process filter would reject it.
 */
#define KDBG_RELEASE_NOPROCFILT(x, ...) \
	        KDBG_(_RELEASE_NOPROCFILT, x, ## __VA_ARGS__, 4, 3, 2, 1, 0)

#endif /* KERNEL_PRIVATE */

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

/*
 * Traced only on debug kernels.
 */
#define KDBG_DEBUG(x, ...) KDBG_(_DEBUG, x, ## __VA_ARGS__, 4, 3, 2, 1, 0)

#pragma mark - kernel API

#ifdef KERNEL_PRIVATE

/*
 * kernel_debug_string provides the same functionality as the
 * kdebug_trace_string syscall as a KPI.  str_id is an in/out
 * parameter that, if it's pointing to a string ID of 0, will
 * receive a generated ID.  If it provides a value in str_id,
 * then that will be used, instead.
 *
 * Returns an errno indicating the type of failure.
 */
int kernel_debug_string(uint32_t debugid, uint64_t *str_id, const char *str);

/*
 * kernel_debug_disable disables event logging, but leaves any buffers
 * intact.
 */
void kernel_debug_disable(void);

#endif /* KERNEL_PRIVATE */

/*
 * Returns true if kdebug is using continuous time for its events, and false
 * otherwise.
 */
bool kdebug_using_continuous_time(void);

/*
 * Convert an absolute time to a kdebug timestamp.
 */
extern uint64_t kdebug_timestamp_from_absolute(uint64_t abstime);

/*
 * Convert a continuous time to a kdebug timestamp.
 */
extern uint64_t kdebug_timestamp_from_continuous(uint64_t conttime);

/*
 * Capture a kdebug timestamp for the current time.
 */
extern uint64_t kdebug_timestamp(void);

/*
 * Returns true if kdebug will log an event with the provided debugid, and
 * false otherwise.
 */
bool kdebug_debugid_enabled(uint32_t debugid);

/*
 * Returns true only if the debugid is explicitly enabled by filters.  Returns
 * false otherwise, including when no filters are active.
 */
bool kdebug_debugid_explicitly_enabled(uint32_t debugid);

uint32_t kdebug_commpage_state(void);

#pragma mark - Coprocessor/IOP tracing

typedef enum {
	/* Trace is now enabled. */
	KD_CALLBACK_KDEBUG_ENABLED,
	/*
	 * Trace is being disabled, but events are still accepted for the duration
	 * of the callback.
	 */
	KD_CALLBACK_KDEBUG_DISABLED,
	/*
	 * 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_SYNC_FLUSH,
	/*
	 * The typefilter is being used.
	 *
	 * A read-only pointer to the typefilter is provided as the argument, valid
	 * only in the callback.
	 */
	KD_CALLBACK_TYPEFILTER_CHANGED,
	/*
	 * The coprocessor should emit data that snapshots the current state of the
	 * system.
	 */
	KD_CALLBACK_SNAPSHOT_STATE,
} kd_callback_type;

__options_decl(kdebug_coproc_flags_t, uint32_t, {
	/*
	 * Event timestamps from this coprocessor are in the continuous timebase.
	 */
	KDCP_CONTINUOUS_TIME = 0x001,
});

typedef void (*kd_callback_fn)(void *context, kd_callback_type reason,
    void *arg);

/*
 * 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.
 */
int kdebug_register_coproc(const char *name, kdebug_coproc_flags_t flags,
    kd_callback_fn callback, void *context);

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);

/*
 * Legacy definitions for the prior IOP tracing.
 */

struct kd_callback {
	kd_callback_fn func;
	void *context;
	/* name of IOP, NUL-terminated */
	char iop_name[8];
};
typedef struct kd_callback kd_callback_t;

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

#pragma mark - internals

#define KDBG_(f, x, a, b, c, d, n, ...) KDBG##n(f, x, a, b, c, d)
#define KDBG0(f, x, a, b, c, d) KERNEL_DEBUG_CONSTANT##f(x, 0, 0, 0, 0, 0)
#define KDBG1(f, x, a, b, c, d) KERNEL_DEBUG_CONSTANT##f(x, a, 0, 0, 0, 0)
#define KDBG2(f, x, a, b, c, d) KERNEL_DEBUG_CONSTANT##f(x, a, b, 0, 0, 0)
#define KDBG3(f, x, a, b, c, d) KERNEL_DEBUG_CONSTANT##f(x, a, b, c, 0, 0)
#define KDBG4(f, x, a, b, c, d) KERNEL_DEBUG_CONSTANT##f(x, a, b, c, d, 0)

#ifdef XNU_KERNEL_PRIVATE
#define KDBG_IMPROBABLE __improbable
#else
#define KDBG_IMPROBABLE
#endif

extern unsigned int kdebug_enable;

/*
 * 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
#define KDEBUG_LEVEL_IST      1
#define KDEBUG_LEVEL_STANDARD 2
#define KDEBUG_LEVEL_FULL     3

#if NO_KDEBUG
#define KDEBUG_LEVEL KDEBUG_LEVEL_NONE
#elif IST_KDEBUG
#define KDEBUG_LEVEL KDEBUG_LEVEL_IST
#elif KDEBUG
#define KDEBUG_LEVEL KDEBUG_LEVEL_FULL
#else
#define KDEBUG_LEVEL KDEBUG_LEVEL_STANDARD
/*
 * Currently, all other kernel configurations (development, etc) build with
 * KDEBUG_LEVEL_STANDARD.
 */
#endif

/*
 * 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.
 */
#if (KDEBUG_LEVEL >= KDEBUG_LEVEL_STANDARD)
#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)
#else /* (KDEBUG_LEVEL >= KDEBUG_LEVEL_STANDARD) */
#define KERNEL_DEBUG_CONSTANT_FILTERED(type, x, a, b, c, d, ...) do {} while (0)
#endif /* (KDEBUG_LEVEL >= KDEBUG_LEVEL_STANDARD) */

#if (KDEBUG_LEVEL >= KDEBUG_LEVEL_IST)
#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)
#else /* (KDEBUG_LEVEL >= KDEBUG_LEVEL_IST) */
#define KERNEL_DEBUG_CONSTANT_RELEASE_NOPROCFILT(x, a, b, c, d, ...) \
	do { } while (0)
#endif /* (KDEBUG_LEVEL >= KDEBUG_LEVEL_IST) */


#if (KDEBUG_LEVEL >= KDEBUG_LEVEL_STANDARD)
#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)

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

#else /* (KDEBUG_LEVEL >= KDEBUG_LEVEL_STANDARD) */
#define KERNEL_DEBUG_CONSTANT(x, a, b, c, d, e) do {} while (0)
#define KERNEL_DEBUG_CONSTANT1(x, a, b, c, d, e) do {} while (0)
#endif /* (KDEBUG_LEVEL >= KDEBUG_LEVEL_STANDARD) */

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

#if (KDEBUG_LEVEL >= KDEBUG_LEVEL_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)

#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)

#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)

#else /* (KDEBUG_LEVEL >= KDEBUG_LEVEL_IST) */
#define KERNEL_DEBUG_CONSTANT_IST(type, x, a, b, c, d, e) do {} while (0)
#define KERNEL_DEBUG_CONSTANT_IST1(x, a, b, c, d, e) do {} while (0)
#define KERNEL_DEBUG_EARLY(x, a, b, c, d) do {} while (0)
#endif /* (KDEBUG_LEVEL >= KDEBUG_LEVEL_IST) */

#if NO_KDEBUG
#define __kdebug_constant_only __unused
#endif

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

#if (KDEBUG_LEVEL >= KDEBUG_LEVEL_FULL)
#define __kdebug_only

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

/*
 * DO NOT USE THIS MACRO -- see warning above for KERNEL_DEBUG_CONSTANT1.
 */
#define KERNEL_DEBUG1(x, a, b, c, d, e)                                  \
	do {                                                                 \
	        if (KDBG_IMPROBABLE(kdebug_enable & ~KDEBUG_ENABLE_PPT)) {       \
	                kernel_debug1((uint32_t)(x), (uintptr_t)(a), (uintptr_t)(b), \
	                        (uintptr_t)(c), (uintptr_t)(d), (uintptr_t)(e));         \
	        }                                                                \
	} while (0)

#else /* (KDEBUG_LEVEL >= KDEBUG_LEVEL_FULL) */
#define __kdebug_only __unused

#undef KERNEL_DEBUG
#define KERNEL_DEBUG(x, a, b, c, d, e) do {} while (0)
#define KERNEL_DEBUG1(x, a, b, c, d, e) do {} while (0)
#endif /* (KDEBUG_LEVEL >= KDEBUG_LEVEL_FULL) */

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

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

__options_decl(kdebug_emit_flags_t, uint64_t, {
	KDBG_FILTER_ONLY = 0x01,
	KDBG_NON_PROCESS = 0x02,
});

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

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

#pragma mark - xnu API

#ifdef XNU_KERNEL_PRIVATE

void kdebug_startup(void);

/* Used in early boot to log events. */
void kernel_debug_early(uint32_t  debugid, uintptr_t arg1, uintptr_t arg2,
    uintptr_t arg3, uintptr_t arg4);
/* Used in early boot to log strings spanning only a single tracepoint. */
void kernel_debug_string_early(const char *message);
/* Used to trace strings within kdebug tracepoints on arbitrary eventids. */
void kernel_debug_string_simple(uint32_t eventid, const char *str);
/* Only used by ktrace to reset kdebug.  ktrace_lock must be held. */
extern void kdebug_reset(void);

void kdbg_dump_trace_to_file(const char *, bool reenable);

enum kdebug_opts {
	KDOPT_WRAPPING = 0x1,
	KDOPT_ATBOOT = 0x2,
};

enum kdebug_mode {
	KDEBUG_MODE_TRACE = 0x1, /* General purpose tracing.*/
	KDEBUG_MODE_TRIAGE = 0x2, /* Collect more information to triage failures / gain insight into in-kernel operations of a thread.*/
};


int kdbg_bootstrap(bool early_trace, int mode);
void kdebug_init(unsigned int n_events, char *filterdesc,
    enum kdebug_opts opts);
void kdebug_trace_start(unsigned int n_events, const char *filterdesc,
    enum kdebug_opts opts);
uint64_t kdebug_wake(void);
void kdebug_free_early_buf(void);


struct proc;
void kdbg_trace_data(struct proc *proc, long *arg_pid, long *arg_uniqueid);

__options_decl(kdebug_vfs_lookup_flags_t, uint32_t, {
	KDBG_VFSLKUP_LOOKUP = 0x01,
	KDBG_VFSLKUP_NOPROCFILT = 0x02,
});
#define KDBG_VFS_LOOKUP_FLAG_LOOKUP 0x01
#define KDBG_VFS_LOOKUP_FLAG_NOPROCFILT 0x02
void kdebug_vfs_lookup(const char *path_words, size_t path_len, void *vnp,
    kdebug_vfs_lookup_flags_t flags);

void ktriage_extract(uint64_t thread_id, void *buf, uint32_t bufsz);

#endif /* XNU_KERNEL_PRIVATE */

#ifdef KERNEL_PRIVATE

typedef struct ktriage_strings {
	int num_strings;
	const char **strings;
} ktriage_strings_t;

int ktriage_register_subsystem_strings(uint8_t subsystem, ktriage_strings_t *subsystem_strings);
int ktriage_unregister_subsystem_strings(uint8_t subsystem);

void ktriage_record(uint64_t thread_id, uint64_t debugid, uintptr_t arg);

#define NUMPARMS 23
void kdebug_lookup_gen_events(long *path_words, int path_len, void *vnp,
    bool lookup);

#pragma mark - EnergyTracing

#define KERNEL_DBG_IST_SANE KDBG_RELEASE
#define ENTR_KDTRACEFUNC KDBG_RELEASE

// value is int64_t, quality is uint32_t
#define KERNEL_ENERGYTRACE(opcode, lifespan, id, quality, value)        \
	    ENTR_KDTRACE(kEnTrCompKernel, opcode, lifespan, id,         \
	                 quality, value)
#define KERNEL_ENTR_ASSOCIATE(par_opcode, par_act_id, sub_opcode, sub_act_id) \
	    ENTR_KDASSOCIATE(kEnTrCompKernel, par_opcode, par_act_id,   \
	                     kEnTrCompKernel, sub_opcode, sub_act_id)

#endif /* KERNEL_PRIVATE */

#endif /* KERNEL */

__END_DECLS

#endif /* !defined(BSD_SYS_KDEBUG_KERNEL_H) */