1.\"- 2.\" Copyright (c) 2002 Chad David 3.\" All rights reserved. 4.\" 5.\" Redistribution and use in source and binary forms, with or without 6.\" modification, are permitted provided that the following conditions 7.\" are met: 8.\" 1. Redistributions of source code must retain the above copyright 9.\" notice, this list of conditions and the following disclaimer. 10.\" 2. Redistributions in binary form must reproduce the above copyright 11.\" notice, this list of conditions and the following disclaimer in the 12.\" documentation and/or other materials provided with the distribution. 13.\" 14.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 15.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 16.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 17.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 18.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 19.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 20.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 21.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 22.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 23.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 24.\" SUCH DAMAGE. 25.\" 26.\" $FreeBSD: src/usr.bin/ktrdump/ktrdump.8,v 1.7 2005/03/08 06:58:56 hmp Exp $ 27.\" $DragonFly: src/usr.bin/ktrdump/ktrdump.8,v 1.15 2007/12/23 00:25:52 swildner Exp $ 28.\" 29.Dd June 8, 2007 30.Dt KTRDUMP 8 31.Os 32.Sh NAME 33.Nm ktrdump 34.Nd print kernel ktr trace buffer 35.Sh SYNOPSIS 36.Nm 37.Op Fl acfilnpqrstx 38.Op Fl N Ar execfile 39.Op Fl M Ar corefile 40.Op Fl o Ar outfile 41.Sh DESCRIPTION 42The 43.Nm 44utility is used to dump the contents of the kernel ktr trace buffer. 45.Pp 46The following options are available: 47.Bl -tag -width ".Fl N Ar execfile" 48.It Fl a 49Print most fields. Implies 50.Fl c 51.Fl i 52.Fl x 53.Fl p 54.Fl r , 55and 56.Fl s . 57Note that 58.Fl f 59is not included. 60.It Fl c 61Print the CPU number that each entry was logged from. 62.It Fl f 63Print the file and line number that each entry was logged from. 64.It Fl i 65Print the ID string field, identifying the facility being logged. 66.It Fl l 67.Nm 68will loop waiting for new data rather than exit. 69.It Fl n 70.Nm 71normally tries to translate the caller fields and (when easily parsed) 72trace arguments into symbols. This option forces hex values to be 73displayed instead. This option will also cause relative timestamps to 74be displayed as TSC timestamps rather than converted to microseconds. 75.It Fl p 76Print the trace data. 77.It Fl q 78Quiet mode; do not print the column header. 79.It Fl r 80Print relative timestamps in microseconds, rather than absolute TSC 81timestamps. 82.It Fl s 83Attempt to merge the KTR logs for all cpus into a single time-sorted 84log. For the numbers to make any sense you probably want to turn 85on the 86.Va debug.ktr.resynchronize 87.Xr sysctl 3 88variable. This sysctl causes the kernel to periodically 89calculate the drift between each CPU's TSC and apply a correction. 90.It Fl x 91Print the call chain leading up to the procedure which issued 92the KTR. 93.It Fl t 94Print the timestamp for each entry. 95.It Fl N Ar execfile 96The kernel image to resolve symbols from. 97The default is the value returned via 98.Xr getbootfile 3 . 99.It Fl M Ar corefile 100The core file or memory image to read from. 101The default is 102.Pa /dev/mem . 103.It Fl o Ar outfile 104The file to write the output to. 105The default is standard output. 106.El 107.Sh OPERATIONAL NOTES 108Users of 109.Nm 110should keep in mind that the act of trace logging will itself affect 111execution overheads. On a 2Ghz cpu a logging call can take anywhere 112from 40ns to 150ns to run. 113.Pp 114The TSC counter is used on cpus equipped with it (which is all modern cpus). 115The TSC counters may not be synchronized on SMP systems and may drift even 116between cores on multi-core cpus. Enabling synchronization between cpus 117via the 118.Va debug.ktr.resynchronize 119sysctl will impose additional system overheads and will generally only be 120accurate to within 100ns or so (and perhaps not even that good). 121Resynchronization only occurs 10 times a second and serious drift will 122cause a great deal of measurement noise when trying to compare events occurring 123on two different cpus. 124.Pp 125Users using the 126.Fl s 127option should be aware that events for each cpu are independently logged 128and one cpu might have more events logged then another, causing earlier 129events to be discarded sooner then other cpus. The beginning portion of 130the sorted output may thus show MP related events for one cpu with no 131corresponding events for other cpus. 132.Pp 133It is possible to somewhat characterize KTR logging overheads by setting 134the 135.Va debug.ktr.testlogcnt 136sysctl and then observing test logging events in the KTR output. Tests 1-3 137log four dummy arguments while tests 4-6 log no arguments. 138.Pp 139It is possible to characterize IPI messaging latencies by setting the 140.Va debug.ktr.testipicnt 141sysctl. A small number between 1 and 1000 is recommended. This will 142cause the system to ping pong a single IPI message between cpu 0 and cpu 1 143asynchronously that number of times, as fast as it can. A 144.Nm 145should be performed almost immediately after setting the sysctl or you 146might miss the logged events. 147.Sh SEE ALSO 148.Xr ktr 4 , 149.Xr ktr 9 150.Sh HISTORY 151The 152.Nm 153utility first appeared in 154.Fx 5.0 . 155.Sh AUTHORS 156.An -nosplit 157The 158.Nm 159utility was originally implemented by 160.An Jake Burkholder Aq jake@FreeBSD.org . 161This manual page was originally written by 162.An Chad David Aq davidc@FreeBSD.org . 163The program and manual page were rewritten pretty much from 164scratch by 165.An Matthew Dillon 166for 167.Dx . 168