1.\" Copyright (c) 2013 Mark Johnston <markj@freebsd.org> 2.\" All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in the 11.\" documentation and/or other materials provided with the distribution. 12.\" 13.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 14.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 15.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 16.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 17.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 18.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 19.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 20.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 21.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 22.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 23.\" SUCH DAMAGE. 24.\" 25.\" $FreeBSD$ 26.\" 27.Dd July 3, 2013 28.Dt SDT 9 29.Os 30.Sh NAME 31.Nm SDT 32.Nd a DTrace framework for adding statically-defined tracing probes 33.Sh SYNOPSIS 34.In sys/sdt.h 35.Fn SDT_PROVIDER_DECLARE prov 36.Fn SDT_PROVIDER_DEFINE prov 37.Fn SDT_PROBE_DECLARE prov mod func name 38.Fn SDT_PROBE_DEFINE prov mod func name sname 39.Fn SDT_PROBE_DEFINE0 prov mod func name sname 40.Fn SDT_PROBE_DEFINE1 prov mod func name sname arg0 41.Fn SDT_PROBE_DEFINE2 prov mod func name sname arg0 arg1 42.Fn SDT_PROBE_DEFINE3 prov mod func name sname arg0 arg1 arg2 43.Fn SDT_PROBE_DEFINE4 prov mod func name sname arg0 arg1 arg2 arg3 44.Fn SDT_PROBE_DEFINE5 prov mod func name sname arg0 arg1 arg2 arg3 arg4 45.Fn SDT_PROBE_DEFINE6 prov mod func name sname arg0 arg1 arg2 arg3 arg4 arg5 46.Fn SDT_PROBE_DEFINE7 prov mod func name sname arg0 arg1 arg2 arg3 arg4 arg5 \ 47 arg6 48.Fn SDT_PROBE0 prov mod func name 49.Fn SDT_PROBE1 prov mod func name arg0 50.Fn SDT_PROBE2 prov mod func name arg0 arg1 51.Fn SDT_PROBE3 prov mod func name arg0 arg1 arg2 52.Fn SDT_PROBE4 prov mod func name arg0 arg1 arg2 arg3 53.Fn SDT_PROBE5 prov mod func name arg0 arg1 arg2 arg3 arg4 54.Fn SDT_PROBE6 prov mod func name arg0 arg1 arg2 arg3 arg4 arg5 55.Fn SDT_PROBE7 prov mod func name arg0 arg1 arg2 arg3 arg4 arg5 arg6 56.Sh DESCRIPTION 57.Pp 58The 59.Nm 60macros allow programmers to define static trace points in kernel code. 61These trace points are used by the 62.Nm 63framework to create DTrace probes, allowing the code to be instrumented 64using 65.Xr dtrace 1 . 66By default, 67.Nm 68trace points are disabled and have no effect on the surrounding code. 69When a DTrace probe corresponding to a given trace point is enabled, threads 70that execute the trace point will call a handler and cause the probe to fire. 71Moreover, trace points can take arguments, making it possible to pass data 72to the DTrace framework when an enabled probe fires. 73.Pp 74Multiple trace points may correspond to a single DTrace probe, allowing 75programmers to create DTrace probes that correspond to logical system events 76rather than tying probes to specific code execution paths. 77For instance, a DTrace probe corresponding to the arrival of an IP packet into 78the network stack may be defined using two 79.Nm 80trace points: one for IPv4 packets and one for IPv6 packets. 81.Pp 82In addition to defining DTrace probes, the 83.Nm 84macros allow programmers to define new DTrace providers, making it possible to 85namespace logically-related probes. 86An example is FreeBSD's sctp provider, which contains 87.Nm 88probes for FreeBSD's 89.Xr sctp 4 90implementation. 91.Pp 92The 93.Fn SDT_PROVIDER_DECLARE 94and 95.Fn SDT_PROVIDER_DEFINE 96macros are used respectively to declare and define a DTrace provider named 97.Ar prov 98with the 99.Nm 100framework. 101A provider need only be defined once; however, the provider must be declared 102before defining any 103.Nm 104probes belonging to that provider. 105.Pp 106Similarly, the 107.Fn SDT_PROBE_DECLARE 108and 109.Fn SDT_PROBE_DEFINE* 110macros are used to declare and define DTrace probes using the 111.Nm 112framework. 113Once a probe has been defined, trace points for that probe may be added to 114kernel code. 115DTrace probe identifiers consist of a provider, module, function and name, all 116of which may be specified in the 117.Nm 118probe definition. 119Note that probes should not specify a module name: the module name of a probe is 120used to determine whether or not it should be destroyed when a kernel module is 121unloaded. 122See the 123.Sx BUGS 124section. 125Note in particular that probes must not be defined across multiple kernel 126modules. 127The 128.Fn SDT_PROBE_DEFINE* 129macros also take an extra 130.Ar sname 131parameter. 132This is used to allow the creation of probes with names containing the 133.Ql - 134character. 135Specifically, the 136.Ar name 137argument should contain the probe name with all dashes converted to underscores, 138and the 139.Ar sname 140argument should be the probe name as it will be referenced by D scripts. 141.Pp 142The 143.Fn SDT_PROBE_DEFINE* 144macros also allow programmers to declare the types of the arguments that are 145passed to probes. 146This is optional; if the argument types are omitted (through use of the 147.Fn SDT_PROBE_DEFINE 148macro), users wishing to make use of the arguments will have to manually cast 149them to the correct types in their D scripts. 150It is strongly recommended that probe definitions include a declaration of their 151argument types. 152.Pp 153The 154.Fn SDT_PROBE* 155macros are used to create 156.Nm 157trace points. 158They are meant to be added to executable code and can be used to instrument the 159code in which they are called. 160.Sh EXAMPLES 161.Pp 162The following probe definition will create a DTrace probe called 163.Ql icmp::unreach:pkt-receive , 164which would hypothetically be triggered when the kernel receives an ICMP packet 165of type Destination Unreachable: 166.Bd -literal -offset indent 167SDT_PROVIDER_DECLARE(icmp); 168 169SDT_PROBE_DEFINE2(icmp, , unreach, pkt_receive, pkt-receive, 170 "struct mbuf *", "struct icmp *"); 171 172.Ed 173This particular probe would take two arguments: a pointer to the 174.Xr mbuf 9 175containing the incoming packet, and a pointer to the ICMP header for the packet. 176Note that the module name of this probe is not specified. 177.Pp 178Consider a DTrace probe which fires when the network stack receives an IP 179packet. 180Such a probe would be defined by multiple tracepoints: 181.Bd -literal -offset indent 182SDT_PROBE_DEFINE2(ip, , , receive, receive, "struct mbuf *", 183 "struct ifnet *", "struct ip *", "struct ip6_hdr *"); 184 185int 186ip_input(struct mbuf *m) 187{ 188 struct ip *ip; 189 ... 190 ip = mtod(m, struct ip *); 191 SDT_PROBE4(ip, , , receive, m, m->m_pkthdr.rcvif, ip, NULL); 192 ... 193} 194 195int 196ip6_input(struct mbuf *m) 197{ 198 struct ip6_hdr *ip6; 199 ... 200 ip6 = mtod(m, struct ip6_hdr *); 201 SDT_PROBE4(ip, , , receive, m, m->m_pkthdr.rcvif, NULL, ip6); 202 ... 203} 204 205.Ed 206In particular, the probe should fire when the kernel receives either an IPv4 207packet or an IPv6 packet. 208.Sh SEE ALSO 209.Xr dtrace 1 210.Sh AUTHORS 211.An -nosplit 212DTrace and the 213.Nm 214framework were originally ported to FreeBSD from Solaris by 215.An John Birrell Aq jb@FreeBSD.org . 216This manual page was written by 217.An Mark Johnston Aq markj@FreeBSD.org . 218.Sh BUGS 219.Pp 220The 221.Nm 222macros allow the module name of a probe to be specified as part of a probe 223definition. 224However, the DTrace framework uses the module name of probes to determine 225which probes should be destroyed when a kernel module is unloaded, so the module 226name of a probe should match the name of the module in which its defined. 227.Nm 228will set the module name properly if it is left unspecified in the probe 229definition; see the 230.Sx EXAMPLES 231section. 232.Pp 233One of the goals of the original 234.Nm 235implementation (and by extension, of FreeBSD's port) is that inactive 236.Nm 237probes should have no performance impact. 238This is unfortunately not the case; 239.Nm 240trace points will add a small but non-zero amount of latency to the code 241in which they are defined. 242A more sophisticated implementation of the probes will help alleviate this 243problem. 244