kernel/linux.git/Documentation/bpf/standardization, branch v6.12.80

bpf, docs: Address comments from IETF Area Directors

2024-06-23T16:10:26+00:00

This patch does the following to address IETF feedback: * Remove mention of "program type" and reference future docs (and mention platform-specific docs exist) for helper functions and BTF. Addresses Roman Danyliw's comments based on GENART review from Ines Robles [0]. * Add reference for endianness as requested by John Scudder [1]. * Added bit numbers to top of 32-bit wide format diagrams as requested by Paul Wouters [2]. * Added more text about why BPF doesn't stand for anything, based on text from ebpf.io [3], as requested by Eric Vyncke and Gunter Van de Velde [4]. * Replaced "htobe16" (and similar) and the direction-specific description with just "be16" (and similar) and a direction-agnostic description, to match the direction-agnostic description in the Byteswap Instructions section. Based on feedback from Eric Vyncke [5]. [0] https://mailarchive.ietf.org/arch/msg/bpf/DvDgDWOiwk05OyNlWlAmELZFPlM/ [1] https://mailarchive.ietf.org/arch/msg/bpf/eKNXpU4jCLjsbZDSw8LjI29M3tM/ [2] https://mailarchive.ietf.org/arch/msg/bpf/hGk8HkYxeZTpdu9qW_MvbGKj7WU/ [3] https://ebpf.io/what-is-ebpf/#what-do-ebpf-and-bpf-stand-for [4] https://mailarchive.ietf.org/arch/msg/bpf/i93lzdN3ewnzzS_JMbinCIYxAIU/ [5] https://mailarchive.ietf.org/arch/msg/bpf/KBWXbMeDcSrq4vsKR_KkBbV6hI4/ Acked-by: David Vernet Signed-off-by: Dave Thaler Link: https://lore.kernel.org/r/20240623150453.10613-1-dthaler1968@gmail.com Signed-off-by: Alexei Starovoitov

bpf, docs: Fix instruction.rst indentation

2024-05-26T16:58:42+00:00

The table captions patch corrected indented most tables to work with the table directive for adding a caption but missed two of them. Signed-off-by: Dave Thaler Reviewed-by: Christoph Hellwig Link: https://lore.kernel.org/r/20240526061815.22497-1-dthaler1968@gmail.com Signed-off-by: Alexei Starovoitov

bpf, docs: Clarify call local offset

2024-05-25T17:41:57+00:00

In the Jump instructions section it explains that the offset is "relative to the instruction following the jump instruction". But the program-local section confusingly said "referenced by offset from the call instruction, similar to JA". This patch updates that sentence with consistent wording, saying it's relative to the instruction following the call instruction. Signed-off-by: Dave Thaler Acked-by: Yonghong Song Link: https://lore.kernel.org/r/20240525153332.21355-1-dthaler1968@gmail.com Signed-off-by: Alexei Starovoitov

bpf, docs: Add table captions

2024-05-25T17:39:31+00:00

As suggested by Ines Robles in his IETF GENART review at https://datatracker.ietf.org/doc/review-ietf-bpf-isa-02-genart-lc-robles-2024-05-16/ Signed-off-by: Dave Thaler Link: https://lore.kernel.org/r/20240524164618.18894-1-dthaler1968@gmail.com Signed-off-by: Alexei Starovoitov

bpf, docs: clarify sign extension of 64-bit use of 32-bit imm

2024-05-25T17:39:03+00:00

imm is defined as a 32-bit signed integer. {MOV, K, ALU64} says it does "dst = src" (where src is 'imm') and it does do dst = (s64)imm, which in that sense does sign extend imm. The MOVSX instruction is explained as sign extending, so added the example of {MOV, K, ALU64} to make this more clear. {JLE, K, JMP} says it does "PC += offset if dst <= src" (where src is 'imm', and the comparison is unsigned). This was apparently ambiguous to some readers as to whether the comparison was "dst <= (u64)(u32)imm" or "dst <= (u64)(s64)imm" so added an example to make this more clear. v1 -> v2: Address comments from Yonghong Signed-off-by: Dave Thaler Acked-by: Yonghong Song Acked-by: David Vernet Link: https://lore.kernel.org/r/20240520215255.10595-1-dthaler1968@gmail.com Signed-off-by: Alexei Starovoitov

bpf, docs: Use RFC 2119 language for ISA requirements

2024-05-25T17:38:35+00:00

Per IETF convention and discussion at LSF/MM/BPF, use MUST etc. keywords as requested by IETF Area Director review. Also as requested, indicate that documenting BTF is out of scope of this document and will be covered by a separate IETF specification. Added paragraph about the terminology that is required IETF boilerplate and must be worded exactly as such. Signed-off-by: Dave Thaler Acked-by: David Vernet Link: https://lore.kernel.org/r/20240517165855.4688-1-dthaler1968@gmail.com Signed-off-by: Alexei Starovoitov

bpf, docs: Move sentence about returning R0 to abi.rst

2024-05-25T17:37:49+00:00

As discussed at LSF/MM/BPF, the sentence about using R0 for returning values from calls is part of the calling convention and belongs in abi.rst. Any further additions or clarifications to this text are left for future patches on abi.rst. The current patch is simply to unblock progression of instruction-set.rst to a standard. In contrast, the restriction of register numbers to the range 0-10 is untouched, left in the instruction-set.rst definition of the src_reg and dst_reg fields. Signed-off-by: Dave Thaler Link: https://lore.kernel.org/r/20240517153445.3914-1-dthaler1968@gmail.com Signed-off-by: Alexei Starovoitov

bpf, docs: Fix the description of 'src' in ALU instructions

2024-05-15T16:34:54+00:00

An ALU instruction's source operand can be the value in the source register or the 32-bit immediate value encoded in the instruction. This is controlled by the 's' bit of the 'opcode'. The current description explicitly uses the phrase 'value of the source register' when defining the meaning of 'src'. Change the description to use 'source operand' in place of 'value of the source register'. Signed-off-by: Puranjay Mohan Acked-by: Dave Thaler Link: https://lore.kernel.org/r/20240514130303.113607-1-puranjay@kernel.org Signed-off-by: Alexei Starovoitov

bpf, docs: Clarify PC use in instruction-set.rst

2024-04-29T09:54:42+00:00

This patch elaborates on the use of PC by expanding the PC acronym, explaining the units, and the relative position to which the offset applies. Signed-off-by: Dave Thaler Signed-off-by: Daniel Borkmann Reviewed-by: David Vernet Link: https://lore.kernel.org/bpf/20240426231126.5130-1-dthaler1968@gmail.com

bpf, docs: Add introduction for use in the ISA Internet Draft

2024-04-26T02:15:21+00:00

The proposed intro paragraph text is derived from the first paragraph of the IETF BPF WG charter at https://datatracker.ietf.org/wg/bpf/about/ Signed-off-by: Dave Thaler Acked-by: David Vernet Link: https://lore.kernel.org/r/20240422190942.24658-1-dthaler1968@gmail.com Signed-off-by: Alexei Starovoitov