1.\" $NetBSD: kernhist.9,v 1.9 2017/11/01 23:00:05 wiz Exp $ 2.\" 3.\" Copyright (c) 2015 Matthew R. Green 4.\" All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 3. The name of the author may not be used to endorse or promote products 15.\" derived from this software without specific prior written permission. 16.\" 17.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR 18.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 19.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 20.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, 21.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, 22.\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 23.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED 24.\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, 25.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 26.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 27.\" SUCH DAMAGE. 28.\" 29.Dd October 25, 2017 30.Dt KERNHIST 9 31.Os 32.Sh NAME 33.Nm kernhist 34.Nd basic low-level kernel history tracing mechanism 35.Sh SYNOPSIS 36.Cd options KERNHIST 37.In sys/kernhist.h 38.Pp 39Below are the functions and macros provided by kernhist.h: 40.Pp 41.Fn KERNHIST_DECL "name" 42.Fn KERNHIST_DEFINE "name" 43.Fn KERNHIST_INIT "name" "unsigned num_entries" 44.Fn KERNHIST_INITIALIZER "name" "void *buffer" 45.Fn KERNHIST_INIT_STATIC "struct kern_history name" "void *buffer" 46.Fn KERNHIST_LOG "struct kern_history name" "const char *fmt" "u_long arg0" \ 47 "u_long arg1" "u_long arg2" "u_long arg3" 48.Fn KERNHIST_CALLARGS "struct kern_history name" "const char *fmt" \ 49 "u_long arg0" "u_long arg1" "u_long arg2" "u_long arg3" 50.Fn KERNHIST_CALLED "struct kern_history name" 51.Fn KERNHIST_FUNC "fname" 52.Fn KERNHIST_DUMP "struct kern_history name" 53.Ft void 54.Fn kernhist_dump "struct kern_history *history" 55.Ft void 56.Fn kernhist_dumpmask "u_int32_t bitmask" 57.Ft void 58.Fn kernhist_print "void (*pr)(const char *, ...)" 59.Sh DESCRIPTION 60The 61.Nm 62facility provides a very low-level tracing facility that can be called 63extremely early in the kernel initialisation. 64It provides a simple restricted 65.Xr printf 3 66format syntax with a maximum of 4 arguments, each of type 67.Vt uintmax_t . 68.Pp 69.Cd options KERNHIST 70must be present in the kernel configuration to enable these functions and 71macros. 72.Pp 73A kernel history is a fixed-size buffer, either statically or dynamically 74allocated, that is written and read on a circular basis. 75Each entry includes the time the entry was made, the CPU from which the entry 76was recorded, the 77.Xr printf 3 78like format string and length, the function name and length, the unique call 79count for this function, and the 4 arguments. 80.Pp 81The history event data can be viewed using the 82.Fl U 83and 84.Fl u 85.Ar histname 86options to 87.Xr vmstat 1 , 88or by using the 89.Ic show kernhist 90command in 91.Xr ddb 4 . 92User-written programs can retrieve history data from the kernel using the 93.Xr sysctl 9 94variable kern.hist.histname. 95.Pp 96The format string must be a literal string that can be referenced later as it 97is not stored with the event (only a pointer to the format string is stored). 98It should only contain conversion specifiers suitable for 99.Vt uintmax_t 100sized values, such as 101.Dq %jx , 102.Dq %ju , 103and 104.Dq %jo , 105and address (pointer) arguments should be cast to 106.Vt uintptr_t 107to avoid compiler errors on architectures where pointers are smaller than 108.Vt uintmax_t 109integers. 110Conversion specifiers without a length modifier, and specifiers with length 111modifiers other than j, should not be used. 112.Pp 113Conversion specifiers that require additional dereferences of their 114corresponding arguments, such as 115.Dq %s , 116will not work in 117.Xr vmstat 1 , 118but will work when called from 119.Xr ddb 4 . 120.Pp 121These macros provide access to most kernel history functionality: 122.Bl -tag -width 4n 123.It Fn KERNHIST_DECL name 124Declare an extern struct kern_history 125.Fa name . 126.It Fn KERNHIST_DEFINE name 127Define a struct kern_history 128.Fa name . 129.It Fn KERNHIST_INIT name num_entries 130Dynamically initialise a kernel history called name with 131.Ar num_entries 132entries. 133.It Fn KERNHIST_INITIALIZER name buffer 134Initialise a statically defined kernel history called 135.Fa name 136using 137.Fa buffer 138as a static allocation used for the buffer. 139.It Fn KERNHIST_INIT_STATIC name buffer 140Initialise a statically declared kernel history 141.Fa name , 142using the statically allocated 143.Fa buffer 144for history entries. 145.It Fn KERNHIST_FUNC fname 146Declare necessary variables for 147.Nm 148to be used this function. 149Callable only once per function. 150.It Fn KERNHIST_LOG name fmt arg0 arg1 arg2 arg3 151For the given kernel history 152.Fa name , 153log the format string and arguments in the history as a unique event. 154.It Fn KERNHIST_CALLED name 155Declare a function as being called. 156Either this or 157.Fn KERNHIST_CALLARGS 158must be used once, near the function entry point, to maintain the number of 159times the function has been called. 160.It Fn KERNHIST_CALLARGS name fmt arg0 arg1 arg2 arg3 161A combination of 162.Fn KERNHIST_CALLED 163and 164.Fn KERNHIST_LOG 165that avoids having a 166.Dq called! 167log message in addition to a message containing normal arguments with a 168format string. 169.It Fn KERNHIST_DUMP name 170Call 171.Fn kernhist_dump 172on the named kernel history. 173.It Fn kernhist_dump history 174Dump the entire contents of the specified kernel history. 175.It Fn kernhist_dumpmask bitmask 176Used to dump a well known list of kernel histories. 177The following histories and their respective value (as seen in 178.Pa kernhist.h ) 179are available: 180.Bl -tag -width KERNHIST_SCDEBUGHISTXXX 181.It KERNHIST_UVMMAPHIST 182Include events from 183.Dq maphist . 184.It KERNHIST_UVMPDHIST 185Include events from 186.Dq pdhist . 187.It KERNHIST_UVMUBCHIST 188Include events from 189.Dq ubchist . 190.It KERNHIST_UVMLOANHIST 191Include events from 192.Dq loanhist . 193.It KERNHIST_USBHIST 194Include events from 195.Dq usbhist . 196.It KERNHIST_SCDEBUGHIST 197Include events from 198.Dq scdebughist . 199.It KERNHIST_BIOHIST 200Include events from 201.Dq biohist . 202.El 203.It Fn kernhist_print pr 204Print all the kernel histories to the kernel message buffer. 205The 206.Fn pr 207argument is currently ignored. 208.El 209.Sh CODE REFERENCES 210The 211.Nm 212functionality is implemented within the files 213.Pa sys/sys/kernhist.h 214and 215.Pa sys/kern/kern_history.c . 216The former file contains the definitions of data structures used to export 217the 218.Nm data 219via the 220.Xr sysctl 9 221mechanism. 222.Sh SEE ALSO 223.Xr vmstat 1 , 224.Xr usbdi 9 , 225.Xr uvm 9 226.\" .Sh EXAMPLES 227.\" 228.\" add example here of code usage 229.\" 230.Sh HISTORY 231A uvm-specific version of the 232.Nm 233facility first appeared in 234.Nx 1.4 . 235The generalized version of 236.Nm 237appeared in 238.Nx 6.0 . 239The 240.Xr sysctl 9 241interface to 242.Nm 243was introduced in 244.Nx 8.0 . 245.Sh AUTHORS 246.An -nosplit 247.Nm 248was originally written by 249.An Charles D. Cranor 250as part of the 251.Xr uvm 9 252framework, under the name UVMHIST. 253.An Matthew R. Green 254generalized it into its current form to be available to non 255.Xr uvm 9 256frameworks. 257.An Paul Goyette Aq Mt pgoyette@NetBSD.org 258provided the 259.Xr sysctl 9 260interface. 261.Sh BUGS 262The restriction against using 263.Dq %s 264.Xr printf 3 265specifier in format strings could be reduced to literal strings (such as 266the table of system call names) if 267.Xr vmstat 1 268was extended to convert 269.Dq %s 270strings into user addresses after copying the strings out. 271.Pp 272.Fn KERNHIST_FUNC 273could be converted to use __func__ always, as all the callers already do. 274.Pp 275The 276.Fn kernhist_dumpmask 277list of masks could be properly published and made available, and as such 278this function may be removed in a future release. 279.Pp 280In addition to a statically-defined set of kernel histories, it would be 281possible to allow modular code to register and unregister their own 282histories dynamically, when a module is loaded or unloaded. 283.Pp 284The 285.Fn kernhist_print 286function currently ignores its 287.Fa pr 288argument. 289