1.\" Copyright (c) 2001 John H. Baldwin <jhb@FreeBSD.org> 2.\" All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in the 11.\" documentation and/or other materials provided with the distribution. 12.\" 13.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 14.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 15.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 16.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 17.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 18.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 19.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 20.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 21.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 22.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 23.\" SUCH DAMAGE. 24.\" 25.\" $FreeBSD: src/share/man/man4/ktr.4,v 1.9 2003/09/08 19:57:19 ru Exp $ 26.\" 27.Dd August 13, 2011 28.Dt KTR 4 29.Os 30.Sh NAME 31.Nm ktr 32.Nd kernel tracing facility 33.Sh SYNOPSIS 34.Cd options KTR 35.Cd options KTR_ENTRIES=8192 36.Cd options KTR_VERBOSE=1 37.Cd options KTR_ALL 38.Cd options KTR_CTXSW 39.Cd options KTR_DMCRYPT 40.Cd options KTR_ETHERNET 41.\".Cd options KTR_HAMMER 42.Cd options KTR_IF_BGE 43.Cd options KTR_IF_EM 44.Cd options KTR_IF_EMX 45.Cd options KTR_IF_START 46.Cd options KTR_IFQ 47.Cd options KTR_IPIQ 48.Cd options KTR_KERNENTRY 49.Cd options KTR_MEMORY 50.Cd options KTR_POLLING 51.Cd options KTR_SERIALIZER 52.Cd options KTR_SPIN_CONTENTION 53.\".Cd options KTR_TCP 54.Cd options KTR_TESTLOG 55.Cd options KTR_TOKENS 56.Cd options KTR_TSLEEP 57.Cd options KTR_USB_MEMORY 58.Sh DESCRIPTION 59The 60.Nm 61facility allows kernel events to be logged while the kernel executes so that 62they can be examined later when debugging. 63The only mandatory option to enable 64.Nm 65is 66.Cd options KTR . 67.Pp 68The 69.Dv KTR_ENTRIES 70option sets the size of the buffer of events. 71It must be a power of two. 72The size of the buffer in the currently running kernel can be found via the 73read-only sysctl 74.Va debug.ktr.entries . 75By default the buffer contains 2048 entries. 76.Pp 77For debugging purposes, the following 78.Nm 79related kernel options exist: 80.Bl -tag -width ".Dv KTR_SPIN_CONTENTION" 81.It Dv KTR_ALL 82turns on all options 83.It Dv KTR_CTXSW 84context switches 85.It Dv KTR_DMCRYPT 86read and write strategy paths of 87.Xr dm 4 Ap s 88.Pa crypt 89target 90.It Dv KTR_ETHERNET 91cost of 92.Fn ether_input_chain 93and 94.Fn ether_input_dispatch 95.It Dv KTR_IF_BGE 96.Xr bge 4 97interrupts and sent/received packets 98.It Dv KTR_IF_EM 99.Xr em 4 100interrupts and sent/received packets 101.It Dv KTR_IF_EMX 102.Xr emx 4 103interrupts and sent/received packets 104.It Dv KTR_IFQ 105classic ifq dequeue/enqueue operation 106.It Dv KTR_IF_START 107running/avoiding/scheduling ifnet.if_start 108.It Dv KTR_IPIQ 109IPI related data (IPI requests, CPU synchronization etc.) 110.It Dv KTR_KERNENTRY 111entry of the kernel from userland (faults, syscalls) 112.It Dv KTR_MEMORY 113.Xr kmalloc 9 114and 115.Xr kfree 9 116events 117.It Dv KTR_POLLING 118.Xr polling 4 119begins and ends 120.It Dv KTR_SERIALIZER 121.Xr serializer 9 122related events 123.It Dv KTR_SPIN_CONTENTION 124.Xr spinlock 9 125contention 126.It Dv KTR_TESTLOG 127IPI performance testing 128.It Dv KTR_TOKENS 129LWKT token related events 130.It Dv KTR_TSLEEP 131.Xr tsleep 9 132and 133.Xr wakeup 9 134.It Dv KTR_USB_MEMORY 135USB memory allocation 136.El 137.Ss Verbose Mode 138By default, events are only logged to the internal buffer for examination 139later, but if the verbose flag is set then they are dumped to the kernel 140console as well. 141This flag can also be set from the loader via the 142.Va debug.ktr.verbose 143environment variable, or it can be examined and set after booting via the 144.Va debug.ktr.verbose 145sysctl. 146If the flag is set to zero, which is the default, then verbose output is 147disabled. 148If the flag is set to one, then the contents of the log message and the CPU 149number are printed to the kernel console. 150If the flag is greater than one, then the filename and line number of the 151event are output to the console in addition to the log message and the CPU 152number. 153The 154.Dv KTR_VERBOSE 155option enables verbose mode and sets the flag to one. 156.Ss Examining the Events 157The KTR buffer can be examined with 158.Xr ktrdump 8 , 159.Xr gdb 1 160or from within 161.Xr ddb 4 162via the 163.Ic show ktr Op Cm /v 164command. 165This command displays the contents of the trace buffer one page at a time. 166At the 167.Dq Li --more-- 168prompt, the Enter key displays one more entry and prompts again. 169The spacebar displays another page of entries. 170Any other key quits. 171By default the timestamp, filename, and line number are not displayed with 172each log entry. 173If the 174.Cm /v 175modifier is specified, then they are displayed in addition to the normal 176output. 177Note that the events are displayed in reverse chronological order. 178That is, the most recent events are displayed first. 179.Sh SYSCTL VARIABLES 180.Bl -tag -width ".Va debug.ktr.resynchronize" 181.It Va debug.ktr.*_enable 182A 32 bit mask used to control event logging. 183Each bit corresponds to one or more events depending on the values of the 184.Fa maskbit 185parameters that were passed to the 186.Xr KTR_INFO 9 187calls which declared the events. 188.Pp 189Unless 190.Dv KTR_ALL 191is specified in the kernel configuration, the default is to turn on logging 192for all corresponding events (i.e.\& setting the sysctl to -1). 193.It Va debug.ktr.*_mask 194Read only sysctls (one per event) that show the 195.Va debug.ktr.*_enable 196values corresponding to the events. 197.It Va debug.ktr.resynchronize 198Resynchronize the TSC across all CPUs 10 times per second in an attempt to 199reduce drift errors. 200Note that this is very expensive and therefore the default is 0. 201.El 202.Sh SEE ALSO 203.Xr gdb 1 , 204.Xr ddb 4 , 205.Xr ktrdump 8 , 206.Xr ktr 9 207.Sh HISTORY 208The KTR kernel tracing facility first appeared in 209.Bsx 3.0 210and was imported into 211.Fx 5.0 212and 213.Dx 1.1 . 214It was completely rewritten by Matthew Dillon in 215.Dx 1.3 . 216