[src/trunk]: src add documentation on "options KERNHIST".

[mrg <mrg%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/73250893bf7b
branches:  trunk
changeset: 341206:73250893bf7b
user:      mrg <mrg%NetBSD.org@localhost>
date:      Mon Oct 26 07:07:36 2015 +0000

description:
add documentation on "options KERNHIST".

diffstat:

 distrib/sets/lists/comp/mi |    5 +-
 share/man/man9/Makefile    |    4 +-
 share/man/man9/kernhist.9  |  195 +++++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 201 insertions(+), 3 deletions(-)

diffs (250 lines):

diff -r 36cec661fabc -r 73250893bf7b distrib/sets/lists/comp/mi
--- a/distrib/sets/lists/comp/mi        Mon Oct 26 02:31:31 2015 +0000
+++ b/distrib/sets/lists/comp/mi        Mon Oct 26 07:07:36 2015 +0000
@@ -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
diff -r 36cec661fabc -r 73250893bf7b share/man/man9/Makefile
--- a/share/man/man9/Makefile   Mon Oct 26 02:31:31 2015 +0000
+++ b/share/man/man9/Makefile   Mon Oct 26 07:07:36 2015 +0000
@@ -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 @@
        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 \
diff -r 36cec661fabc -r 73250893bf7b share/man/man9/kernhist.9
--- /dev/null   Thu Jan 01 00:00:00 1970 +0000
+++ b/share/man/man9/kernhist.9 Mon Oct 26 07:07:36 2015 +0000
@@ -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.