diff options
Diffstat (limited to 'doc/Tapset_Reference_Guide')
| -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 |
3 files changed, 197 insertions, 4 deletions
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 |