Skip to contentSkip to conversation

bpf, docs: Add extended call instructions

PATCH Superseded Dave Thaler 2 participants 2 messages Mar 12, 2023 – Mar 13, 2023

Subsystems (2)

v3 of 5 Superseded Latest is v5 →

lore
Share & tools
lore
#0 lore raw

PATCH v3 1/1 bpf, docs: Add extended call instructions

From: Dave Thaler <[email protected]>

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

V2 -> V3: make descriptions in table consistent with updated names

---
 Documentation/bpf/instruction-set.rst | 63 +++++++++++++++++----------
 Documentation/bpf/linux-notes.rst     |  4 ++
 2 files changed, 44 insertions(+), 23 deletions(-)
Documentation/bpf/instruction-set.rst +40 -23
index 5e43e14abe8..f890bcd0dba 100644
@@ -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 platform-agnostic helper function imm   see `Platform-agnostic helper functions`_
+BPF_CALL  0x8    0x1  call PC += offset                            see `BPF-local functions`_
+BPF_CALL  0x8    0x2  call platform-specific helper 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
 ===========================
Documentation/bpf/linux-notes.rst +4 -0
index f43b9c797bc..bdc41293e8a 100644
@@ -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
 =====================================
 
Signature · 1 line
2.33.4
#1 lore raw
Quoted 78 lines · Dave Thaler

From: Dave Thaler <[email protected]>

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

V2 -> V3: make descriptions in table consistent with updated names

---
 Documentation/bpf/instruction-set.rst | 63 +++++++++++++++++----------
 Documentation/bpf/linux-notes.rst     |  4 ++
 2 files changed, 44 insertions(+), 23 deletions(-)
Documentation/bpf/instruction-set.rst +24 -23
index 5e43e14abe8..f890bcd0dba 100644
@@ -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 platform-agnostic helper function imm   see `Platform-agnostic helper functions`_
+BPF_CALL  0x8    0x1  call PC += offset                            see `BPF-local functions`_
+BPF_CALL  0x8    0x2  call platform-specific helper 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.

Documentation/bpf/instruction-set.rst Jump instructions · line 284

Quoted 10 lines
Documentation/bpf/instruction-set.rst +10 -0
+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.

I don't think it's a right distinction.
helper vs kfunc are just different mechanisms. Like old approach and new. Both can be platform specific and agnostic.
Take bpf_inode_storage_get() or bpf_find_vma(),
I doubt anything like this will be available on non-Linux OS. While bpf_obj_new_impl() might very well be in every OS.

Documentation/bpf/instruction-set.rst Jump instructions · line 290

Quoted 6 lines
Documentation/bpf/instruction-set.rst +6 -0
+
+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.

Instead of saying 'BPF-local' may be use 'program local' ?