[PATCH bpf-next] bpf, docs: Address comments from IETF Area Directors

[PATCH bpf-next] bpf, docs: Address comments from IETF Area Directors

[Dave Thaler]

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/

Signed-off-by: Dave Thaler <dthaler1968@googlemail.com>
---
 .../bpf/standardization/instruction-set.rst   | 80 +++++++++++--------
 1 file changed, 45 insertions(+), 35 deletions(-)

diff --git a/Documentation/bpf/standardization/instruction-set.rst b/Documentation/bpf/standardization/instruction-set.rst
index 398f27bab..84f581dd2 100644
--- a/Documentation/bpf/standardization/instruction-set.rst
+++ b/Documentation/bpf/standardization/instruction-set.rst
@@ -5,12 +5,19 @@
 BPF Instruction Set Architecture (ISA)
 ======================================
 
-eBPF (which is no longer an acronym for anything), also commonly
+eBPF, also commonly
 referred to as BPF, is a technology with origins in the Linux kernel
 that can run untrusted programs in a privileged context such as an
 operating system kernel. This document specifies the BPF instruction
 set architecture (ISA).
 
+As a historical note, BPF originally stood for Berkeley Packet Filter,
+but now that it can do so much more than packet filtering, the acronym
+no longer makes sense. BPF is now considered a standalone term that
+doesn't stand for anything.  The original BPF is sometimes referred to
+as cBPF (classic BPF) to distinguish it from the now widely deployed
+eBPF (extended BPF).
+
 Documentation conventions
 =========================
 
@@ -18,7 +25,7 @@ The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
 "OPTIONAL" in this document are to be interpreted as described in
 BCP 14 `<https://www.rfc-editor.org/info/rfc2119>`_
-`RFC8174 <https://www.rfc-editor.org/info/rfc8174>`_
+`<https://www.rfc-editor.org/info/rfc8174>`_
 when, and only when, they appear in all capitals, as shown here.
 
 For brevity and consistency, this document refers to families
@@ -59,24 +66,18 @@ numbers.
 
 Functions
 ---------
-* htobe16: Takes an unsigned 16-bit number in host-endian format and
-  returns the equivalent number as an unsigned 16-bit number in big-endian
-  format.
-* htobe32: Takes an unsigned 32-bit number in host-endian format and
-  returns the equivalent number as an unsigned 32-bit number in big-endian
-  format.
-* htobe64: Takes an unsigned 64-bit number in host-endian format and
-  returns the equivalent number as an unsigned 64-bit number in big-endian
-  format.
-* htole16: Takes an unsigned 16-bit number in host-endian format and
-  returns the equivalent number as an unsigned 16-bit number in little-endian
-  format.
-* htole32: Takes an unsigned 32-bit number in host-endian format and
-  returns the equivalent number as an unsigned 32-bit number in little-endian
-  format.
-* htole64: Takes an unsigned 64-bit number in host-endian format and
-  returns the equivalent number as an unsigned 64-bit number in little-endian
-  format.
+
+The following byteswap functions are direction-agnostic.  That is,
+the same function is used for conversion in either direction discussed
+below.
+
+* be16: Takes an unsigned 16-bit number and converts it between
+  host byte order and big-endian
+  (`IEN137 <https://www.rfc-editor.org/ien/ien137.txt>`_) byte order.
+* be32: Takes an unsigned 32-bit number and converts it between
+  host byte order and big-endian byte order.
+* be64: Takes an unsigned 64-bit number and converts it between
+  host byte order and big-endian byte order.
 * bswap16: Takes an unsigned 16-bit number in either big- or little-endian
   format and returns the equivalent number with the same bit width but
   opposite endianness.
@@ -86,7 +87,12 @@ Functions
 * bswap64: Takes an unsigned 64-bit number in either big- or little-endian
   format and returns the equivalent number with the same bit width but
   opposite endianness.
-
+* le16: Takes an unsigned 16-bit number and converts it between
+  host byte order and little-endian byte order.
+* le32: Takes an unsigned 32-bit number and converts it between
+  host byte order and little-endian byte order.
+* le64: Takes an unsigned 64-bit number and converts it between
+  host byte order and little-endian byte order.
 
 Definitions
 -----------
