289 lines
8.1 KiB
Groff
289 lines
8.1 KiB
Groff
.\" $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.
|