SDT_PROBE_DEFINE (9)

Leading comments

Copyright (c) 2013-2015 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
   ...

(The comments found at the beginning of the groff file "man9/SDT_PROBE_DEFINE.9freebsd".)

NAME

SDT - a DTrace framework for adding statically-defined tracing probes

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 Fn SDT_PROBE_DEFINE0 prov mod func name Fn SDT_PROBE_DEFINE1 prov mod func name arg0 Fn SDT_PROBE_DEFINE2 prov mod func name arg0 arg1 Fn SDT_PROBE_DEFINE3 prov mod func name arg0 arg1 arg2 Fn SDT_PROBE_DEFINE4 prov mod func name arg0 arg1 arg2 arg3 Fn SDT_PROBE_DEFINE5 prov mod func name arg0 arg1 arg2 arg3 arg4 Fn SDT_PROBE_DEFINE6 prov mod func name arg0 arg1 arg2 arg3 arg4 arg5 Fn SDT_PROBE_DEFINE7 prov mod func name arg0 arg1 arg2 arg3 arg4 arg5
    arg6 Fn SDT_PROBE_DEFINE0_XLATE prov mod func name Fn SDT_PROBE_DEFINE1_XLATE prov mod func name arg0 xarg0 Fn SDT_PROBE_DEFINE2_XLATE prov mod func name arg0 xarg0 arg1 xarg1 Fn SDT_PROBE_DEFINE3_XLATE prov mod func name arg0 xarg0 arg1 xarg1
    arg2 xarg2 Fn SDT_PROBE_DEFINE4_XLATE prov mod func name arg0 xarg0 arg1 xarg1
    arg2 xarg2 arg3 xarg3 Fn SDT_PROBE_DEFINE5_XLATE prov mod func name arg0 xarg0 arg1 xarg1
    arg2 xarg2 arg3 xarg3 arg4 xarg4 Fn SDT_PROBE_DEFINE6_XLATE prov mod func name arg0 xarg0 arg1 xarg1
    arg2 xarg2 arg3 xarg3 arg4 xarg4 arg5 xarg5 Fn SDT_PROBE_DEFINE7_XLATE prov mod func name arg0 xarg0 arg1 xarg1
    arg2 xarg2 arg3 xarg3 arg4 xarg4 arg5 xarg5 arg6 xarg6 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

DESCRIPTION

The ifconfig macros allow programmers to define static trace points in kernel code. These trace points are used by the ifconfig framework to create DTrace probes, allowing the code to be instrumented using dtrace(1). By default, ifconfig 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.

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 ifconfig trace points: one for IPv4 packets and one for IPv6 packets.

In addition to defining DTrace probes, the ifconfig 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 ifconfig probes for FreeBSD's sctp(4) implementation.

The Fn SDT_PROVIDER_DECLARE and Fn SDT_PROVIDER_DEFINE macros are used respectively to declare and define a DTrace provider named prov with the ifconfig framework. A provider need only be defined once; however, the provider must be declared before defining any ifconfig probes belonging to that provider.

Similarly, the Fn SDT_PROBE_DECLARE and Fn SDT_PROBE_DEFINE* macros are used to declare and define DTrace probes using the ifconfig 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 ifconfig 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.

If `-' character (dash) is wanted in a probe name, then it should be represented as `__' (double underscore) in the probe name parameter passed to various Fn SDT_* macros, because of technical reasons (a dash is not valid in C identifiers).

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.

The Fn SDT_PROBE_DEFINE*_XLATE macros are used for probes whose argument types are to be dynamically translated to the types specified by the corresponding xarg arguments. This is mainly useful when porting probe definitions from other operating systems. As seen by dtrace(1), the arguments of a probe defined using these macros will have types which match the xarg types in the probe definition. However, the arguments passed in at the trace point will have types matching the native argument types in the probe definition, and thus the native type is dynamically translated to the translated type. So long as an appropriate translator is defined in /usr/lib/dtrace scripts making use of the probe need not concern themselves with the underlying type of a given ifconfig probe argument.

The Fn SDT_PROBE* macros are used to create ifconfig trace points. They are meant to be added to executable code and can be used to instrument the code in which they are called.

EXAMPLES

The following probe definition will create a DTrace probe called `icmp::unreach:pkt-receive' , which would hypothetically be triggered when the kernel receives an ICMP packet of type Destination Unreachable:

SDT_PROVIDER_DECLARE(icmp);

SDT_PROBE_DEFINE1(icmp, , unreach, pkt__receive,
    "struct icmp *");

This particular probe would take a single argument: a pointer to the struct containing the ICMP header for the packet. Note that the module name of this probe is not specified.

Consider a DTrace probe which fires when the network stack receives an IP packet. Such a probe would be defined by multiple tracepoints:

SDT_PROBE_DEFINE3(ip, , , receive, "struct ifnet *",
    "struct ip *", "struct ip6_hdr *");

int
ip_input(struct mbuf *m)
{
        struct ip *ip;
        ...
        ip = mtod(m, struct ip *);
        SDT_PROBE3(ip, , , receive, m->m_pkthdr.rcvif, ip, NULL);
        ...
}

int
ip6_input(struct mbuf *m)
{
        struct ip6_hdr *ip6;
        ...
        ip6 = mtod(m, struct ip6_hdr *);
        SDT_PROBE3(ip, , , receive, m->m_pkthdr.rcvif, NULL, ip6);
        ...
}

In particular, the probe should fire when the kernel receives either an IPv4 packet or an IPv6 packet.

Consider the ICMP probe discussed above. We note that its second argument is of type struct icmp which is a type defined in the FreeBSD kernel to represent the ICMP header of an ICMP packet, defined in RFC 792. Linux has a corresponding type, struct icmphdr for the same purpose, but its field names differ from FreeBSD's struct icmp Similarly, illumos defines the icmph_t type, again with different field names. Even with the `icmp:::pkt-receive' probes defined in all three operating systems, one would still have to write OS-specific scripts to extract a given field out of the ICMP header argument. Dynamically-translated types solve this problem: one can define an OS-independent c(7) struct to represent an ICMP header, say struct icmp_hdr_dt and define translators from each of the three OS-specific types to struct icmp_hdr_dt all in the dtrace(1) library path. Then the FreeBSD probe above can be defined with:

SDT_PROBE_DEFINE1_XLATE(ip, , , receive, "struct icmp *",
    "struct icmp_hdr_dt *");

SEE ALSO

dtrace(1)

AUTHORS

An -nosplit DTrace and the ifconfig 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 .

BUGS

The ifconfig 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. ifconfig will set the module name properly if it is left unspecified in the probe definition; see the Sx EXAMPLES section.

One of the goals of the original ifconfig implementation (and by extension, of FreeBSD's port) is that inactive ifconfig probes should have no performance impact. This is unfortunately not the case; ifconfig 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.