From owner-freebsd-dtrace@FreeBSD.ORG Fri Jul 5 03:25:00 2013 Return-Path: Delivered-To: freebsd-dtrace@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:1900:2254:206a::19:1]) by hub.freebsd.org (Postfix) with ESMTP id 4A10B813 for ; Fri, 5 Jul 2013 03:25:00 +0000 (UTC) (envelope-from markjdb@gmail.com) Received: from mail-yh0-x231.google.com (mail-yh0-x231.google.com [IPv6:2607:f8b0:4002:c01::231]) by mx1.freebsd.org (Postfix) with ESMTP id 13D711DE6 for ; Fri, 5 Jul 2013 03:25:00 +0000 (UTC) Received: by mail-yh0-f49.google.com with SMTP id v1so706386yhn.8 for ; Thu, 04 Jul 2013 20:24:59 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20120113; h=sender:date:from:to:subject:message-id:references:mime-version :content-type:content-disposition:in-reply-to:user-agent; bh=krEmr+CZ5CytMaqRIS8xA+jZULHG+wxHlEebYZQHmdc=; b=g4Jqzt1uFnjAcTKaPspXVTucRj45VInC3Yo2N93WV8/RHdveANz81FoG+vIq+tFWnD XlYFjy5szKJeBqlrdJyQmTYM+T4SM3D0SWo3zbPvqRkaEUSKl9yzi6hYPZ2QY6KdhKfG Hny3rYYXxw5iQtQ8e4aKisOGXEm21h0PCrS0nFQvsbo3SKQc6K54a0HOJQH/o5gUfYFB PAmh7+AfPQ8YAPBq6XkrfnXjwzdGQbTlb9nacspWL0QjipN1ittdQyZpQy7h1Iv+o4EK SbYHM2x1SGisXvIVLe1MWZujLJdETPQcvAe0Prc3NLC7jtn2AbDV0iDgbJFbDz7rENm6 nh3w== X-Received: by 10.236.202.211 with SMTP id d59mr4576528yho.221.1372994699510; Thu, 04 Jul 2013 20:24:59 -0700 (PDT) Received: from charmander ([173.243.41.218]) by mx.google.com with ESMTPSA id o32sm9929979yhi.5.2013.07.04.20.24.58 for (version=TLSv1 cipher=ECDHE-RSA-RC4-SHA bits=128/128); Thu, 04 Jul 2013 20:24:58 -0700 (PDT) Sender: Mark Johnston Date: Thu, 4 Jul 2013 23:25:36 -0400 From: Mark Johnston To: freebsd-dtrace@freebsd.org Subject: Re: [RFC] reworking FreeBSD's SDT implementation Message-ID: <20130705032536.GA1570@charmander> References: <20130703041023.GA82673@raichu> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <20130703041023.GA82673@raichu> User-Agent: Mutt/1.5.21 (2010-09-15) X-BeenThere: freebsd-dtrace@freebsd.org X-Mailman-Version: 2.1.14 Precedence: list List-Id: "A discussion list for developers working on DTrace in FreeBSD." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Fri, 05 Jul 2013 03:25:00 -0000 On Wed, Jul 03, 2013 at 12:10:23AM -0400, Mark Johnston wrote: > Hello, > > There are a few problems with the way SDT is currently implemented in > FreeBSD. First, the DTrace framework isn't notified when modules are > unloaded, so any probes created by these modules are never destroyed > (this problem isn't specific to SDT though, FBT probes have the same > problem). Second, there is currently nothing preventing one from > unloading a module while some of its SDT probes are enabled; doing this > will generally cause a panic. Finally, providers are "tied" to modules > in the sense that dtrace_unregister() is called on each provider > declared in a module when that module is unloaded. This is inflexible - > probes already have a "module" field to indicate which module they're > defined in, and it would restrict the implementation of, say, a > hypothetical GEOM or netgraph provider, which would probably contain > some common probes for each GEOM or netgraph module. Plus a panic will > occur if a probe from one module is enabled and a second module > declaring the provider of the probe is unloaded. > > I have a patch at [1] which tries to solve all of these problems. It > more or less completely reworks FreeBSD's SDT implementation (currently > contained in kern/kern_sdt.c and cddl/dev/sdt/sdt.c) and changes a > number of things: > > [...] > > I'm also writing a man page for the SDT macros so that there's some > guidance on how to create SDT probes and providers. I've copied a draft SDT man page below. Any suggestions/corrections/comments/criticisms are most welcome. I would also like to have man pages for individual providers, but this is a start. :) Thanks, -Mark SDT(9) FreeBSD Kernel Developer's Manual SDT(9) NAME SDT -- a DTrace framework for adding statically-defined tracing probes SYNOPSIS #include SDT_PROVIDER_DECLARE(prov); SDT_PROVIDER_DEFINE(prov); SDT_PROBE_DECLARE(prov, mod, func, name); SDT_PROBE_DEFINE(prov, mod, func, name, sname); SDT_PROBE_DEFINE0(prov, mod, func, name, sname); SDT_PROBE_DEFINE1(prov, mod, func, name, sname, arg0); SDT_PROBE_DEFINE2(prov, mod, func, name, sname, arg0, arg1); SDT_PROBE_DEFINE3(prov, mod, func, name, sname, arg0, arg1, arg2); SDT_PROBE_DEFINE4(prov, mod, func, name, sname, arg0, arg1, arg2, arg3); SDT_PROBE_DEFINE5(prov, mod, func, name, sname, arg0, arg1, arg2, arg3, arg4); SDT_PROBE_DEFINE6(prov, mod, func, name, sname, arg0, arg1, arg2, arg3, arg4, arg5); SDT_PROBE_DEFINE7(prov, mod, func, name, sname, arg0, arg1, arg2, arg3, arg4, arg5, arg6); SDT_PROBE0(prov, mod, func, name); SDT_PROBE1(prov, mod, func, name, arg0); SDT_PROBE2(prov, mod, func, name, arg0, arg1); SDT_PROBE3(prov, mod, func, name, arg0, arg1, arg2); SDT_PROBE4(prov, mod, func, name, arg0, arg1, arg2, arg3); SDT_PROBE5(prov, mod, func, name, arg0, arg1, arg2, arg3, arg4); SDT_PROBE6(prov, mod, func, name, arg0, arg1, arg2, arg3, arg4, arg5); SDT_PROBE7(prov, mod, func, name, arg0, arg1, arg2, arg3, arg4, arg5, arg6); DESCRIPTION The SDT macros allow programmers to define static trace points in kernel code. These trace points are used by the SDT framework to create DTrace probes, allowing the code to be instrumented using dtrace(1). By default, SDT trace points are disabled and have no effect on the sur- rounding 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, mak- ing 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 SDT trace points: one for IPv4 packets and one for IPv6 packets. In addition to defining DTrace probes, the SDT macros allow programmers to define new DTrace providers, making it possible to namespace logi- cally-related probes. An example is FreeBSD's sctp provider, which con- tains SDT probes for FreeBSD's sctp(4) implementation. The SDT_PROVIDER_DECLARE() and SDT_PROVIDER_DEFINE() macros are used respectively to declare and define a DTrace provider named prov with the SDT framework. A provider need only be defined once; however, the provider must be declared before defining any SDT probes belonging to that provider. Similarly, the SDT_PROBE_DECLARE() and SDT_PROBE_DEFINE*() macros are used to declare and define DTrace probes using the SDT framework. Once a probe has been defined, trace points for that probe may be added to ker- nel code. DTrace probe identifiers consist of a provider, module, func- tion and name, all of which may be specified in the SDT 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 BUGS section. Note in particular that probes must not be defined across multiple kernel modules. The SDT_PROBE_DEFINE*() macros also take an extra sname parameter. This is used to allow the creation of probes with names containing the `-' char- acter. Specifically, the name argument should contain the probe name with all dashes converted to underscores, and the sname argument should be the probe name as it will be referenced by D scripts. The 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 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 recom- mended that probe definitions include a declaration of their argument types. The SDT_PROBE*() macros are used to create SDT 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_DEFINE2(icmp, , unreach, pkt_receive, pkt-receive, "struct mbuf *", "struct icmp *"); This particular probe would take two arguments: a pointer to the 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. 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_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); ... } In particular, the probe should fire when the kernel receives either an IPv4 packet or an IPv6 packet. SEE ALSO dtrace(1) AUTHORS DTrace and the SDT framework were originally ported to FreeBSD from Solaris by John Birrell . This manual page was written by Mark Johnston . BUGS The SDT 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 ker- nel module is unloaded, so the module name of a probe should match the name of the module in which its defined. SDT will set the module name properly if it is left unspecified in the probe definition; see the EXAMPLES section. One of the goals of the original SDT implementation (and by extension, of FreeBSD's port) is that inactive SDT probes should have no performance impact. This is unfortunately not the case; SDT 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. FreeBSD 10.0 July 3, 2013 FreeBSD 10.0