svn commit: r262021 - stable/9/share/man/man9

[Andriy Gapon]

Author: avg
Date: Mon Feb 17 11:22:59 2014
New Revision: 262021
URL: http://svnweb.freebsd.org/changeset/base/262021

Log:
  MFC r252895: Add a man page for the SDT_* macros

Added:
  stable/9/share/man/man9/SDT.9
     - copied unchanged from r252895, head/share/man/man9/SDT.9
Modified:
  stable/9/share/man/man9/Makefile
Directory Properties:
  stable/9/share/man/man9/   (props changed)

Modified: stable/9/share/man/man9/Makefile
==============================================================================
--- stable/9/share/man/man9/Makefile	Mon Feb 17 11:05:57 2014	(r262020)
+++ stable/9/share/man/man9/Makefile	Mon Feb 17 11:22:59 2014	(r262021)
@@ -233,6 +233,7 @@ MAN=	accept_filter.9 \
 	rwlock.9 \
 	sbuf.9 \
 	scheduler.9 \
+	SDT.9 \
 	securelevel_gt.9 \
 	selrecord.9 \
 	sema.9 \
@@ -1128,6 +1129,11 @@ MLINKS+=scheduler.9 curpriority_cmp.9 \
 	scheduler.9 sched_setup.9 \
 	scheduler.9 setrunnable.9 \
 	scheduler.9 updatepri.9
+MLINKS+=SDT.9 SDT_PROVIDER_DECLARE.9 \
+	SDT.9 SDT_PROVIDER_DEFINE.9 \
+	SDT.9 SDT_PROBE_DECLARE.9 \
+	SDT.9 SDT_PROBE_DEFINE.9 \
+	SDT.9 SDT_PROBE.9
 MLINKS+=securelevel_gt.9 securelevel_ge.9
 MLINKS+=selrecord.9 seldrain.9 \
 	selrecord.9 selwakeup.9

