KERNHIST(9)            NetBSD 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 inte-
     gers.  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 cor-
     responding 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 argu-
           ments 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 contain-
           ing 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 his-
     tories dynamically, when a module is loaded or unloaded.

     The kernhist_print() function currently ignores its pr argument.

NetBSD 8.0                     October 25, 2017                     NetBSD 8.0

You can also request any man page by name and (optionally) by section:

Command: 
Section: 
Architecture: 
Collection: 
 

Use the DEFAULT collection to view manual pages for third-party software.


©1994 Man-cgi 1.15, Panagiotis Christias
©1996-2018 Modified for NetBSD by Kimmo Suominen