add examples for including additional header files

Fix issue iovisor#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 <[email protected]>

tools/argdist.py

@@ -590,6 +590,13 @@ class Tool(object):
  -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 @@ def __init__(self):
  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 @@ class Tool(object):
  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 @@ def __init__(self):
  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.