diff options
3 files changed, 95 insertions, 38 deletions
diff --git a/doc/SystemTap_Beginners_Guide/en-US/Scripts.xml b/doc/SystemTap_Beginners_Guide/en-US/Scripts.xml index bbd265c2..e8f9c3cb 100644 --- a/doc/SystemTap_Beginners_Guide/en-US/Scripts.xml +++ b/doc/SystemTap_Beginners_Guide/en-US/Scripts.xml @@ -56,25 +56,15 @@ probe <replaceable>[event]</replaceable>, <section id="systemtapscript-events"> <title>Events</title> -<para> - SystemTap supports multiple events per probe; as shown in <xref linkend="scriptformats"/>, multiple events are delimited by a comma (<command>,</command>). Sample <replaceable>[event]</replaceable>s include:</para> +<para>SystemTap events can be broadly classified into two types: <firstterm>synchronous</firstterm> and <firstterm>asynchronous</firstterm>.</para> -<variablelist> - -<varlistentry> - <term>begin</term> - <listitem> - <para>The startup of a SystemTap session; i.e. as soon as the SystemTap script is run.</para> - </listitem> -</varlistentry> +<formalpara><title>Synchronous Events</title> + <para>A <firstterm>synchronous</firstterm> event occurs when any processor executes an instruction matched by the specification. This gives other events a reference point (or instruction address) from which more contextual data may be available.</para> +</formalpara> -<varlistentry> - <term>end</term> - <listitem> - <para>The end of a SystemTap session.</para> - </listitem> -</varlistentry> +<para>Examples of synchronous events include:</para> +<variablelist> <varlistentry> <term>kernel.function("<replaceable>[function]</replaceable>")</term> <listitem> @@ -100,6 +90,56 @@ probe kernel.function("*@net/socket.c").return { } <para>To identify what system calls are made by a specific program/command, use <command>strace <replaceable>command</replaceable></command>.</para> </listitem> </varlistentry> + +<varlistentry> + <term>module("<replaceable>[module]</replaceable>").function("<replaceable>[function]</replaceable>")</term> + <listitem> + <para>Allows you to probe functions within modules. For example:</para> + + <example id="eventsmodules"><title>Module Probe</title> + <programlisting> + probe module("ext3").function("*") { } + probe module("ext3").function("*").return { } + </programlisting> + </example> + + <para> + The first probe in <xref linkend="eventsmodules"/> points to the entry of <emphasis>all</emphasis> functions for the <filename>ext3</filename> module. The second probe points to the exits of all entries for that same module; the use of the <command>.return</command> suffix is similar to <command>kernel.function()</command>. Note that the probes in <xref linkend="eventsmodules"/> also do not contain probe bodies, and as such will not print any useful data (as in <xref linkend="wildcards"/>). + </para> + + <para> + A system's loaded modules are typically located in <filename>/lib/modules/<replaceable>[kernel version]</replaceable></filename>, where <replaceable>kernel version</replaceable> refers to the currently loaded kernel. Modules use the filename extension <filename>.ko</filename>. + </para> + + </listitem> +</varlistentry> +</variablelist> + + +<formalpara> + <title>Asynchronous Events</title> + <para><firstterm>Asynchronous</firstterm> events, on the other hand, do not point to any reference point. This family of probe points consists mainly of counters, timers, and similar constructs.</para> +</formalpara> + + <para>Examples of asynchronous events include:</para> + +<variablelist> + +<varlistentry> + <term>begin</term> + <listitem> + <para>The startup of a SystemTap session; i.e. as soon as the SystemTap script is run.</para> + </listitem> +</varlistentry> + +<varlistentry> + <term>end</term> + <listitem> + <para>The end of a SystemTap session.</para> + </listitem> +</varlistentry> + + <varlistentry> <term>timer.ms()</term> @@ -122,28 +162,7 @@ probe timer.ms(4000) </listitem> </varlistentry> -<varlistentry> - <term>module("<replaceable>[module]</replaceable>").function("<replaceable>[function]</replaceable>")</term> - <listitem> - <para>Allows you to probe functions within modules. For example:</para> - -<example id="eventsmodules"><title>Module Probe</title> -<programlisting> -probe module("ext3").function("*") { }
-probe module("ext3").function("*").return { } -</programlisting> -</example> - - <para> - The first probe in <xref linkend="eventsmodules"/> points to the entry of <emphasis>all</emphasis> functions for the <filename>ext3</filename> module. The second probe points to the exits of all entries for that same module; the use of the <command>.return</command> suffix is similar to <command>kernel.function()</command>. Note that the probes in <xref linkend="eventsmodules"/> also do not contain probe bodies, and as such will not print any useful data (as in <xref linkend="wildcards"/>). - </para> - - <para> - A system's loaded modules are typically located in <filename>/lib/modules/<replaceable>[kernel version]</replaceable></filename>, where <replaceable>kernel version</replaceable> refers to the currently loaded kernel. Modules use the filename extension <filename>.ko</filename>. - </para> - </listitem> -</varlistentry> <!--<remark>add timer.ms() to events list!</remark>--> <!-- @@ -164,7 +183,12 @@ probe module("ext3").function("*").return { } </para> </important> +<para> + SystemTap supports multiple events per probe; as shown in <xref linkend="scriptformats"/>, multiple events are delimited by a comma (<command>,</command>). If multiple events are specified in a single probe, SystemTap will execute the handler when any of the specified events occur. +</para> + <remark>is reference appropriate? too advanced for readers (it seems so to me)? please advise.</remark> + </section> <section id="systemtapscript-handlers"> diff --git a/doc/SystemTap_Beginners_Guide/en-US/Understanding_How_SystemTap_Works.xml b/doc/SystemTap_Beginners_Guide/en-US/Understanding_How_SystemTap_Works.xml index 76296507..116e7453 100644 --- a/doc/SystemTap_Beginners_Guide/en-US/Understanding_How_SystemTap_Works.xml +++ b/doc/SystemTap_Beginners_Guide/en-US/Understanding_How_SystemTap_Works.xml @@ -59,7 +59,34 @@ <remark> definition, significance, difference with stap scripts (previous section), library of tapsets in system: location - </remark> + </remark> + + <para> + <firstterm>Tapsets</firstterm> are scripts that form a library of pre-written probes and functions to be used in SystemTap scripts. When a user runs a SystemTap script, SystemTap checks the script's probe events and handlers against the tapset library; SystemTap then loads the corresponding probes and functions before translating the script to C (refer to <xref linkend="understanding-architecture-tools"/> for information on what transpires in a SystemTap session). + </para> +<!-- + <para> + Simply put, the tapset library is an abstraction layer designed to make it easier for users to define events and functions. In a way, tapsets provide useful "aliases" for functions that users may want to specify as an event; knowing the proper alias to use is, for the most part, easier than understanding how to specify a specific kernel function. + </para> + --> + <para> + Like SystemTap scripts, tapsets use the filename extension <filename>.stp</filename>. The standard library of tapsets is located in <filename>/usr/share/systemtap/tapset/</filename> by default. However, unlike SystemTap scripts, tapsets are not meant for direct execution; rather, they constitute the library from which other scripts can pull definitions. + </para> + + + <para> + Simply put, the tapset library is an abstraction layer designed to make it easier for users to define events and functions. In a manner of speaking, tapsets provide useful "aliases" for functions that users may want to specify as an event; knowing the proper alias to use is, for the most part, easier than understanding how to specify a specific kernel function. + </para> + + <para> + Several handlers and functions in <xref linkend="systemtapscript-events"/> and <xref linkend="systemtapscript-handlers"/> are defined in tapsets. For example, <command>thread_indent()</command> is defined in <filename>indent.stp</filename>. + </para> + + +<remark> + any other details to be included? i dont want to dwell too long here, though, since IMHO tapset development is beyond the scope of this "beginner's guide" +</remark> + </section> </chapter> diff --git a/doc/SystemTap_Beginners_Guide/en-US/Using_SystemTap.xml b/doc/SystemTap_Beginners_Guide/en-US/Using_SystemTap.xml index f3f7a276..dfb345c8 100644 --- a/doc/SystemTap_Beginners_Guide/en-US/Using_SystemTap.xml +++ b/doc/SystemTap_Beginners_Guide/en-US/Using_SystemTap.xml @@ -12,10 +12,16 @@ <remark> required packages, installation thru yum, repos (?); possibly, a script to install all required packages </remark> + + <remark> + notes in ~/Desktop/SystemTap/aug21chatlog and ~/Desktop/SystemTap/noted_wcohenmeeting + </remark> <formalpara> <title>Cross-Compiling</title> <para>TBD</para> </formalpara> +<remark>cross-compiling script from here: http://sources.redhat.com/ml/systemtap/2008-q3/msg00310.html</remark> + <remark>above; add short description, significance, howto, script (test first)</remark> </section> |