[PATCH bpf-next] bpf: Document PROG_TEST_RUN limitations

[PATCH bpf-next] bpf: Document PROG_TEST_RUN limitations

[Joe Stringer]

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>
---
CC: Lorenz Bauer <lmb@cloudflare.com>
CC: Song Liu <songliubraving@fb.com>
CC: Stanislav Fomichev <sdf@google.com>
---
 include/uapi/linux/bpf.h | 21 +++++++++++++++++++++
 1 file changed, 21 insertions(+)

diff --git a/include/uapi/linux/bpf.h b/include/uapi/linux/bpf.h
index 49371eba98ba..e1ee1be7e49b 100644
--- 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.
-- 
2.27.0

Re: [PATCH bpf-next] bpf: Document PROG_TEST_RUN limitations

[Yonghong Song]

On 4/10/21 10:45 AM, Joe Stringer wrote:
> 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>
> ---
> CC: Lorenz Bauer <lmb@cloudflare.com>
> CC: Song Liu <songliubraving@fb.com>
> CC: Stanislav Fomichev <sdf@google.com>

Thanks for the fix of the doc.

Acked-by: Yonghong Song <yhs@fb.com>

Re: [PATCH bpf-next] bpf: Document PROG_TEST_RUN limitations

[Lorenz Bauer]

On Sat, 10 Apr 2021 at 18:45, Joe Stringer <joe@cilium.io> wrote:
>
> 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>

Thanks Joe!

Acked-by: Lorenz Bauer <lmb@cloudflare.com>


-- 
Lorenz Bauer  |  Systems Engineer
6th Floor, County Hall/The Riverside Building, SE1 7PB, UK

www.cloudflare.com

Re: [PATCH bpf-next] bpf: Document PROG_TEST_RUN limitations

[patchwork-bot+netdevbpf]

Hello:

This patch was applied to bpf/bpf-next.git (refs/heads/master):

On Sat, 10 Apr 2021 10:45:48 -0700 you wrote:
> 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.
> 
> [...]

Here is the summary with links:
  - [bpf-next] bpf: Document PROG_TEST_RUN limitations
    https://git.kernel.org/bpf/bpf-next/c/f3c45326ee71

You are awesome, thank you!
--
Deet-doot-dot, I am a bot.
https://korg.docs.kernel.org/patchwork/pwbot.html