inital docs for tracepoint args

README.md

@@ -97,6 +97,39 @@ verify_cpu+0
 ]: 150
 ```
 
+## One-Liners
+
+The following one-liners demonstrate different capabilities:
+
+```
+# Files opened by process
+bpftrace -e 'tracepoint:syscalls:sys_enter_open { printf("%s %s\n", comm, str(args->filename)); }'
+
+# Syscall count by program
+bpftrace -e 'tracepoint:raw_syscalls:sys_enter { @[comm] = count(); }'
+
+# Read bytes by process:
+bpftrace -e 'tracepoint:syscalls:sys_exit_read /args->ret/ { @[comm] = sum(args->ret); }'
+
+# Read size distribution by process:
+bpftrace -e 'tracepoint:syscalls:sys_exit_read { @[comm] = hist(args->ret); }'
+
+# Show per-second syscall rates:
+bpftrace -e 'tracepoint:raw_syscalls:sys_enter { @ = count(); } interval:s:1 { print(@); clear(@); }'
+
+# Trace disk size by process
+bpftrace -e 'tracepoint:block:block_rq_issue { printf("%d %s %d\n", pid, comm, args->bytes); }'
+
+# Count page faults by process
+bpftrace -e 'software:faults:1 { @[comm] = count(); }'
+
+# Count LLC cache misses by process name and PID (uses PMCs):
+bpftrace -e 'hardware:cache-misses:1000000 { @[comm, pid] = count(); }'
+
+# Profile user-level stacks at 99 Hertz, for PID 189:
+bpftrace -e 'profile:hz:99 /pid == 189/ { @[ustack] = count(); }'
+```
+
 ## Tools
 
 bpftrace contains various tools, which also serve as examples of programming in the bpftrace language.

docs/reference_guide.md

@@ -362,15 +362,15 @@ These can be used in bpftrace scripts to document your code.
 
 ## 4. `->`: C Struct Navigation
 
-**TODO**: see issue [#31](https://github.com/iovisor/bpftrace/issues/31)
-
-Future example:
+Example:
 
 ```
-bpftrace -e 'kprobe:do_nanosleep { printf("secs: %d\n", arg0->tv_nsec); }
+bpftrace -e 'tracepoint:syscalls:sys_enter_open { printf("%s %s\n", comm, str(args->filename)); }'
 ```
 
-or
+This is returning the `filename` member from the `args` struct, which for tracepoint probes contains the tracepoint arguments.
+
+A future example is to add struct support to kprobes, so that this is possible (see issue [#34](https://github.com/iovisor/bpftrace/issues/34)):
 
 ```
 bpftrace -e 'kprobe:do_nanosleep { printf("secs: %d\n", ((struct timespec *)arg0)->tv_nsec); }'
@@ -454,6 +454,8 @@ returned: 21
 [...]
 ```
 
+**TODO**: see issue [#34](https://github.com/iovisor/bpftrace/issues/34) for supporting struct arguments on kprobes.
+
 ## 3. `uprobe`/`uretprobe`: Dynamic Tracing, User-Level
 
 Syntax:
@@ -559,14 +561,42 @@ block I/O created by 28941
 
 ## 6. `tracepoint`: Static Tracing, Kernel-Level Arguments
 
-**TODO**: see issue [#32](https://github.com/iovisor/bpftrace/issues/32)
+Example:
+
+```
+# bpftrace-tp -e 'tracepoint:syscalls:sys_enter_open { printf("%s %s\n", comm, str(args->filename)); }'
+Attaching 1 probe...
+irqbalance /proc/interrupts
+irqbalance /proc/stat
+snmpd /proc/diskstats
+snmpd /proc/stat
+snmpd /proc/vmstat
+snmpd /proc/net/dev
+[...]
+```
 
-Future examples:
+The available members for each tracepoint can be listed from their /format file in /sys. For example:
 
 ```
-bpftrace -e 'tracepoint:block:block_rq_insert { printf("sectors: %d\n", args->nr_sector); }'
+# cat /sys/kernel/debug/tracing/events/syscalls/sys_enter_open/format
+name: sys_enter_open
+ID: 603
+format:
+	field:unsigned short common_type;	offset:0;	size:2;	signed:0;
+	field:unsigned char common_flags;	offset:2;	size:1;	signed:0;
+	field:unsigned char common_preempt_count;	offset:3;	size:1;	signed:0;
+	field:int common_pid;	offset:4;	size:4;	signed:1;
+
+	field:int __syscall_nr;	offset:8;	size:4;	signed:1;
+	field:const char * filename;	offset:16;	size:8;	signed:0;
+	field:int flags;	offset:24;	size:8;	signed:0;
+	field:umode_t mode;	offset:32;	size:8;	signed:0;
+
+print fmt: "filename: 0x%08lx, flags: 0x%08lx, mode: 0x%08lx", ((unsigned long)(REC->filename)), ((unsigned long)(REC->flags)), ((unsigned long)(REC->mode))
 ```
 
+Apart from the `filename` member, we can also print `flags`, `mode`, and more. After the "common" members listed first, the members are specific to the tracepoint.
+
 ## 7. `usdt`: Static Tracing, User-Level
 
 Syntax: