diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/Makefile.in | 1 | ||||
| -rw-r--r-- | doc/SystemTap_Tapset_Reference/Makefile.am | 6 | ||||
| -rw-r--r-- | doc/SystemTap_Tapset_Reference/Makefile.in | 7 | ||||
| -rw-r--r-- | doc/SystemTap_Tapset_Reference/tapsets.tmpl | 59 | ||||
| -rw-r--r-- | doc/Tapset_Reference_Guide/en-US/Tapset_Dev_Guide.xml | 20 | ||||
| -rwxr-xr-x | doc/Tapset_Reference_Guide/manpager.sh | 120 |
6 files changed, 160 insertions, 53 deletions
diff --git a/doc/Makefile.in b/doc/Makefile.in index 93753666..e23a6699 100644 --- a/doc/Makefile.in +++ b/doc/Makefile.in @@ -163,6 +163,7 @@ staplog_CPPFLAGS = @staplog_CPPFLAGS@ subdirs = @subdirs@ sysconfdir = @sysconfdir@ target_alias = @target_alias@ +top_build_prefix = @top_build_prefix@ top_builddir = @top_builddir@ top_srcdir = @top_srcdir@ PDF_FILES = tutorial.pdf langref.pdf diff --git a/doc/SystemTap_Tapset_Reference/Makefile.am b/doc/SystemTap_Tapset_Reference/Makefile.am index 9e7d2069..68dfd971 100644 --- a/doc/SystemTap_Tapset_Reference/Makefile.am +++ b/doc/SystemTap_Tapset_Reference/Makefile.am @@ -2,7 +2,7 @@ ## process this file with automake to produce Makefile.in DOC_INSTALL_DIR = $(DESTDIR)$(datadir)/doc/systemtap -MAN_INSTALL_DIR = $(DESTDIR)$(mandir)/man5 +MAN_INSTALL_DIR = $(DESTDIR)$(mandir)/man3stap HTML_INSTALL_DIR = $(DESTDIR)$(datadir)/doc/systemtap/tapsets @@ -36,7 +36,7 @@ tapsets.pdf: tapsets.xml xmlto pdf tapsets.xml stamp-mandocs: tapsets.xml - xmlto man -o man5 tapsets.xml + xmlto man -o man3stap tapsets.xml touch stamp-mandocs #FIXME need to figure out where to install things appropriately @@ -45,7 +45,7 @@ install-data-hook: $(MKDIR_P) $(DOC_INSTALL_DIR) $(INSTALL_DATA) tapsets.pdf $(DOC_INSTALL_DIR) $(MKDIR_P) $(MAN_INSTALL_DIR) - $(INSTALL_DATA) man5/* $(MAN_INSTALL_DIR) + $(INSTALL_DATA) man3stap/* $(MAN_INSTALL_DIR) $(MKDIR_P) $(HTML_INSTALL_DIR) $(INSTALL_DATA) tapsets/* $(HTML_INSTALL_DIR) endif diff --git a/doc/SystemTap_Tapset_Reference/Makefile.in b/doc/SystemTap_Tapset_Reference/Makefile.in index 84d2114c..2f8a5294 100644 --- a/doc/SystemTap_Tapset_Reference/Makefile.in +++ b/doc/SystemTap_Tapset_Reference/Makefile.in @@ -166,10 +166,11 @@ staplog_CPPFLAGS = @staplog_CPPFLAGS@ subdirs = @subdirs@ sysconfdir = @sysconfdir@ target_alias = @target_alias@ +top_build_prefix = @top_build_prefix@ top_builddir = @top_builddir@ top_srcdir = @top_srcdir@ DOC_INSTALL_DIR = $(DESTDIR)$(datadir)/doc/systemtap -MAN_INSTALL_DIR = $(DESTDIR)$(mandir)/man5 +MAN_INSTALL_DIR = $(DESTDIR)$(mandir)/man3stap HTML_INSTALL_DIR = $(DESTDIR)$(datadir)/doc/systemtap/tapsets SRCTREE = $(abs_top_srcdir)/ DOCPROC = $(abs_builddir)/docproc @@ -429,7 +430,7 @@ uninstall-am: @BUILD_REFDOCS_TRUE@ xmlto pdf tapsets.xml @BUILD_REFDOCS_TRUE@stamp-mandocs: tapsets.xml -@BUILD_REFDOCS_TRUE@ xmlto man -o man5 tapsets.xml +@BUILD_REFDOCS_TRUE@ xmlto man -o man3stap tapsets.xml @BUILD_REFDOCS_TRUE@ touch stamp-mandocs #FIXME need to figure out where to install things appropriately @@ -438,7 +439,7 @@ uninstall-am: @BUILD_REFDOCS_TRUE@ $(MKDIR_P) $(DOC_INSTALL_DIR) @BUILD_REFDOCS_TRUE@ $(INSTALL_DATA) tapsets.pdf $(DOC_INSTALL_DIR) @BUILD_REFDOCS_TRUE@ $(MKDIR_P) $(MAN_INSTALL_DIR) -@BUILD_REFDOCS_TRUE@ $(INSTALL_DATA) man5/* $(MAN_INSTALL_DIR) +@BUILD_REFDOCS_TRUE@ $(INSTALL_DATA) man3stap/* $(MAN_INSTALL_DIR) @BUILD_REFDOCS_TRUE@ $(MKDIR_P) $(HTML_INSTALL_DIR) @BUILD_REFDOCS_TRUE@ $(INSTALL_DATA) tapsets/* $(HTML_INSTALL_DIR) # Tell versions [3.59,3.63) of GNU make to not export all variables. diff --git a/doc/SystemTap_Tapset_Reference/tapsets.tmpl b/doc/SystemTap_Tapset_Reference/tapsets.tmpl index 798cfb3b..21706ea2 100644 --- a/doc/SystemTap_Tapset_Reference/tapsets.tmpl +++ b/doc/SystemTap_Tapset_Reference/tapsets.tmpl @@ -5,23 +5,10 @@ <book id="TapsetRef"> <bookinfo> <title>SystemTap Tapset Reference Manual</title> - - <authorgroup> - <author> - <firstname>William</firstname> - <surname>Cohen</surname> - <contrib></contrib> - <affiliation> - <address> - <email>wcohen@redhat.com</email> - </address> - </affiliation> - </author> - </authorgroup> <copyright> - <year>2008, 2009</year> - <holder>Red Hat, Inc.</holder> + <year>2008-2009</year> + <holder>Red Hat, Inc. and others</holder> </copyright> <legalnotice> @@ -117,8 +104,8 @@ <title>Context Functions</title> <para> The context functions provide additional information about where - the event occurred. - These functions can provide information such as a backtrace + an event occurred. + These functions can provide information such as a backtrace to where the event occured and the current register values for the processor. </para> @@ -132,22 +119,26 @@ <para> Each timestamp function returns a value to indicate when 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. + These returned values can then be used to indicate + when an event occurred, provide an ordering for events, or compute + the amount of time elapsed between two time stamps. </para> !Itapset/timestamp.stp </chapter> <chapter id="memory_stp"> <title>Memory Tapset</title> + <para> + This family of probe points is used to probe memory-related events. + It contains the following probe points: + </para> !Itapset/memory.stp </chapter> <chapter id="iosched.stp"> <title>IO Scheduler Tapset</title> <para> - This family of probe points is used to probe the IO scheduler activities. + This family of probe points is used to probe IO scheduler activities. It contains the following probe points: </para> !Itapset/ioscheduler.stp @@ -156,7 +147,7 @@ <chapter id="scsi.stp"> <title>SCSI Tapset</title> <para> - This family of probe points is used to probe the SCSI activities. + This family of probe points is used to probe SCSI activities. It contains the following probe points: </para> !Itapset/scsi.stp @@ -166,11 +157,12 @@ <title>Networking Tapset</title> <para> This family of probe points is used to probe the activities of - the network device, TCP layer, and UDP layer. + the network device and protocol layers. </para> !Itapset/networking.stp !Itapset/tcp.stp !Itapset/udp.stp +!Itapset/ip.stp </chapter> <chapter id="socket.stp"> @@ -181,29 +173,10 @@ </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> - - </chapter> - - <chapter id="upd.stp"> - <title>UDP Tapset</title> - <para> - This family of probe points is used to probe UDP layer activities. - It contains the following probe points: - </para> - - </chapter> ---> <chapter id="process.stp"> <title>Process Tapset</title> <para> - This family of probe points is used to probe the process activities. + This family of probe points is used to probe process-related activities. It contains the following probe points: </para> !Itapset/process.stp 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..d497eae6 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: </para> +<para> <programlisting> probe process.exec = kernel.function("do_execve"), kernel.function("compat_do_execve") {<replaceable>probe body</replaceable>} </programlisting> +</para> <para> Try to place probes on stable interfaces (i.e., functions @@ -102,6 +104,7 @@ kernel.function("compat_do_execve") defined in <filename>task.stp</filename>. </para> +<para> <programlisting> 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) } </programlisting> +</para> <para> 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: </para> +<para> <programlisting> /** * 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". **/ </programlisting> - +</para> + <para>For example:</para> +<para> <programlisting> /** * 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 <command>vm.shared_write</command>. **/ </programlisting> +</para> -<para>To override the automatically-generated <command>Synopsis</command> content, use: +<para>To override the automatically-generated <command>Synopsis</command> content, use:</para> +<para> <programlisting> * Synopsis: - * <programlisting>Synopsis string</programlisting> + * <replaceable>New Synopsis string</replaceable> * </programlisting> +</para> <para>For example:</para> +<para> <programlisting> /** * 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> */ </programlisting> +</para> <para> It is recommended that you use the <command><programlisting></command> tag in @@ -264,7 +276,7 @@ probe process.create = kernel.function("copy_process").return <listitem><para><command>emphasis</command></para></listitem> <listitem><para><command>programlisting</command></para></listitem> <listitem><para><command>remark</command> (tagged strings will appear in Publican beta - builds of the document.</para></listitem> + builds of the document)</para></listitem> </itemizedlist> diff --git a/doc/Tapset_Reference_Guide/manpager.sh b/doc/Tapset_Reference_Guide/manpager.sh new file mode 100755 index 00000000..0051d208 --- /dev/null +++ b/doc/Tapset_Reference_Guide/manpager.sh @@ -0,0 +1,120 @@ +#!/bin/bash +# This script builds the man pages from comments in tapsets. As such, the man page content +# generated herein should be in sync with Tapset Reference Guide + +# cleanup +rm -rf man_pages + +# create working directory +mkdir workingdir ; + +# create list of man pages to generate +cat ../SystemTap_Tapset_Reference/tapsets.tmpl | grep ^\!Itapset > manpageus ; +sed -i -e 's/\!Itapset\///g' manpageus ; + +# copy list of man pages into working directory +for i in `cat manpageus` ; do cp ../../tapset/$i workingdir ; done ; + +# enter workdir +cd workingdir ; + +# copy tapsetdescriptions, then clean +for i in `cat ../manpageus`; do +sed -n '/\/\/ <tapsetdescription>/,/\/\/ <\/tapsetdescription>/ s/.*/&/w temp' < $i ; +mv temp $i.tapsetdescription ; +sed -i -e 's/\/\/ <tapsetdescription>//g' $i.tapsetdescription ; +sed -i -e 's/\/\/ <\/tapsetdescription>//g' $i.tapsetdescription ; +sed -i -e 's/\/\///g' $i.tapsetdescription ; +done + +# strip all tapset files to just comments; but all comments must be exactly 1 space before and after "*" +for i in `cat ../manpageus` ; do sed -i -e 's/^ \*/ \*/g' $i; +sed -i -e 's/^ \* / \* /g' $i; +# mark the start of each probe entry (sub "/**") +perl -p -i -e 's|^/\*\*| *probestart|g' $i; +sed -i -e '/^ \*/!d' $i; +# rename all tapsets (remove .stp filename suffix), create templates +echo $i > tempname ; +sed -i -e 's/.stp//g' tempname ; +mv $i `cat tempname` ; mv tempname $i ; +done ; + +# create man page headers +for i in `ls | grep -v .stp | grep -v tapsetdescription` ; do +#echo ".\" -*- nroff -*-" >> $i.template ; +echo ".TH STAPPROBES."$i" 5 @DATE@ "IBM"" >> $i.template ; +echo ".SH NAME" >> $i.template ; +echo "stapprobes."`cat $i.stp`" \- systemtap "`cat $i.stp`" probe points" >> $i.template ; +echo " " >> $i.template ; +echo ".SH DESCRIPTION" >> $i.template ; +cat $i.stp.tapsetdescription >> $i.template ; +echo " " >> $i.template ; +echo ".SH PROBES" >> $i.template ; +echo ".br" >> $i.template ; +echo ".P" >> $i.template ; +echo ".TP" >> $i.template ; +done + +# MOST IMPORTANT: clean man page body! +sed -i -e 's/\.stp$//g' ../manpageus ; +for i in `cat ../manpageus` ; +do mv $i $i.tmp ; +perl -p -i -e 's| \* sfunction|.BR|g' $i.tmp ; +perl -p -i -e 's| \* probe|.BR|g' $i.tmp ; +perl -p -i -e 's| -|\ninitlinehere|g' $i.tmp ; +perl -p -i -e 's|^initlinehere([^\n]*)\n|$1\n |g' $i.tmp ; +perl -p -i -e 's| \* @([^:]*):|\n.I $1:\n|g' $i.tmp ; +perl -p -i -e 's| \* ([^:]*):|\n.BR $1:\n|g' $i.tmp ; +perl -p -i -e 's| \* ||g' $i.tmp +perl -p -i -e 's|\*probestart|\n.P\n.TP|g' $i.tmp ; +perl -p -i -e 's|\.I|\n.I|g' $i.tmp ; +# remove empty lines +sed -i -e '/^$/d' $i.tmp ; +sed -i -e '/^$/d' $i.tmp ; +sed -i -e 's/^[ \t]*//g' $i.tmp ; +# process Description headers +perl -p -i -e 's|^\*[^/]|\n.BR Description:\n|g' $i.tmp ; +perl -p -i -e 'undef $/;s|\.BR Description:\n\.BR|.BR|g' $i.tmp ; +perl -p -i -e 'undef $/;s|\.BR Description:\n\*\/||g' $i.tmp ; +# process Argument headers +perl -p -i -e 'undef $/;s|\n\n.I|\n.br\n.BR Arguments:\n.I|g' $i.tmp ; +# clean up formatting of arguments +perl -p -i -e 's|^.I([^:]*:)|\n.br\n.br\n.IR$1\n.br\n\t|g' $i.tmp ; +done + +# make tags work +for i in `cat ../manpageus` ; do +perl -p -i -e 's|</[^>]*>([^.])|$1\n|g' $i.tmp ; +perl -p -i -e 's|<[^>]*>|\n.B |g' $i.tmp ; +# the previous two statements create excess empty lines, remove some of them +sed -i -e '/^$/d' $i.tmp ; +# increase whitespace between some headers +perl -p -i -e 's|^\.BR ([^:]*:)|\n.br\n.BR $1\n.br\n|g' $i.tmp +done + +# generate footer template +echo ".SH SEE ALSO" >> footer +echo ".IR stap (1)," >> footer +echo ".IR stapprobes (5)," >> footer +for i in `cat ../manpageus`; do echo ".IR stapprobes."$i" (5)," >> footer ; done + +# assemble parts +for i in `cat ../manpageus`; do +cat $i.template >> stapprobes.$i.5 ; +cat $i.tmp >> stapprobes.$i.5 ; +cat footer >> stapprobes.$i.5 ; +# final polish +sed -i -e 's/\*\/$//g' stapprobes.$i.5 ; +done + +# cleanup +for i in `ls | grep -v 'stapprobes.*.5'` ; do +rm $i ; +done + +rm ../manpageus ; +cd .. +mv workingdir man_pages +echo " " +echo "Finished! man pages generated in ./man_pages." +echo " "
\ No newline at end of file |