From 71902863085ce10e904161e589e5556f9d4b878a Mon Sep 17 00:00:00 2001 From: avg Date: Mon, 17 Feb 2014 11:22:59 +0000 Subject: [PATCH] MFC r252895: Add a man page for the SDT_* macros git-svn-id: svn://svn.freebsd.org/base/stable/9@262021 ccf9f872-aa2e-dd11-9fc8-001c23d0bc1f --- share/man/man9/Makefile | 6 + share/man/man9/SDT.9 | 243 ++++++++++++++++++++++++++++++++++++++++ 2 files changed, 249 insertions(+) create mode 100644 share/man/man9/SDT.9 diff --git a/share/man/man9/Makefile b/share/man/man9/Makefile index 60245fca3..064dad45c 100644 --- a/share/man/man9/Makefile +++ b/share/man/man9/Makefile @@ -233,6 +233,7 @@ MAN= accept_filter.9 \ rwlock.9 \ sbuf.9 \ scheduler.9 \ + SDT.9 \ securelevel_gt.9 \ selrecord.9 \ sema.9 \ @@ -1128,6 +1129,11 @@ MLINKS+=scheduler.9 curpriority_cmp.9 \ scheduler.9 sched_setup.9 \ scheduler.9 setrunnable.9 \ scheduler.9 updatepri.9 +MLINKS+=SDT.9 SDT_PROVIDER_DECLARE.9 \ + SDT.9 SDT_PROVIDER_DEFINE.9 \ + SDT.9 SDT_PROBE_DECLARE.9 \ + SDT.9 SDT_PROBE_DEFINE.9 \ + SDT.9 SDT_PROBE.9 MLINKS+=securelevel_gt.9 securelevel_ge.9 MLINKS+=selrecord.9 seldrain.9 \ selrecord.9 selwakeup.9 diff --git a/share/man/man9/SDT.9 b/share/man/man9/SDT.9 new file mode 100644 index 000000000..38c35be7b --- /dev/null +++ b/share/man/man9/SDT.9 @@ -0,0 +1,243 @@ +.\" Copyright (c) 2013 Mark Johnston +.\" 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. -- 2.45.0