summaryrefslogtreecommitdiff
path: root/Documentation/bpf/standardization
AgeCommit message (Collapse)Author
2024-03-04bpf, docs: Rename legacy conformance group to packetDave Thaler
There could be other legacy conformance groups in the future, so use a more descriptive name. The status of the conformance group in the IANA registry is what designates it as legacy, not the name of the group. Signed-off-by: Dave Thaler <dthaler1968@gmail.com> Link: https://lore.kernel.org/r/20240302012229.16452-1-dthaler1968@gmail.com Signed-off-by: Alexei Starovoitov <ast@kernel.org> Signed-off-by: Daniel Borkmann <daniel@iogearbox.net>
2024-03-02bpf, docs: Use IETF format for field definitions in instruction-set.rstDave Thaler
In preparation for publication as an IETF RFC, the WG chairs asked me to convert the document to use IETF packet format for field layout, so this patch attempts to make it consistent with other IETF documents. Some fields that are not byte aligned were previously inconsistent in how values were defined. Some were defined as the value of the byte containing the field (like 0x20 for a field holding the high four bits of the byte), and others were defined as the value of the field itself (like 0x2). This PR makes them be consistent in using just the values of the field itself, which is IETF convention. As a result, some of the defines that used BPF_* would no longer match the value in the spec, and so this patch also drops the BPF_* prefix to avoid confusion with the defines that are the full-byte equivalent values. For consistency, BPF_* is then dropped from other fields too. BPF_<foo> is thus the Linux implementation-specific define for <foo> as it appears in the BPF ISA specification. The syntax BPF_ADD | BPF_X | BPF_ALU only worked for full-byte values so the convention {ADD, X, ALU} is proposed for referring to field values instead. Also replace the redundant "LSB bits" with "least significant bits". A preview of what the resulting Internet Draft would look like can be seen at: https://htmlpreview.github.io/?https://raw.githubusercontent.com/dthaler/ebp f-docs-1/format/draft-ietf-bpf-isa.html v1->v2: Fix sphinx issue as recommended by David Vernet Signed-off-by: Dave Thaler <dthaler1968@gmail.com> Acked-by: David Vernet <void@manifault.com> Link: https://lore.kernel.org/r/20240301222337.15931-1-dthaler1968@gmail.com Signed-off-by: Alexei Starovoitov <ast@kernel.org>
2024-02-22bpf, docs: specify which BPF_ABS and BPF_IND fields were zeroDave Thaler
Specifying which fields were unused allows IANA to only list as deprecated instructions that were actually used, leaving the rest as unassigned and possibly available for future use for something else. Signed-off-by: Dave Thaler <dthaler1968@gmail.com> Acked-by: David Vernet <void@manifault.com> Link: https://lore.kernel.org/r/20240221175419.16843-1-dthaler1968@gmail.com Signed-off-by: Alexei Starovoitov <ast@kernel.org>
2024-02-22bpf, docs: Fix typos in instruction-set.rstDave Thaler
* "BPF ADD" should be "BPF_ADD". * "src" should be "src_reg" in several places. The latter is the field name in the instruction. The former refers to the value of the register, or the immediate. * Add '' around field names in one sentence, for consistency with the rest of the document. Signed-off-by: Dave Thaler <dthaler1968@gmail.com> Acked-by: David Vernet <void@manifault.com> Link: https://lore.kernel.org/r/20240221173535.16601-1-dthaler1968@gmail.com Signed-off-by: Alexei Starovoitov <ast@kernel.org>
2024-02-13bpf, docs: Update ISA document titleDave Thaler
* Use "Instruction Set Architecture (ISA)" instead of "Instruction Set Specification" * Remove version number As previously discussed on the mailing list at https://mailarchive.ietf.org/arch/msg/bpf/SEpn3OL9TabNRn-4rDX9A6XVbjM/ Signed-off-by: Dave Thaler <dthaler1968@gmail.com> Signed-off-by: Daniel Borkmann <daniel@iogearbox.net> Acked-by: David Vernet <void@manifault.com> Link: https://lore.kernel.org/bpf/20240208221449.12274-1-dthaler1968@gmail.com
2024-02-06bpf, docs: Fix typos in instructions-set.rstDave Thaler
* "imm32" should just be "imm" * Add blank line to fix formatting error reported by Stephen Rothwell [0] [0]: https://lore.kernel.org/bpf/20240206153301.4ead0bad@canb.auug.org.au/T/#u Signed-off-by: Dave Thaler <dthaler1968@gmail.com> Acked-by: David Vernet <void@manifault.com> Link: https://lore.kernel.org/r/20240206045146.4965-1-dthaler1968@gmail.com Signed-off-by: Alexei Starovoitov <ast@kernel.org>
2024-02-05bpf, docs: Expand set of initial conformance groupsDave Thaler
This patch attempts to update the ISA specification according to the latest mailing list discussion about conformance groups, in a way that is intended to be consistent with IANA registry processes and IETF 118 WG meeting discussion. It does the following: * Split basic into base32 and base64 for 32-bit vs 64-bit base instructions * Split division/multiplication/modulo instructions out of base groups * Split atomic instructions out of base groups There may be additional changes as discussion continues, but there seems to be consensus on the principles above. v1->v2: fixed typo pointed out by David Vernet v2->v3: Moved multiplication to same groups as division/modulo Signed-off-by: Dave Thaler <dthaler1968@gmail.com> Acked-by: David Vernet <void@manifault.com> Link: https://lore.kernel.org/r/20240202221110.3872-1-dthaler1968@gmail.com Signed-off-by: Alexei Starovoitov <ast@kernel.org>
2024-02-01bpf, docs: Clarify which legacy packet instructions existedDave Thaler
As discussed on the BPF IETF mailing list (see link), this patch updates the "Legacy BPF Packet access instructions" section to clarify which instructions are deprecated (vs which were never defined and so are not deprecated). Signed-off-by: Dave Thaler <dthaler1968@gmail.com> Signed-off-by: Daniel Borkmann <daniel@iogearbox.net> Acked-by: Yonghong Song <yonghong.song@linux.dev> Acked-by: David Vernet <void@manifault.com> Link: https://mailarchive.ietf.org/arch/msg/bpf/5LnnKm093cGpOmDI9TnLQLBXyys Link: https://lore.kernel.org/bpf/20240131033759.3634-1-dthaler1968@gmail.com
2024-01-29docs/bpf: Improve documentation of 64-bit immediate instructionsYonghong Song
For 64-bit immediate instruction, 'BPF_IMM | BPF_DW | BPF_LD' and src_reg=[0-6], the current documentation describes the 64-bit immediate is constructed by: imm64 = (next_imm << 32) | imm But actually imm64 is only used when src_reg=0. For all other variants (src_reg != 0), 'imm' and 'next_imm' have separate special encoding requirement and imm64 cannot be easily used to describe instruction semantics. This patch clarifies that 64-bit immediate instructions use two 32-bit immediate values instead of a 64-bit immediate value, so later describing individual 64-bit immediate instructions becomes less confusing. Signed-off-by: Yonghong Song <yonghong.song@linux.dev> Signed-off-by: Daniel Borkmann <daniel@iogearbox.net> Acked-by: Dave Thaler <dthaler1968@gmail.com> Link: https://lore.kernel.org/bpf/20240127194629.737589-1-yonghong.song@linux.dev
2024-01-26bpf, docs: Clarify definitions of various instructionsDave Thaler
Clarify definitions of several instructions: * BPF_NEG does not support BPF_X * BPF_CALL does not support BPF_JMP32 or BPF_X * BPF_EXIT does not support BPF_X * BPF_JA does not support BPF_X (was implied but not explicitly stated) Also fix a typo in the wide instruction figure where the field is actually named "opcode" not "code". Signed-off-by: Dave Thaler <dthaler1968@gmail.com> Signed-off-by: Daniel Borkmann <daniel@iogearbox.net> Acked-by: Yonghong Song <yonghong.song@linux.dev> Link: https://lore.kernel.org/bpf/20240126040050.8464-1-dthaler1968@gmail.com
2024-01-23bpf, docs: Clarify that MOVSX is only for BPF_X not BPF_KDave Thaler
Per discussion on the mailing list at https://mailarchive.ietf.org/arch/msg/bpf/uQiqhURdtxV_ZQOTgjCdm-seh74/ the MOVSX operation is only defined to support register extension. The document didn't previously state this and incorrectly implied that one could use an immediate value. Signed-off-by: Dave Thaler <dthaler1968@gmail.com> Acked-by: David Vernet <void@manifault.com> Acked-by: Yonghong Song <yonghong.song@linux.dev> Link: https://lore.kernel.org/r/20240118232954.27206-1-dthaler1968@gmail.com Signed-off-by: Alexei Starovoitov <ast@kernel.org>
2024-01-23Introduce concept of conformance groupsDave Thaler
The discussion of what the actual conformance groups should be is still in progress, so this is just part 1 which only uses "legacy" for deprecated instructions and "basic" for everything else. Subsequent patches will add more groups as discussion continues. Signed-off-by: Dave Thaler <dthaler1968@gmail.com> Acked-by: David Vernet <void@manifault.com> Link: https://lore.kernel.org/r/20240108214231.5280-1-dthaler1968@gmail.com Signed-off-by: Alexei Starovoitov <ast@kernel.org>
2023-10-19bpf, docs: Define signed modulo as using truncated divisionDave Thaler
There's different mathematical definitions (truncated, floored, rounded, etc.) and different languages have chosen different definitions [0][1]. E.g., languages/libraries that follow Knuth use a different mathematical definition than C uses. This patch specifies which definition BPF uses, as verified by Eduard [2] and others. [0] https://en.wikipedia.org/wiki/Modulo#Variants_of_the_definition [1] https://torstencurdt.com/tech/posts/modulo-of-negative-numbers/ [2] https://lore.kernel.org/bpf/57e6fefadaf3b2995bb259fa8e711c7220ce5290.camel@gmail.com/ Signed-off-by: Dave Thaler <dthaler@microsoft.com> Signed-off-by: Daniel Borkmann <daniel@iogearbox.net> Acked-by: David Vernet <void@manifault.com> Acked-by: Eduard Zingerman <eddyz87@gmail.com> Link: https://lore.kernel.org/bpf/20231017203020.1500-1-dthaler1968@googlemail.com
2023-08-30bpf, docs: s/eBPF/BPF in standards documentsDavid Vernet
There isn't really anything other than just "BPF" at this point, so referring to it as "eBPF" in our standards document just causes unnecessary confusion. Let's just be consistent and use "BPF". Suggested-by: Will Hawkins <hawkinsw@obs.cr> Signed-off-by: David Vernet <void@manifault.com> Signed-off-by: Daniel Borkmann <daniel@iogearbox.net> Link: https://lore.kernel.org/bpf/20230828155948.123405-4-void@manifault.com
2023-08-30bpf, docs: Add abi.rst document to standardization subdirectoryDavid Vernet
As specified in the IETF BPF charter, the BPF working group has plans to add one or more informational documents that recommend conventions and guidelines for producing portable BPF program binaries. The instruction-set.rst document currently contains a "Registers and calling convention" subsection which dictates a calling convention that belongs in an ABI document, rather than an instruction set document. Let's move it to a new abi.rst document so we can clean it up. The abi.rst document will of course be significantly changed and expanded upon over time. For now, it's really just a placeholder which will contain ABI-specific language that doesn't belong in other documents. Signed-off-by: David Vernet <void@manifault.com> Signed-off-by: Daniel Borkmann <daniel@iogearbox.net> Link: https://lore.kernel.org/bpf/20230828155948.123405-3-void@manifault.com
2023-08-30bpf, docs: Move linux-notes.rst to root bpf docs treeDavid Vernet
In commit 4d496be9ca05 ("bpf,docs: Create new standardization subdirectory"), I added a standardization/ directory to the BPF documentation, which will contain the docs that will be standardized as part of the effort with the IETF. I included linux-notes.rst in that directory, but I shouldn't have. It doesn't contain anything that will be standardized. Let's move it back to Documentation/bpf. Signed-off-by: David Vernet <void@manifault.com> Signed-off-by: Daniel Borkmann <daniel@iogearbox.net> Link: https://lore.kernel.org/bpf/20230828155948.123405-2-void@manifault.com
2023-08-30bpf, docs: Correct source of offset for program-local callWill Hawkins
The offset to use when calculating the target of a program-local call is in the instruction's imm field, not its offset field. Signed-off-by: Will Hawkins <hawkinsw@obs.cr> Signed-off-by: Daniel Borkmann <daniel@iogearbox.net> Acked-by: Eduard Zingerman <eddyz87@gmail.com> Acked-by: David Vernet <void@manifault.com> Link: https://lore.kernel.org/bpf/20230826053258.1860167-1-hawkinsw@obs.cr
2023-08-08bpf, docs: Fix small typo and define semantics of sign extensionWill Hawkins
Add additional precision on the semantics of the sign extension operations in BPF. In addition, fix a very minor typo. Signed-off-by: Will Hawkins <hawkinsw@obs.cr> Acked-by: David Vernet <void@manifault.com> Link: https://lore.kernel.org/r/20230808212503.197834-1-hawkinsw@obs.cr Signed-off-by: Martin KaFai Lau <martin.lau@kernel.org>
2023-08-07bpf, docs: Formalize type notation and function semantics in ISA standardWill Hawkins
Give a single place where the shorthand for types are defined and the semantics of helper functions are described. Signed-off-by: Will Hawkins <hawkinsw@obs.cr> Acked-by: David Vernet <void@manifault.com> Link: https://lore.kernel.org/r/20230807140651.122484-1-hawkinsw@obs.cr Signed-off-by: Martin KaFai Lau <martin.lau@kernel.org>
2023-07-29docs/bpf: Fix malformed documentationYonghong Song
Two issues are fixed: 1. Malformed table due to newly-introduced BPF_MOVSX 2. Missing reference link for ``Sign-extension load operations`` Fixes: 245d4c40c09b ("docs/bpf: Add documentation for new instructions") Cc: bpf@ietf.org Reported-by: kernel test robot <lkp@intel.com> Closes: https://lore.kernel.org/oe-kbuild-all/202307291840.Cqhj7uox-lkp@intel.com/ Signed-off-by: Yonghong Song <yonghong.song@linux.dev> Link: https://lore.kernel.org/r/20230730004251.381307-1-yonghong.song@linux.dev Signed-off-by: Alexei Starovoitov <ast@kernel.org>
2023-07-28docs/bpf: Improve documentation for cpu=v4 instructionsYonghong Song
Improve documentation for cpu=v4 instructions based on David's suggestions. Cc: bpf@ietf.org Suggested-by: David Vernet <void@manifault.com> Acked-by: David Vernet <void@manifault.com> Signed-off-by: Yonghong Song <yonghong.song@linux.dev> Link: https://lore.kernel.org/r/20230728225105.919595-1-yonghong.song@linux.dev Signed-off-by: Alexei Starovoitov <ast@kernel.org>
2023-07-27docs/bpf: Add documentation for new instructionsYonghong Song
Add documentation in instruction-set.rst for new instruction encoding and their corresponding operations. Also removed the question related to 'no BPF_SDIV' in bpf_design_QA.rst since we have BPF_SDIV insn now. Cc: bpf@ietf.org Signed-off-by: Yonghong Song <yonghong.song@linux.dev> Link: https://lore.kernel.org/r/20230728011342.3724411-1-yonghong.song@linux.dev Signed-off-by: Alexei Starovoitov <ast@kernel.org>
2023-07-27bpf, docs: fix BPF_NEG entry in instruction-set.rstJose E. Marchesi
This patch fixes the documentation of the BPF_NEG instruction to denote that it does not use the source register operand. Signed-off-by: Jose E. Marchesi <jose.marchesi@oracle.com> Acked-by: Dave Thaler <dthaler@microsoft.com> Acked-by: Yonghong Song <yonghong.song@linux.dev> Link: https://lore.kernel.org/r/20230726092543.6362-1-jose.marchesi@oracle.com Signed-off-by: Alexei Starovoitov <ast@kernel.org>
2023-07-10bpf,docs: Create new standardization subdirectoryDavid Vernet
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 <void@manifault.com> Link: https://lore.kernel.org/r/20230710183027.15132-1-void@manifault.com Signed-off-by: Alexei Starovoitov <ast@kernel.org>