@@ -441,8 +447,8 @@ and MUST be set to 0.
   =====  ========  =====  =================================================
   class  source    value  description
   =====  ========  =====  =================================================
-  ALU    TO_LE     0      convert between host byte order and little endian
-  ALU    TO_BE     1      convert between host byte order and big endian
+  ALU    LE        0      convert between host byte order and little endian
+  ALU    BE        1      convert between host byte order and big endian
   ALU64  Reserved  0      do byte swap unconditionally
   =====  ========  =====  =================================================
 
@@ -453,19 +459,19 @@ conformance group.
 
 Examples:
 
-``{END, TO_LE, ALU}`` with 'imm' = 16/32/64 means::
+``{END, LE, ALU}`` with 'imm' = 16/32/64 means::
 
-  dst = htole16(dst)
-  dst = htole32(dst)
-  dst = htole64(dst)
+  dst = le16(dst)
+  dst = le32(dst)
+  dst = le64(dst)
 
-``{END, TO_BE, ALU}`` with 'imm' = 16/32/64 means::
+``{END, BE, ALU}`` with 'imm' = 16/32/64 means::
 
-  dst = htobe16(dst)
-  dst = htobe32(dst)
-  dst = htobe64(dst)
+  dst = be16(dst)
+  dst = be32(dst)
+  dst = be64(dst)
 
-``{END, TO_LE, ALU64}`` with 'imm' = 16/32/64 means::
+``{END, TO, ALU64}`` with 'imm' = 16/32/64 means::
 
   dst = bswap16(dst)
   dst = bswap32(dst)
@@ -545,13 +551,17 @@ Helper functions are a concept whereby BPF programs can call into a
 set of function calls exposed by the underlying platform.
 
 Historically, each helper function was identified by a static ID
-encoded in the 'imm' field.  The available helper functions may differ
-for each program type, but static IDs are unique across all program types.
+encoded in the 'imm' field.  Further documentation of helper functions
+is outside the scope of this document and standardization is left for
+future work, but use is widely deployed and more information can be
+found in platform-specific documentation (e.g., Linux kernel documentations).
 
 Platforms that support the BPF Type Format (BTF) support identifying
 a helper function by a BTF ID encoded in the 'imm' field, where the BTF ID
 identifies the helper name and type.  Further documentation of BTF
-is outside the scope of this document and is left for future work.
+is outside the scope of this document and standardization is left for
+future work, but use is widely deployed and more information can be
+found in platform-specific documentation (e.g., Linux kernel documentations).
 
 Program-local functions
 ~~~~~~~~~~~~~~~~~~~~~~~
-- 
2.40.1

[Bpf] [PATCH bpf-next] bpf, docs: Address comments from IETF Area Directors

[Dave Thaler]

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/

Signed-off-by: Dave Thaler <dthaler1968@googlemail.com>
---
 .../bpf/standardization/instruction-set.rst   | 80 +++++++++++--------
 1 file changed, 45 insertions(+), 35 deletions(-)

diff --git a/Documentation/bpf/standardization/instruction-set.rst b/Documentation/bpf/standardization/instruction-set.rst
index 398f27bab..84f581dd2 100644
--- a/Documentation/bpf/standardization/instruction-set.rst
+++ b/Documentation/bpf/standardization/instruction-set.rst
@@ -5,12 +5,19 @@
 BPF Instruction Set Architecture (ISA)
 ======================================
 
-eBPF (which is no longer an acronym for anything), also commonly
+eBPF, also commonly
 referred to as BPF, is a technology with origins in the Linux kernel
 that can run untrusted programs in a privileged context such as an
 operating system kernel. This document specifies the BPF instruction
 set architecture (ISA).
 
+As a historical note, BPF originally stood for Berkeley Packet Filter,
+but now that it can do so much more than packet filtering, the acronym
+no longer makes sense. BPF is now considered a standalone term that
+doesn't stand for anything.  The original BPF is sometimes referred to
+as cBPF (classic BPF) to distinguish it from the now widely deployed
+eBPF (extended BPF).
+
 Documentation conventions
 =========================
 
@@ -18,7 +25,7 @@ The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
 "OPTIONAL" in this document are to be interpreted as described in
 BCP 14 `<https://www.rfc-editor.org/info/rfc2119>`_
