From owner-svn-src-all@FreeBSD.ORG Sat Jul 6 20:31:22 2013 Return-Path: Delivered-To: svn-src-all@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [8.8.178.115]) by hub.freebsd.org (Postfix) with ESMTP id BB89F8F9; Sat, 6 Jul 2013 20:31:22 +0000 (UTC) (envelope-from markj@FreeBSD.org) Received: from svn.freebsd.org (svn.freebsd.org [IPv6:2001:1900:2254:2068::e6a:0]) by mx1.freebsd.org (Postfix) with ESMTP id AC0CF1390; Sat, 6 Jul 2013 20:31:22 +0000 (UTC) Received: from svn.freebsd.org ([127.0.1.70]) by svn.freebsd.org (8.14.7/8.14.7) with ESMTP id r66KVMcj099131; Sat, 6 Jul 2013 20:31:22 GMT (envelope-from markj@svn.freebsd.org) Received: (from markj@localhost) by svn.freebsd.org (8.14.7/8.14.5/Submit) id r66KVMt8099129; Sat, 6 Jul 2013 20:31:22 GMT (envelope-from markj@svn.freebsd.org) Message-Id: <201307062031.r66KVMt8099129@svn.freebsd.org> From: Mark Johnston Date: Sat, 6 Jul 2013 20:31:22 +0000 (UTC) To: src-committers@freebsd.org, svn-src-all@freebsd.org, svn-src-head@freebsd.org Subject: svn commit: r252895 - head/share/man/man9 X-SVN-Group: head MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit X-BeenThere: svn-src-all@freebsd.org X-Mailman-Version: 2.1.14 Precedence: list List-Id: "SVN commit messages for the entire src tree \(except for " user" and " projects" \)" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Sat, 06 Jul 2013 20:31:22 -0000 Author: markj Date: Sat Jul 6 20:31:22 2013 New Revision: 252895 URL: http://svnweb.freebsd.org/changeset/base/252895 Log: Add a man page for the SDT_* macros, which can be used to define new static DTrace probes and providers in kernel code. MFC after: 1 week Added: head/share/man/man9/SDT.9 (contents, props changed) Modified: head/share/man/man9/Makefile Modified: head/share/man/man9/Makefile ============================================================================== --- head/share/man/man9/Makefile Sat Jul 6 20:21:35 2013 (r252894) +++ head/share/man/man9/Makefile Sat Jul 6 20:31:22 2013 (r252895) @@ -236,6 +236,7 @@ MAN= accept_filter.9 \ rwlock.9 \ sbuf.9 \ scheduler.9 \ + SDT.9 \ securelevel_gt.9 \ selrecord.9 \ sema.9 \ @@ -1147,6 +1148,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 Added: head/share/man/man9/SDT.9 ============================================================================== --- /dev/null 00:00:00 1970 (empty, because file is newly added) +++ head/share/man/man9/SDT.9 Sat Jul 6 20:31:22 2013 (r252895) @@ -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.