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.
     The format must be a literal string that can be referenced later as it is
     not stored with the event, only a pointer to it.

     options KERNHIST must be present in the kernel configuration to enable
     these functions and macros.

     Arguments that require additional dereferences, such as ``%s'', will not
     work in vmstat(1), but will when called from ddb(4).

     A kernel history is a fixed-size buffer of an either statically or dynam-
     ically allocated buffer that is used and read in a cycled basis.  It
     includes the time an entry was made, the CPU that the entry was recorded
     from, the printf(3) like format and length, the function name and length,
     the unique call count for this function, and the 4 argumnts.

     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 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 near the function entry point.

     KERNHIST_CALLARGS(name, fmt, arg0, arg1, arg2, arg3)
           A frontend to KERNHIST_LOG() that avoids that ``called!'' log mes-
           sage in addition to normal arguments.

     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_print(pr)
           Print all the kernel histories to the kernel message buffer.  The
           pr() argument is currently ignored.

SEE ALSO
     vmstat(1), usbdi(9), uvm(9)

HISTORY
     kernhist was originally written by Charles D. Cranor as part of the
     uvm(9) framework, under the name UVMHIST.  Matthew R. Green generalised
     it into its current form to be available to non uvm(9) frameworks.

BUGS
     The restriction about using ``%s'' printf(3) 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.

     The kernhist_print() function currently ignores its pr argument.

NetBSD 8.0                     October 28, 2015                     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-2017 Modified for NetBSD by Kimmo Suominen