1.\" $NetBSD: kernhist.9,v 1.4 2015/10/29 00:32:55 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.\" 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 28, 2015 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. 67The format must be a literal string that can be referenced later as it 68is not stored with the event, only a pointer to it. 69.Pp 70.Cd options KERNHIST 71must be present in the kernel configuration to enable these functions and 72macros. 73.Pp 74Arguments that require additional dereferences, such as 75.Dq %s , 76will not work in 77.Xr vmstat 1 , 78but will when called from 79.Xr ddb 4 . 80.Pp 81A kernel history is a fixed-size buffer of an either statically or dynamically 82allocated buffer that is used and read in a cycled basis. 83It includes the time an entry was made, the CPU that the entry was recorded 84from, the 85.Xr printf 3 86like format and length, the function name and length, the unique call count 87for this function, and the 4 argumnts. 88.Pp 89These macros provide access to most kernel history functionality: 90.Bl -tag -width 4n 91.It Fn KERNHIST_DECL name 92Declare an extern struct kern_history 93.Fa name . 94.It Fn KERNHIST_DEFINE name 95Define a struct kern_history 96.Fa name . 97.It Fn KERNHIST_INIT name num_entries 98Dynamically initialise a kernel history called name with 99.Ar num_entries 100entries. 101.It Fn KERNHIST_INITIALIZER name buffer 102Initialise a statically defined kernel history called 103.Fa name 104using 105.Fa buffer 106as a static allocation used for the buffer. 107.It Fn KERNHIST_INIT_STATIC name buffer 108Initialise a statically declared kernel history 109.Fa name , 110using the statically allocated 111.Fa buffer 112for history entries. 113.It Fn KERNHIST_FUNC fname 114Declare necessary variables for 115.Nm 116to be used this function. 117Callable only once per function. 118.It Fn KERNHIST_LOG name fmt arg0 arg1 arg2 arg3 119For the given kernel history 120.Fa name , 121log the format and arguments in the history as a unique event. 122.It Fn KERNHIST_CALLED name 123Declare a function as being called. 124Either this or 125.Fn KERNHIST_CALLARGS 126must be used near the function entry point. 127.It Fn KERNHIST_CALLARGS name fmt arg0 arg1 arg2 arg3 128A frontend to 129.Fn KERNHIST_LOG 130that avoids that 131.Dq called! 132log message in addition to normal arguments. 133.It Fn KERNHIST_DUMP name 134Call 135.Fn kernhist_dump 136on the named kernel history. 137.It Fn kernhist_dump history 138Dump the entire contents of the specified kernel history. 139.It Fn kernhist_dumpmask bitmask 140Used to dump a well known list of kernel histories. 141The following histories and their respective value (as seen in 142.Pa kernhist.h ) 143are available: 144.Bl -tag 145.It KERNHIST_UVMMAPHIST 146Include events from 147.Dq maphist . 148.It KERNHIST_UVMPDHIST 149Include events from 150.Dq pdhist . 151.It KERNHIST_UVMUBCHIST 152Include events from 153.Dq ubchist . 154.It KERNHIST_UVMLOANHIST 155Include events from 156.Dq loanhist . 157.It KERNHIST_USBHIST 158Include events from 159.Dq usbhist . 160.It KERNHIST_SCDEBUGHIST 161Include events from 162.Dq scdebughist . 163.El 164.It Fn kernhist_print pr 165Print all the kernel histories to the kernel message buffer. 166The 167.Fn pr 168argument is currently ignored. 169.El 170.Sh SEE ALSO 171.Xr vmstat 1 , 172.Xr usbdi 9 , 173.Xr uvm 9 174.\" .Sh EXAMPLES 175.\" 176.\" add example here of code usage 177.\" 178.Sh HISTORY 179.Nm 180was originally written by 181.An Charles D. Cranor 182as part of the 183.Xr uvm 9 184framework, under the name UVMHIST. 185.An Matthew R. Green 186generalised it into its current form to be available to non 187.Xr uvm 9 188frameworks. 189.Sh BUGS 190The restriction about using 191.Dq %s 192.Xr printf 3 193format strings could be reduced to literal strings (such as the table of 194system call names) if 195.Xr vmstat 1 196was extended to convert 197.Dq %s 198strings into user addresses after copying the strings out. 199.Pp 200.Fn KERNHIST_FUNC 201could be converted to use __func__ always, as all the callers already do. 202.Pp 203The 204.Fn kernhist_dumpmask 205list of masks could be properly published and made available, and as such 206this function may be removed in a future release. 207.Pp 208The 209.Fn kernhist_print 210function currently ignores its 211.Fa pr 212argument. 213