NAME
kernhist —
basic low-level kernel
history tracing mechanism
SYNOPSIS
options KERNHIST
#include <sys/kernhist.h>
Below are the functions and macros provided by kernhist.h:
KERNHIST_DECL(
name);
KERNHIST_DEFINE(
name);
KERNHIST_INIT(
name,
unsigned num_entries);
KERNHIST_INITIALIZER(
name,
void *buffer);
KERNHIST_INIT_STATIC(
struct
kern_history name,
void
*buffer);
KERNHIST_LOG(
struct
kern_history name,
const
char *fmt,
u_long
arg0,
u_long arg1,
u_long arg2,
u_long arg3);
KERNHIST_CALLARGS(
struct
kern_history name,
const
char *fmt,
u_long
arg0,
u_long arg1,
u_long arg2,
u_long arg3);
KERNHIST_CALLED(
struct
kern_history name);
KERNHIST_FUNC(
fname);
KERNHIST_DUMP(
struct
kern_history name);
void
kernhist_dump(
struct
kern_history *history);
void
kernhist_dumpmask(
u_int32_t
bitmask);
void
kernhist_print(
void
(*pr)(const char *, ...));
DESCRIPTION
The
kernhist facility provides a very low-level tracing
facility that can be called extremely early in the kernel initialisation. It
provides a simple restricted
printf(3) format syntax with a
maximum of 4 arguments, each of type
uintmax_t.
options KERNHIST must be present in the kernel configuration
to enable these functions and macros.
A kernel history is a fixed-size buffer,either statically or dynamically
allocated, that is written and read on a circular basis. Each entry includes
the time the entry was made, the CPU from which the entry was recorded, the
printf(3) like format string and
length, the function name and length, the unique call count for this function,
and the 4 arguments.
The history event data can be viewed using the
-U and
-u histname options to
vmstat(1), or by using the
show kernhist command in
ddb(4). User-written programs can
retrieve history data from the kernel using the
sysctl(9) variable
kern.hist.histname.
The format string must be a literal string that can be referenced later as it is
not stored with the event (only a pointer to the format string is stored). It
should only contain conversion specifiers suitable for
uintmax_t sized values, such as “%jx”,
“%ju”, and “%jo”, and address (pointer) arguments
should be cast to
uintptr_t to avoid compiler errors on
architectures where pointers are smaller than
uintmax_t
integers. Conversion specifiers without a length modifier, and specifiers with
length modifiers other than j, should not be used.
Conversion specifiers that require additional dereferences of their
corresponding arguments, such as “%s”, will not work in
vmstat(1), but will work when
called from
ddb(4).
These macros provide access to most kernel history functionality:
-
-
- KERNHIST_DECL(name)
- Declare an extern struct kern_history
name.
-
-
- KERNHIST_DEFINE(name)
- Define a struct kern_history
name.
-
-
- KERNHIST_INIT(name,
num_entries)
- Dynamically initialise a kernel history called name with
num_entries entries.
-
-
- KERNHIST_INITIALIZER(name,
buffer)
- Initialise a statically defined kernel history called
name using buffer as a static
allocation used for the buffer.
-
-
- KERNHIST_INIT_STATIC(name,
buffer)
- Initialise a statically declared kernel history
name, using the statically allocated
buffer for history entries.
-
-
- KERNHIST_FUNC(fname)
- Declare necessary variables for kernhist
to be used this function. Callable only once per function.
-
-
- KERNHIST_LOG(name,
fmt, arg0,
arg1, arg2,
arg3)
- For the given kernel history name,
log the format string and arguments in the history as a unique event.
-
-
- KERNHIST_CALLED(name)
- Declare a function as being called. Either this or
KERNHIST_CALLARGS() must be used once, near the function
entry point, to maintain the number of times the function has been
called.
-
-
- KERNHIST_CALLARGS(name,
fmt, arg0,
arg1, arg2,
arg3)
- A combination of KERNHIST_CALLED() and
KERNHIST_LOG() that avoids having a
“called!” log message in addition to a message containing
normal arguments with a format string.
-
-
- KERNHIST_DUMP(name)
- Call kernhist_dump() on the named kernel
history.
-
-
- kernhist_dump(history)
- Dump the entire contents of the specified kernel
history.
-
-
- kernhist_dumpmask(bitmask)
- Used to dump a well known list of kernel histories. The
following histories and their respective value (as seen in
kernhist.h) are available:
-
-
- KERNHIST_UVMMAPHIST
- Include events from “maphist”.
-
-
- KERNHIST_UVMPDHIST
- Include events from “pdhist”.
-
-
- KERNHIST_UVMUBCHIST
- Include events from “ubchist”.
-
-
- KERNHIST_UVMLOANHIST
- Include events from “loanhist”.
-
-
- KERNHIST_USBHIST
- Include events from “usbhist”.
-
-
- KERNHIST_SCDEBUGHIST
- Include events from “scdebughist”.
-
-
- KERNHIST_BIOHIST
- Include events from “biohist”.
-
-
- kernhist_print(pr)
- Print all the kernel histories to the kernel message
buffer. The pr() argument is currently ignored.
CODE REFERENCES
The
kernhist functionality is implemented within the files
sys/sys/kernhist.h and
sys/kern/kern_history.c. The former file contains the
definitions of data structures used to export the
data via
the
sysctl(9) mechanism.
SEE ALSO
vmstat(1),
usbdi(9),
uvm(9)
HISTORY
A uvm-specific version of the
kernhist facility first appeared
in
NetBSD 1.4. The generalized version of
kernhist appeared in
NetBSD 6.0. The
sysctl(9) interface to
kernhist was introduced in
NetBSD
8.0.
AUTHORS
kernhist was originally written by
Charles D.
Cranor as part of the
uvm(9)
framework, under the name UVMHIST.
Matthew R. Green
generalized it into its current form to be available to non
uvm(9) frameworks.
Paul Goyette
<
pgoyette@NetBSD.org>
provided the
sysctl(9)
interface.
BUGS
The restriction against using “%s”
printf(3) specifier in format
strings could be reduced to literal strings (such as the table of system call
names) if
vmstat(1) was extended
to convert “%s” strings into user addresses after copying the
strings out.
KERNHIST_FUNC() could be converted to use __func__ always, as
all the callers already do.
The
kernhist_dumpmask() list of masks could be properly
published and made available, and as such this function may be removed in a
future release.
In addition to a statically-defined set of kernel histories, it would be
possible to allow modular code to register and unregister their own histories
dynamically, when a module is loaded or unloaded.
The
kernhist_print() function currently ignores its
pr argument.