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