feat: Added NetBSD man pages

1 files changed, 286 insertions, 0 deletions

diff --git a/static/netbsd/man9/kernhist.9 b/static/netbsd/man9/kernhist.9
new file mode 100644
index 00000000..6ee93408
--- /dev/null
+++ b/static/netbsd/man9/kernhist.9
@@ -0,0 +1,286 @@
+.\"	$NetBSD: kernhist.9,v 1.10 2021/12/11 19:24:19 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.
+.\"
+.\" 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.