From 1be743e94d919e139a468a93dc0d2fab2cbed04c Mon Sep 17 00:00:00 2001
From: srinivasa <srinivasa>
Date: Mon, 18 Feb 2008 10:56:00 +0000
Subject: Frequently Asked questions for SystemTap.

---
 FAQ | 137 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 137 insertions(+)
 create mode 100644 FAQ

diff --git a/FAQ b/FAQ
new file mode 100644
index 00000000..d0347202
--- /dev/null
+++ b/FAQ
@@ -0,0 +1,137 @@
+1) I have installed SystemTap but am getting a "semantic error: libdwfl 
+failure (missing kernel debuginfo): No such file or directory", when I
+try to run a script. What am I missing? How do I fix it?
+
+This error message is related to the processing of debug-information. It
+may simply be missing, or may have some consistency/correctness problems.
+So please make sure that kernel-debuginfo rpm is installed in your system
+or in case of custom built kernels, your kernel is compiled with debug 
+options(ref Q.2). Please refer this link  
+http://sources.redhat.com/systemtap/tutorial/node27.html
+
+Common error messages that one may encounter while using SystemTap along
+with possible reasons for them, are listed at
+http://sources.redhat.com/systemtap/tutorial/node23.html and 
+http://sources.redhat.com/systemtap/tutorial/node27.html
+
+2) What config options need to be enabled to be able to use SystemTap on 
+custom built kernels?
+
+Look at http://sources.redhat.com/systemtap/wiki/SystemTapWithSelfBuiltKernel
+for the specific config options to be enabled for SystemTap.
+
+3) I have a kernel built with options listed in (2), but still can't get
+SystemTap to work. What am I missing?
+
+See Q2. Also, if you've used 'make install' to install your custom built kernel,
+it may not have copied the uncompressed 'vmlinux' to /boot/vmlinux-'uname-r'
+
+4) Is it possible for me to view the kernel module generated by SystemTap?
+
+You can specify -p3 to look at the kernel module code translated by SystemTap.
+stap -p3 <script> | less
+stap -p3 -e '...' | less
+
+man stap(1)
+[...]
+   -p NUM     stop after pass NUM 1-5, instead of 5
+              (parse, elaborate, translate, compile, run)
+
+5) How do I run prebuilt SystemTap modules?
+
+Prebuilt SystemTap modules can be run using the 'staprun(8)'
+
+$ staprun /path/to/<name>.ko
+
+Also see
+http://sources.redhat.com/git/gitweb.cgi?p=systemtap.git;a=blob_plain;f=README.security;hb=HEAD
+
+6) What should I do when some tapsets functions fails to resolve like 
+"semantic error: unresolved arity-1 function: identifier 'log'"
+
+Ensure that the tapsets are installed at the right location:
+/usr/share/systemtap/tapset/ (in RHEL or Fedora) or 
+/usr/local/systemtap/tapset if you install from source.
+
+7) This is way cool! I want to write my own scripts. Where do I look for more
+information?
+
+a. Read the SystemTap tutorial - http://sources.redhat.com/systemtap/tutorial/
+b. Read the Language reference guide at - http://sourceware.org/systemtap/langref/
+c. Check out our wiki - http://sources.redhat.com/systemtap/wiki/
+d. Look at http://sources.redhat.com/systemtap/getinvolved.html as to how you
+   can get involved.
+e. Subscribe to our mailing list at http://sources.redhat.com/ml/systemtap/.
+f. Join our IRC channel on freenode (#systemtap) and fire away your queries.
+
+8) Is it possible to override some of the macros in SystemTap generated 
+"C" module.
+
+Yup. Use -D option with stap command.
+man stap
+[...]
+-D NM=VAL  emit macro definition into generated C code
+
+9) What is a tapset?
+
+A tapset is just a script that designed for reuse by installation into a
+special directory.See http://sources.redhat.com/systemtap/tutorial/node15.html
+for more information.
+
+10) I see that there is no tapset for my favourite subsystem. What do I do?
+
+SystemTap community encourages users to write tapsets. See our tapset developer
+guide at http://sources.redhat.com/git/gitweb.cgi?p=systemtap.git;a=blob_plain;f=tapset/DEVGUIDE;hb=HEAD
+
+Learn how to write your own tapset looking at the existing ones under 
+/usr/share/systemtap/tapset.
+
+11) I hear the latest Linux Kernels come with marker support. Does SystemTap
+support markers?
+
+Yes, SystemTap supports kernel markers. See
+http://sources.redhat.com/systemtap/wiki/UsingMarkers for more information.
+
+12) I am a non-root user, but still want to run SystemTap scripts.
+Is that possible?
+
+Yes, it is possible. Add yourself as a member of 'stapusr' group. Members
+of stapusr group can run SystemTap scripts/modules located at 
+/lib/modules/`uname -r`/systemtap directory.
+
+13) This is fantastic! But how does it all work?
+
+Internals of translation in SystemTap is described in src/INTERNALS* file.
+Documentation on kprobes is available at kernel source
+(Documentation/kprobes.txt).
+
+* http://sources.redhat.com/git/gitweb.cgi?p=systemtap.git;a=blob_plain;f=INTERNALS;hb=HEAD
+
+14) Do I have to be a RedHat Enterprise Linux/Fedora user to be able to 
+use SystemTap?
+
+No, It is possible to use SystemTap on other Linux distributions. Our
+wiki http://sources.redhat.com/systemtap/wiki has more information on this.
+
+15) I found a bug when using the tool. How do I report it?
+
+a. You can file a bug at SystemTap bugzilla
+    http://sources.redhat.com/bugzilla/enter_bug.cgi?product=systemtap
+b. Drop us a note with details of the bug at systemtap@sources.redhat.com
+
+16) I'd like to contribute to the project. Where to I start?
+
+See http://sources.redhat.com/systemtap/getinvolved.html. You can even work on 
+some bugs listed in SystemTap bugzilla (look for "current bugs/pending features"
+link at the bottom of the getinvolved page)
+
+17) I am a RHEL/Fedora user, but don't have the debuginfo rpm. Where can I find it?
+
+For RHEL, you can find the rpm at: http://people.redhat.com/duffy/debuginfo.
+For Fedora, you can run: yum --enablerepo=fedora-debuginfo install 
+kernel-debuginfo
+
+18) How can I find a list of blacklisted functions?
+
+See output of:
+stap -vvv -e 'probe kernel.function("*") {}' -p4 2>&1 | grep blacklisted
-- 
cgit