Author: markj
Date: Sat Jul 6 20:31:22 2013
New Revision: 252895
URL: http://svnweb.freebsd.org/changeset/base/252895
Log:
Add a man page for the SDT_* macros, which can be used to define new static
DTrace probes and providers in kernel code.
MFC after: 1 week
Added:
head/share/man/man9/SDT.9 (contents, props changed)
Modified:
head/share/man/man9/Makefile
Modified: head/share/man/man9/Makefile
==============================================================================
--- head/share/man/man9/Makefile Sat Jul 6 20:21:35 2013
(r252894)
+++ head/share/man/man9/Makefile Sat Jul 6 20:31:22 2013
(r252895)
@@ -236,6 +236,7 @@ MAN= accept_filter.9 \
rwlock.9 \
sbuf.9 \
scheduler.9 \
+ SDT.9 \
securelevel_gt.9 \
selrecord.9 \
sema.9 \
@@ -1147,6 +1148,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
Added: head/share/man/man9/SDT.9
==============================================================================
--- /dev/null 00:00:00 1970 (empty, because file is newly added)
+++ head/share/man/man9/SDT.9 Sat Jul 6 20:31:22 2013 (r252895)
@@ -0,0 +1,243 @@
+.\" Copyright (c) 2013 Mark Johnston <ma...@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 j...@freebsd.org .
+This manual page was written by
+.An Mark Johnston Aq ma...@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.
_______________________________________________
svn-src-all@freebsd.org mailing list
http://lists.freebsd.org/mailman/listinfo/svn-src-all
To unsubscribe, send any mail to "svn-src-all-unsubscr...@freebsd.org"
