linux-kernel - Re: [PATCH bpf-next] Documentation: bpf: escape underscore in BPF type name prefix

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-ID: <CAEf4Bzau0QuBiNsXoMq_QRV+_MTyodQsvW7O2kbScgmVmbuXkQ@mail.gmail.com>
Date:   Fri, 4 Nov 2022 16:11:10 -0700
From:   Andrii Nakryiko <andrii.nakryiko@...il.com>
To:     Bagas Sanjaya <bagasdotme@...il.com>
Cc:     bpf@...r.kernel.org, linux-doc@...r.kernel.org,
        linux-kernel@...r.kernel.org, Alexei Starovoitov <ast@...nel.org>,
        Daniel Borkmann <daniel@...earbox.net>,
        Andrii Nakryiko <andrii@...nel.org>,
        Martin KaFai Lau <martin.lau@...ux.dev>,
        Song Liu <song@...nel.org>, Yonghong Song <yhs@...com>,
        John Fastabend <john.fastabend@...il.com>,
        KP Singh <kpsingh@...nel.org>,
        Stanislav Fomichev <sdf@...gle.com>,
        Hao Luo <haoluo@...gle.com>, Jiri Olsa <jolsa@...nel.org>,
        Jonathan Corbet <corbet@....net>,
        David Vernet <void@...ifault.com>,
        Kumar Kartikeya Dwivedi <memxor@...il.com>
Subject: Re: [PATCH bpf-next] Documentation: bpf: escape underscore in BPF
 type name prefix

On Fri, Nov 4, 2022 at 5:39 AM Bagas Sanjaya <bagasdotme@...il.com> wrote:
>
> Sphinx reported unknown target warning:
>
> Documentation/bpf/bpf_design_QA.rst:329: WARNING: Unknown target name: "bpf".
>
> The warning is caused by BPF type name prefix ("bpf_") which is written
> without escaping the trailing underscore.
>
> Escape the underscore to fix the warning. While at it, wrap the
> containing paragraph in less than 80 characters.
>
> Fixes: 9805af8d8a5b17 ("bpf: Document UAPI details for special BPF types")
> Signed-off-by: Bagas Sanjaya <bagasdotme@...il.com>
> ---
>  Documentation/bpf/bpf_design_QA.rst | 8 ++++----
>  1 file changed, 4 insertions(+), 4 deletions(-)
>

Applied, thanks. But would the other similar case be problematic?

$ rg 'bpf_\b'
bpf_design_QA.rst
329:NOTE: BPF subsystem specially reserves the 'bpf_' prefix for type names, in
331:avoid defining types with 'bpf_' prefix to not be broken in future
releases. In
333:with 'bpf_' prefix.

libbpf/libbpf_naming_convention.rst
12:following prefixes: ``bpf_``, ``btf_``, ``libbpf_``, ``btf_dump_``,
59:described above should have ``libbpf_`` prefix, e.g.


> diff --git a/Documentation/bpf/bpf_design_QA.rst b/Documentation/bpf/bpf_design_QA.rst
> index 4e4af398607b58..17e774d96c5e4b 100644
> --- a/Documentation/bpf/bpf_design_QA.rst
> +++ b/Documentation/bpf/bpf_design_QA.rst
> @@ -326,11 +326,11 @@ size, type, and alignment, or any other user visible API or ABI detail across
>  kernel releases. The users must adapt their BPF programs to the new changes and
>  update them to make sure their programs continue to work correctly.
>
> -NOTE: BPF subsystem specially reserves the 'bpf_' prefix for type names, in
> +NOTE: BPF subsystem specially reserves the 'bpf\_' prefix for type names, in
>  order to introduce more special fields in the future. Hence, user programs must
> -avoid defining types with 'bpf_' prefix to not be broken in future releases. In
> -other words, no backwards compatibility is guaranteed if one using a type in BTF
> -with 'bpf_' prefix.
> +avoid defining types with 'bpf\_' prefix to not be broken in future releases.
> +In other words, no backwards compatibility is guaranteed if one using a type
> +in BTF with 'bpf\_' prefix.
>
>  Q: What is the compatibility story for special BPF types in local kptrs?
>  ------------------------------------------------------------------------
>
> base-commit: f71b2f64177a199d5b1d2047e155d45fd98f564a
> --
> An old man doll... just what I always wanted! - Clara
>