[PATCH bpf-next v2] bpf, docs: Add extended call instructions

* [PATCH bpf-next v2] bpf, docs: Add extended call instructions
@ 2023-03-11 22:09 Dave Thaler
  2023-03-14  5:07 ` John Fastabend
  0 siblings, 1 reply; 2+ messages in thread
From: Dave Thaler @ 2023-03-11 22:09 UTC (permalink / raw)
  To: bpf; +Cc: bpf, Dave Thaler

From: Dave Thaler <dthaler@microsoft.com>

Add extended call instructions.  Since BPF can be used in userland
or SmartNICs, this uses the more generic "Platform-specific helper functions"
term as suggested by David Vernet, rather than the kernel specific "kfuncs".

---
V1 -> V2: addressed comments from David Vernet

Signed-off-by: Dave Thaler <dthaler@microsoft.com>
---
 Documentation/bpf/instruction-set.rst | 63 +++++++++++++++++----------
 Documentation/bpf/linux-notes.rst     |  4 ++
 2 files changed, 44 insertions(+), 23 deletions(-)

diff --git a/Documentation/bpf/instruction-set.rst b/Documentation/bpf/instruction-set.rst
index 5e43e14abe8..dc348544542 100644
--- a/Documentation/bpf/instruction-set.rst
+++ b/Documentation/bpf/instruction-set.rst
@@ -242,35 +242,52 @@ Jump instructions
 otherwise identical operations.
 The 'code' field encodes the operation as below:
 
-========  =====  =========================  ============
-code      value  description                notes
-========  =====  =========================  ============
-BPF_JA    0x00   PC += off                  BPF_JMP only
-BPF_JEQ   0x10   PC += off if dst == src
-BPF_JGT   0x20   PC += off if dst > src     unsigned
-BPF_JGE   0x30   PC += off if dst >= src    unsigned
-BPF_JSET  0x40   PC += off if dst & src
-BPF_JNE   0x50   PC += off if dst != src
-BPF_JSGT  0x60   PC += off if dst > src     signed
-BPF_JSGE  0x70   PC += off if dst >= src    signed
-BPF_CALL  0x80   function call              see `Helper functions`_
-BPF_EXIT  0x90   function / program return  BPF_JMP only
-BPF_JLT   0xa0   PC += off if dst < src     unsigned
-BPF_JLE   0xb0   PC += off if dst <= src    unsigned
-BPF_JSLT  0xc0   PC += off if dst < src     signed
-BPF_JSLE  0xd0   PC += off if dst <= src    signed
-========  =====  =========================  ============
+========  =====  ===  ==========================  =========================================
+code      value  src  description                 notes
+========  =====  ===  ==========================  =========================================
+BPF_JA    0x0    0x0  PC += offset                BPF_JMP only
+BPF_JEQ   0x1    any  PC += offset if dst == src
+BPF_JGT   0x2    any  PC += offset if dst > src   unsigned
+BPF_JGE   0x3    any  PC += offset if dst >= src  unsigned
+BPF_JSET  0x4    any  PC += offset if dst & src
+BPF_JNE   0x5    any  PC += offset if dst != src
+BPF_JSGT  0x6    any  PC += offset if dst > src   signed
+BPF_JSGE  0x7    any  PC += offset if dst >= src  signed
+BPF_CALL  0x8    0x0  call helper function imm    see `Platform-agnostic helper functions`_
+BPF_CALL  0x8    0x1  call PC += offset           see `BPF-local functions`_
+BPF_CALL  0x8    0x2  call runtime function imm   see `Platform-specific helper functions`_
+BPF_EXIT  0x9    0x0  return                      BPF_JMP only
+BPF_JLT   0xa    any  PC += offset if dst < src   unsigned
+BPF_JLE   0xb    any  PC += offset if dst <= src  unsigned
+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
 BPF_EXIT.
 
-Helper functions
-~~~~~~~~~~~~~~~~
+Platform-agnostic helper functions
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Helper functions are a concept whereby BPF programs can call into a
-set of function calls exposed by the runtime.  Each helper
+Platform-agnostic helper functions are a concept whereby BPF programs can call
+into a set of function calls exposed by the runtime.  Each helper
 function is identified by an integer used in a ``BPF_CALL`` instruction.
-The available helper functions may differ for each program type.
+The available platform-agnostic helper functions may differ for each program
+type, but integer values are unique across all program types.
+
+Platform-specific helper functions
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Platform-specific helper functions are helper functions that are unique to
+a particular platform.  They use a separate integer numbering space from
+platform-agnostic helper functions, but otherwise the same considerations
+apply.  Platforms are not required to implement any platform-specific
+functions.
+
+BPF-local functions
+~~~~~~~~~~~~~~
+BPF-local functions are functions exposed by the same BPF program as the caller,
+and are referenced by offset from the call instruction, similar to ``BPF_JA``.
+A ``BPF_EXIT`` within the BPF-local function will return to the caller.
 
 Load and store instructions
 ===========================
diff --git a/Documentation/bpf/linux-notes.rst b/Documentation/bpf/linux-notes.rst
index f43b9c797bc..bdc41293e8a 100644
--- a/Documentation/bpf/linux-notes.rst
+++ b/Documentation/bpf/linux-notes.rst
@@ -20,6 +20,10 @@ integer would be read from a specified register, is not currently supported
 by the verifier.  Any programs with this instruction will fail to load
 until such support is added.
 
+For historical reasons, Linux has a number of Linux-specific helper functions
+that are encoded as platform-agnostic helper functions rather than
+ platform-specific helper functions ("kfuncs").
+
 Legacy BPF Packet access instructions
 =====================================
 
-- 
2.33.4


^ permalink raw reply related	[flat|nested] 2+ messages in thread