.\"	$NetBSD: kernhist.9,v 1.4 2015/10/29 00:32:55 mrg 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 28, 2015
.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.
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.
.Pp
.Cd options KERNHIST
must be present in the kernel configuration to enable these functions and
macros.
.Pp
Arguments that require additional dereferences, such as
.Dq %s ,
will not work in
.Xr vmstat 1 ,
but will when called from
.Xr ddb 4 .
.Pp
A kernel history is a fixed-size buffer of an either statically or dynamically
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
.Xr printf 3
like format and length, the function name and length, the unique call count
for this function, and the 4 argumnts.
.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 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 near the function entry point.
.It Fn KERNHIST_CALLARGS name fmt arg0 arg1 arg2 arg3
A frontend to
.Fn KERNHIST_LOG
that avoids that
.Dq called!
log message in addition to normal arguments.
.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
.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 .
.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 SEE ALSO
.Xr vmstat 1 ,
.Xr usbdi 9 ,
.Xr uvm 9
.\" .Sh EXAMPLES
.\"
.\" add example here of code usage
.\"
.Sh HISTORY
.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
generalised it into its current form to be available to non
.Xr uvm 9
frameworks.
.Sh BUGS
The restriction about using
.Dq %s
.Xr printf 3
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
The
.Fn kernhist_print
function currently ignores its
.Fa pr
argument.