[PATCH bpf-next 0/3] Clean up some standardization stuff

[PATCH bpf-next 0/3] Clean up some standardization stuff

[David Vernet]

The Documentation/bpf/standardization subdirectory contains documents
that will be standardized with the IETF. There are a few things we can
do to clean it up:

- Move linux-notes.rst back to Documentation/bpf. It doesn't belong in
  the standardization directory.
- Move ABI-specific verbiage from instruction-set.rst into a new abi.rst
  document. This document will be expanded significantly over time. For
  now, we just need to get anything describing ABI out of
  instruction-set.rst.
- Say BPF instead of eBPF in our documents. It's just creating
  confusion.

There is more we can and should do. For example, we should create a
maps.rst document that will be a proposed standard for cross platform
map types, and remove any relevant content from instruction-set.rst.
This can be done in a subsequent patch set.

David Vernet (3):
  bpf,docs: Move linux-notes.rst to root bpf docs tree
  bpf,docs: Add abi.rst document to standardization subdirectory
  bpf,docs: s/eBPF/BPF in standards documents

 Documentation/bpf/index.rst                   |  1 +
 .../bpf/{standardization => }/linux-notes.rst |  0
 Documentation/bpf/standardization/abi.rst     | 25 ++++++++++++
 Documentation/bpf/standardization/index.rst   |  2 +-
 .../bpf/standardization/instruction-set.rst   | 38 ++++++-------------
 5 files changed, 38 insertions(+), 28 deletions(-)
 rename Documentation/bpf/{standardization => }/linux-notes.rst (100%)
 create mode 100644 Documentation/bpf/standardization/abi.rst

-- 
2.41.0

[PATCH bpf-next 1/3] bpf,docs: Move linux-notes.rst to root bpf docs tree

