Update documentation for 4.17, add documentation for probability option

man/man8/inject.8

@@ -3,7 +3,7 @@
 inject \- injects appropriate error into function if input call chain and
 predicates are satisfied. Uses Linux eBPF/bcc.
 .SH SYNOPSIS
-.B trace -h [-I header] [-v]
+.B inject -h [-I header] [-P probability] [-v] mode spec
 .SH DESCRIPTION
 inject injects errors into specified kernel functionality when a given call
 chain and associated predicates are satsified.
@@ -13,13 +13,6 @@ kernel. You should know what you're doing if you're using this tool.
 
 This makes use of a Linux 4.16 feature (bpf_override_return())
 
-Additionally, use of the kmalloc failure mode is only possible with 
-
- commit f7174d08a5fc ("mm: make should_failslab always available for
- fault injection")
-
-which is in mm-tree but not yet in mainline (as of 4.16-rc5).
-
 Since this uses BPF, only the root user can use this tool.
 .SH REQUIREMENTS
 CONFIG_BPF, CONFIG_BPF_KPROBE_OVERRIDE, bcc
@@ -33,6 +26,9 @@ Display the generated BPF program, for debugging or modification.
 .TP
 \-I header
 Necessary headers to be included.
+.TP
+\-P probability
+Optional probability of failure, default 1.
 .SH EXAMPLES
 Please see inject_example.txt
 .SH SOURCE

tools/inject_example.txt

@@ -5,22 +5,24 @@ mode (kmalloc,bio,etc) given a call chain and an optional set of predicates. You
 can also optionally print out the generated BPF program for
 modification/debugging purposes.
 
-As a simple example, let's say you wanted to fail all mounts. While we cannot
-fail the mount() syscall directly (a patch is in the works), we can easily
-fail do_mount() calls like so:
+As a simple example, let's say you wanted to fail all mounts. As of 4.17 we can
+fail syscalls directly, so let's do that:
 
-# ./inject.py kmalloc -v 'do_mount()'
+# ./inject.py kmalloc -v 'SyS_mount()'
 
 The first argument indicates the mode (or what to fail). Appropriate headers are
-specified. The verbosity flag prints the generated program.
+specified, if necessary. The verbosity flag prints the generated program. Note
+that some syscalls will be available as 'SyS_xyz' and some will be available as
+'sys_xyz'. This is largely dependent on the number of arguments each syscall
+takes.
 
 Trying to mount various filesystems will fail and report an inability to
 allocate memory, as expected.
 
 Whenever a predicate is missing, an implicit "(true)" is inserted. The example
 above can be explicitly written as:
 
-# ./inject.py kmalloc -v '(true) => do_mount()(true)'
+# ./inject.py kmalloc -v '(true) => SyS_mount()(true)'
 
 The "(true)" without an associated function is a predicate for the error
 injection mechanism of the current mode. In the case of kmalloc, the predicate
@@ -106,9 +108,14 @@ As an extension to the above, one could easily fail all btrfs superblock writes
 (we only fail the primary) by calculating the sector number of the mirrors and
 amending the predicate accordingly.
 
-USAGE message:
+Inject also provides a probability option; this allows you to fail the
+path+predicates some percentage of the time. For example, let's say we want to
+fail our mounts half the time:
+
+# ./inject.py kmalloc -v -P 0.01 'SyS_mount()'
 
-usage: inject.py [-h] [-I header] [-v] mode spec
+USAGE message:
+usage: inject.py [-h] [-I header] [-P probability] [-v] mode spec
 
 Fail specified kernel functionality when call chain and predicates are met
 
@@ -120,5 +127,6 @@ optional arguments:
  -h, --help show this help message and exit
  -I header, --include header
  additional header files to include in the BPF program
+ -P probability, --probability probability
+ probability that this call chain will fail
  -v, --verbose print BPF program
-