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(-) 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