bpf: Document PROG_TEST_RUN limitations

Per net/bpf/test_run.c, particular prog types have additional
restrictions around the parameters that can be provided, so document
these in the header.

I didn't bother documenting the limitation on duration for raw
tracepoints since that's an output parameter anyway.

Tested with ./tools/testing/selftests/bpf/test_doc_build.sh.

Suggested-by: Yonghong Song <yhs@fb.com>
Signed-off-by: Joe Stringer <joe@cilium.io>
Signed-off-by: Daniel Borkmann <daniel@iogearbox.net>
Acked-by: Yonghong Song <yhs@fb.com>
Acked-by: Lorenz Bauer <lmb@cloudflare.com>
Link: https://lore.kernel.org/bpf/20210410174549.816482-1-joe@cilium.io

diff --git a/include/uapi/linux/bpf.h b/include/uapi/linux/bpf.h
index 49371eba98ba70ce9fc1f2e009253dafaedc8d51..e1ee1be7e49b164d94ef0b351b3a8d93a437654c 100644 (file)
--- a/include/uapi/linux/bpf.h
+++ b/include/uapi/linux/bpf.h
@@ -312,6 +312,27 @@ union bpf_iter_link_info {
  *             *ctx_out*, *data_out* (for example, packet data), result of the
  *             execution *retval*, and *duration* of the test run.
  *
+ *             The sizes of the buffers provided as input and output
+ *             parameters *ctx_in*, *ctx_out*, *data_in*, and *data_out* must
+ *             be provided in the corresponding variables *ctx_size_in*,
+ *             *ctx_size_out*, *data_size_in*, and/or *data_size_out*. If any
+ *             of these parameters are not provided (ie set to NULL), the
+ *             corresponding size field must be zero.
+ *
+ *             Some program types have particular requirements:
+ *
+ *             **BPF_PROG_TYPE_SK_LOOKUP**
+ *                     *data_in* and *data_out* must be NULL.
+ *
+ *             **BPF_PROG_TYPE_XDP**
+ *                     *ctx_in* and *ctx_out* must be NULL.
+ *
+ *             **BPF_PROG_TYPE_RAW_TRACEPOINT**,
+ *             **BPF_PROG_TYPE_RAW_TRACEPOINT_WRITABLE**
+ *
+ *                     *ctx_out*, *data_in* and *data_out* must be NULL.
+ *                     *repeat* must be zero.
+ *
  *     Return
  *             Returns zero on success. On error, -1 is returned and *errno*
  *             is set appropriately.