diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/SystemTap_Tapset_Reference/tapsets.tmpl | 25 | ||||
| -rw-r--r-- | doc/Tapset_Reference_Guide/en-US/Introduction.xml | 59 | ||||
| -rw-r--r-- | doc/Tapset_Reference_Guide/en-US/Tapset_Dev_Guide.xml | 117 | ||||
| -rwxr-xr-x | doc/Tapset_Reference_Guide/publicanize.sh | 25 |
4 files changed, 211 insertions, 15 deletions
diff --git a/doc/SystemTap_Tapset_Reference/tapsets.tmpl b/doc/SystemTap_Tapset_Reference/tapsets.tmpl index d6b3b309..798cfb3b 100644 --- a/doc/SystemTap_Tapset_Reference/tapsets.tmpl +++ b/doc/SystemTap_Tapset_Reference/tapsets.tmpl @@ -51,9 +51,9 @@ </para> </legalnotice> </bookinfo> - +<!-- pls dont remove marker comments, as they are used in publican conversion--> <toc></toc> - +<!--starthere--> <chapter id="introduction"> <title>Introduction</title> <para> @@ -98,7 +98,6 @@ the kernel. This is common among asynchronous events such as timers, exit functions, and print functions. </para> - <!-- <varlistentry> <term></term> @@ -111,11 +110,13 @@ </section> </chapter> - +<!--endhere--> +<!--markerforxi--> +<!-- pls dont remove marker comments, as they are used in publican conversion--> <chapter id="context_stp"> <title>Context Functions</title> <para> - The context functions provide additional information about the where + The context functions provide additional information about where the event occurred. These functions can provide information such as a backtrace where the event occured @@ -130,7 +131,7 @@ <title>Timestamp Functions</title> <para> Each timestamp function returns a value to indicate when - the function is executed. + a function is executed. Thus, these returned values can be used to indicate when an event occurs, provide an ordering for events, or compute the amount of time elapsed between to time stamps. @@ -165,9 +166,11 @@ <title>Networking Tapset</title> <para> This family of probe points is used to probe the activities of - network device. + the network device, TCP layer, and UDP layer. </para> !Itapset/networking.stp +!Itapset/tcp.stp +!Itapset/udp.stp </chapter> <chapter id="socket.stp"> @@ -178,14 +181,14 @@ </para> !Itapset/socket.stp </chapter> - +<!-- <chapter id="tcp.stp"> <title>TCP Tapset</title> <para> This family of probe points is used to probe TCP layer activities. It contains the following probe points: </para> -!Itapset/tcp.stp + </chapter> <chapter id="upd.stp"> @@ -194,9 +197,9 @@ This family of probe points is used to probe UDP layer activities. It contains the following probe points: </para> -!Itapset/udp.stp - </chapter> + </chapter> +--> <chapter id="process.stp"> <title>Process Tapset</title> <para> diff --git a/doc/Tapset_Reference_Guide/en-US/Introduction.xml b/doc/Tapset_Reference_Guide/en-US/Introduction.xml new file mode 100644 index 00000000..633521e1 --- /dev/null +++ b/doc/Tapset_Reference_Guide/en-US/Introduction.xml @@ -0,0 +1,59 @@ +<?xml version='1.0'?> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ +]> + +<chapter id="introduction"> + <title>Introduction</title> + + <para> + SystemTap provides free software (GPL) infrastructure to simplify the + gathering of information about the running Linux system. This assists + diagnosis of a performance or functional problem. SystemTap eliminates the + need for the developer to go through the tedious and disruptive instrument, + recompile, install, and reboot sequence that may be otherwise required to + collect data. + </para> + + <para> + SystemTap provides a simple command line interface and scripting language + for writing instrumentation for a live, running kernel. This instrumentation + uses probe points and functions provided in the <firstterm>tapset</firstterm> library. + </para> + + <para> + Simply put, tapsets are scripts that encapsulate knowledge about a kernel subsystem + into pre-written probes and functions that can be used by other scripts. + Tapsets are analogous to libraries for C programs. They hide the + underlying details of a kernel area while exposing the key information + needed to manage and monitor that aspect of the kernel. They are typically + developed by kernel subject-matter experts. + </para> + + <para> + A tapset exposes the high-level data and state transitions of a + subsystem. For the most part, good tapset developers assume that + SystemTap users know little to nothing about the kernel subsystem's + low-level details. As such, tapset developers write tapsets that help + ordinary SystemTap users write meaningful and useful SystemTap scripts. + </para> + +<!-- add xref to upcoming section on how to write Tapsets/Tapset Comments --> + + <section id="docsgoals"> + <title>Documentation Goals</title> + + <para> + This guide aims to document SystemTap's most useful and common tapset entries; it + also contains guidelines on proper tapset development and documentation. + The tapset definitions contained in this guide are extracted automatically from + properly-formatted comments in the code of each tapset file. As such, any revisions + to the definitions in this guide should be applied directly to their respective + tapset file. + </para> + +<remark>add: "while users can read from code, it's easier to read from here!"</remark> +<remark>add: target audience, expected proficiency of readers</remark> + + </section> + +</chapter>
\ No newline at end of file diff --git a/doc/Tapset_Reference_Guide/en-US/Tapset_Dev_Guide.xml b/doc/Tapset_Reference_Guide/en-US/Tapset_Dev_Guide.xml new file mode 100644 index 00000000..26ea9896 --- /dev/null +++ b/doc/Tapset_Reference_Guide/en-US/Tapset_Dev_Guide.xml @@ -0,0 +1,117 @@ +<?xml version='1.0'?> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ +]> + +<chapter id="Tapset_Dev_Guide"> + <title>Tapset Development Guidelines</title> + +<para> + This chapter describes the upstream guidelines on proper tapset documentation. It also contains + information on how to properly document your tapsets, to ensure that they are properly + defined in this guide. +</para> + + <section id="Tapsetcontents"> + <title>Writing Good Tapsets</title> + +<para> + The first step to writing good tapsets is to create a simple model of your subject area. For + example, a model of the process subsystem might include the following: +</para> + +<formalpara> + <title>Key Data</title> + <para> + <itemizedlist> + <listitem><para>process ID</para></listitem> + <listitem><para>parent process ID</para></listitem> + <listitem><para>process group ID</para></listitem> + </itemizedlist> + </para> +</formalpara> + +<formalpara> + <title>State Transitions</title> + <para> + <itemizedlist> + <listitem><para>forked</para></listitem> + <listitem><para>exec'd</para></listitem> + <listitem><para>running</para></listitem> + <listitem><para>stopped</para></listitem> + <listitem><para>terminated</para></listitem> + </itemizedlist> + </para> +</formalpara> + +<note> + <title>Note</title> + <para>Both lists are examples, and are not meant to represent a complete list.</para> +</note> + +<para> + Use your subsystem expertise to find probe points (function entries and + exits) that expose the elements of the model, then define probe aliases + for those points. Be aware that some state transitions can occur in more + than one place. In those cases, an alias can place a probe in multiple + locations. +</para> + +<para> + For example, process execs can occur in either the <command>do_execve()</command> or the + <command>compat_do_execve()</command> functions. The following alias inserts probes at the + beginning of those functions: +</para> + +<programlisting> +probe process.exec = kernel.function("do_execve"), +kernel.function("compat_do_execve") +{<replaceable>probe body</replaceable>} +</programlisting> + +<para> + Try to place probes on stable interfaces (i.e., functions + that are unlikely to change at the interface level) whenever possible. This will + make the tapset less likely to break due to kernel changes. Where + kernel version or architecture dependencies are unavoidable, use + preprocessor conditionals (see the <command>stap(1)</command> man page for details). +</para> + + +<para> + Fill in the probe bodies with the key data available at the probe points. + Function entry probes can access the entry parameters specified to + the function, while exit probes can access the entry parameters and the + return value. Convert the data into meaningful forms where appropriate + (e.g., bytes to kilobytes, state values to strings, etc). +</para> + +<para> + You may need to use auxiliary functions to access or convert some of the data. Auxiliary + functions often use embedded C to do things that cannot be done in the + SystemTap language, like access structure fields in some contexts, follow + linked lists, etc. You can use auxiliary functions defined in other tapsets + or write your own. +</para> + +<para> + In the following example, <command>copy_process()</command> returns a + pointer to the <command>task_struct</command> for the new process. Note + that the process ID of the new process is retrieved by calling + <command>task_pid()</command> and passing it the <command>task_struct</command> + pointer. In this case, the auxiliary function is an embedded C function + that's defined in the task tapset (<filename>task.stp</filename>). +</para> + +<remark>info from here:http://sources.redhat.com/git/?p=systemtap.git;a=blob_plain;f=tapset/DEVGUIDE</remark> + + </section> +<!-- + <section id="Tapset_Reference_Guide-Test-Section_2_Test"> + <title>Section 2 Test</title> + <para> + Test of a section + </para> + </section> +--> +</chapter> + diff --git a/doc/Tapset_Reference_Guide/publicanize.sh b/doc/Tapset_Reference_Guide/publicanize.sh index 1139b34d..d4da6e02 100755 --- a/doc/Tapset_Reference_Guide/publicanize.sh +++ b/doc/Tapset_Reference_Guide/publicanize.sh @@ -1,10 +1,15 @@ #!/bin/bash #copy the automated tapsets.xml -cp ../SystemTap_Tapset_Reference/tapsets.xml en-US/Tapset_Reference_Guide.xml ; +cp ../SystemTap_Tapset_Reference/tapsets.xml temp.xml ; #remove all excess whitespace -sed -i -e 's/^\s*//g' en-US/Tapset_Reference_Guide.xml ; +sed -i -e 's/^\s*//g' temp.xml ; + +#remove marked Intro (starthere to endhere), then copy it to en-US +sed '/starthere/,/endhere/d' temp.xml > Tapset_Reference_Guide.xml +cp Tapset_Reference_Guide.xml en-US/Tapset_Reference_Guide.xml; +rm Tapset_Reference_Guide.xml #re-convert programlisting tags sed -i -e 's/<programlisting>/<programlisting>/g' en-US/Tapset_Reference_Guide.xml; @@ -22,15 +27,24 @@ perl -p -e 'undef $/;s|<para>\nYou should have received a copy of the GNU Genera perl -p -e 'undef $/;s|<para>\nFor more details see the file COPYING in the source\ndistribution of Linux.\n</para>\n</legalnotice>\n</bookinfo>||msg' | perl -p -e 'undef $/;s|<toc></toc>||msg' | perl -p -e 'undef $/;s|\n\n\n\n\n\n\n\n\n\n\n\n\n\n||msg' | +perl -p -e 'undef $/;s|\n\n\n\n\n\n\n\n\n\n\n||msg' | perl -p -e 'undef $/;s|<programlisting>\n|<programlisting>\n<emphasis>function <\/emphasis>|msg' | perl -p -e 'undef $/;s|<para>\n</para>||msg' | perl -p -e 'undef $/;s|<para>\n\n</para>||msg' | perl -p -e 'undef $/;s|<para>\n<programlisting>|<programlisting>|msg' | perl -p -e 'undef $/;s|</programlisting>\n</para>|</programlisting>|msg' > clean.xml +#replace Intro with my own +perl -p -i -e 's|<!--markerforxi-->|<xi:include href="Introduction.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />\n<xi:include href="Tapset_Dev_Guide.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />|g' clean.xml + +#for tapset name format section +#perl -p -i -e 'undef $/;s|<screen>\nname:return \(parameters\)\ndefinition\n</screen>|<screen>\n<replaceable>function/probe</replaceable> tapset_name:return \(parameters\)\n</screen>|msg' clean.xml +#perl -p -i -e 's|<para>In this guide, tapset definitions appear in the following format:</para>|<para>In this guide, the synopsis of each tapset appears in the following format:</para>|g' clean.xml +#perl -p -i -e 's|<!-- markerforxi pls dont remove -->|<xi:include href="tapsetnameformat-lastpara.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />\n<xi:include href="refentry-example.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />|g' clean.xml + cp clean.xml en-US/Tapset_Reference_Guide.xml rm clean.xml - + # statements change synopsis tags, as they are still currently unfixed in publican-redhat sed -i -e 's/refsynopsisdiv>/refsect1>/g' en-US/Tapset_Reference_Guide.xml; sed -i -e 's/refsect1>/refsection>/g' en-US/Tapset_Reference_Guide.xml; @@ -45,4 +59,7 @@ sed -i -e 's/<remark>/<remark>/g' en-US/Tapset_Reference_Guide.xml; sed -i -e 's/<\/remark>/<\/remark>/g' en-US/Tapset_Reference_Guide.xml; sed -i -e 's/<command>/<command>/g' en-US/Tapset_Reference_Guide.xml; -sed -i -e 's/<\/command>/<\/command>/g' en-US/Tapset_Reference_Guide.xml;
\ No newline at end of file +sed -i -e 's/<\/command>/<\/command>/g' en-US/Tapset_Reference_Guide.xml; + +#useful marker script; moves content between starthere and endhere to file target +#sed -n '/starthere/,/endhere/ s/.*/&/w target' Tapset_Reference_Guide.xml
\ No newline at end of file |