-`RFC8174 <https://www.rfc-editor.org/info/rfc8174>`_
+`<https://www.rfc-editor.org/info/rfc8174>`_
 when, and only when, they appear in all capitals, as shown here.
 
 For brevity and consistency, this document refers to families
@@ -59,24 +66,18 @@ numbers.
 
 Functions
 ---------
-* htobe16: Takes an unsigned 16-bit number in host-endian format and
-  returns the equivalent number as an unsigned 16-bit number in big-endian
-  format.
-* htobe32: Takes an unsigned 32-bit number in host-endian format and
-  returns the equivalent number as an unsigned 32-bit number in big-endian
-  format.
-* htobe64: Takes an unsigned 64-bit number in host-endian format and
-  returns the equivalent number as an unsigned 64-bit number in big-endian
-  format.
-* htole16: Takes an unsigned 16-bit number in host-endian format and
-  returns the equivalent number as an unsigned 16-bit number in little-endian
-  format.
-* htole32: Takes an unsigned 32-bit number in host-endian format and
-  returns the equivalent number as an unsigned 32-bit number in little-endian
-  format.
-* htole64: Takes an unsigned 64-bit number in host-endian format and
-  returns the equivalent number as an unsigned 64-bit number in little-endian
-  format.
+
+The following byteswap functions are direction-agnostic.  That is,
+the same function is used for conversion in either direction discussed
+below.
+
+* be16: Takes an unsigned 16-bit number and converts it between
+  host byte order and big-endian
+  (`IEN137 <https://www.rfc-editor.org/ien/ien137.txt>`_) byte order.
+* be32: Takes an unsigned 32-bit number and converts it between
+  host byte order and big-endian byte order.
+* be64: Takes an unsigned 64-bit number and converts it between
+  host byte order and big-endian byte order.
 * bswap16: Takes an unsigned 16-bit number in either big- or little-endian
   format and returns the equivalent number with the same bit width but
   opposite endianness.
@@ -86,7 +87,12 @@ Functions
 * bswap64: Takes an unsigned 64-bit number in either big- or little-endian
   format and returns the equivalent number with the same bit width but
   opposite endianness.
-
+* le16: Takes an unsigned 16-bit number and converts it between
+  host byte order and little-endian byte order.
+* le32: Takes an unsigned 32-bit number and converts it between
+  host byte order and little-endian byte order.
+* le64: Takes an unsigned 64-bit number and converts it between
+  host byte order and little-endian byte order.
 
 Definitions
 -----------
@@ -441,8 +447,8 @@ and MUST be set to 0.
   =====  ========  =====  =================================================
   class  source    value  description
   =====  ========  =====  =================================================
-  ALU    TO_LE     0      convert between host byte order and little endian
-  ALU    TO_BE     1      convert between host byte order and big endian
+  ALU    LE        0      convert between host byte order and little endian
+  ALU    BE        1      convert between host byte order and big endian
   ALU64  Reserved  0      do byte swap unconditionally
   =====  ========  =====  =================================================
 
@@ -453,19 +459,19 @@ conformance group.
 
 Examples:
 
-``{END, TO_LE, ALU}`` with 'imm' = 16/32/64 means::
+``{END, LE, ALU}`` with 'imm' = 16/32/64 means::
 
-  dst = htole16(dst)
-  dst = htole32(dst)
-  dst = htole64(dst)
+  dst = le16(dst)
+  dst = le32(dst)
+  dst = le64(dst)
 
-``{END, TO_BE, ALU}`` with 'imm' = 16/32/64 means::
+``{END, BE, ALU}`` with 'imm' = 16/32/64 means::
 
-  dst = htobe16(dst)
-  dst = htobe32(dst)
-  dst = htobe64(dst)
+  dst = be16(dst)
+  dst = be32(dst)
+  dst = be64(dst)
 
-``{END, TO_LE, ALU64}`` with 'imm' = 16/32/64 means::
+``{END, TO, ALU64}`` with 'imm' = 16/32/64 means::
 
   dst = bswap16(dst)
   dst = bswap32(dst)
@@ -545,13 +551,17 @@ Helper functions are a concept whereby BPF programs can call into a
 set of function calls exposed by the underlying platform.
 
 Historically, each helper function was identified by a static ID
