| KERNHIST(9) | Kernel Developer's Manual | KERNHIST(9) | 
kernhist —
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 *, ...));
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)KERNHIST_DEFINE(name)KERNHIST_INIT(name,
    num_entries)KERNHIST_INITIALIZER(name,
    buffer)KERNHIST_INIT_STATIC(name,
    buffer)KERNHIST_FUNC(fname)kernhist to be
      used this function. Callable only once per function.KERNHIST_LOG(name,
    fmt, arg0,
    arg1, arg2,
    arg3)KERNHIST_CALLED(name)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)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)kernhist_dump() on the named kernel
    history.kernhist_dump(history)kernhist_dumpmask(bitmask)kernhist_print(pr)pr() argument is currently ignored.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.
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.
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.
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 10.0 |