KERNHIST(9) | Kernel Developer's Manual | KERNHIST(9)

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

October 25, 2017 | NetBSD 9.4