Copied: stable/9/share/man/man9/SDT.9 (from r252895, head/share/man/man9/SDT.9)
==============================================================================
--- /dev/null	00:00:00 1970	(empty, because file is newly added)
+++ stable/9/share/man/man9/SDT.9	Mon Feb 17 11:22:59 2014	(r262021, copy of r252895, head/share/man/man9/SDT.9)
@@ -0,0 +1,243 @@
+.\" Copyright (c) 2013 Mark Johnston <markj at 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 July 3, 2013
+.Dt SDT 9
+.Os
+.Sh NAME
+.Nm SDT
+.Nd a DTrace framework for adding statically-defined tracing probes
+.Sh SYNOPSIS
+.In sys/sdt.h
+.Fn SDT_PROVIDER_DECLARE prov
+.Fn SDT_PROVIDER_DEFINE prov
+.Fn SDT_PROBE_DECLARE prov mod func name
+.Fn SDT_PROBE_DEFINE prov mod func name sname
+.Fn SDT_PROBE_DEFINE0 prov mod func name sname
+.Fn SDT_PROBE_DEFINE1 prov mod func name sname arg0
+.Fn SDT_PROBE_DEFINE2 prov mod func name sname arg0 arg1
+.Fn SDT_PROBE_DEFINE3 prov mod func name sname arg0 arg1 arg2
+.Fn SDT_PROBE_DEFINE4 prov mod func name sname arg0 arg1 arg2 arg3
+.Fn SDT_PROBE_DEFINE5 prov mod func name sname arg0 arg1 arg2 arg3 arg4
+.Fn SDT_PROBE_DEFINE6 prov mod func name sname arg0 arg1 arg2 arg3 arg4 arg5
+.Fn SDT_PROBE_DEFINE7 prov mod func name sname arg0 arg1 arg2 arg3 arg4 arg5   \
+    arg6
+.Fn SDT_PROBE0 prov mod func name
+.Fn SDT_PROBE1 prov mod func name arg0
+.Fn SDT_PROBE2 prov mod func name arg0 arg1
+.Fn SDT_PROBE3 prov mod func name arg0 arg1 arg2
+.Fn SDT_PROBE4 prov mod func name arg0 arg1 arg2 arg3
+.Fn SDT_PROBE5 prov mod func name arg0 arg1 arg2 arg3 arg4
+.Fn SDT_PROBE6 prov mod func name arg0 arg1 arg2 arg3 arg4 arg5
+.Fn SDT_PROBE7 prov mod func name arg0 arg1 arg2 arg3 arg4 arg5 arg6
+.Sh DESCRIPTION
+.Pp
+The
+.Nm
+macros allow programmers to define static trace points in kernel code.
+These trace points are used by the
+.Nm
+framework to create DTrace probes, allowing the code to be instrumented
+using
+.Xr dtrace 1 .
+By default,
+.Nm
+trace points are disabled and have no effect on the surrounding code.
+When a DTrace probe corresponding to a given trace point is enabled, threads
+that execute the trace point will call a handler and cause the probe to fire.
+Moreover, trace points can take arguments, making it possible to pass data
+to the DTrace framework when an enabled probe fires.
+.Pp
+Multiple trace points may correspond to a single DTrace probe, allowing
+programmers to create DTrace probes that correspond to logical system events
+rather than tying probes to specific code execution paths.
+For instance, a DTrace probe corresponding to the arrival of an IP packet into
+the network stack may be defined using two
+.Nm
+trace points: one for IPv4 packets and one for IPv6 packets.
+.Pp
+In addition to defining DTrace probes, the
+.Nm
+macros allow programmers to define new DTrace providers, making it possible to
+namespace logically-related probes.
+An example is FreeBSD's sctp provider, which contains
+.Nm
+probes for FreeBSD's
+.Xr sctp 4
+implementation.
+.Pp
+The
+.Fn SDT_PROVIDER_DECLARE
+and
+.Fn SDT_PROVIDER_DEFINE
+macros are used respectively to declare and define a DTrace provider named
+.Ar prov
+with the
+.Nm
+framework.
+A provider need only be defined once; however, the provider must be declared
+before defining any
+.Nm
+probes belonging to that provider.
+.Pp
+Similarly, the
+.Fn SDT_PROBE_DECLARE
+and
+.Fn SDT_PROBE_DEFINE*
+macros are used to declare and define DTrace probes using the
+.Nm
+framework.
+Once a probe has been defined, trace points for that probe may be added to
+kernel code.
+DTrace probe identifiers consist of a provider, module, function and name, all
+of which may be specified in the
+.Nm
+probe definition.
+Note that probes should not specify a module name: the module name of a probe is
+used to determine whether or not it should be destroyed when a kernel module is
+unloaded.
+See the
+.Sx BUGS
+section.
+Note in particular that probes must not be defined across multiple kernel
+modules.
+The
+.Fn SDT_PROBE_DEFINE*
+macros also take an extra
+.Ar sname
+parameter.
+This is used to allow the creation of probes with names containing the
+.Ql -
+character.
+Specifically, the
+.Ar name
+argument should contain the probe name with all dashes converted to underscores,
+and the
+.Ar sname
+argument should be the probe name as it will be referenced by D scripts.
+.Pp
+The
+.Fn SDT_PROBE_DEFINE*
+macros also allow programmers to declare the types of the arguments that are
+passed to probes.
+This is optional; if the argument types are omitted (through use of the
+.Fn SDT_PROBE_DEFINE
+macro), users wishing to make use of the arguments will have to manually cast
+them to the correct types in their D scripts.
+It is strongly recommended that probe definitions include a declaration of their
+argument types.
+.Pp
+The
+.Fn SDT_PROBE*
+macros are used to create
+.Nm
+trace points.
+They are meant to be added to executable code and can be used to instrument the
+code in which they are called.
+.Sh EXAMPLES
+.Pp
+The following probe definition will create a DTrace probe called
+.Ql icmp::unreach:pkt-receive ,
+which would hypothetically be triggered when the kernel receives an ICMP packet
+of type Destination Unreachable:
+.Bd -literal -offset indent
+SDT_PROVIDER_DECLARE(icmp);
+
+SDT_PROBE_DEFINE2(icmp, , unreach, pkt_receive, pkt-receive,
+    "struct mbuf *", "struct icmp *");
+
+.Ed
+This particular probe would take two arguments: a pointer to the
+.Xr mbuf 9
+containing the incoming packet, and a pointer to the ICMP header for the packet.
+Note that the module name of this probe is not specified.
+.Pp
+Consider a DTrace probe which fires when the network stack receives an IP
+packet.
+Such a probe would be defined by multiple tracepoints:
+.Bd -literal -offset indent
+SDT_PROBE_DEFINE2(ip, , , receive, receive, "struct mbuf *",
+    "struct ifnet *", "struct ip *", "struct ip6_hdr *");
+
+int
+ip_input(struct mbuf *m)
+{
+	struct ip *ip;
+	...
+	ip = mtod(m, struct ip *);
+	SDT_PROBE4(ip, , , receive, m, m->m_pkthdr.rcvif, ip, NULL);
+	...
+}
+
+int
+ip6_input(struct mbuf *m)
+{
+	struct ip6_hdr *ip6;
+	...
+	ip6 = mtod(m, struct ip6_hdr *);
+	SDT_PROBE4(ip, , , receive, m, m->m_pkthdr.rcvif, NULL, ip6);
+	...
+}
+
+.Ed
+In particular, the probe should fire when the kernel receives either an IPv4
+packet or an IPv6 packet.
+.Sh SEE ALSO
+.Xr dtrace 1
+.Sh AUTHORS
+.An -nosplit
+DTrace and the
+.Nm
+framework were originally ported to FreeBSD from Solaris by
+.An John Birrell Aq jb at FreeBSD.org .
+This manual page was written by
+.An Mark Johnston Aq markj at FreeBSD.org .
+.Sh BUGS
+.Pp
+The
+.Nm
+macros allow the module name of a probe to be specified as part of a probe
+definition.
+However, the DTrace framework uses the module name of probes to determine
+which probes should be destroyed when a kernel module is unloaded, so the module
+name of a probe should match the name of the module in which its defined.
+.Nm
+will set the module name properly if it is left unspecified in the probe
+definition; see the
+.Sx EXAMPLES
+section.
+.Pp
+One of the goals of the original
+.Nm
+implementation (and by extension, of FreeBSD's port) is that inactive
+.Nm
+probes should have no performance impact.
+This is unfortunately not the case;
+.Nm
+trace points will add a small but non-zero amount of latency to the code
+in which they are defined.
+A more sophisticated implementation of the probes will help alleviate this
+problem.