Update the documentation of the k/uprobe offset support

man/man8/trace.8

@@ -86,7 +86,7 @@ information. See PROBE SYNTAX below.
 .SH PROBE SYNTAX
 The general probe syntax is as follows:
 
-.B [{p,r}]:[library]:function[(signature)] [(predicate)] ["format string"[, arguments]]
+.B [{p,r}]:[library]:function[+offset][(signature)] [(predicate)] ["format string"[, arguments]]
 
 .B {t:category:event,u:library:probe} [(predicate)] ["format string"[, arguments]]
 .TP
@@ -107,6 +107,10 @@ The tracepoint category. For example, "sched" or "irq".
 .TP
 .B function
 The function to probe.
+.B offset
+The offset after the address of the function where the probe should injected.
+For example "kfree_skb+56" in decimal or hexadecimal "kfree_skb+0x38" format.
+Only works with kprobes and uprobes. Zero if omitted.
 .TP
 .B signature
 The optional signature of the function to probe. This can make it easier to

tools/trace_example.txt

@@ -287,7 +287,52 @@ STRCMP helper in binary mode (--bin_cmp flag) to compare optval array
 against int value of 108 (parametr of setsockopt call) in hex representation
 (little endian format)
 
-
+For advanced users there is a possibility to insert the kprobes or uprobes
+after a certain offset, rather than the start of the function call
+This is useful for tracing register values at different places of the
+execution of a function. Lets consider the following example:
+
+int main()
+{
+ int val = 0xdead;
+ printf("%d\n", val);
+ val = 0xbeef;
+ printf("%d\n", val);
+}
+
+After compiling the code with -O3 optimization the object code looks
+like the following (with GCC 10 and x86_64 architecture):
+
+objdump --disassemble=main --prefix-addresses a.out
+
+0000000000001060 <main> endbr64
+0000000000001064 <main+0x4> sub $0x8,%rsp
+0000000000001068 <main+0x8> mov $0xdead,%edx
+000000000000106d <main+0xd> mov $0x1,%edi
+0000000000001072 <main+0x12> xor %eax,%eax
+0000000000001074 <main+0x14> lea 0xf89(%rip),%rsi
+000000000000107b <main+0x1b> callq 0000000000001050 <__printf_chk@plt>
+0000000000001080 <main+0x20> mov $0xbeef,%edx
+0000000000001085 <main+0x25> lea 0xf78(%rip),%rsi
+000000000000108c <main+0x2c> xor %eax,%eax
+000000000000108e <main+0x2e> mov $0x1,%edi
+0000000000001093 <main+0x33> callq 0000000000001050 <__printf_chk@plt>
+0000000000001098 <main+0x38> xor %eax,%eax
+000000000000109a <main+0x3a> add $0x8,%rsp
+000000000000109e <main+0x3e> retq
+
+The 0xdead and later the 0xbeef values are moved into the edx register.
+As the dissassembly shows the edx register contains the 0xdead value
+after the 0xd offset and 0xbeef after the 0x25 offset. To verify this
+with trace lets insert probes to those offsets. The following
+command insert two uprobe one after the 0xd offset and another one
+after the 0x25 offset of the main function. The probe print the
+value of the edx register which will show us the correct values.
+
+trace 'p:/tmp/a.out:main+0xd "%x", ctx->dx' 'p:/tmp/a.out:main+0x25 "%x", ctx->dx'
+PID TID COMM FUNC -
+25754 25754 a.out main dead
+25754 25754 a.out main beef
 
 
 USAGE message:
@@ -335,6 +380,8 @@ EXAMPLES:
 
 trace do_sys_open
  Trace the open syscall and print a default trace message when entered
+trace kfree_skb+0x12
+ Trace the kfree_skb kernel function after the instruction on the 0x12 offset
 trace 'do_sys_open "%s", arg2@user'
  Trace the open syscall and print the filename being opened. @user is
  added to arg2 in kprobes to ensure that char * should be copied from