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 57The 58.Nm 59macros allow programmers to define static trace points in kernel code. 60These trace points are used by the 61.Nm 62framework to create DTrace probes, allowing the code to be instrumented 63using 64.Xr dtrace 1 . 65By default, 66.Nm 67trace points are disabled and have no effect on the surrounding code. 68When a DTrace probe corresponding to a given trace point is enabled, threads 69that execute the trace point will call a handler and cause the probe to fire. 70Moreover, trace points can take arguments, making it possible to pass data 71to the DTrace framework when an enabled probe fires. 72.Pp 73Multiple trace points may correspond to a single DTrace probe, allowing 74programmers to create DTrace probes that correspond to logical system events 75rather than tying probes to specific code execution paths. 76For instance, a DTrace probe corresponding to the arrival of an IP packet into 77the network stack may be defined using two 78.Nm 79trace points: one for IPv4 packets and one for IPv6 packets. 80.Pp 81In addition to defining DTrace probes, the 82.Nm 83macros allow programmers to define new DTrace providers, making it possible to 84namespace logically-related probes. 85An example is FreeBSD's sctp provider, which contains 86.Nm 87probes for FreeBSD's 88.Xr sctp 4 89implementation. 90.Pp 91The 92.Fn SDT_PROVIDER_DECLARE 93and 94.Fn SDT_PROVIDER_DEFINE 95macros are used respectively to declare and define a DTrace provider named 96.Ar prov 97with the 98.Nm 99framework. 100A provider need only be defined once; however, the provider must be declared 101before defining any 102.Nm 103probes belonging to that provider. 104.Pp 105Similarly, the 106.Fn SDT_PROBE_DECLARE 107and 108.Fn SDT_PROBE_DEFINE* 109macros are used to declare and define DTrace probes using the 110.Nm 111framework. 112Once a probe has been defined, trace points for that probe may be added to 113kernel code. 114DTrace probe identifiers consist of a provider, module, function and name, all 115of which may be specified in the 116.Nm 117probe definition. 118Note that probes should not specify a module name: the module name of a probe is 119used to determine whether or not it should be destroyed when a kernel module is 120unloaded. 121See the 122.Sx BUGS 123section. 124Note in particular that probes must not be defined across multiple kernel 125modules. 126The 127.Fn SDT_PROBE_DEFINE* 128macros also take an extra 129.Ar sname 130parameter. 131This is used to allow the creation of probes with names containing the 132.Ql - 133character. 134Specifically, the 135.Ar name 136argument should contain the probe name with all dashes converted to underscores, 137and the 138.Ar sname 139argument should be the probe name as it will be referenced by D scripts. 140.Pp 141The 142.Fn SDT_PROBE_DEFINE* 143macros also allow programmers to declare the types of the arguments that are 144passed to probes. 145This is optional; if the argument types are omitted (through use of the 146.Fn SDT_PROBE_DEFINE 147macro), users wishing to make use of the arguments will have to manually cast 148them to the correct types in their D scripts. 149It is strongly recommended that probe definitions include a declaration of their 150argument types. 151.Pp 152The 153.Fn SDT_PROBE* 154macros are used to create 155.Nm 156trace points. 157They are meant to be added to executable code and can be used to instrument the 158code in which they are called. 159.Sh EXAMPLES 160The following probe definition will create a DTrace probe called 161.Ql icmp::unreach:pkt-receive , 162which would hypothetically be triggered when the kernel receives an ICMP packet 163of type Destination Unreachable: 164.Bd -literal -offset indent 165SDT_PROVIDER_DECLARE(icmp); 166 167SDT_PROBE_DEFINE2(icmp, , unreach, pkt_receive, pkt-receive, 168 "struct mbuf *", "struct icmp *"); 169 170.Ed 171This particular probe would take two arguments: a pointer to the 172.Xr mbuf 9 173containing the incoming packet, and a pointer to the ICMP header for the packet. 174Note that the module name of this probe is not specified. 175.Pp 176Consider a DTrace probe which fires when the network stack receives an IP 177packet. 178Such a probe would be defined by multiple tracepoints: 179.Bd -literal -offset indent 180SDT_PROBE_DEFINE2(ip, , , receive, receive, "struct mbuf *", 181 "struct ifnet *", "struct ip *", "struct ip6_hdr *"); 182 183int 184ip_input(struct mbuf *m) 185{ 186 struct ip *ip; 187 ... 188 ip = mtod(m, struct ip *); 189 SDT_PROBE4(ip, , , receive, m, m->m_pkthdr.rcvif, ip, NULL); 190 ... 191} 192 193int 194ip6_input(struct mbuf *m) 195{ 196 struct ip6_hdr *ip6; 197 ... 198 ip6 = mtod(m, struct ip6_hdr *); 199 SDT_PROBE4(ip, , , receive, m, m->m_pkthdr.rcvif, NULL, ip6); 200 ... 201} 202 203.Ed 204In particular, the probe should fire when the kernel receives either an IPv4 205packet or an IPv6 packet. 206.Sh SEE ALSO 207.Xr dtrace 1 208.Sh AUTHORS 209.An -nosplit 210DTrace and the 211.Nm 212framework were originally ported to FreeBSD from Solaris by 213.An John Birrell Aq jb@FreeBSD.org . 214This manual page was written by 215.An Mark Johnston Aq markj@FreeBSD.org . 216.Sh BUGS 217The 218.Nm 219macros allow the module name of a probe to be specified as part of a probe 220definition. 221However, the DTrace framework uses the module name of probes to determine 222which probes should be destroyed when a kernel module is unloaded, so the module 223name of a probe should match the name of the module in which its defined. 224.Nm 225will set the module name properly if it is left unspecified in the probe 226definition; see the 227.Sx EXAMPLES 228section. 229.Pp 230One of the goals of the original 231.Nm 232implementation (and by extension, of FreeBSD's port) is that inactive 233.Nm 234probes should have no performance impact. 235This is unfortunately not the case; 236.Nm 237trace points will add a small but non-zero amount of latency to the code 238in which they are defined. 239A more sophisticated implementation of the probes will help alleviate this 240problem. 241