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

bpf, doc: Improve wording of docs

2025-06-11T19:30:41+00:00

The phrase "dividing -1" is one I find confusing. E.g., "INT_MIN dividing -1" sounds like "-1 / INT_MIN" rather than the inverse. "divided by" instead of "dividing" assuming the inverse is meant. Signed-off-by: Eslam Khafagy Acked-by: Yonghong Song Link: https://lore.kernel.org/r/20250607222434.227890-1-eslam.medhat1993@gmail.com Signed-off-by: Alexei Starovoitov

Documentation: Fix spelling mistake.

2025-06-07T02:22:36+00:00

Fix typo "desination => destination" in file Documentation/bpf/standardization/instruction-set.rst Signed-off-by: Eslam Khafagy Acked-by: Dave Thaler Acked-by: David Vernet Link: https://lore.kernel.org/r/20250606100511.368450-1-eslam.medhat1993@gmail.com Signed-off-by: Alexei Starovoitov

docs/bpf: Document some special sdiv/smod operations

2025-02-26T15:54:49+00:00

Patch [1] fixed possible kernel crash due to specific sdiv/smod operations in bpf program. The following are related operations and the expected results of those operations: - LLONG_MIN/-1 = LLONG_MIN - INT_MIN/-1 = INT_MIN - LLONG_MIN%-1 = 0 - INT_MIN%-1 = 0 Those operations are replaced with codes which won't cause kernel crash. This patch documents what operations may cause exception and what replacement operations are. [1] https://lore.kernel.org/all/20240913150326.1187788-1-yonghong.song@linux.dev/ Signed-off-by: Yonghong Song Link: https://lore.kernel.org/r/20241107170924.2944681-1-yonghong.song@linux.dev Signed-off-by: Alexei Starovoitov

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