[David 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>
---
 Documentation/bpf/index.rst                             | 1 +
 Documentation/bpf/{standardization => }/linux-notes.rst | 0
 Documentation/bpf/standardization/index.rst             | 1 -
 3 files changed, 1 insertion(+), 1 deletion(-)
 rename Documentation/bpf/{standardization => }/linux-notes.rst (100%)

diff --git a/Documentation/bpf/index.rst b/Documentation/bpf/index.rst
index 1ff177b89d66..aeaeb35e6d4a 100644
--- a/Documentation/bpf/index.rst
+++ b/Documentation/bpf/index.rst
@@ -29,6 +29,7 @@ that goes into great technical depth about the BPF Architecture.
    bpf_licensing
    test_debug
    clang-notes
+   linux-notes
    other
    redirect
 
diff --git a/Documentation/bpf/standardization/linux-notes.rst b/Documentation/bpf/linux-notes.rst
similarity index 100%
rename from Documentation/bpf/standardization/linux-notes.rst
rename to Documentation/bpf/linux-notes.rst
diff --git a/Documentation/bpf/standardization/index.rst b/Documentation/bpf/standardization/index.rst
index 09c6ba055fd7..d7b946f71261 100644
--- a/Documentation/bpf/standardization/index.rst
+++ b/Documentation/bpf/standardization/index.rst
@@ -12,7 +12,6 @@ for the working group charter, documents, and more.
    :maxdepth: 1
 
    instruction-set
-   linux-notes
 
 .. Links:
 .. _IETF BPF Working Group: https://datatracker.ietf.org/wg/bpf/about/
-- 
2.41.0

[PATCH bpf-next 2/3] bpf,docs: Add abi.rst document to standardization subdirectory

[David 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>
---
 Documentation/bpf/standardization/abi.rst     | 25 +++++++++++++++++++
 Documentation/bpf/standardization/index.rst   |  1 +
 .../bpf/standardization/instruction-set.rst   | 16 ------------
 3 files changed, 26 insertions(+), 16 deletions(-)
 create mode 100644 Documentation/bpf/standardization/abi.rst

diff --git a/Documentation/bpf/standardization/abi.rst b/Documentation/bpf/standardization/abi.rst
new file mode 100644
index 000000000000..0c2e10eeb89a
--- /dev/null
+++ b/Documentation/bpf/standardization/abi.rst
@@ -0,0 +1,25 @@
+.. contents::
+.. sectnum::
+
+===================================================
+BPF ABI Recommended Conventions and Guidelines v1.0
+===================================================
+
+This is version 1.0 of an informational document containing recommended
+conventions and guidelines for producing portable BPF program binaries.
+
+Registers and calling convention
+================================
+
+BPF has 10 general purpose registers and a read-only frame pointer register,
+all of which are 64-bits wide.
+
+The BPF calling convention is defined as:
+
+* R0: return value from function calls, and exit value for BPF programs
+* R1 - R5: arguments for function calls
+* R6 - R9: callee saved registers that function calls will preserve
+* R10: read-only frame pointer to access stack
+
+R0 - R5 are scratch registers and BPF programs needs to spill/fill them if
+necessary across calls.
diff --git a/Documentation/bpf/standardization/index.rst b/Documentation/bpf/standardization/index.rst
index d7b946f71261..a50c3baf6345 100644
--- a/Documentation/bpf/standardization/index.rst
+++ b/Documentation/bpf/standardization/index.rst
@@ -12,6 +12,7 @@ for the working group charter, documents, and more.
    :maxdepth: 1
 
    instruction-set
+   abi
 
 .. Links:
 .. _IETF BPF Working Group: https://datatracker.ietf.org/wg/bpf/about/
diff --git a/Documentation/bpf/standardization/instruction-set.rst b/Documentation/bpf/standardization/instruction-set.rst
index 4f73e9dc8d9e..cfe85129a303 100644
--- a/Documentation/bpf/standardization/instruction-set.rst
+++ b/Documentation/bpf/standardization/instruction-set.rst
@@ -97,22 +97,6 @@ Definitions
     A:          10000110
     B: 11111111 10000110
 
-Registers and calling convention
-================================
-
-eBPF has 10 general purpose registers and a read-only frame pointer register,
-all of which are 64-bits wide.
-
-The eBPF calling convention is defined as:
-
-* R0: return value from function calls, and exit value for eBPF programs
-* R1 - R5: arguments for function calls
-* R6 - R9: callee saved registers that function calls will preserve
-* R10: read-only frame pointer to access stack
-
-R0 - R5 are scratch registers and eBPF programs needs to spill/fill them if
-necessary across calls.
-
 Instruction encoding
 ====================
 
-- 
2.41.0

[PATCH bpf-next 3/3] bpf,docs: s/eBPF/BPF in standards documents

[David 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>
---
 .../bpf/standardization/instruction-set.rst   | 22 +++++++++----------
 1 file changed, 11 insertions(+), 11 deletions(-)

diff --git a/Documentation/bpf/standardization/instruction-set.rst b/Documentation/bpf/standardization/instruction-set.rst
index cfe85129a303..8afe6567209e 100644
--- a/Documentation/bpf/standardization/instruction-set.rst
+++ b/Documentation/bpf/standardization/instruction-set.rst
@@ -1,11 +1,11 @@
 .. contents::
 .. sectnum::
 
-========================================
-eBPF Instruction Set Specification, v1.0
-========================================
+=======================================
+BPF Instruction Set Specification, v1.0
+=======================================
 
-This document specifies version 1.0 of the eBPF instruction set.
+This document specifies version 1.0 of the BPF instruction set.
 
 Documentation conventions
 =========================
@@ -100,7 +100,7 @@ Definitions
 Instruction encoding
 ====================
 
-eBPF has two instruction encodings:
+BPF has two instruction encodings:
 
 * the basic instruction encoding, which uses 64 bits to encode an instruction
 * the wide instruction encoding, which appends a second 64-bit immediate (i.e.,
@@ -244,7 +244,7 @@ BPF_END    0xd0   0        byte swap operations (see `Byte swap instructions`_ b
 =========  =====  =======  ==========================================================
 
 Underflow and overflow are allowed during arithmetic operations, meaning
-the 64-bit or 32-bit value will wrap. If eBPF program execution would
+the 64-bit or 32-bit value will wrap. If BPF program execution would
 result in division by zero, the destination register is instead set to zero.
 If execution would result in modulo by zero, for ``BPF_ALU64`` the value of
 the destination register is unchanged whereas for ``BPF_ALU`` the upper
@@ -366,7 +366,7 @@ BPF_JSLT  0xc    any  PC += offset if dst < src                    signed
 BPF_JSLE  0xd    any  PC += offset if dst <= src                   signed
 ========  =====  ===  ===========================================  =========================================
 
-The eBPF program needs to store the return value into register R0 before doing a
+The BPF program needs to store the return value into register R0 before doing a
 ``BPF_EXIT``.
 
 Example:
@@ -486,9 +486,9 @@ Atomic operations
 
 Atomic operations are operations that operate on memory and can not be
 interrupted or corrupted by other access to the same memory region
-by other eBPF programs or means outside of this specification.
+by other BPF programs or means outside of this specification.
 
-All atomic operations supported by eBPF are encoded as store operations
+All atomic operations supported by BPF are encoded as store operations
 that use the ``BPF_ATOMIC`` mode modifier as follows:
 
 * ``BPF_ATOMIC | BPF_W | BPF_STX`` for 32-bit operations
@@ -578,7 +578,7 @@ where
 Maps
 ~~~~
 
-Maps are shared memory regions accessible by eBPF programs on some platforms.
+Maps are shared memory regions accessible by BPF programs on some platforms.
 A map can have various semantics as defined in a separate document, and may or
 may not have a single contiguous memory region, but the 'map_val(map)' is
 currently only defined for maps that do have a single contiguous memory region.
@@ -600,6 +600,6 @@ identified by the given id.
 Legacy BPF Packet access instructions
 -------------------------------------
 
-eBPF previously introduced special instructions for access to packet data that were
+BPF previously introduced special instructions for access to packet data that were
 carried over from classic BPF. However, these instructions are
 deprecated and should no longer be used.
-- 
2.41.0

Re: [PATCH bpf-next 0/3] Clean up some standardization stuff

[patchwork-bot+netdevbpf]

Hello:

This series was applied to bpf/bpf.git (master)
by Daniel Borkmann <daniel@iogearbox.net>:

On Mon, 28 Aug 2023 10:59:45 -0500 you wrote:
> The Documentation/bpf/standardization subdirectory contains documents
> that will be standardized with the IETF. There are a few things we can
> do to clean it up:
> 
> - Move linux-notes.rst back to Documentation/bpf. It doesn't belong in
>   the standardization directory.
> - Move ABI-specific verbiage from instruction-set.rst into a new abi.rst
>   document. This document will be expanded significantly over time. For
>   now, we just need to get anything describing ABI out of
>   instruction-set.rst.
> - Say BPF instead of eBPF in our documents. It's just creating
>   confusion.
> 
> [...]

Here is the summary with links:
  - [bpf-next,1/3] bpf,docs: Move linux-notes.rst to root bpf docs tree
    https://git.kernel.org/bpf/bpf/c/aee1720eeb87
  - [bpf-next,2/3] bpf,docs: Add abi.rst document to standardization subdirectory
    https://git.kernel.org/bpf/bpf/c/deb884072546
  - [bpf-next,3/3] bpf,docs: s/eBPF/BPF in standards documents
    https://git.kernel.org/bpf/bpf/c/7d35eb1a184a

You are awesome, thank you!
-- 
Deet-doot-dot, I am a bot.
https://korg.docs.kernel.org/patchwork/pwbot.html