Update 'tools/wakeuptime' documentation

This updates the manpage and examples for 'tools/wakeuptime'
so that they include descriptions of the new arguments.
Signed-off-by: Sandipan Das <sandipan@linux.vnet.ibm.com>

man/man8/wakeuptime.8

@@ -2,7 +2,7 @@
 .SH NAME
 wakeuptime \- Summarize sleep to wakeup time by waker kernel stack. Uses Linux eBPF/bcc.
 .SH SYNOPSIS
-.B wakeuptime [\-h] [\-u] [\-p PID] [\-v] [\-f] [duration]
+.B wakeuptime [\-h] [\-u] [\-p PID] [\-v] [\-f] [\-\-stack-storage-size STACK_STORAGE_SIZE] [\-m MIN_BLOCK_TIME] [\-M MAX_BLOCK_TIME] [duration]
 .SH DESCRIPTION
 This program shows the kernel stack traces for threads that woke up other 
 blocked threads, along with the process names of the waker and target, along
@@ -23,10 +23,8 @@ of the blocked thread. wakeuptime shows the stack trace of the waker thread.
 
 See http://www.brendangregg.com/FlameGraphs/offcpuflamegraphs.html
 
-The stack depth is currently limited to 20, and the stack traces are kernel
-mode only. Check for newer versions where either may be improved.
-
-This currently only works on x86_64. Check for future versions.
+This tool only works on Linux 4.6+. It uses the new `BPF_STACK_TRACE` table
+APIs to generate the in-kernel stack traces.
 .SH REQUIREMENTS
 CONFIG_BPF and bcc.
 .SH OPTIONS
@@ -46,8 +44,17 @@ Show raw addresses (for non-folded format).
 \-p PID
 Trace this process ID only (filtered in-kernel).
 .TP
+\-\-stack-storage-size STACK_STORAGE_SIZE
+Change the number of unique stack traces that can be stored and displayed.
+.TP
 duration
 Duration to trace, in seconds.
+.TP
+\-m MIN_BLOCK_TIME
+The amount of time in microseconds over which we store traces (default 1)
+.TP
+\-M MAX_BLOCK_TIME
+The amount of time in microseconds under which we store traces (default U64_MAX)
 .SH EXAMPLES
 .TP
 Trace all thread blocking events, and summarize (in-kernel) by kernel stack trace and total blocked time:
@@ -77,8 +84,8 @@ printed. While these techniques greatly lower overhead, scheduler events are
 still a high frequency event, as they can exceed 1 million events per second,
 and so caution should still be used. Test before production use.
 
-If the overhead is still a problem, take a look at the MINBLOCK_US tunable in
-the code. If your aim is to chase down longer blocking events, then this could
+If the overhead is still a problem, take a look at the min block option.
+If your aim is to chase down longer blocking events, then this could
 be increased to filter shorter blocking events, further lowering overhead.
 .SH SOURCE
 This is from bcc.

tools/wakeuptime_example.txt

@@ -448,20 +448,31 @@ creating your "wakeup time flame graphs".
 USAGE message:
 
 # ./wakeuptime -h
-usage: wakeuptime [-h] [-u] [-p PID] [-v] [-f] [duration]
+usage: wakeuptime [-h] [-u] [-p PID] [-v] [-f]
+                  [--stack-storage-size STACK_STORAGE_SIZE]
+                  [-m MIN_BLOCK_TIME] [-M MAX_BLOCK_TIME]
+                  [duration]
 
 Summarize sleep to wakeup time by waker kernel stack
 
 positional arguments:
-  duration           duration of trace, in seconds
+  duration              duration of trace, in seconds
 
 optional arguments:
-  -h, --help         show this help message and exit
-  -u, --useronly     user threads only (no kernel threads)
-  -p PID, --pid PID  trace this PID only
-  -v, --verbose      show raw addresses
-  -f, --folded       output folded format
-
+  -h, --help            show this help message and exit
+  -u, --useronly        user threads only (no kernel threads)
+  -p PID, --pid PID     trace this PID only
+  -v, --verbose         show raw addresses
+  -f, --folded          output folded format
+  --stack-storage-size STACK_STORAGE_SIZE
+                        the number of unique stack traces that can be stored
+                        and displayed (default 1024)
+  -m MIN_BLOCK_TIME, --min-block-time MIN_BLOCK_TIME
+                        the amount of time in microseconds over which we store
+                        traces (default 1)
+  -M MAX_BLOCK_TIME, --max-block-time MAX_BLOCK_TIME
+                        the amount of time in microseconds under which we
+                        store traces (default U64_MAX)
 examples:
     ./wakeuptime             # trace blocked time with waker stacks
     ./wakeuptime 5           # trace for 5 seconds only