163 lines
4.9 KiB
Groff
163 lines
4.9 KiB
Groff
.\" 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.
|