Merge pull request #1539 from hMcLauchlan/override-return-helper

Add bpf_override_return() helper definition

docs/kernel-versions.md

@@ -162,3 +162,4 @@ Helper | Kernel version | Commit
 `BPF_FUNC_trace_printk()` | 4.1 | [9c959c863f82](https://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/commit/?id=9c959c863f8217a2ff3d7c296e8223654d240569)
 `BPF_FUNC_xdp_adjust_head()` | 4.10 | [17bedab27231](https://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/commit/?id=17bedab2723145d17b14084430743549e6943d03)
 `BPF_FUNC_xdp_adjust_meta()` | 4.15 | [de8f3a83b0a0](https://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/commit/?id=de8f3a83b0a0fddb2cf56e7a718127e9619ea3da)
+`BPF_FUNC_override_return()` | 4.16 | [9802d86585db](https://git.kernel.org/pub/scm/linux/kernel/git/davem/net-next.git/commit/?id=9802d86585db91655c7d1929a4f6bbe0952ea88e)

docs/reference_guide.md

@@ -22,6 +22,8 @@ This guide is incomplete. If something feels missing, check the bcc and kernel s
         - [5. bpf_get_current_uid_gid()](#5-bpf_get_current_uid_gid)
         - [6. bpf_get_current_comm()](#6-bpf_get_current_comm)
         - [7. bpf_log2l()](#7-bpflog2l)
+    - [Debugging](#debugging)
+        - [1. bpf_override_return()](#1-bpf_override_return)
     - [Output](#output)
         - [1. bpf_trace_printk()](#1-bpf_trace_printk)
         - [2. BPF_PERF_OUTPUT](#2-bpf_perf_output)
@@ -324,6 +326,32 @@ Examples in situ:
 [search /examples](https://github.com/iovisor/bcc/search?q=bpf_log2l+path%3Aexamples&type=Code),
 [search /tools](https://github.com/iovisor/bcc/search?q=bpf_log2l+path%3Atools&type=Code)
 
+## Debugging
+
+### 1. bpf_override_return()
+
+Syntax: ```int bpf_override_return(struct pt_regs *, unsigned long rc)```
+
+Return: 0 on success
+
+When used in a program attached to a function entry kprobe, causes the
+execution of the function to be skipped, immediately returning `rc` instead.
+This is used for targeted error injection. 
+
+bpf_override_return will only work when the kprobed function is whitelisted to
+allow error injections. Whitelisting entails tagging a function with
+`BPF_ALLOW_ERROR_INJECTION()` in the kernel source tree; see `io_ctl_init` for
+an example. If the kprobed function is not whitelisted, the bpf program will
+fail to attach with ` ioctl(PERF_EVENT_IOC_SET_BPF): Invalid argument`
+
+
+```C
+int kprobe__io_ctl_init(void *ctx) {
+	bpf_override_return(ctx, -ENOMEM);
+	return 0;
+}
+```
+
 ## Output
 
 ### 1. bpf_trace_printk()

src/cc/export/helpers.h

@@ -299,6 +299,8 @@ static int (*bpf_skb_change_head)(void *ctx, u32 len, u64 flags) =
   (void *) BPF_FUNC_skb_change_head;
 static int (*bpf_xdp_adjust_head)(void *ctx, int offset) =
   (void *) BPF_FUNC_xdp_adjust_head;
+static int (*bpf_override_return)(void *pt_regs, unsigned long rc) =
+  (void *) BPF_FUNC_override_return;
 
 /* llvm builtin functions that eBPF C program may use to
  * emit BPF_LD_ABS and BPF_LD_IND instructions