kernel/git/stable/linux.git/Documentation/bpf/instruction-set.rst, branch master

bpf,docs: Create new standardization subdirectory

2023-07-11T01:12:50+00:00

The BPF standardization effort is actively underway with the IETF. As described in the BPF Working Group (WG) charter in [0], there are a number of proposed documents, some informational and some proposed standards, that will be drafted as part of the standardization effort. [0]: https://datatracker.ietf.org/wg/bpf/about/ Though the specific documents that will formally be standardized will exist as Internet Drafts (I-D) and WG documents in the BPF WG datatracker page, the source of truth from where those documents will be generated will reside in the kernel documentation tree (originating in the bpf-next tree). Because these documents will be used to generate the I-D and WG documents which will be standardized with the IETF, they are a bit special as far as kernel-tree documentation goes: - They will be dual licensed with LGPL-2.1 OR BSD-2-Clause - IETF I-D and WG documents (the documents which will actually be standardized) will be auto-generated from these documents. In order to keep things clearly organized in the BPF documentation tree, and to make it abundantly clear where standards-related documentation needs to go, we should move standards-relevant documents into a separate standardization/ subdirectory. Signed-off-by: David Vernet Link: https://lore.kernel.org/r/20230710183027.15132-1-void@manifault.com Signed-off-by: Alexei Starovoitov

bpf, docs: Fix definition of BPF_NEG operation

2023-06-29T13:58:50+00:00

Instruction is an arithmetic negative, not a bitwise inverse. Signed-off-by: Dave Thaler Signed-off-by: Daniel Borkmann Acked-by: David Vernet Link: https://lore.kernel.org/bpf/20230627213912.951-1-dthaler1968@googlemail.com

bpf, docs: Shift operations are defined to use a mask

2023-05-17T14:18:33+00:00

Update the documentation regarding shift operations to explain the use of a mask, since otherwise shifting by a value out of range (like negative) is undefined. Signed-off-by: Dave Thaler Signed-off-by: Daniel Borkmann Acked-by: Yonghong Song Link: https://lore.kernel.org/bpf/20230509180845.1236-1-dthaler1968@googlemail.com

bpf, docs: Add docs on extended 64-bit immediate instructions

2023-04-03T00:02:54+00:00

Add docs on extended 64-bit immediate instructions, including six instructions previously undocumented. Include a brief description of maps and variables, as used by those instructions. V1 -> V2: rebased on top of latest master V2 -> V3: addressed comments from Alexei V3 -> V4: addressed comments from David Vernet Signed-off-by: Dave Thaler Link: https://lore.kernel.org/r/20230326054946.2331-1-dthaler1968@googlemail.com Signed-off-by: Alexei Starovoitov

bpf, docs: Add extended call instructions

2023-03-26T03:58:36+00:00

Add extended call instructions. Uses the term "program-local" for call by offset. And there are instructions for calling helper functions by "address" (the old way of using integer values), and for calling helper functions by BTF ID (for kfuncs). V1 -> V2: addressed comments from David Vernet V2 -> V3: make descriptions in table consistent with updated names V3 -> V4: addressed comments from Alexei V4 -> V5: fixed alignment Signed-off-by: Dave Thaler Acked-by: David Vernet Link: https://lore.kernel.org/r/20230326033117.1075-1-dthaler1968@googlemail.com Signed-off-by: Alexei Starovoitov

bpf, docs: Add signed comparison example

2023-03-14T05:10:45+00:00

Improve clarity by adding an example of a signed comparison instruction Signed-off-by: Dave Thaler Acked-by: David Vernet Acked-by: John Fastabend Link: https://lore.kernel.org/r/20230310233814.4641-1-dthaler1968@googlemail.com Signed-off-by: Alexei Starovoitov

bpf, docs: Explain helper functions

2023-03-10T21:02:00+00:00

Add brief text about existence of helper functions, with details to go in separate psABI text. Note that text about runtime functions (kfuncs) is part of a separate patch, not this one. Signed-off-by: Dave Thaler Link: https://lore.kernel.org/r/20230308205303.1308-1-dthaler1968@googlemail.com Signed-off-by: Alexei Starovoitov

bpf, docs: Document BPF insn encoding in term of stored bytes

2023-02-28T17:55:18+00:00

[Changes from V4: - s/regs:16/regs:8 in figure.] [Changes from V3: - Back to src_reg and dst_reg, since they denote register numbers as opposed to the values stored in these registers.] [Changes from V2: - Use src and dst consistently in the document. - Use a more graphical depiction of the 128-bit instruction. - Remove `Where:' fragment. - Clarify that unused bits are reserved and shall be zeroed.] [Changes from V1: - Use rst literal blocks for figures. - Avoid using | in the basic instruction/pseudo instruction figure. - Rebased to today's bpf-next master branch.] This patch modifies instruction-set.rst so it documents the encoding of BPF instructions in terms of how the bytes are stored (be it in an ELF file or as bytes in a memory buffer to be loaded into the kernel or some other BPF consumer) as opposed to how the instruction looks like once loaded. This is hopefully easier to understand by implementors looking to generate and/or consume bytes conforming BPF instructions. The patch also clarifies that the unused bytes in a pseudo-instruction shall be cleared with zeros. Signed-off-by: Jose E. Marchesi Acked-by: Yonghong Song Acked-by: David Vernet Link: https://lore.kernel.org/r/87h6v6i0da.fsf_-_@oracle.com Signed-off-by: Alexei Starovoitov

bpf, docs: Add explanation of endianness

2023-02-22T22:04:55+00:00

Document the discussion from the email thread on the IETF bpf list, where it was explained that the raw format varies by endianness of the processor. Signed-off-by: Dave Thaler Acked-by: David Vernet Link: https://lore.kernel.org/r/20230220223742.1347-1-dthaler1968@googlemail.com Signed-off-by: Alexei Starovoitov

bpf, docs: Add note about type convention

2023-02-08T17:25:26+00:00

Add explanation about use of "u64", "u32", etc. as the type convention used in BPF documentation. Signed-off-by: Dave Thaler Acked-by: David Vernet Link: https://lore.kernel.org/r/20230127014706.1005-1-dthaler1968@googlemail.com Signed-off-by: Alexei Starovoitov