-encoded in the 'imm' field.  The available helper functions may differ
-for each program type, but static IDs are unique across all program types.
+encoded in the 'imm' field.  Further documentation of helper functions
+is outside the scope of this document and standardization is left for
+future work, but use is widely deployed and more information can be
+found in platform-specific documentation (e.g., Linux kernel documentations).
 
 Platforms that support the BPF Type Format (BTF) support identifying
 a helper function by a BTF ID encoded in the 'imm' field, where the BTF ID
 identifies the helper name and type.  Further documentation of BTF
-is outside the scope of this document and is left for future work.
+is outside the scope of this document and standardization is left for
+future work, but use is widely deployed and more information can be
+found in platform-specific documentation (e.g., Linux kernel documentations).
 
 Program-local functions
 ~~~~~~~~~~~~~~~~~~~~~~~
-- 
2.40.1

-- 
Bpf mailing list -- bpf@ietf.org
To unsubscribe send an email to bpf-leave@ietf.org

Re: [Bpf] [PATCH bpf-next] bpf, docs: Address comments from IETF Area Directors

[David Vernet]

[-- Attachment #1: Type: text/plain, Size: 9301 bytes --]

On Sat, Jun 22, 2024 at 06:55:31PM -0700, Dave Thaler wrote:
> 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/
> 
> Signed-off-by: Dave Thaler <dthaler1968@googlemail.com>

Acked-by: David Vernet <void@manifault.com>

Dave, please feel free to ignore any of these suggestions; especially if they
slow down the ratification process beyond just iterating on the list here.

> ---
>  .../bpf/standardization/instruction-set.rst   | 80 +++++++++++--------
>  1 file changed, 45 insertions(+), 35 deletions(-)
> 
> diff --git a/Documentation/bpf/standardization/instruction-set.rst b/Documentation/bpf/standardization/instruction-set.rst
> index 398f27bab..84f581dd2 100644
> --- a/Documentation/bpf/standardization/instruction-set.rst
> +++ b/Documentation/bpf/standardization/instruction-set.rst
> @@ -5,12 +5,19 @@
>  BPF Instruction Set Architecture (ISA)
>  ======================================
>  
> -eBPF (which is no longer an acronym for anything), also commonly
> +eBPF, also commonly
>  referred to as BPF, is a technology with origins in the Linux kernel
>  that can run untrusted programs in a privileged context such as an
>  operating system kernel. This document specifies the BPF instruction
>  set architecture (ISA).
>  
> +As a historical note, BPF originally stood for Berkeley Packet Filter,
> +but now that it can do so much more than packet filtering, the acronym
> +no longer makes sense. BPF is now considered a standalone term that
> +doesn't stand for anything.  The original BPF is sometimes referred to

Given that we don't use conjunctions anywhere else, should we expand this to
"does not"? Feel free to ignore if this is normal.

> +as cBPF (classic BPF) to distinguish it from the now widely deployed
> +eBPF (extended BPF).
> +
>  Documentation conventions
>  =========================
>  
> @@ -18,7 +25,7 @@ The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
>  "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
>  "OPTIONAL" in this document are to be interpreted as described in
>  BCP 14 `<https://www.rfc-editor.org/info/rfc2119>`_
> -`RFC8174 <https://www.rfc-editor.org/info/rfc8174>`_
> +`<https://www.rfc-editor.org/info/rfc8174>`_
>  when, and only when, they appear in all capitals, as shown here.
>  
>  For brevity and consistency, this document refers to families
> @@ -59,24 +66,18 @@ numbers.
>  
>  Functions
>  ---------
> -* htobe16: Takes an unsigned 16-bit number in host-endian format and
> -  returns the equivalent number as an unsigned 16-bit number in big-endian
> -  format.
> -* htobe32: Takes an unsigned 32-bit number in host-endian format and
> -  returns the equivalent number as an unsigned 32-bit number in big-endian
> -  format.
> -* htobe64: Takes an unsigned 64-bit number in host-endian format and
> -  returns the equivalent number as an unsigned 64-bit number in big-endian
> -  format.
> -* htole16: Takes an unsigned 16-bit number in host-endian format and
> -  returns the equivalent number as an unsigned 16-bit number in little-endian
> -  format.
> -* htole32: Takes an unsigned 32-bit number in host-endian format and
> -  returns the equivalent number as an unsigned 32-bit number in little-endian
> -  format.
> -* htole64: Takes an unsigned 64-bit number in host-endian format and
> -  returns the equivalent number as an unsigned 64-bit number in little-endian
> -  format.
> +
> +The following byteswap functions are direction-agnostic.  That is,
> +the same function is used for conversion in either direction discussed
> +below.
> +
> +* be16: Takes an unsigned 16-bit number and converts it between
> +  host byte order and big-endian
> +  (`IEN137 <https://www.rfc-editor.org/ien/ien137.txt>`_) byte order.
> +* be32: Takes an unsigned 32-bit number and converts it between
> +  host byte order and big-endian byte order.
> +* be64: Takes an unsigned 64-bit number and converts it between
> +  host byte order and big-endian byte order.
>  * bswap16: Takes an unsigned 16-bit number in either big- or little-endian
>    format and returns the equivalent number with the same bit width but
>    opposite endianness.
> @@ -86,7 +87,12 @@ Functions
>  * bswap64: Takes an unsigned 64-bit number in either big- or little-endian
>    format and returns the equivalent number with the same bit width but
>    opposite endianness.
> -
> +* le16: Takes an unsigned 16-bit number and converts it between
> +  host byte order and little-endian byte order.
> +* le32: Takes an unsigned 32-bit number and converts it between
> +  host byte order and little-endian byte order.
> +* le64: Takes an unsigned 64-bit number and converts it between
> +  host byte order and little-endian byte order.
>  
>  Definitions
>  -----------
> @@ -441,8 +447,8 @@ and MUST be set to 0.
>    =====  ========  =====  =================================================
>    class  source    value  description
>    =====  ========  =====  =================================================
> -  ALU    TO_LE     0      convert between host byte order and little endian
> -  ALU    TO_BE     1      convert between host byte order and big endian
> +  ALU    LE        0      convert between host byte order and little endian
> +  ALU    BE        1      convert between host byte order and big endian
>    ALU64  Reserved  0      do byte swap unconditionally
>    =====  ========  =====  =================================================
>  
> @@ -453,19 +459,19 @@ conformance group.
>  
>  Examples:
>  
> -``{END, TO_LE, ALU}`` with 'imm' = 16/32/64 means::
> +``{END, LE, ALU}`` with 'imm' = 16/32/64 means::
>  
> -  dst = htole16(dst)
> -  dst = htole32(dst)
> -  dst = htole64(dst)
> +  dst = le16(dst)
> +  dst = le32(dst)
> +  dst = le64(dst)
>  
> -``{END, TO_BE, ALU}`` with 'imm' = 16/32/64 means::
> +``{END, BE, ALU}`` with 'imm' = 16/32/64 means::
>  
> -  dst = htobe16(dst)
> -  dst = htobe32(dst)
> -  dst = htobe64(dst)
> +  dst = be16(dst)
> +  dst = be32(dst)
> +  dst = be64(dst)
>  
> -``{END, TO_LE, ALU64}`` with 'imm' = 16/32/64 means::
> +``{END, TO, ALU64}`` with 'imm' = 16/32/64 means::
>  
>    dst = bswap16(dst)
>    dst = bswap32(dst)
> @@ -545,13 +551,17 @@ Helper functions are a concept whereby BPF programs can call into a
>  set of function calls exposed by the underlying platform.
>  
>  Historically, each helper function was identified by a static ID
> -encoded in the 'imm' field.  The available helper functions may differ
> -for each program type, but static IDs are unique across all program types.
> +encoded in the 'imm' field.  Further documentation of helper functions
> +is outside the scope of this document and standardization is left for
> +future work, but use is widely deployed and more information can be
> +found in platform-specific documentation (e.g., Linux kernel documentations).
>  
>  Platforms that support the BPF Type Format (BTF) support identifying
>  a helper function by a BTF ID encoded in the 'imm' field, where the BTF ID
>  identifies the helper name and type.  Further documentation of BTF
> -is outside the scope of this document and is left for future work.
> +is outside the scope of this document and standardization is left for
> +future work, but use is widely deployed and more information can be
> +found in platform-specific documentation (e.g., Linux kernel documentations).

Here and above, can we please change this to say "documentation" instead of
"documentations"? "Documentations" is technically a valid word but
"documentation" is also a valid plural, uncountable form and IMO reads more
naturally.

>  
>  Program-local functions
>  ~~~~~~~~~~~~~~~~~~~~~~~
> -- 
> 2.40.1
> 
> -- 
> Bpf mailing list -- bpf@ietf.org
> To unsubscribe send an email to bpf-leave@ietf.org

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 228 bytes --]

