bpf: update bpf_{g,s}et_retval documentation

* replace 'syscall' with 'upper layers', still mention that it's being
  exported via syscall errno
* describe what happens in set_retval(-EPERM) + return 1
* describe what happens with bind's 'return 3'

Acked-by: Martin KaFai Lau <kafai@fb.com>
Signed-off-by: Stanislav Fomichev <sdf@google.com>
Link: https://lore.kernel.org/r/20220823222555.523590-5-sdf@google.com
Signed-off-by: Alexei Starovoitov <ast@kernel.org>

diff --git a/include/uapi/linux/bpf.h b/include/uapi/linux/bpf.h
index 7f87012..644600d 100644 (file)
--- a/include/uapi/linux/bpf.h
+++ b/include/uapi/linux/bpf.h
@@ -5085,17 +5085,29 @@ union bpf_attr {
  *
  * int bpf_get_retval(void)
  *     Description
- *             Get the syscall's return value that will be returned to userspace.
+ *             Get the BPF program's return value that will be returned to the upper layers.
  *
- *             This helper is currently supported by cgroup programs only.
+ *             This helper is currently supported by cgroup programs and only by the hooks
+ *             where BPF program's return value is returned to the userspace via errno.
  *     Return
- *             The syscall's return value.
+ *             The BPF program's return value.
  *
  * int bpf_set_retval(int retval)
  *     Description
- *             Set the syscall's return value that will be returned to userspace.
+ *             Set the BPF program's return value that will be returned to the upper layers.
+ *
+ *             This helper is currently supported by cgroup programs and only by the hooks
+ *             where BPF program's return value is returned to the userspace via errno.
+ *
+ *             Note that there is the following corner case where the program exports an error
+ *             via bpf_set_retval but signals success via 'return 1':
+ *
+ *                     bpf_set_retval(-EPERM);
+ *                     return 1;
+ *
+ *             In this case, the BPF program's return value will use helper's -EPERM. This
+ *             still holds true for cgroup/bind{4,6} which supports extra 'return 3' success case.
  *
- *             This helper is currently supported by cgroup programs only.
  *     Return
  *             0 on success, or a negative error in case of failure.
  *

diff --git a/tools/include/uapi/linux/bpf.h b/tools/include/uapi/linux/bpf.h
index f38814f..4fb6855 100644 (file)
--- a/tools/include/uapi/linux/bpf.h
+++ b/tools/include/uapi/linux/bpf.h
@@ -5085,17 +5085,29 @@ union bpf_attr {
  *
  * int bpf_get_retval(void)
  *     Description
- *             Get the syscall's return value that will be returned to userspace.
+ *             Get the BPF program's return value that will be returned to the upper layers.
  *
- *             This helper is currently supported by cgroup programs only.
+ *             This helper is currently supported by cgroup programs and only by the hooks
+ *             where BPF program's return value is returned to the userspace via errno.
  *     Return
- *             The syscall's return value.
+ *             The BPF program's return value.
  *
  * int bpf_set_retval(int retval)
  *     Description
- *             Set the syscall's return value that will be returned to userspace.
+ *             Set the BPF program's return value that will be returned to the upper layers.
+ *
+ *             This helper is currently supported by cgroup programs and only by the hooks
+ *             where BPF program's return value is returned to the userspace via errno.
+ *
+ *             Note that there is the following corner case where the program exports an error
+ *             via bpf_set_retval but signals success via 'return 1':
+ *
+ *                     bpf_set_retval(-EPERM);
+ *                     return 1;
+ *
+ *             In this case, the BPF program's return value will use helper's -EPERM. This
+ *             still holds true for cgroup/bind{4,6} which supports extra 'return 3' success case.
  *
- *             This helper is currently supported by cgroup programs only.
  *     Return
  *             0 on success, or a negative error in case of failure.
  *