bpf, docs: Address comments from IETF Area Directors

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 <void@manifault.com>
Signed-off-by: Dave Thaler <dthaler1968@googlemail.com>
Link: https://lore.kernel.org/r/20240623150453.10613-1-dthaler1968@gmail.com
Signed-off-by: Alexei Starovoitov <ast@kernel.org>

authored by

Dave Thaler and committed by

Alexei Starovoitov 2 years ago 04efaebd 93265a0b

+45 -35

1 changed file

expand all

Documentation

bpf

standardization

instruction-set.rst

+45 -35

Documentation/bpf/standardization/instruction-set.rst

··· 5 5 BPF Instruction Set Architecture (ISA) 6 6 ====================================== 7 7 8 - eBPF (which is no longer an acronym for anything), also commonly 8 + eBPF, also commonly 9 9 referred to as BPF, is a technology with origins in the Linux kernel 10 10 that can run untrusted programs in a privileged context such as an 11 11 operating system kernel. This document specifies the BPF instruction 12 12 set architecture (ISA). 13 + 14 + As a historical note, BPF originally stood for Berkeley Packet Filter, 15 + but now that it can do so much more than packet filtering, the acronym 16 + no longer makes sense. BPF is now considered a standalone term that 17 + does not stand for anything. The original BPF is sometimes referred to 18 + as cBPF (classic BPF) to distinguish it from the now widely deployed 19 + eBPF (extended BPF). 13 20 14 21 Documentation conventions 15 22 ========================= ··· 25 18 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 26 19 "OPTIONAL" in this document are to be interpreted as described in 27 20 BCP 14 `<https://www.rfc-editor.org/info/rfc2119>`_ 28 - `RFC8174 <https://www.rfc-editor.org/info/rfc8174>`_ 21 + `<https://www.rfc-editor.org/info/rfc8174>`_ 29 22 when, and only when, they appear in all capitals, as shown here. 30 23 31 24 For brevity and consistency, this document refers to families ··· 66 59 67 60 Functions 68 61 --------- 69 - * htobe16: Takes an unsigned 16-bit number in host-endian format and 70 - returns the equivalent number as an unsigned 16-bit number in big-endian 71 - format. 72 - * htobe32: Takes an unsigned 32-bit number in host-endian format and 73 - returns the equivalent number as an unsigned 32-bit number in big-endian 74 - format. 75 - * htobe64: Takes an unsigned 64-bit number in host-endian format and 76 - returns the equivalent number as an unsigned 64-bit number in big-endian 77 - format. 78 - * htole16: Takes an unsigned 16-bit number in host-endian format and 79 - returns the equivalent number as an unsigned 16-bit number in little-endian 80 - format. 81 - * htole32: Takes an unsigned 32-bit number in host-endian format and 82 - returns the equivalent number as an unsigned 32-bit number in little-endian 83 - format. 84 - * htole64: Takes an unsigned 64-bit number in host-endian format and 85 - returns the equivalent number as an unsigned 64-bit number in little-endian 86 - format. 62 + 63 + The following byteswap functions are direction-agnostic. That is, 64 + the same function is used for conversion in either direction discussed 65 + below. 66 + 67 + * be16: Takes an unsigned 16-bit number and converts it between 68 + host byte order and big-endian 69 + (`IEN137 <https://www.rfc-editor.org/ien/ien137.txt>`_) byte order. 70 + * be32: Takes an unsigned 32-bit number and converts it between 71 + host byte order and big-endian byte order. 72 + * be64: Takes an unsigned 64-bit number and converts it between 73 + host byte order and big-endian byte order. 87 74 * bswap16: Takes an unsigned 16-bit number in either big- or little-endian 88 75 format and returns the equivalent number with the same bit width but 89 76 opposite endianness. ··· 87 86 * bswap64: Takes an unsigned 64-bit number in either big- or little-endian 88 87 format and returns the equivalent number with the same bit width but 89 88 opposite endianness. 90 - 89 + * le16: Takes an unsigned 16-bit number and converts it between 90 + host byte order and little-endian byte order. 91 + * le32: Takes an unsigned 32-bit number and converts it between 92 + host byte order and little-endian byte order. 93 + * le64: Takes an unsigned 64-bit number and converts it between 94 + host byte order and little-endian byte order. 91 95 92 96 Definitions 93 97 ----------- ··· 443 437 ===== ======== ===== ================================================= 444 438 class source value description 445 439 ===== ======== ===== ================================================= 446 - ALU TO_LE 0 convert between host byte order and little endian 447 - ALU TO_BE 1 convert between host byte order and big endian 440 + ALU LE 0 convert between host byte order and little endian 441 + ALU BE 1 convert between host byte order and big endian 448 442 ALU64 Reserved 0 do byte swap unconditionally 449 443 ===== ======== ===== ================================================= 450 444 ··· 455 449 456 450 Examples: 457 451 458 - ``{END, TO_LE, ALU}`` with 'imm' = 16/32/64 means:: 452 + ``{END, LE, ALU}`` with 'imm' = 16/32/64 means:: 459 453 460 - dst = htole16(dst) 461 - dst = htole32(dst) 462 - dst = htole64(dst) 454 + dst = le16(dst) 455 + dst = le32(dst) 456 + dst = le64(dst) 463 457 464 - ``{END, TO_BE, ALU}`` with 'imm' = 16/32/64 means:: 458 + ``{END, BE, ALU}`` with 'imm' = 16/32/64 means:: 465 459 466 - dst = htobe16(dst) 467 - dst = htobe32(dst) 468 - dst = htobe64(dst) 460 + dst = be16(dst) 461 + dst = be32(dst) 462 + dst = be64(dst) 469 463 470 - ``{END, TO_LE, ALU64}`` with 'imm' = 16/32/64 means:: 464 + ``{END, TO, ALU64}`` with 'imm' = 16/32/64 means:: 471 465 472 466 dst = bswap16(dst) 473 467 dst = bswap32(dst) ··· 547 541 set of function calls exposed by the underlying platform. 548 542 549 543 Historically, each helper function was identified by a static ID 550 - encoded in the 'imm' field. The available helper functions may differ 551 - for each program type, but static IDs are unique across all program types. 544 + encoded in the 'imm' field. Further documentation of helper functions 545 + is outside the scope of this document and standardization is left for 546 + future work, but use is widely deployed and more information can be 547 + found in platform-specific documentation (e.g., Linux kernel documentation). 552 548 553 549 Platforms that support the BPF Type Format (BTF) support identifying 554 550 a helper function by a BTF ID encoded in the 'imm' field, where the BTF ID 555 551 identifies the helper name and type. Further documentation of BTF 556 - is outside the scope of this document and is left for future work. 552 + is outside the scope of this document and standardization is left for 553 + future work, but use is widely deployed and more information can be 554 + found in platform-specific documentation (e.g., Linux kernel documentation). 557 555 558 556 Program-local functions 559 557 ~~~~~~~~~~~~~~~~~~~~~~~

Configure Feed

Configure Feed