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 July 17, 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_USB_MEMORY 131USB memory allocation 132.El 133.Ss Verbose Mode 134By default, events are only logged to the internal buffer for examination 135later, but if the verbose flag is set then they are dumped to the kernel 136console as well. 137This flag can also be set from the loader via the 138.Va debug.ktr.verbose 139environment variable, or it can be examined and set after booting via the 140.Va debug.ktr.verbose 141sysctl. 142If the flag is set to zero, which is the default, then verbose output is 143disabled. 144If the flag is set to one, then the contents of the log message and the CPU 145number are printed to the kernel console. 146If the flag is greater than one, then the filename and line number of the 147event are output to the console in addition to the log message and the CPU 148number. 149The 150.Dv KTR_VERBOSE 151option enables verbose mode and sets the flag to one. 152.Ss Examining the Events 153The KTR buffer can be examined with 154.Xr ktrdump 8 , 155.Xr gdb 1 156or from within 157.Xr ddb 4 158via the 159.Ic show ktr Op Cm /v 160command. 161This command displays the contents of the trace buffer one page at a time. 162At the 163.Dq Li --more-- 164prompt, the Enter key displays one more entry and prompts again. 165The spacebar displays another page of entries. 166Any other key quits. 167By default the timestamp, filename, and line number are not displayed with 168each log entry. 169If the 170.Cm /v 171modifier is specified, then they are displayed in addition to the normal 172output. 173Note that the events are displayed in reverse chronological order. 174That is, the most recent events are displayed first. 175.Sh SYSCTL VARIABLES 176.Bl -tag -width ".Va debug.ktr.resynchronize" 177.It Va debug.ktr.*_enable 178A 32 bit mask used to control event logging. 179Each bit corresponds to one or more events depending on the values of the 180.Fa maskbit 181parameters that were passed to the 182.Xr KTR_INFO 9 183calls which declared the events. 184.Pp 185Unless 186.Dv KTR_ALL 187is specified in the kernel configuration, the default is to turn on logging 188for all corresponding events (i.e.\& setting the sysctl to -1). 189.It Va debug.ktr.*_mask 190Read only sysctls (one per event) that show the 191.Va debug.ktr.*_enable 192values corresponding to the events. 193.It Va debug.ktr.resynchronize 194Resynchronize the TSC across all CPUs 10 times per second in an attempt to 195reduce drift errors. 196Note that this is very expensive and therefore the default is 0. 197.El 198.Sh SEE ALSO 199.Xr gdb 1 , 200.Xr ddb 4 , 201.Xr ktrdump 8 , 202.Xr ktr 9 203.Sh HISTORY 204The KTR kernel tracing facility first appeared in 205.Bsx 3.0 206and was imported into 207.Fx 5.0 208and 209.Dx 1.1 . 210It was completely rewritten by Matthew Dillon in 211.Dx 1.3 . 212