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 August 17, 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 39.Fn SDT_PROBE_DEFINE0 prov mod func name 40.Fn SDT_PROBE_DEFINE1 prov mod func name arg0 41.Fn SDT_PROBE_DEFINE2 prov mod func name arg0 arg1 42.Fn SDT_PROBE_DEFINE3 prov mod func name arg0 arg1 arg2 43.Fn SDT_PROBE_DEFINE4 prov mod func name arg0 arg1 arg2 arg3 44.Fn SDT_PROBE_DEFINE5 prov mod func name arg0 arg1 arg2 arg3 arg4 45.Fn SDT_PROBE_DEFINE6 prov mod func name arg0 arg1 arg2 arg3 arg4 arg5 46.Fn SDT_PROBE_DEFINE7 prov mod func name arg0 arg1 arg2 arg3 arg4 arg5 \ 47 arg6 48.Fn SDT_PROBE_DEFINE0_XLATE prov mod func name 49.Fn SDT_PROBE_DEFINE1_XLATE prov mod func name arg0 xarg0 50.Fn SDT_PROBE_DEFINE2_XLATE prov mod func name arg0 xarg0 arg1 xarg1 51.Fn SDT_PROBE_DEFINE3_XLATE prov mod func name arg0 xarg0 arg1 xarg1 \ 52 arg2 xarg2 53.Fn SDT_PROBE_DEFINE4_XLATE prov mod func name arg0 xarg0 arg1 xarg1 \ 54 arg2 xarg2 arg3 xarg3 55.Fn SDT_PROBE_DEFINE5_XLATE prov mod func name arg0 xarg0 arg1 xarg1 \ 56 arg2 xarg2 arg3 xarg3 arg4 xarg4 57.Fn SDT_PROBE_DEFINE6_XLATE prov mod func name arg0 xarg0 arg1 xarg1 \ 58 arg2 xarg2 arg3 xarg3 arg4 xarg4 arg5 xarg5 59.Fn SDT_PROBE_DEFINE7_XLATE prov mod func name arg0 xarg0 arg1 xarg1 \ 60 arg2 xarg2 arg3 xarg3 arg4 xarg4 arg5 xarg5 arg6 xarg6 61.Fn SDT_PROBE0 prov mod func name 62.Fn SDT_PROBE1 prov mod func name arg0 63.Fn SDT_PROBE2 prov mod func name arg0 arg1 64.Fn SDT_PROBE3 prov mod func name arg0 arg1 arg2 65.Fn SDT_PROBE4 prov mod func name arg0 arg1 arg2 arg3 66.Fn SDT_PROBE5 prov mod func name arg0 arg1 arg2 arg3 arg4 67.Fn SDT_PROBE6 prov mod func name arg0 arg1 arg2 arg3 arg4 arg5 68.Fn SDT_PROBE7 prov mod func name arg0 arg1 arg2 arg3 arg4 arg5 arg6 69.Sh DESCRIPTION 70The 71.Nm 72macros allow programmers to define static trace points in kernel code. 73These trace points are used by the 74.Nm 75framework to create DTrace probes, allowing the code to be instrumented 76using 77.Xr dtrace 1 . 78By default, 79.Nm 80trace points are disabled and have no effect on the surrounding code. 81When a DTrace probe corresponding to a given trace point is enabled, threads 82that execute the trace point will call a handler and cause the probe to fire. 83Moreover, trace points can take arguments, making it possible to pass data 84to the DTrace framework when an enabled probe fires. 85.Pp 86Multiple trace points may correspond to a single DTrace probe, allowing 87programmers to create DTrace probes that correspond to logical system events 88rather than tying probes to specific code execution paths. 89For instance, a DTrace probe corresponding to the arrival of an IP packet into 90the network stack may be defined using two 91.Nm 92trace points: one for IPv4 packets and one for IPv6 packets. 93.Pp 94In addition to defining DTrace probes, the 95.Nm 96macros allow programmers to define new DTrace providers, making it possible to 97namespace logically-related probes. 98An example is FreeBSD's sctp provider, which contains 99.Nm 100probes for FreeBSD's 101.Xr sctp 4 102implementation. 103.Pp 104The 105.Fn SDT_PROVIDER_DECLARE 106and 107.Fn SDT_PROVIDER_DEFINE 108macros are used respectively to declare and define a DTrace provider named 109.Ar prov 110with the 111.Nm 112framework. 113A provider need only be defined once; however, the provider must be declared 114before defining any 115.Nm 116probes belonging to that provider. 117.Pp 118Similarly, the 119.Fn SDT_PROBE_DECLARE 120and 121.Fn SDT_PROBE_DEFINE* 122macros are used to declare and define DTrace probes using the 123.Nm 124framework. 125Once a probe has been defined, trace points for that probe may be added to 126kernel code. 127DTrace probe identifiers consist of a provider, module, function and name, all 128of which may be specified in the 129.Nm 130probe definition. 131Note that probes should not specify a module name: the module name of a probe is 132used to determine whether or not it should be destroyed when a kernel module is 133unloaded. 134See the 135.Sx BUGS 136section. 137Note in particular that probes must not be defined across multiple kernel 138modules. 139.Pp 140If 141.Ql - 142character (dash) is wanted in a probe name, 143then it should be represented as 144.Ql __ 145(double underscore) in the probe 146.Ar name 147parameter passed to various 148.Fn SDT_* 149macros, 150because of technical reasons 151(a dash is not valid in C identifiers). 152.Pp 153The 154.Fn SDT_PROBE_DEFINE* 155macros also allow programmers to declare the types of the arguments that are 156passed to probes. 157This is optional; if the argument types are omitted (through use of the 158.Fn SDT_PROBE_DEFINE 159macro), users wishing to make use of the arguments will have to manually cast 160them to the correct types in their D scripts. 161It is strongly recommended that probe definitions include a declaration of their 162argument types. 163.Pp 164The 165.Fn SDT_PROBE_DEFINE*_XLATE 166macros are used for probes whose argument types are to be dynamically translated 167to the types specified by the corresponding 168.Ar xarg 169arguments. 170This is mainly useful when porting probe definitions from other operating 171systems. 172As seen by 173.Xr dtrace 1 , 174the arguments of a probe defined using these macros will have types which match 175the 176.Ar xarg 177types in the probe definition. 178However, the arguments passed in at the trace point will have types matching the 179native argument types in the probe definition, and thus the native type is 180dynamically translated to the translated type. 181So long as an appropriate translator is defined in 182.Pa /usr/lib/dtrace , 183scripts making use of the probe need not concern themselves with the underlying 184type of a given 185.Nm 186probe argument. 187.Pp 188The 189.Fn SDT_PROBE* 190macros are used to create 191.Nm 192trace points. 193They are meant to be added to executable code and can be used to instrument the 194code in which they are called. 195.Sh EXAMPLES 196The following probe definition will create a DTrace probe called 197.Ql icmp::unreach:pkt-receive , 198which would hypothetically be triggered when the kernel receives an ICMP packet 199of type Destination Unreachable: 200.Bd -literal -offset indent 201SDT_PROVIDER_DECLARE(icmp); 202 203SDT_PROBE_DEFINE1(icmp, , unreach, pkt_receive, pkt-receive, 204 "struct icmp *"); 205 206.Ed 207This particular probe would take a single argument: a pointer to the struct 208containing the ICMP header for the packet. 209Note that the module name of this probe is not specified. 210.Pp 211Consider a DTrace probe which fires when the network stack receives an IP 212packet. 213Such a probe would be defined by multiple tracepoints: 214.Bd -literal -offset indent 215SDT_PROBE_DEFINE3(ip, , , receive, receive, "struct ifnet *", 216 "struct ip *", "struct ip6_hdr *"); 217 218int 219ip_input(struct mbuf *m) 220{ 221 struct ip *ip; 222 ... 223 ip = mtod(m, struct ip *); 224 SDT_PROBE3(ip, , , receive, m->m_pkthdr.rcvif, ip, NULL); 225 ... 226} 227 228int 229ip6_input(struct mbuf *m) 230{ 231 struct ip6_hdr *ip6; 232 ... 233 ip6 = mtod(m, struct ip6_hdr *); 234 SDT_PROBE3(ip, , , receive, m->m_pkthdr.rcvif, NULL, ip6); 235 ... 236} 237 238.Ed 239In particular, the probe should fire when the kernel receives either an IPv4 240packet or an IPv6 packet. 241.Pp 242Consider the ICMP probe discussed above. 243We note that its second argument is of type 244.Ar struct icmp , 245which is a type defined in the FreeBSD kernel to represent the ICMP header of 246an ICMP packet, defined in RFC 792. 247Linux has a corresponding type, 248.Ar struct icmphdr , 249for the same purpose, but its field names differ from FreeBSD's 250.Ar struct icmp . 251Similarly, illumos defines the 252.Ar icmph_t 253type, again with different field names. 254Even with the 255.Ql icmp:::pkt-receive 256probes defined in all three operating systems, 257one would still have to write OS-specific scripts to extract a given field out 258of the ICMP header argument. 259Dynamically-translated types solve this problem: one can define an 260OS-independent 261.Xr c 7 262struct to represent an ICMP header, say 263.Ar struct icmp_hdr_dt , 264and define translators from each of the three OS-specific types to 265.Ar struct icmp_hdr_dt , 266all in the 267.Xr dtrace 1 268library path. 269Then the FreeBSD probe above can be defined with: 270.Bd -literal -offset indent 271SDT_PROBE_DEFINE1_XLATE(ip, , , receive, receive, "struct icmp *", 272 "struct icmp_hdr_dt *"); 273.Ed 274.Sh SEE ALSO 275.Xr dtrace 1 276.Sh AUTHORS 277.An -nosplit 278DTrace and the 279.Nm 280framework were originally ported to FreeBSD from Solaris by 281.An John Birrell Aq jb@FreeBSD.org . 282This manual page was written by 283.An Mark Johnston Aq markj@FreeBSD.org . 284.Sh BUGS 285The 286.Nm 287macros allow the module name of a probe to be specified as part of a probe 288definition. 289However, the DTrace framework uses the module name of probes to determine 290which probes should be destroyed when a kernel module is unloaded, so the module 291name of a probe should match the name of the module in which its defined. 292.Nm 293will set the module name properly if it is left unspecified in the probe 294definition; see the 295.Sx EXAMPLES 296section. 297.Pp 298One of the goals of the original 299.Nm 300implementation (and by extension, of FreeBSD's port) is that inactive 301.Nm 302probes should have no performance impact. 303This is unfortunately not the case; 304.Nm 305trace points will add a small but non-zero amount of latency to the code 306in which they are defined. 307A more sophisticated implementation of the probes will help alleviate this 308problem. 309