bpf, docs: Add extended call instructions
Subsystems (2)
PATCH v2 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
--- 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
@@ -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 ===========================
Documentation/bpf/linux-notes.rst +4 -0
@@ -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
Quoted 74 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 VernetSigned-off-by Dave Thaler <[email protected]>--- 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
-22@@ -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
Documentation/bpf/instruction-set.rst Jump instructions · line 282
Quoted 10 lines
Documentation/bpf/instruction-set.rst +8
-1function 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
How does the separate integer numbering space work in Linux? Here I guess we have platform agnostic and Linux specific helpers all mingled together correct?
Quoted 16 lines
Documentation/bpf/instruction-set.rst +8
-0+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 +0
-0
Documentation/bpf/linux-notes.rst integer would be read from a specified register, is not currently supported · line 25
Quoted 6 lines
Documentation/bpf/linux-notes.rst +3
-0@@ -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").
Is this the comment to address above integer numbering space on Linux being inconsistent with above docs?
Quoted 7 lines
Documentation/bpf/linux-notes.rst +1
-0+ Legacy BPF Packet access instructions =====================================Signature · 1 line
2.33.4