kernel: Remove unused KTR_POLLING option.
[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.\"
d84d3f48 27.Dd September 18, 2012
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
c112b277 50.Cd options KTR_SERIALIZER
980c9f64
SW
51.Cd options KTR_SPIN_CONTENTION
52.\".Cd options KTR_TCP
c112b277 53.Cd options KTR_TESTLOG
980c9f64 54.Cd options KTR_TOKENS
1e1b2beb 55.Cd options KTR_TSLEEP
980c9f64 56.Cd options KTR_USB_MEMORY
c1dc8fe1 57.Cd options KTR_USCHED_BSD4
d84d3f48 58.Cd options KTR_USCHED_DFLY
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
c112b277
SW
118.It Dv KTR_SERIALIZER
119.Xr serializer 9
120related events
980c9f64
SW
121.It Dv KTR_SPIN_CONTENTION
122.Xr spinlock 9
123contention
c112b277
SW
124.It Dv KTR_TESTLOG
125IPI performance testing
980c9f64
SW
126.It Dv KTR_TOKENS
127LWKT token related events
1e1b2beb
SW
128.It Dv KTR_TSLEEP
129.Xr tsleep 9
130and
131.Xr wakeup 9
980c9f64
SW
132.It Dv KTR_USB_MEMORY
133USB memory allocation
c1dc8fe1
AH
134.It Dv KTR_USCHED_BSD4
135usched_bsd4 scheduling decisions
d84d3f48
SW
136.It Dv KTR_USCHED_DFLY
137usched_dfly scheduling decisions
980c9f64 138.El
81540c2d
EN
139.Ss Verbose Mode
140By default, events are only logged to the internal buffer for examination
141later, but if the verbose flag is set then they are dumped to the kernel
142console as well.
143This flag can also be set from the loader via the
144.Va debug.ktr.verbose
145environment variable, or it can be examined and set after booting via the
146.Va debug.ktr.verbose
147sysctl.
148If the flag is set to zero, which is the default, then verbose output is
149disabled.
150If the flag is set to one, then the contents of the log message and the CPU
151number are printed to the kernel console.
152If the flag is greater than one, then the filename and line number of the
153event are output to the console in addition to the log message and the CPU
154number.
155The
156.Dv KTR_VERBOSE
e6d55b2d 157option enables verbose mode and sets the flag to one.
81540c2d 158.Ss Examining the Events
980c9f64
SW
159The KTR buffer can be examined with
160.Xr ktrdump 8 ,
161.Xr gdb 1
162or from within
81540c2d
EN
163.Xr ddb 4
164via the
165.Ic show ktr Op Cm /v
166command.
167This command displays the contents of the trace buffer one page at a time.
168At the
169.Dq Li --more--
170prompt, the Enter key displays one more entry and prompts again.
171The spacebar displays another page of entries.
172Any other key quits.
173By default the timestamp, filename, and line number are not displayed with
174each log entry.
175If the
176.Cm /v
177modifier is specified, then they are displayed in addition to the normal
178output.
179Note that the events are displayed in reverse chronological order.
180That is, the most recent events are displayed first.
46da84fa 181.Sh SYSCTL VARIABLES
2d0db798 182.Bl -tag -width ".Va debug.ktr.resynchronize"
46da84fa
SW
183.It Va debug.ktr.*_enable
184A 32 bit mask used to control event logging.
185Each bit corresponds to one or more events depending on the values of the
186.Fa maskbit
187parameters that were passed to the
188.Xr KTR_INFO 9
189calls which declared the events.
190.Pp
191Unless
192.Dv KTR_ALL
193is specified in the kernel configuration, the default is to turn on logging
194for all corresponding events (i.e.\& setting the sysctl to -1).
195.It Va debug.ktr.*_mask
196Read only sysctls (one per event) that show the
197.Va debug.ktr.*_enable
198values corresponding to the events.
2d0db798
SW
199.It Va debug.ktr.resynchronize
200Resynchronize the TSC across all CPUs 10 times per second in an attempt to
201reduce drift errors.
202Note that this is very expensive and therefore the default is 0.
ad6fda00 203.El
81540c2d 204.Sh SEE ALSO
980c9f64
SW
205.Xr gdb 1 ,
206.Xr ddb 4 ,
207.Xr ktrdump 8 ,
81540c2d
EN
208.Xr ktr 9
209.Sh HISTORY
210The KTR kernel tracing facility first appeared in
211.Bsx 3.0
212and was imported into
213.Fx 5.0
214and
215.Dx 1.1 .
980c9f64
SW
216It was completely rewritten by Matthew Dillon in
217.Dx 1.3 .