add examples for including additional header files

Fix issue #1478
Two tools, trace.py and argdist.py, and their corresponding
example files were changed.
Fixed a minor typo in one of trace.py error messages.
Signed-off-by: Yonghong Song <yhs@fb.com>

tools/argdist.py

@@ -590,6 +590,13 @@ argdist -p 2780 -z 120 \\
         -C 'p:c:write(int fd, char* buf, size_t len):char*:buf:fd==1'
         Spy on writes to STDOUT performed by process 2780, up to a string size
         of 120 characters
+
+argdist -I 'kernel/sched/sched.h' \\
+        -C 'p::__account_cfs_rq_runtime(struct cfs_rq *cfs_rq):s64:cfs_rq->runtime_remaining'
+        Trace on the cfs scheduling runqueue remaining runtime. The struct cfs_rq is defined
+        in kernel/sched/sched.h which is in kernel source tree and not in kernel-devel
+        package.  So this command needs to run at the kernel source tree root directory
+        so that the added header file can be found by the compiler.
 """
 
         def __init__(self):
@@ -625,7 +632,9 @@ argdist -p 2780 -z 120 \\
                 parser.add_argument("-I", "--include", action="append",
                   metavar="header",
                   help="additional header files to include in the BPF program "
-                       "as either full path, or relative to '/usr/include'")
+                       "as either full path, "
+                       "or relative to relative to current working directory, "
+                       "or relative to default kernel header search path")
                 self.args = parser.parse_args()
                 self.usdt_ctx = None
 

tools/argdist_example.txt

@@ -363,7 +363,8 @@ optional arguments:
                         below)
   -I header, --include header
                         additional header files to include in the BPF program
-                        as either full path, or relative to '/usr/include'
+                        as either full path, or relative to current working directory,
+                        or relative to default kernel header search path
 
 Probe specifier syntax:
         {p,r,t,u}:{[library],category}:function(signature)[:type[,type...]:expr[,expr...][:filter]][#label]
@@ -439,3 +440,10 @@ argdist -p 2780 -z 120 \
         -C 'p:c:write(int fd, char* buf, size_t len):char*:buf:fd==1'
         Spy on writes to STDOUT performed by process 2780, up to a string size
         of 120 characters 
+
+argdist -I 'kernel/sched/sched.h' \
+        -C 'p::__account_cfs_rq_runtime(struct cfs_rq *cfs_rq):s64:cfs_rq->runtime_remaining'
+        Trace on the cfs scheduling runqueue remaining runtime. The struct cfs_rq is defined
+        in kernel/sched/sched.h which is in kernel source tree and not in kernel-devel
+        package.  So this command needs to run at the kernel source tree root directory
+        so that the added header file can be found by the compiler.

tools/trace.py

@@ -576,6 +576,16 @@ trace 'u:pthread:pthread_create (arg4 != 0)'
         Trace the USDT probe pthread_create when its 4th argument is non-zero
 trace 'p::SyS_nanosleep(struct timespec *ts) "sleep for %lld ns", ts->tv_nsec'
         Trace the nanosleep syscall and print the sleep duration in ns
+trace -I 'linux/fs.h' \\
+      'p::uprobe_register(struct inode *inode) "a_ops = %llx", inode->i_mapping->a_ops'
+        Trace the uprobe_register inode mapping ops, and the symbol can be found
+        in /proc/kallsyms
+trace -I 'kernel/sched/sched.h' \\
+      'p::__account_cfs_rq_runtime(struct cfs_rq *cfs_rq) "%d", cfs_rq->runtime_remaining'
+        Trace the cfs scheduling runqueue remaining runtime. The struct cfs_rq is defined
+        in kernel/sched/sched.h which is in kernel source tree and not in kernel-devel
+        package.  So this command needs to run at the kernel source tree root directory
+        so that the added header file can be found by the compiler.
 """
 
         def __init__(self):
@@ -615,10 +625,12 @@ trace 'p::SyS_nanosleep(struct timespec *ts) "sleep for %lld ns", ts->tv_nsec'
                 parser.add_argument("-I", "--include", action="append",
                   metavar="header",
                   help="additional header files to include in the BPF program "
-                       "as either full path, or relative to '/usr/include'")
+                       "as either full path, "
+                       "or relative to current working directory, "
+                       "or relative to default kernel header search path")
                 self.args = parser.parse_args()
                 if self.args.tgid and self.args.pid:
-                        parser.error("only one of -p and -t may be specified")
+                        parser.error("only one of -p and -L may be specified")
 
         def _create_probes(self):
                 Probe.configure(self.args)

tools/trace_example.txt

@@ -249,7 +249,8 @@ optional arguments:
   -U, --user-stack      output user stack trace
   -I header, --include header
                         additional header files to include in the BPF program
-                        as either full path, or relative to '/usr/include'
+                        as either full path, or relative to current working directory,
+                        or relative to default kernel header search path
 
 EXAMPLES:
 
@@ -277,3 +278,13 @@ trace 'u:pthread:pthread_create (arg4 != 0)'
         Trace the USDT probe pthread_create when its 4th argument is non-zero
 trace 'p::SyS_nanosleep(struct timespec *ts) "sleep for %lld ns", ts->tv_nsec'
         Trace the nanosleep syscall and print the sleep duration in ns
+trace -I 'linux/fs.h' \
+      'p::uprobe_register(struct inode *inode) "a_ops = %llx", inode->i_mapping->a_ops'
+        Trace the uprobe_register inode mapping ops, and the symbol can be found
+        in /proc/kallsyms
+trace -I 'kernel/sched/sched.h' \
+      'p::__account_cfs_rq_runtime(struct cfs_rq *cfs_rq) "%d", cfs_rq->runtime_remaining'
+        Trace the cfs scheduling runqueue remaining runtime. The struct cfs_rq is defined
+        in kernel/sched/sched.h which is in kernel source tree and not in kernel-devel
+        package.  So this command needs to run at the kernel source tree root directory
+        so that the added header file can be found by the compiler.