From 501f43617a8d33f24e07a3ccbbf7636cd72cb5fe Mon Sep 17 00:00:00 2001 From: ddomingo Date: Thu, 5 Mar 2009 10:53:35 +1000 Subject: function instead of (sfunction) --- doc/Tapset_Reference_Guide/publicanize.sh | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'doc/Tapset_Reference_Guide') diff --git a/doc/Tapset_Reference_Guide/publicanize.sh b/doc/Tapset_Reference_Guide/publicanize.sh index 96c20a11..1139b34d 100755 --- a/doc/Tapset_Reference_Guide/publicanize.sh +++ b/doc/Tapset_Reference_Guide/publicanize.sh @@ -22,7 +22,7 @@ perl -p -e 'undef $/;s|\nYou should have received a copy of the GNU Genera perl -p -e 'undef $/;s|\nFor more details see the file COPYING in the source\ndistribution of Linux.\n\n\n||msg' | perl -p -e 'undef $/;s|||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(sfunction) <\/emphasis>|msg' | +perl -p -e 'undef $/;s|\n|\nfunction <\/emphasis>|msg' | perl -p -e 'undef $/;s|\n||msg' | perl -p -e 'undef $/;s|\n\n||msg' | perl -p -e 'undef $/;s|\n||msg' | -- cgit From f72226cf3584bf8dfe3e8d3021b7780b3bd9ec46 Mon Sep 17 00:00:00 2001 From: ddomingo Date: Thu, 5 Mar 2009 10:54:46 +1000 Subject: add Makefile --- doc/Tapset_Reference_Guide/Makefile | 15 +++++++++++++++ 1 file changed, 15 insertions(+) create mode 100644 doc/Tapset_Reference_Guide/Makefile (limited to 'doc/Tapset_Reference_Guide') diff --git a/doc/Tapset_Reference_Guide/Makefile b/doc/Tapset_Reference_Guide/Makefile new file mode 100644 index 00000000..05220405 --- /dev/null +++ b/doc/Tapset_Reference_Guide/Makefile @@ -0,0 +1,15 @@ +#Makefile for Tapset_Reference_Guide + +XML_LANG = en-US +DOCNAME = Tapset_Reference_Guide +#PRODUCT = FIX_ME! +BRAND = RedHat + +#OTHER_LANGS = as-IN bn-IN de-DE es-ES fr-FR gu-IN hi-IN it-IT ja-JP kn-IN ko-KR ml-IN mr-IN or-IN pa-IN pt-BR ru-RU si-LK ta-IN te-IN zh-CN zh-TW + +# Extra Parameters start here + +# Extra Parameters stop here +COMMON_CONFIG = /usr/share/publican +include $(COMMON_CONFIG)/make/Makefile.common + -- cgit From 9c9118af3062f3dc1e53ba8426993a24bbedaa97 Mon Sep 17 00:00:00 2001 From: ddomingo Date: Thu, 5 Mar 2009 10:56:39 +1000 Subject: add images --- doc/Tapset_Reference_Guide/en-US/images/icon.svg | 3936 ++++++++++++++++++++++ 1 file changed, 3936 insertions(+) create mode 100644 doc/Tapset_Reference_Guide/en-US/images/icon.svg (limited to 'doc/Tapset_Reference_Guide') diff --git a/doc/Tapset_Reference_Guide/en-US/images/icon.svg b/doc/Tapset_Reference_Guide/en-US/images/icon.svg new file mode 100644 index 00000000..c471a607 --- /dev/null +++ b/doc/Tapset_Reference_Guide/en-US/images/icon.svg @@ -0,0 +1,3936 @@ + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + id="path2858" /> + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + -- cgit From ff2349408bbbfe83487335ed2d34346f70c15588 Mon Sep 17 00:00:00 2001 From: ddomingo Date: Thu, 5 Mar 2009 10:58:01 +1000 Subject: add other required XMLs --- doc/Tapset_Reference_Guide/en-US/Book_Info.xml | 32 ++++++++++++++++++++++ doc/Tapset_Reference_Guide/en-US/Legal_Notice.xml | 30 ++++++++++++++++++++ doc/Tapset_Reference_Guide/en-US/Preface.xml | 15 ++++++++++ .../en-US/Tapset_Reference_Guide.ent | 5 ++++ 4 files changed, 82 insertions(+) create mode 100644 doc/Tapset_Reference_Guide/en-US/Book_Info.xml create mode 100644 doc/Tapset_Reference_Guide/en-US/Legal_Notice.xml create mode 100644 doc/Tapset_Reference_Guide/en-US/Preface.xml create mode 100644 doc/Tapset_Reference_Guide/en-US/Tapset_Reference_Guide.ent (limited to 'doc/Tapset_Reference_Guide') diff --git a/doc/Tapset_Reference_Guide/en-US/Book_Info.xml b/doc/Tapset_Reference_Guide/en-US/Book_Info.xml new file mode 100644 index 00000000..fc3d4273 --- /dev/null +++ b/doc/Tapset_Reference_Guide/en-US/Book_Info.xml @@ -0,0 +1,32 @@ + + + + + Tapset Reference Guide + For SystemTap in &RHEL;.3 + Red Hat Enterprise Linux + 5.2 + 1.0 + 0 + + The Tapset Reference Guide describes the most common tapset definitions users can apply to SystemTap scripts. All included tapsets documented in this guide are current as of &RHEL;.3. + + + + + + + Logo + + + + &YEAR; + &HOLDER; + + + + + + + diff --git a/doc/Tapset_Reference_Guide/en-US/Legal_Notice.xml b/doc/Tapset_Reference_Guide/en-US/Legal_Notice.xml new file mode 100644 index 00000000..1fcb7b99 --- /dev/null +++ b/doc/Tapset_Reference_Guide/en-US/Legal_Notice.xml @@ -0,0 +1,30 @@ + + + + + + This documentation is free software; you can redistribute + it and/or modify it under the terms of the GNU General Public + License version 2 as published by the Free Software Foundation. + + + + This program is distributed in the hope that it will be + useful, but WITHOUT ANY WARRANTY; without even the implied + warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. + See the GNU General Public License for more details. + + + + You should have received a copy of the GNU General Public + License along with this program; if not, write to the Free + Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, + MA 02111-1307 USA + + + + For more details see the file COPYING in the source + distribution of Linux. + + diff --git a/doc/Tapset_Reference_Guide/en-US/Preface.xml b/doc/Tapset_Reference_Guide/en-US/Preface.xml new file mode 100644 index 00000000..6acf0c3e --- /dev/null +++ b/doc/Tapset_Reference_Guide/en-US/Preface.xml @@ -0,0 +1,15 @@ + + + + + Preface + + + + + + + + + diff --git a/doc/Tapset_Reference_Guide/en-US/Tapset_Reference_Guide.ent b/doc/Tapset_Reference_Guide/en-US/Tapset_Reference_Guide.ent new file mode 100644 index 00000000..6638d812 --- /dev/null +++ b/doc/Tapset_Reference_Guide/en-US/Tapset_Reference_Guide.ent @@ -0,0 +1,5 @@ + + + + + \ No newline at end of file -- cgit From a06948f6631daaeb1cf3f63d9ecd20795deebc21 Mon Sep 17 00:00:00 2001 From: ddomingo Date: Thu, 5 Mar 2009 11:22:27 +1000 Subject: change to fedora --- doc/Tapset_Reference_Guide/en-US/Book_Info.xml | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) (limited to 'doc/Tapset_Reference_Guide') diff --git a/doc/Tapset_Reference_Guide/en-US/Book_Info.xml b/doc/Tapset_Reference_Guide/en-US/Book_Info.xml index fc3d4273..ddf0f205 100644 --- a/doc/Tapset_Reference_Guide/en-US/Book_Info.xml +++ b/doc/Tapset_Reference_Guide/en-US/Book_Info.xml @@ -4,13 +4,17 @@ Tapset Reference Guide - For SystemTap in &RHEL;.3 - Red Hat Enterprise Linux - 5.2 + For SystemTap in Fedora 10 + Fedora + 10 1.0 0 - The Tapset Reference Guide describes the most common tapset definitions users can apply to SystemTap scripts. All included tapsets documented in this guide are current as of &RHEL;.3. + + The Tapset Reference Guide describes the most common tapset definitions + users can apply to SystemTap scripts. All included tapsets documented in this guide are current + as of Fedora 10 and the latest upstream version of SystemTap. + -- cgit From 345f6a4daad184385b7ee1dc3797f57a3be01452 Mon Sep 17 00:00:00 2001 From: ddomingo Date: Thu, 5 Mar 2009 11:23:00 +1000 Subject: change to fedora, add README for more info --- doc/Tapset_Reference_Guide/Makefile | 2 +- doc/Tapset_Reference_Guide/README | 35 +++++++++++++++++++++++++++++++++++ 2 files changed, 36 insertions(+), 1 deletion(-) create mode 100644 doc/Tapset_Reference_Guide/README (limited to 'doc/Tapset_Reference_Guide') diff --git a/doc/Tapset_Reference_Guide/Makefile b/doc/Tapset_Reference_Guide/Makefile index 05220405..87a1fb5f 100644 --- a/doc/Tapset_Reference_Guide/Makefile +++ b/doc/Tapset_Reference_Guide/Makefile @@ -3,7 +3,7 @@ XML_LANG = en-US DOCNAME = Tapset_Reference_Guide #PRODUCT = FIX_ME! -BRAND = RedHat +BRAND = fedora #OTHER_LANGS = as-IN bn-IN de-DE es-ES fr-FR gu-IN hi-IN it-IT ja-JP kn-IN ko-KR ml-IN mr-IN or-IN pa-IN pt-BR ru-RU si-LK ta-IN te-IN zh-CN zh-TW diff --git a/doc/Tapset_Reference_Guide/README b/doc/Tapset_Reference_Guide/README new file mode 100644 index 00000000..1f27abe7 --- /dev/null +++ b/doc/Tapset_Reference_Guide/README @@ -0,0 +1,35 @@ +This is an automated source build of the SystemTap_Tapset_Reference Guide, +used to build it in Publican. + +To build the DocBook XML source (required by Publican), run: + + bash publicanize.sh + +This will copy and clean the XML source of SystemTap_Tapset_Reference +created by kernel-doc. You can now build it in pdf, html, etc using +Publican. + +The main source of the Language Reference Guide is: + + ../SystemTap_Tapset_Reference/tapsets.xml + +This main source is generated by kernel-doc when you run 'make' in the +main git tree. The tapset documentation inside is collected from all +tapset files defined in the following template file: + + ../SystemTap_Tapset_Reference/tapsets.tmpl + +The tapset file definitions appear in tapsets.tmpl as: + + !Itapset/context.stp + !Itapset/context-symbols.stp + etc + +context.stp, context-symbols, and all the other tapset files are located in: + + ../../tapset + +All tapset documentation should be done inside their respective tapset files. +For more information about this project, refer to: + + http://sourceware.org/systemtap/wiki/ProjectTapsetReferenceGuide \ No newline at end of file -- cgit From 70a9a66e609c4068b368bfb3a6ae36d3ca9f14b1 Mon Sep 17 00:00:00 2001 From: ddomingo Date: Thu, 5 Mar 2009 15:20:24 +1000 Subject: removes marked range of strings (intro) and replaces with Intro and Tapset Dev Guide --- doc/Tapset_Reference_Guide/publicanize.sh | 25 +++++++++++++++++++++---- 1 file changed, 21 insertions(+), 4 deletions(-) (limited to 'doc/Tapset_Reference_Guide') 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>//g' en-US/Tapset_Reference_Guide.xml; @@ -22,15 +27,24 @@ perl -p -e 'undef $/;s|\nYou should have received a copy of the GNU Genera perl -p -e 'undef $/;s|\nFor more details see the file COPYING in the source\ndistribution of Linux.\n\n\n||msg' | perl -p -e 'undef $/;s|||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|\n|\nfunction <\/emphasis>|msg' | perl -p -e 'undef $/;s|\n||msg' | perl -p -e 'undef $/;s|\n\n||msg' | perl -p -e 'undef $/;s|\n||msg' | perl -p -e 'undef $/;s|\n||msg' > clean.xml +#replace Intro with my own +perl -p -i -e 's||\n|g' clean.xml + +#for tapset name format section +#perl -p -i -e 'undef $/;s|\nname:return \(parameters\)\ndefinition\n|\nfunction/probe tapset_name:return \(parameters\)\n|msg' clean.xml +#perl -p -i -e 's|In this guide, tapset definitions appear in the following format:|In this guide, the synopsis of each tapset appears in the following format:|g' clean.xml +#perl -p -i -e 's||\n|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>//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>//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 -- cgit From c08b296b08208a4406d80e12da6aac34df64bd8f Mon Sep 17 00:00:00 2001 From: ddomingo Date: Thu, 5 Mar 2009 15:21:10 +1000 Subject: new intro, tapset dev guide --- doc/Tapset_Reference_Guide/en-US/Introduction.xml | 59 ++++++++++++++++++++++ .../en-US/Tapset_Dev_Guide.xml | 33 ++++++++++++ 2 files changed, 92 insertions(+) create mode 100644 doc/Tapset_Reference_Guide/en-US/Introduction.xml create mode 100644 doc/Tapset_Reference_Guide/en-US/Tapset_Dev_Guide.xml (limited to 'doc/Tapset_Reference_Guide') 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 @@ + + + + + Introduction + + + 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. + + + + 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 tapset library. + + + + 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. + + + + 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. + + + + +
+ Documentation Goals + + + 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. + + +add: "while users can read from code, it's easier to read from here!" +add: target audience, expected proficiency of readers + +
+ + \ 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..be59d944 --- /dev/null +++ b/doc/Tapset_Reference_Guide/en-US/Tapset_Dev_Guide.xml @@ -0,0 +1,33 @@ + + + + + Tapset Development Guidelines + + + 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. + + +
+ Writing Good Tapsets + + + 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: + +info from here:http://sources.redhat.com/git/?p=systemtap.git;a=blob_plain;f=tapset/DEVGUIDE + +
+ +
+ Section 2 Test + + Test of a section + +
+ + + -- cgit From 4a05792180ad1299f499b5dbd77d5d4e9c4970fb Mon Sep 17 00:00:00 2001 From: ddomingo Date: Fri, 6 Mar 2009 14:57:12 +1000 Subject: added more content for tapset dev --- .../en-US/Tapset_Dev_Guide.xml | 88 +++++++++++++++++++++- 1 file changed, 86 insertions(+), 2 deletions(-) (limited to 'doc/Tapset_Reference_Guide') diff --git a/doc/Tapset_Reference_Guide/en-US/Tapset_Dev_Guide.xml b/doc/Tapset_Reference_Guide/en-US/Tapset_Dev_Guide.xml index be59d944..26ea9896 100644 --- a/doc/Tapset_Reference_Guide/en-US/Tapset_Dev_Guide.xml +++ b/doc/Tapset_Reference_Guide/en-US/Tapset_Dev_Guide.xml @@ -18,16 +18,100 @@ 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: + + + Key Data + + + process ID + parent process ID + process group ID + + + + + + State Transitions + + + forked + exec'd + running + stopped + terminated + + + + + + Note + Both lists are examples, and are not meant to represent a complete list. + + + + 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. + + + + For example, process execs can occur in either the do_execve() or the + compat_do_execve() functions. The following alias inserts probes at the + beginning of those functions: + + + +probe process.exec = kernel.function("do_execve"), +kernel.function("compat_do_execve") +{probe body} + + + + 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 stap(1) man page for details). + + + + + 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). + + + + 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. + + + + In the following example, copy_process() returns a + pointer to the task_struct for the new process. Note + that the process ID of the new process is retrieved by calling + task_pid() and passing it the task_struct + pointer. In this case, the auxiliary function is an embedded C function + that's defined in the task tapset (task.stp). + + info from here:http://sources.redhat.com/git/?p=systemtap.git;a=blob_plain;f=tapset/DEVGUIDE - + -- cgit From 2e802851f3c72d841fe436ec1e178d858bb37f6d Mon Sep 17 00:00:00 2001 From: ddomingo Date: Mon, 9 Mar 2009 11:10:13 +1000 Subject: added commenting/documentation guidelines --- .../en-US/Tapset_Dev_Guide.xml | 181 ++++++++++++++++++++- 1 file changed, 174 insertions(+), 7 deletions(-) (limited to 'doc/Tapset_Reference_Guide') diff --git a/doc/Tapset_Reference_Guide/en-US/Tapset_Dev_Guide.xml b/doc/Tapset_Reference_Guide/en-US/Tapset_Dev_Guide.xml index 26ea9896..555fa7e6 100644 --- a/doc/Tapset_Reference_Guide/en-US/Tapset_Dev_Guide.xml +++ b/doc/Tapset_Reference_Guide/en-US/Tapset_Dev_Guide.xml @@ -99,19 +99,186 @@ kernel.function("compat_do_execve") that the process ID of the new process is retrieved by calling task_pid() and passing it the task_struct pointer. In this case, the auxiliary function is an embedded C function - that's defined in the task tapset (task.stp). + defined in task.stp. + + + +probe process.create = kernel.function("copy_process").return +{ + task = $return + new_pid = task_pid(task) +} + + + + It is not advisable to write probes for every function. Most SystemTap users + will not need or understand them. Keep your tapsets simple and high-level. info from here:http://sources.redhat.com/git/?p=systemtap.git;a=blob_plain;f=tapset/DEVGUIDE + +
+ Elements of a Tapset + + + The following sections describe the most important aspects of writing a tapset. Most of + the content herein is suitable for developers who wish to contribute to + SystemTap's upstream library of tapsets. + + +
+ Tapset Files + + + Tapset files are stored in src/tapset/ + of the SystemTap GIT directory. Most tapset files are kept at that level. If you have + code that only works with a specific architecture or kernel version, you may + choose to put your tapset in the appropriate subdirectory. + + + + Installed tapsets are located in /usr/share/systemtap/tapset/ + or /usr/local/share/systemtap/tapset. + + + + Personal tapsets can be stored anywhere. However, to ensure that SystemTap + can use them, use -I tapset_directory + to specify their location when invoking stap. + +
+ +
+ Namespace + + + + Probe alias names should take the form + tapset_name.probe_name. + For example, the probe for sending a signal could be named + signal.send. + + + + Global symbol names (probes, functions, and variables) should be unique + accross all tapsets. This helps avoid namespace collisions in scripts + that use multiple tapsets. To ensure this, use tapset-specific + prefixes in your global symbols. + + + + Internal symbol names should be prefixed with an underscore + (_). + +
+ +
+ Comments and Documentation + + + All probes and functions should include comment blocks that describe + their purpose, the data they provide, and the context in which they run + (e.g. interrupt, process, etc). Use comments in areas where your intent may not + be clear from reading the code. + + + + Note that specially-formatted comments are automatically extracted from most + tapsets and included in this guide. This helps ensure that tapset contributors + can write their tapset and document it in the same place. + The specified format for documenting tapsets is as follows: + + + +/** + * probe tapset.name - Short summary of what the tapset does. + * @argument: Explanation of argument. + * @argument2: Explanation of argument2. Probes can have multiple arguments. + * + * Context: + * A brief explanation of the tapset context. + * Note that the context should only be 1 paragraph short. + * + * Text that will appear under "Description." + * + * A new paragraph that will also appear under the heading "Description". + * + * Header: + * A paragraph that will appear under the heading "Header". + **/ + + +For example: + + +/** + * probe vm.write_shared_copy- Page copy for shared page write. + * @address: The address of the shared write. + * @zero: Boolean indicating whether it is a zero page + * (can do a clear instead of a copy). + * + * Context: + * The process attempting the write. + * + * Fires when a write to a shared page requires a page copy. This is + * always preceded by a vm.shared_write. + **/ + + +To override the automatically-generated Synopsis content, use: + + + * Synopsis: + * Synopsis string + * + + +For example: + + +/** + * probe signal.handle - Fires when the signal handler is invoked + * @sig: The signal number that invoked the signal handler + * + * Synopsis: + * <programlisting>static int handle_signal(unsigned long sig, siginfo_t *info, struct k_sigaction *ka, + * sigset_t *oldset, struct pt_regs * regs)</programlisting> + */ + + + + It is recommended that you use the <programlisting> tag in + this instance, since overriding the Synopsis content of an entry + does not automatically form the necessary tags. + + + + For the purposes of improving the DocBook XML output of your comments, you can also + use the following XML tags in your comments: + + + + command + emphasis + programlisting + remark (tagged strings will appear in Publican beta + builds of the document. + + + +
+ +
+ -- cgit