diff options
Diffstat (limited to 'share/man/man9/ktr.9')
| -rw-r--r-- | share/man/man9/ktr.9 | 162 |
1 files changed, 162 insertions, 0 deletions
diff --git a/share/man/man9/ktr.9 b/share/man/man9/ktr.9 new file mode 100644 index 000000000000..98b601d669cc --- /dev/null +++ b/share/man/man9/ktr.9 @@ -0,0 +1,162 @@ +.\" Copyright (c) 2001 John H. Baldwin <jhb@FreeBSD.org> +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd November 30, 2008 +.Dt KTR 9 +.Os +.Sh NAME +.Nm CTR0 , CTR1 , CTR2 , CTR3 , CTR4 , CTR5 +.Nd kernel tracing facility +.Sh SYNOPSIS +.In sys/param.h +.In sys/ktr.h +.Vt "extern int ktr_cpumask" ; +.Vt "extern int ktr_entries" ; +.Vt "extern int ktr_extend" ; +.Vt "extern int ktr_mask" ; +.Vt "extern int ktr_verbose" ; +.Vt "extern struct ktr_entry ktr_buf[]" ; +.Ft void +.Fn CTR0 "u_int mask" "char *format" +.Ft void +.Fn CTR1 "u_int mask" "char *format" "arg1" +.Ft void +.Fn CTR2 "u_int mask" "char *format" "arg1" "arg2" +.Ft void +.Fn CTR3 "u_int mask" "char *format" "arg1" "arg2" "arg3" +.Ft void +.Fn CTR4 "u_int mask" "char *format" "arg1" "arg2" "arg3" "arg4" +.Ft void +.Fn CTR5 "u_int mask" "char *format" "arg1" "arg2" "arg3" "arg4" "arg5" +.Ft void +.Fn CTR6 "u_int mask" "char *format" "arg1" "arg2" "arg3" "arg4" "arg5" "arg6" +.Sh DESCRIPTION +KTR provides a circular buffer of events that can be logged in a +.Xr printf 9 +style +fashion. +These events can then be dumped with +.Xr ddb 4 , +.Xr gdb 1 +or +.Xr ktrdump 8 . +.Pp +Events are created and logged in the kernel via the +.Dv CTR Ns Ar x +macros. +The first parameter is a mask of event types +.Pq Dv KTR_* +defined in +.In sys/ktr.h . +The event will be logged only if any of the event types specified in +.Fa mask +are enabled in the global event mask stored in +.Va ktr_mask . +The +.Fa format +argument is a +.Xr printf 9 +style format string used to build the text of the event log message. +Following the +.Fa format +string are zero to five arguments referenced by +.Fa format . +Each event is logged with a file name and source line number of the +originating CTR call, and a timestamp in addition to the log message. +.Pp +The event is stored in the circular buffer with supplied arguments as is, +and formatting is done at the dump time. +Do not use pointers to the objects with limited lifetime, for instance, +strings, because the pointer may become invalid when buffer is printed. +.Pp +Note that the different macros differ only in the number of arguments each +one takes, as indicated by its name. +.Pp +The +.Va ktr_entries +variable contains the number of entries in the +.Va ktr_buf +array. +These variables are mostly useful for post-mortem crash dump tools to locate +the base of the circular trace buffer and its length. +.Pp +The +.Va ktr_mask +variable contains the run time mask of events to log. +.Pp +The CPU event mask is stored in the +.Va ktr_cpumask +variable. +.Pp +The +.Va ktr_verbose +variable stores the verbose flag that controls whether events are logged to +the console in addition to the event buffer. +.Sh EXAMPLES +This example demonstrates the use of tracepoints at the +.Dv KTR_PROC +logging level. +.Bd -literal +void +mi_switch() +{ + ... + /* + * Pick a new current process and record its start time. + */ + ... + CTR3(KTR_PROC, "mi_switch: old proc %p (pid %d)", p, p->p_pid); + ... + cpu_switch(); + ... + CTR3(KTR_PROC, "mi_switch: new proc %p (pid %d)", p, p->p_pid); + ... +} +.Ed +.Sh SEE ALSO +.Xr ktr 4 , +.Xr ktrdump 8 +.Sh HISTORY +The KTR kernel tracing facility first appeared in +.Bsx 3.0 +and was imported into +.Fx 5.0 . +.Sh BUGS +Currently there is one global buffer shared among all CPUs. +It might be profitable at some point in time to use per-CPU buffers instead +so that if one CPU halts or starts spinning, then the log messages it +emitted just prior to halting or spinning will not be drowned out by events +from the other CPUs. +.Pp +The arguments given in +.Fn CTRx +macros are stored as +.Vt u_long , +so do not pass arguments larger than size of an +.Vt u_long +type. +For example passing 64bit arguments on 32bit architectures will give incorrect +results. |