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/en-US') 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/en-US') 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/en-US') 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 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/en-US') 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/en-US') 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/en-US') 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 From 354c462465ffc80fc9a55beb9d6066cfa6048bc1 Mon Sep 17 00:00:00 2001 From: William Cohen Date: Fri, 13 Mar 2009 23:12:19 -0400 Subject: Add missing . --- doc/Tapset_Reference_Guide/en-US/Tapset_Dev_Guide.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'doc/Tapset_Reference_Guide/en-US') 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 555fa7e6..5d8cdfee 100644 --- a/doc/Tapset_Reference_Guide/en-US/Tapset_Dev_Guide.xml +++ b/doc/Tapset_Reference_Guide/en-US/Tapset_Dev_Guide.xml @@ -227,7 +227,7 @@ probe process.create = kernel.function("copy_process").return **/ -To override the automatically-generated Synopsis content, use: +To override the automatically-generated Synopsis content, use: * Synopsis: -- cgit From 20f933f0749322bc9787cc1972698a7aeffb08df Mon Sep 17 00:00:00 2001 From: William Cohen Date: Sat, 14 Mar 2009 08:46:52 -0400 Subject: Fixups to allow Tapset_Reference_guide documentation to build. --- doc/Tapset_Reference_Guide/en-US/Tapset_Dev_Guide.xml | 16 ++++++++++++++-- 1 file changed, 14 insertions(+), 2 deletions(-) (limited to 'doc/Tapset_Reference_Guide/en-US') 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 5d8cdfee..01e4c358 100644 --- a/doc/Tapset_Reference_Guide/en-US/Tapset_Dev_Guide.xml +++ b/doc/Tapset_Reference_Guide/en-US/Tapset_Dev_Guide.xml @@ -62,11 +62,13 @@ 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 @@ -102,6 +104,7 @@ kernel.function("compat_do_execve") defined in task.stp. + probe process.create = kernel.function("copy_process").return { @@ -109,6 +112,7 @@ probe process.create = kernel.function("copy_process").return new_pid = task_pid(task) } + It is not advisable to write probes for every function. Most SystemTap users @@ -191,6 +195,7 @@ probe process.create = kernel.function("copy_process").return The specified format for documenting tapsets is as follows: + /** * probe tapset.name - Short summary of what the tapset does. @@ -209,9 +214,11 @@ probe process.create = kernel.function("copy_process").return * A paragraph that will appear under the heading "Header". **/ - + + For example: + /** * probe vm.write_shared_copy- Page copy for shared page write. @@ -226,17 +233,21 @@ probe process.create = kernel.function("copy_process").return * always preceded by a vm.shared_write. **/ + To override the automatically-generated Synopsis content, use: + * Synopsis: - * Synopsis string + * New Synopsis string * + For example: + /** * probe signal.handle - Fires when the signal handler is invoked @@ -247,6 +258,7 @@ probe process.create = kernel.function("copy_process").return * sigset_t *oldset, struct pt_regs * regs)</programlisting> */ + It is recommended that you use the <programlisting> tag in -- cgit From bdc56b7c2a00cf360d0b7cd92ed5bea836c4223b Mon Sep 17 00:00:00 2001 From: ddomingo Date: Tue, 17 Mar 2009 13:42:14 +1000 Subject: minor edits --- doc/Tapset_Reference_Guide/en-US/Tapset_Dev_Guide.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'doc/Tapset_Reference_Guide/en-US') 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 01e4c358..d497eae6 100644 --- a/doc/Tapset_Reference_Guide/en-US/Tapset_Dev_Guide.xml +++ b/doc/Tapset_Reference_Guide/en-US/Tapset_Dev_Guide.xml @@ -276,7 +276,7 @@ probe process.create = kernel.function("copy_process").return emphasis programlisting remark (tagged strings will appear in Publican beta - builds of the document. + builds of the document) -- cgit