[Bpf] Re: [PATCH bpf-next] bpf, docs: Address comments from IETF Area Directors

[David Vernet]

[-- Attachment #1.1: Type: text/plain, Size: 9301 bytes --]

On Sat, Jun 22, 2024 at 06:55:31PM -0700, Dave Thaler wrote:
> 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/
> 
> Signed-off-by: Dave Thaler <dthaler1968@googlemail.com>

Acked-by: David Vernet <void@manifault.com>

Dave, please feel free to ignore any of these suggestions; especially if they
slow down the ratification process beyond just iterating on the list here.

> ---
>  .../bpf/standardization/instruction-set.rst   | 80 +++++++++++--------
>  1 file changed, 45 insertions(+), 35 deletions(-)
> 
> diff --git a/Documentation/bpf/standardization/instruction-set.rst b/Documentation/bpf/standardization/instruction-set.rst
> index 398f27bab..84f581dd2 100644
> --- a/Documentation/bpf/standardization/instruction-set.rst
> +++ b/Documentation/bpf/standardization/instruction-set.rst
> @@ -5,12 +5,19 @@
>  BPF Instruction Set Architecture (ISA)
>  ======================================
>  
> -eBPF (which is no longer an acronym for anything), also commonly
> +eBPF, also commonly
>  referred to as BPF, is a technology with origins in the Linux kernel
>  that can run untrusted programs in a privileged context such as an
>  operating system kernel. This document specifies the BPF instruction
>  set architecture (ISA).
>  
> +As a historical note, BPF originally stood for Berkeley Packet Filter,
> +but now that it can do so much more than packet filtering, the acronym
> +no longer makes sense. BPF is now considered a standalone term that
> +doesn't stand for anything.  The original BPF is sometimes referred to

Given that we don't use conjunctions anywhere else, should we expand this to
"does not"? Feel free to ignore if this is normal.

> +as cBPF (classic BPF) to distinguish it from the now widely deployed
> +eBPF (extended BPF).
> +
>  Documentation conventions
>  =========================
>  
> @@ -18,7 +25,7 @@ The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
>  "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
>  "OPTIONAL" in this document are to be interpreted as described in
>  BCP 14 `<https://www.rfc-editor.org/info/rfc2119>`_
> -`RFC8174 <https://www.rfc-editor.org/info/rfc8174>`_
> +`<https://www.rfc-editor.org/info/rfc8174>`_
>  when, and only when, they appear in all capitals, as shown here.
>  
>  For brevity and consistency, this document refers to families
> @@ -59,24 +66,18 @@ numbers.
>  
>  Functions
>  ---------
> -* htobe16: Takes an unsigned 16-bit number in host-endian format and
> -  returns the equivalent number as an unsigned 16-bit number in big-endian
> -  format.
> -* htobe32: Takes an unsigned 32-bit number in host-endian format and
> -  returns the equivalent number as an unsigned 32-bit number in big-endian
> -  format.
> -* htobe64: Takes an unsigned 64-bit number in host-endian format and
> -  returns the equivalent number as an unsigned 64-bit number in big-endian
> -  format.
> -* htole16: Takes an unsigned 16-bit number in host-endian format and
> -  returns the equivalent number as an unsigned 16-bit number in little-endian
> -  format.
> -* htole32: Takes an unsigned 32-bit number in host-endian format and
> -  returns the equivalent number as an unsigned 32-bit number in little-endian
> -  format.
> -* htole64: Takes an unsigned 64-bit number in host-endian format and
> -  returns the equivalent number as an unsigned 64-bit number in little-endian
> -  format.
> +
> +The following byteswap functions are direction-agnostic.  That is,
> +the same function is used for conversion in either direction discussed
> +below.
> +
> +* be16: Takes an unsigned 16-bit number and converts it between
> +  host byte order and big-endian
> +  (`IEN137 <https://www.rfc-editor.org/ien/ien137.txt>`_) byte order.
> +* be32: Takes an unsigned 32-bit number and converts it between
> +  host byte order and big-endian byte order.
> +* be64: Takes an unsigned 64-bit number and converts it between
> +  host byte order and big-endian byte order.
>  * bswap16: Takes an unsigned 16-bit number in either big- or little-endian
>    format and returns the equivalent number with the same bit width but
>    opposite endianness.
> @@ -86,7 +87,12 @@ Functions
>  * bswap64: Takes an unsigned 64-bit number in either big- or little-endian
>    format and returns the equivalent number with the same bit width but
>    opposite endianness.
> -
> +* le16: Takes an unsigned 16-bit number and converts it between
> +  host byte order and little-endian byte order.
> +* le32: Takes an unsigned 32-bit number and converts it between
> +  host byte order and little-endian byte order.
> +* le64: Takes an unsigned 64-bit number and converts it between
> +  host byte order and little-endian byte order.
>  
>  Definitions
>  -----------
> @@ -441,8 +447,8 @@ and MUST be set to 0.
>    =====  ========  =====  =================================================
>    class  source    value  description
>    =====  ========  =====  =================================================
> -  ALU    TO_LE     0      convert between host byte order and little endian
> -  ALU    TO_BE     1      convert between host byte order and big endian
> +  ALU    LE        0      convert between host byte order and little endian
> +  ALU    BE        1      convert between host byte order and big endian
>    ALU64  Reserved  0      do byte swap unconditionally
>    =====  ========  =====  =================================================
>  
> @@ -453,19 +459,19 @@ conformance group.
>  
>  Examples:
>  
> -``{END, TO_LE, ALU}`` with 'imm' = 16/32/64 means::
> +``{END, LE, ALU}`` with 'imm' = 16/32/64 means::
>  
> -  dst = htole16(dst)
> -  dst = htole32(dst)
> -  dst = htole64(dst)
> +  dst = le16(dst)
> +  dst = le32(dst)
> +  dst = le64(dst)
>  
> -``{END, TO_BE, ALU}`` with 'imm' = 16/32/64 means::
> +``{END, BE, ALU}`` with 'imm' = 16/32/64 means::
>  
> -  dst = htobe16(dst)
> -  dst = htobe32(dst)
> -  dst = htobe64(dst)
> +  dst = be16(dst)
> +  dst = be32(dst)
> +  dst = be64(dst)
>  
> -``{END, TO_LE, ALU64}`` with 'imm' = 16/32/64 means::
> +``{END, TO, ALU64}`` with 'imm' = 16/32/64 means::
>  
>    dst = bswap16(dst)
>    dst = bswap32(dst)
> @@ -545,13 +551,17 @@ Helper functions are a concept whereby BPF programs can call into a
>  set of function calls exposed by the underlying platform.
>  
>  Historically, each helper function was identified by a static ID
> -encoded in the 'imm' field.  The available helper functions may differ
> -for each program type, but static IDs are unique across all program types.
> +encoded in the 'imm' field.  Further documentation of helper functions
> +is outside the scope of this document and standardization is left for
> +future work, but use is widely deployed and more information can be
> +found in platform-specific documentation (e.g., Linux kernel documentations).
>  
>  Platforms that support the BPF Type Format (BTF) support identifying
>  a helper function by a BTF ID encoded in the 'imm' field, where the BTF ID
>  identifies the helper name and type.  Further documentation of BTF
> -is outside the scope of this document and is left for future work.
> +is outside the scope of this document and standardization is left for
> +future work, but use is widely deployed and more information can be
> +found in platform-specific documentation (e.g., Linux kernel documentations).

Here and above, can we please change this to say "documentation" instead of
"documentations"? "Documentations" is technically a valid word but
"documentation" is also a valid plural, uncountable form and IMO reads more
naturally.

>  
>  Program-local functions
>  ~~~~~~~~~~~~~~~~~~~~~~~
> -- 
> 2.40.1
> 
> -- 
> Bpf mailing list -- bpf@ietf.org
> To unsubscribe send an email to bpf-leave@ietf.org

[-- Attachment #1.2: signature.asc --]
[-- Type: application/pgp-signature, Size: 228 bytes --]

[-- Attachment #2: Type: text/plain, Size: 88 bytes --]

-- 
Bpf mailing list -- bpf@ietf.org
To unsubscribe send an email to bpf-leave@ietf.org