Add a new manpage to document the CTRx macros used when adding new KTR

tracepoints to kernel code.

2 files changed, 159 insertions, 1 deletions

diff --git a/share/man/man9/Makefile b/share/man/man9/Makefile
index f8a3e2d..4ac640b 100644
--- a/share/man/man9/Makefile
+++ b/share/man/man9/Makefile
@@ -20,7 +20,7 @@ MAN=	CONDSPLASSERT.9 DECLARE_MODULE.9 DELAY.9 DEV_MODULE.9 KASSERT.9 MD5.9 \
 	fetch.9 \
 	get_cyclecounter.9 \
 	ifnet.9 inittodr.9 intro.9 ithread.9 \
-	kernacc.9 kthread.9 \
+	kernacc.9 kthread.9 ktr.9 \
 	malloc.9 make_dev.9 mbuf.9 mbchain.9 mdchain.9 \
 	microseq.9 microtime.9 microuptime.9 \
 	mi_switch.9 module.9 mutex.9 \
@@ -109,6 +109,8 @@ MLINKS+=kthread.9 kproc_start.9 kthread.9 kproc_shutdown.9
 MLINKS+=kthread.9 kthread_create.9 kthread.9 kthread_exit.9
 MLINKS+=kthread.9 kthread_resume.9 kthread.9 kthread_suspend.9
 MLINKS+=kthread.9 kthread_suspend_check.9
+MLINKS+=ktr.9 CTR0.9 ktr.9 CTR1.9 ktr.9 CTR2.9
+MLINKS+=ktr.9 CTR3.9 ktr.9 CTR4.9 ktr.9 CTR5.9
 MLINKS+=make_dev.9 depends_dev.9
 MLINKS+=make_dev.9 destroy_dev.9
 MLINKS+=make_dev.9 make_dev_alias.9
diff --git a/share/man/man9/ktr.9 b/share/man/man9/ktr.9
new file mode 100644
index 0000000..a816d61
--- /dev/null
+++ b/share/man/man9/ktr.9
@@ -0,0 +1,156 @@
+.\" 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 February 15, 2001
+.Dt KTR 9
+.Os
+.Sh NAME
+.Nm CTR0 ,
+.Nm CTR1 ,
+.Nm CTR2 ,
+.Nm CTR3 ,
+.Nm CTR4 ,
+.Nm CTR5
+.Nd kernel tracing facility
+.Sh SYNOPSIS
+.Fd #include <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"
+.Sh DESCRIPTION
+KTR provides a circular buffer of events that can be logged in a printf style
+fashion.
+These events can then be dumped either via
+.Xr ddb 4
+or
+.Xr gdb 1 .
+.Pp
+Events are created and logged in the kernel via the
+.Dv CTRx
+macros.
+The first parameter is a mask of event types
+.Pq Dv KTR_*
+defined in
+.Aq Pa 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 .
+Note that the different macros differ only in the number of arguments each
+one takes, as indicated by its name.
+Each event is logged with a timestamp in addition to the log message.
+.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 kernel can be configured to compile with several extensions to the base
+functionality.
+These extensions can be checked for at runtime via the
+.Va ktr_extend
+variable.
+It will be set to zero if the extensions are not compiled in and non-zero
+if they are compiled in.
+This is useful for post-mortem debugging tools such as
+.Xr gdb 1
+that are used to analyze kernel crash dumps.
+.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 -offset indent
+void
+mi_switch()
+{
+	...
+	/*
+	 * Pick a new current process and record its start time.
+	 */
+	...
+	CTR3(KTR_PROC, "mi_switch: old proc %p (pid %d, %s)", p, p->p_pid,
+	    p->p_comm);
+	...
+	cpu_switch();
+	...
+	CTR3(KTR_PROC, "mi_switch: new proc %p (pid %d, %s)", p, p->p_pid,
+	    p->p_comm);
+	...
+}
+.Ed
+.Sh SEE ALSO
+.Xr ktr 4
+.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.