213 lines
6.4 KiB
Groff
213 lines
6.4 KiB
Groff
.\" $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.
|