ktr.4 - add note about KTR_USCHED_BSD4
[dragonfly.git] / share / man / man4 / ktr.4
CommitLineData
81540c2d
EN
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 $
81540c2d 26.\"
1e1b2beb 27.Dd August 13, 2011
81540c2d
EN
28.Dt KTR 4
29.Os
30.Sh NAME
31.Nm ktr
32.Nd kernel tracing facility
33.Sh SYNOPSIS
34.Cd options KTR
81540c2d 35.Cd options KTR_ENTRIES=8192
980c9f64
SW
36.Cd options KTR_VERBOSE=1
37.Cd options KTR_ALL
b58c6bd7 38.Cd options KTR_CTXSW
3cb3310a 39.Cd options KTR_DMCRYPT
4a54556c 40.Cd options KTR_ETHERNET
b58c6bd7 41.\".Cd options KTR_HAMMER
980c9f64
SW
42.Cd options KTR_IF_BGE
43.Cd options KTR_IF_EM
b58c6bd7 44.Cd options KTR_IF_EMX
ff94fe49
SZ
45.Cd options KTR_IF_START
46.Cd options KTR_IFQ
980c9f64 47.Cd options KTR_IPIQ
d0377f9b 48.Cd options KTR_KERNENTRY
980c9f64 49.Cd options KTR_MEMORY
d16c94f7 50.Cd options KTR_POLLING
c112b277 51.Cd options KTR_SERIALIZER
980c9f64
SW
52.Cd options KTR_SPIN_CONTENTION
53.\".Cd options KTR_TCP
c112b277 54.Cd options KTR_TESTLOG
980c9f64 55.Cd options KTR_TOKENS
1e1b2beb 56.Cd options KTR_TSLEEP
980c9f64 57.Cd options KTR_USB_MEMORY
c1dc8fe1 58.Cd options KTR_USCHED_BSD4
81540c2d
EN
59.Sh DESCRIPTION
60The
61.Nm
62facility allows kernel events to be logged while the kernel executes so that
63they can be examined later when debugging.
64The only mandatory option to enable
65.Nm
66is
980c9f64 67.Cd options KTR .
81540c2d
EN
68.Pp
69The
70.Dv KTR_ENTRIES
71option sets the size of the buffer of events.
6d22945a 72It must be a power of two.
81540c2d
EN
73The size of the buffer in the currently running kernel can be found via the
74read-only sysctl
75.Va debug.ktr.entries .
980c9f64 76By default the buffer contains 2048 entries.
81540c2d 77.Pp
980c9f64
SW
78For debugging purposes, the following
79.Nm
80related kernel options exist:
140d9d68 81.Bl -tag -width ".Dv KTR_SPIN_CONTENTION"
980c9f64
SW
82.It Dv KTR_ALL
83turns on all options
b58c6bd7
SW
84.It Dv KTR_CTXSW
85context switches
3cb3310a
SW
86.It Dv KTR_DMCRYPT
87read and write strategy paths of
88.Xr dm 4 Ap s
89.Pa crypt
90target
4a54556c
SW
91.It Dv KTR_ETHERNET
92cost of
28eba747 93.Fn ether_input_pkt
4a54556c 94and
28eba747 95.Fn ether_dispatch
980c9f64
SW
96.It Dv KTR_IF_BGE
97.Xr bge 4
98interrupts and sent/received packets
99.It Dv KTR_IF_EM
100.Xr em 4
b58c6bd7
SW
101interrupts and sent/received packets
102.It Dv KTR_IF_EMX
103.Xr emx 4
104interrupts and sent/received packets
ff94fe49
SZ
105.It Dv KTR_IFQ
106classic ifq dequeue/enqueue operation
107.It Dv KTR_IF_START
108running/avoiding/scheduling ifnet.if_start
980c9f64
SW
109.It Dv KTR_IPIQ
110IPI related data (IPI requests, CPU synchronization etc.)
d0377f9b
SW
111.It Dv KTR_KERNENTRY
112entry of the kernel from userland (faults, syscalls)
980c9f64
SW
113.It Dv KTR_MEMORY
114.Xr kmalloc 9
115and
116.Xr kfree 9
117events
d16c94f7
SZ
118.It Dv KTR_POLLING
119.Xr polling 4
120begins and ends
c112b277
SW
121.It Dv KTR_SERIALIZER
122.Xr serializer 9
123related events
980c9f64
SW
124.It Dv KTR_SPIN_CONTENTION
125.Xr spinlock 9
126contention
c112b277
SW
127.It Dv KTR_TESTLOG
128IPI performance testing
980c9f64
SW
129.It Dv KTR_TOKENS
130LWKT token related events
1e1b2beb
SW
131.It Dv KTR_TSLEEP
132.Xr tsleep 9
133and
134.Xr wakeup 9
980c9f64
SW
135.It Dv KTR_USB_MEMORY
136USB memory allocation
c1dc8fe1
AH
137.It Dv KTR_USCHED_BSD4
138usched_bsd4 scheduling decisions
980c9f64 139.El
81540c2d
EN
140.Ss Verbose Mode
141By default, events are only logged to the internal buffer for examination
142later, but if the verbose flag is set then they are dumped to the kernel
143console as well.
144This flag can also be set from the loader via the
145.Va debug.ktr.verbose
146environment variable, or it can be examined and set after booting via the
147.Va debug.ktr.verbose
148sysctl.
149If the flag is set to zero, which is the default, then verbose output is
150disabled.
151If the flag is set to one, then the contents of the log message and the CPU
152number are printed to the kernel console.
153If the flag is greater than one, then the filename and line number of the
154event are output to the console in addition to the log message and the CPU
155number.
156The
157.Dv KTR_VERBOSE
e6d55b2d 158option enables verbose mode and sets the flag to one.
81540c2d 159.Ss Examining the Events
980c9f64
SW
160The KTR buffer can be examined with
161.Xr ktrdump 8 ,
162.Xr gdb 1
163or from within
81540c2d
EN
164.Xr ddb 4
165via the
166.Ic show ktr Op Cm /v
167command.
168This command displays the contents of the trace buffer one page at a time.
169At the
170.Dq Li --more--
171prompt, the Enter key displays one more entry and prompts again.
172The spacebar displays another page of entries.
173Any other key quits.
174By default the timestamp, filename, and line number are not displayed with
175each log entry.
176If the
177.Cm /v
178modifier is specified, then they are displayed in addition to the normal
179output.
180Note that the events are displayed in reverse chronological order.
181That is, the most recent events are displayed first.
46da84fa 182.Sh SYSCTL VARIABLES
2d0db798 183.Bl -tag -width ".Va debug.ktr.resynchronize"
46da84fa
SW
184.It Va debug.ktr.*_enable
185A 32 bit mask used to control event logging.
186Each bit corresponds to one or more events depending on the values of the
187.Fa maskbit
188parameters that were passed to the
189.Xr KTR_INFO 9
190calls which declared the events.
191.Pp
192Unless
193.Dv KTR_ALL
194is specified in the kernel configuration, the default is to turn on logging
195for all corresponding events (i.e.\& setting the sysctl to -1).
196.It Va debug.ktr.*_mask
197Read only sysctls (one per event) that show the
198.Va debug.ktr.*_enable
199values corresponding to the events.
2d0db798
SW
200.It Va debug.ktr.resynchronize
201Resynchronize the TSC across all CPUs 10 times per second in an attempt to
202reduce drift errors.
203Note that this is very expensive and therefore the default is 0.
ad6fda00 204.El
81540c2d 205.Sh SEE ALSO
980c9f64
SW
206.Xr gdb 1 ,
207.Xr ddb 4 ,
208.Xr ktrdump 8 ,
81540c2d
EN
209.Xr ktr 9
210.Sh HISTORY
211The KTR kernel tracing facility first appeared in
212.Bsx 3.0
213and was imported into
214.Fx 5.0
215and
216.Dx 1.1 .
980c9f64
SW
217It was completely rewritten by Matthew Dillon in
218.Dx 1.3 .