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/man9/ktr.9,v 1.8 2005/03/08 01:37:36 hmp Exp $ 26.\" $DragonFly: src/share/man/man9/ktr.9,v 1.10 2007/01/07 11:26:56 swildner Exp $ 27.\" 28.Dd January 6, 2007 29.Dt KTR 9 30.Os 31.Sh NAME 32.Nm KTR_INFO_MASTER , 33.Nm KTR_INFO , 34.Nm KTR_LOG , 35.Nm KTR_LOG_PTR 36.Nd kernel tracing facility 37.Sh SYNOPSIS 38.In sys/ktr.h 39.Vt "extern int ktr_entries" ; 40.Vt "extern int ktr_verbose" ; 41.Vt "extern struct ktr_entry *ktr_buf[MAXCPU]" ; 42.Fn KTR_INFO_MASTER "master" 43.Fn KTR_INFO "compile" "master" "name" "maskbit" "format" "datasize" 44.Fn KTR_LOG "info" "arg ..." 45.Fn KTR_LOG_PTR "info" "ptr" 46.Sh DESCRIPTION 47The 48.Nm ktr 49facility provides a circular buffer of events that can be logged in a 50.Xr kprintf 9 51style fashion. 52These events can then be dumped with 53.Xr ddb 4 , 54.Xr gdb 1 55or 56.Xr ktrdump 8 . 57.Pp 58.Fn KTR_INFO_MASTER 59declares a new master variable 60.Dv ktr Ns _ Ns Fa master Ns _ Ns Dv enable 61that is used to turn on and off event logging. 62.Pp 63The 64.Fn KTR_INFO 65macro registers a new event 66.Fa name 67that will be controlled by the 68.Fa master 69enable variable. 70Code for logging this event will be compiled in when 71.Fa compile 72is defined. 73The 74.Fa format 75argument is a 76.Xr kprintf 9 77style format string used to build the text of the event log message while 78.Fa datasize 79specifies the size of the data to be logged, either the total size of the 80arguments required by the 81.Fa format 82string or the size of the data pointer 83.Fa ptr . 84For logging a fixed string with 85.Fn KTR_INFO , 86.Fa datasize 87is 0. 88The 89.Fa maskbit 90is currently unused and can be set to 0. 91.Pp 92Kernel events are logged via the 93.Fn KTR_LOG 94and 95.Fn KTR_LOG_PTR 96macros. 97The 98.Fa info 99parameter is an identifier of the format 100.Fa master Ns _ Ns Fa name . 101.Fn KTR_LOG 102accepts zero or more additional 103.Fa arg 104arguments as required by the 105.Fa format 106string passed to the associated 107.Fn KTR_INFO 108call. 109The 110.Fn KTR_LOG_PTR 111macro behaves similarly but takes a single data pointer 112.Fa ptr 113instead. 114.Pp 115The 116.Va ktr_entries 117variable contains the number of entries in the 118.Va ktr_buf 119array. 120These variables are mostly useful for post-mortem crash dump tools to locate 121the base of the circular trace buffer and its length. 122.Pp 123The 124.Va ktr_verbose 125variable stores the verbose flag that controls whether events are logged to 126the console in addition to the event buffer. 127.Sh EXAMPLES 128This example demonstrates a simple usage of the KTR facility: 129.Pp 130.Bd -literal -compact 131KTR_INFO_MASTER(ktrtest); 132KTR_INFO(KTR_TEST, ktrtest, t1, 0, "func() called", 0); 133 134\&... 135 136void 137func(void) 138{ 139 KTR_LOG(ktrtest_t1); 140 ... 141} 142.Ed 143.Sh SEE ALSO 144.Xr gdb 1 , 145.Xr ddb 4 , 146.Xr ktr 4 , 147.Xr ktrdump 8 , 148.Xr kprintf 9 149.Sh HISTORY 150The 151.Nm ktr 152kernel tracing facility first appeared in 153.Bsx 3.0 154and was imported into 155.Fx 5.0 156and 157.Dx 1.1 . 158It was completely rewritten by Matthew Dillon in 159.Dx 1.3 . 160