Module Name: src
Committed By: mrg
Date: Mon Oct 26 07:07:36 UTC 2015
Modified Files:
src/distrib/sets/lists/comp: mi
src/share/man/man9: Makefile
Added Files:
src/share/man/man9: kernhist.9
Log Message:
add documentation on "options KERNHIST".
To generate a diff of this commit:
cvs rdiff -u -r1.1998 -r1.1999 src/distrib/sets/lists/comp/mi
cvs rdiff -u -r1.392 -r1.393 src/share/man/man9/Makefile
cvs rdiff -u -r0 -r1.1 src/share/man/man9/kernhist.9
Please note that diffs are not public domain; they are subject to the
copyright notices on the relevant files.
Modified files:
Index: src/distrib/sets/lists/comp/mi
diff -u src/distrib/sets/lists/comp/mi:1.1998 src/distrib/sets/lists/comp/mi:1.1999
--- src/distrib/sets/lists/comp/mi:1.1998 Wed Oct 14 15:20:44 2015
+++ src/distrib/sets/lists/comp/mi Mon Oct 26 07:07:36 2015
@@ -1,4 +1,4 @@
-# $NetBSD: mi,v 1.1998 2015/10/14 15:20:44 christos Exp $
+# $NetBSD: mi,v 1.1999 2015/10/26 07:07:36 mrg Exp $
#
# Note: don't delete entries from here - mark them as "obsolete" instead.
./etc/mtree/set.comp comp-sys-root
@@ -10055,6 +10055,7 @@
./usr/share/man/cat9/kcpuset_use.0 comp-sys-catman .cat
./usr/share/man/cat9/kcpuset_zero.0 comp-sys-catman .cat
./usr/share/man/cat9/kernacc.0 comp-obsolete obsolete
+./usr/share/man/cat9/kernhist.0 comp-sys-catman .cat
./usr/share/man/cat9/kfilter_register.0 comp-sys-catman .cat
./usr/share/man/cat9/kfilter_unregister.0 comp-sys-catman .cat
./usr/share/man/cat9/killproc.0 comp-sys-catman .cat
@@ -16877,6 +16878,7 @@
./usr/share/man/html9/kcpuset_unuse.html comp-sys-htmlman html
./usr/share/man/html9/kcpuset_use.html comp-sys-htmlman html
./usr/share/man/html9/kcpuset_zero.html comp-sys-htmlman html
+./usr/share/man/html9/kernhist.html comp-sys-htmlman html
./usr/share/man/html9/kfilter_register.html comp-sys-htmlman html
./usr/share/man/html9/kfilter_unregister.html comp-sys-htmlman html
./usr/share/man/html9/killproc.html comp-sys-htmlman html
@@ -23853,6 +23855,7 @@
./usr/share/man/man9/kcpuset_use.9 comp-sys-man .man
./usr/share/man/man9/kcpuset_zero.9 comp-sys-man .man
./usr/share/man/man9/kernacc.9 comp-obsolete obsolete
+./usr/share/man/man9/kernhist.9 comp-sys-man .man
./usr/share/man/man9/kfilter_register.9 comp-sys-man .man
./usr/share/man/man9/kfilter_unregister.9 comp-sys-man .man
./usr/share/man/man9/killproc.9 comp-sys-man .man
Index: src/share/man/man9/Makefile
diff -u src/share/man/man9/Makefile:1.392 src/share/man/man9/Makefile:1.393
--- src/share/man/man9/Makefile:1.392 Fri Oct 2 05:22:49 2015
+++ src/share/man/man9/Makefile Mon Oct 26 07:07:36 2015
@@ -1,4 +1,4 @@
-# $NetBSD: Makefile,v 1.392 2015/10/02 05:22:49 msaitoh Exp $
+# $NetBSD: Makefile,v 1.393 2015/10/26 07:07:36 mrg Exp $
# Makefile for section 9 (kernel function and variable) manual pages.
@@ -29,7 +29,7 @@ MAN= accept_filter.9 accf_data.9 accf_ht
in_getifa.9 \
in4_cksum.9 inittodr.9 interrupt_distribute.9 intro.9 ioasic.9 \
ioctl.9 ipkdb.9 ipi.9 isa.9 isapnp.9 itimerfix.9 kauth.9 kcopy.9 \
- kcpuset.9 kmem.9 kpause.9 \
+ kcpuset.9 kernhist.9 kmem.9 kpause.9 \
kfilter_register.9 knote.9 \
kprintf.9 kthread.9 linedisc.9 lock.9 log.9 ltsleep.9 \
LWP_CACHE_CREDS.9 \
Added files:
Index: src/share/man/man9/kernhist.9
diff -u /dev/null src/share/man/man9/kernhist.9:1.1
--- /dev/null Mon Oct 26 07:07:36 2015
+++ src/share/man/man9/kernhist.9 Mon Oct 26 07:07:36 2015
@@ -0,0 +1,195 @@
+.\" $NetBSD: kernhist.9,v 1.1 2015/10/26 07:07:36 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 25, 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 9 .
+.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
+Declares an extern struct kern_history
+.Fa name .
+.It Fn KERNHIST_DEFINE name
+Defines a struct kern_history
+.Fa name .
+.It Fn KERNHIST_INIT name num_entries
+Dynamically initialise a kernel history called name with
+.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
+Declares 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
+Declares 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
+Calls
+.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.
+Currently only the 4
+.Xr uvm 9
+histories,
+.Va maphist ,
+.Va pdhist ,
+.Va ubchist ,
+and
+.Va loanhist
+are available via this mechanism.
+.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 usb 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.
