.\" Copyright (c) 2013 Mark Johnston <markj@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@FreeBSD.org .
This manual page was written by
.An Mark Johnston Aq markj@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.