.\"	$NetBSD: kernhist.9,v 1.9 2017/11/01 23:00:05 wiz Exp $
.\"
.\" Copyright (c) 2015 Matthew R. Green
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 3. The name of the author may not be used to endorse or promote products
.\"    derived from this software without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
.\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
.\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.Dd October 25, 2017
.Dt KERNHIST 9
.Os
.Sh NAME
.Nm kernhist
.Nd basic low-level kernel history tracing mechanism
.Sh SYNOPSIS
.Cd options KERNHIST
.In sys/kernhist.h
.Pp
Below are the functions and macros provided by kernhist.h:
.Pp
.Fn KERNHIST_DECL "name"
.Fn KERNHIST_DEFINE "name"
.Fn KERNHIST_INIT "name" "unsigned num_entries"
.Fn KERNHIST_INITIALIZER "name" "void *buffer"
.Fn KERNHIST_INIT_STATIC "struct kern_history name" "void *buffer"
.Fn KERNHIST_LOG "struct kern_history name" "const char *fmt" "u_long arg0" \
 "u_long arg1" "u_long arg2" "u_long arg3"
.Fn KERNHIST_CALLARGS "struct kern_history name" "const char *fmt" \
 "u_long arg0" "u_long arg1" "u_long arg2" "u_long arg3"
.Fn KERNHIST_CALLED "struct kern_history name"
.Fn KERNHIST_FUNC "fname"
.Fn KERNHIST_DUMP "struct kern_history name"
.Ft void
.Fn kernhist_dump "struct kern_history *history"
.Ft void
.Fn kernhist_dumpmask "u_int32_t bitmask"
.Ft void
.Fn kernhist_print "void (*pr)(const char *, ...)"
.Sh DESCRIPTION
The
.Nm
facility provides a very low-level tracing facility that can be called
extremely early in the kernel initialisation.
It provides a simple restricted
.Xr printf 3
format syntax with a maximum of 4 arguments, each of type
.Vt uintmax_t .
.Pp
.Cd options KERNHIST
must be present in the kernel configuration to enable these functions and
macros.
.Pp
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
.Xr printf 3
like format string and length, the function name and length, the unique call
count for this function, and the 4 arguments.
.Pp
The history event data can be viewed using the
.Fl U
and
.Fl u
.Ar histname
options to
.Xr vmstat 1 ,
or by using the
.Ic show kernhist
command in
.Xr ddb 4 .
User-written programs can retrieve history data from the kernel using the
.Xr sysctl 9
variable kern.hist.histname.
.Pp
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
.Vt uintmax_t
sized values, such as
.Dq %jx ,
.Dq %ju ,
and
.Dq %jo ,
and address (pointer) arguments should be cast to
.Vt uintptr_t
to avoid compiler errors on architectures where pointers are smaller than
.Vt uintmax_t
integers.
Conversion specifiers without a length modifier, and specifiers with length
modifiers other than j, should not be used.
.Pp
Conversion specifiers that require additional dereferences of their
corresponding arguments, such as
.Dq %s ,
will not work in
.Xr vmstat 1 ,
but will work when called from
.Xr ddb 4 .
.Pp
These macros provide access to most kernel history functionality:
.Bl -tag -width 4n
.It Fn KERNHIST_DECL name
Declare an extern struct kern_history
.Fa name .
.It Fn KERNHIST_DEFINE name
Define a struct kern_history
.Fa name .
.It Fn KERNHIST_INIT name num_entries
Dynamically initialise a kernel history called name with
.Ar num_entries
entries.
.It Fn KERNHIST_INITIALIZER name buffer
Initialise a statically defined kernel history called
.Fa name
using
.Fa buffer
as a static allocation used for the buffer.
.It Fn KERNHIST_INIT_STATIC name buffer
Initialise a statically declared kernel history
.Fa name ,
using the statically allocated
.Fa buffer
for history entries.
.It Fn KERNHIST_FUNC fname
Declare necessary variables for
.Nm
to be used this function.
Callable only once per function.
.It Fn KERNHIST_LOG name fmt arg0 arg1 arg2 arg3
For the given kernel history
.Fa name ,
log the format string and arguments in the history as a unique event.
.It Fn KERNHIST_CALLED name
Declare a function as being called.
Either this or
.Fn KERNHIST_CALLARGS
must be used once, near the function entry point, to maintain the number of
times the function has been called.
.It Fn KERNHIST_CALLARGS name fmt arg0 arg1 arg2 arg3
A combination of
.Fn KERNHIST_CALLED
and
.Fn KERNHIST_LOG
that avoids having a
.Dq called!
log message in addition to a message containing normal arguments with a
format string.
.It Fn KERNHIST_DUMP name
Call
.Fn kernhist_dump
on the named kernel history.
.It Fn kernhist_dump history
Dump the entire contents of the specified kernel history.
.It Fn kernhist_dumpmask bitmask
Used to dump a well known list of kernel histories.
The following histories and their respective value (as seen in
.Pa kernhist.h )
are available:
.Bl -tag -width KERNHIST_SCDEBUGHISTXXX
.It KERNHIST_UVMMAPHIST
Include events from
.Dq maphist .
.It KERNHIST_UVMPDHIST
Include events from
.Dq pdhist .
.It KERNHIST_UVMUBCHIST
Include events from
.Dq ubchist .
.It KERNHIST_UVMLOANHIST
Include events from
.Dq loanhist .
.It KERNHIST_USBHIST
Include events from
.Dq usbhist .
.It KERNHIST_SCDEBUGHIST
Include events from
.Dq scdebughist .
.It KERNHIST_BIOHIST
Include events from
.Dq biohist .
.El
.It Fn kernhist_print pr
Print all the kernel histories to the kernel message buffer.
The
.Fn pr
argument is currently ignored.
.El
.Sh CODE REFERENCES
The
.Nm
functionality is implemented within the files
.Pa sys/sys/kernhist.h
and
.Pa sys/kern/kern_history.c .
The former file contains the definitions of data structures used to export
the
.Nm data
via the
.Xr sysctl 9
mechanism.
.Sh SEE ALSO
.Xr vmstat 1 ,
.Xr usbdi 9 ,
.Xr uvm 9
.\" .Sh EXAMPLES
.\"
.\" add example here of code usage
.\"
.Sh HISTORY
A uvm-specific version of the
.Nm
facility first appeared in
.Nx 1.4 .
The generalized version of
.Nm
appeared in
.Nx 6.0 .
The
.Xr sysctl 9
interface to
.Nm
was introduced in
.Nx 8.0 .
.Sh AUTHORS
.An -nosplit
.Nm
was originally written by
.An Charles D. Cranor
as part of the
.Xr uvm 9
framework, under the name UVMHIST.
.An Matthew R. Green
generalized it into its current form to be available to non
.Xr uvm 9
frameworks.
.An Paul Goyette Aq Mt pgoyette@NetBSD.org
provided the
.Xr sysctl 9
interface.
.Sh BUGS
The restriction against using
.Dq %s
.Xr printf 3
specifier in format strings could be reduced to literal strings (such as
the table of system call names) if
.Xr vmstat 1
was extended to convert
.Dq %s
strings into user addresses after copying the strings out.
.Pp
.Fn KERNHIST_FUNC
could be converted to use __func__ always, as all the callers already do.
.Pp
The
.Fn kernhist_dumpmask
list of masks could be properly published and made available, and as such
this function may be removed in a future release.
.Pp
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.
.Pp
The
.Fn kernhist_print
function currently ignores its
.Fa pr
argument.