bpf, docs: Explain helper functions
Subsystems (2)
PATCH v3 1/1 bpf, docs: Explain helper functions
From: Dave Thaler <[email protected]>
Add text explaining helper functions.
Note that text about runtime functions (kfuncs) is part of a separate patch, not this one.
---
V1 -> V2: addressed comments from Alexei and Stanislav
V2 -> V3: addressed comments from David Vernet
--- Documentation/bpf/clang-notes.rst | 6 ++++++ Documentation/bpf/instruction-set.rst | 19 ++++++++++++++++++- Documentation/bpf/linux-notes.rst | 8 ++++++++ 3 files changed, 32 insertions(+), 1 deletion(-)
Documentation/bpf/clang-notes.rst +6 -0
@@ -20,6 +20,12 @@ Arithmetic instructions For CPU versions prior to 3, Clang v7.0 and later can enable ``BPF_ALU`` support with ``-Xclang -target-feature -Xclang +alu32``. In CPU version 3, support is automatically included. +Jump instructions +================= + +If ``-O0`` is used, Clang will generate the ``BPF_CALL | BPF_X | BPF_JMP`` (0x8d) +instruction, which is not supported by the Linux kernel verifier. + Atomic operations =================
Documentation/bpf/instruction-set.rst +18 -1
@@ -239,7 +239,7 @@ 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 +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
@@ -250,6 +250,23 @@ BPF_JSLE 0xd0 PC += off if dst <= src signed The eBPF program needs to store the return value into register R0 before doing a BPF_EXIT. +Helper functions +~~~~~~~~~~~~~~~~ + +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. + +Conceptually, each helper function is implemented with a commonly shared function +signature defined as: + + u64 function(u64 r1, u64 r2, u64 r3, u64 r4, u64 r5) + +In actuality, each helper function is defined as taking between 0 and 5 arguments, +with the remaining registers being ignored. The definition of a helper function +is responsible for specifying the type (e.g., integer, pointer, etc.) of the value returned, +the number of arguments, and the type of each argument. Load and store instructions ===========================
Documentation/bpf/linux-notes.rst +8 -0
@@ -12,6 +12,14 @@ Byte swap instructions ``BPF_FROM_LE`` and ``BPF_FROM_BE`` exist as aliases for ``BPF_TO_LE`` and ``BPF_TO_BE`` respectively. +Jump instructions +================= + +``BPF_CALL | BPF_X | BPF_JMP`` (0x8d), where the helper function +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. + Legacy BPF Packet access instructions =====================================
Signature · 1 line
2.33.4
Quoted 23 lines · Dave Thaler
From: Dave Thaler <[email protected]>
Add text explaining helper functions.
Note that text about runtime functions (kfuncs) is part of a separate patch, not this one.Signed-off-by Dave Thaler <[email protected]>---
V1 -> V2: addressed comments from Alexei and StanislavV2 -> V3: addressed comments from David Vernet
--- Documentation/bpf/clang-notes.rst | 6 ++++++ Documentation/bpf/instruction-set.rst | 19 ++++++++++++++++++- Documentation/bpf/linux-notes.rst | 8 ++++++++ 3 files changed, 32 insertions(+), 1 deletion(-)Documentation/bpf/clang-notes.rst +0
-0
Documentation/bpf/clang-notes.rst Arithmetic instructions · line 27
Quoted 8 lines
Documentation/bpf/clang-notes.rst +5
-0@@ -20,6 +20,12 @@ Arithmetic instructions For CPU versions prior to 3, Clang v7.0 and later can enable ``BPF_ALU`` support with ``-Xclang -target-feature -Xclang +alu32``. In CPU version 3, support is automatically included. +Jump instructions +================= + +If ``-O0`` is used, Clang will generate the ``BPF_CALL | BPF_X | BPF_JMP`` (0x8d) +instruction, which is not supported by the Linux kernel verifier.
This is fine here.
Quoted 28 lines
Documentation/bpf/clang-notes.rst +1
-0+ Atomic operations =================Documentation/bpf/instruction-set.rst +8
-1@@ -239,7 +239,7 @@ 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 +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@@ -250,6 +250,23 @@ BPF_JSLE 0xd0 PC += off if dst <= src signed The eBPF program needs to store the return value into register R0 before doing a BPF_EXIT. +Helper functions +~~~~~~~~~~~~~~~~ + +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 BPF_JSLE 0xd0 PC += off if dst <= src signed · line 269
Quoted 10 lines
Documentation/bpf/instruction-set.rst +10
-0+ +Conceptually, each helper function is implemented with a commonly shared function +signature defined as: + + u64 function(u64 r1, u64 r2, u64 r3, u64 r4, u64 r5) + +In actuality, each helper function is defined as taking between 0 and 5 arguments, +with the remaining registers being ignored. The definition of a helper function +is responsible for specifying the type (e.g., integer, pointer, etc.) of the value returned, +the number of arguments, and the type of each argument.
Above is correct, but it aims to describe the calling convention which should be done in a separate BPF psABI doc and not in instruction-set.rst.
And if we start describing calling convention we should talk about promotion rules, sign extensions, expectations for return values, for passing structs by value, etc.
Quoted 7 lines
Documentation/bpf/instruction-set.rst +0
-0Load and store instructions ===========================Documentation/bpf/linux-notes.rst +0
-0
Documentation/bpf/linux-notes.rst Byte swap instructions · line 21
Quoted 10 lines
Documentation/bpf/linux-notes.rst +7
-0@@ -12,6 +12,14 @@ Byte swap instructions ``BPF_FROM_LE`` and ``BPF_FROM_BE`` exist as aliases for ``BPF_TO_LE`` and ``BPF_TO_BE`` respectively. +Jump instructions +================= + +``BPF_CALL | BPF_X | BPF_JMP`` (0x8d), where the helper function +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.
This is fine here as well.
Alexei Starovoitov <[email protected]> writes:
[...]
Quoted 19 lines
Quoted 7 lines
Documentation/bpf/instruction-set.rst +7
-0+Helper functions +~~~~~~~~~~~~~~~~ + +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 BPF_JSLE 0xd0 PC += off if dst <= src signed
Quoted 10 lines
Documentation/bpf/instruction-set.rst +10
-0+ +Conceptually, each helper function is implemented with a commonly +shared function signature defined as: + + u64 function(u64 r1, u64 r2, u64 r3, u64 r4, u64 r5) + +In actuality, each helper function is defined as taking between 0 and +5 arguments, with the remaining registers being ignored. The +definition of a helper function is responsible for specifying the +type (e.g., integer, pointer, etc.) of the value returned, the number ofarguments, and the type of each argument.
Quoted 5 lines
Above is correct, but it aims to describe the calling convention which should be done in a separate BPF psABI doc and not in
instruction-set.rst. And if we start describing calling convention we should talk about promotion rules, sign extensions, expectations for return values, for passing structs by value, etc.
The instruction itself requires defining the concept of a helper function, so is the text in question the part starting with "Conceptually," down to the end of the quoted text?
Since there is no separate BPF psABI document (and I'm not sure the scope of that document myself) can we put it here for now and move it when that doc
is created? If not, what part of the text above would be in a separate document?
[...]
Dave
Quoted 22 lines · Dave Thaler
Alexei Starovoitov <[email protected]> writes:
[...]Quoted 19 lines
Quoted 7 lines
Documentation/bpf/instruction-set.rst +7
-0+Helper functions +~~~~~~~~~~~~~~~~ + +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 BPF_JSLE 0xd0 PC += off if dst <= src signed
Quoted 10 lines
Documentation/bpf/instruction-set.rst +10
-0+ +Conceptually, each helper function is implemented with a commonly +shared function signature defined as: + + u64 function(u64 r1, u64 r2, u64 r3, u64 r4, u64 r5) + +In actuality, each helper function is defined as taking between 0 and +5 arguments, with the remaining registers being ignored. The +definition of a helper function is responsible for specifying the +type (e.g., integer, pointer, etc.) of the value returned, the number ofarguments, and the type of each argument.
Quoted 7 lines
Quoted 5 lines
Above is correct, but it aims to describe the calling convention which should be done in a separate BPF psABI doc and not in
instruction-set.rst. And if we start describing calling convention we should talk about promotion rules, sign extensions, expectations for return values, for passing structs by value, etc.The instruction itself requires defining the concept of a helper function,
Not really. BPF_CALL instruction doesn't have to define what it's calling and how the call is being made.
Typical cpu will define CALL insn as:
1. pushes the return address on the stack.
2. changes IP to the call destination
That's it. Mechanics of CALL have no overlap with calling convention. Different languages and operating systems can do it differently. BPF ISA doc should describe mechanics of instructions only.
Quoted 3 lines
so is the
text in question the part starting with "Conceptually," down to the end of the quoted text?
Right, that part doesn't belong in BPF ISA doc.
Even
"Each helper function is identified by an integer used in a ``BPF_CALL`` instruction."
arguably belongs in psABI, since it's a bpf's flavor of relocations. Other cpus do it in ELF relocations while bpf does it inline as part of instruction encoding. That is not an ISA.
It's a protocol between user and kernel.
We just happen to use bits in instruction to indicate relocation that kernel has to perform before executing call insn.
At the end JITs will map BPF_CALL insn one to one to CPU call insn on architectures where calling conventions match.
Quoted 3 lines
Since there is no separate BPF psABI document (and I'm not sure the scope of that document myself) can we put it here for now and move it when that doc
is created? If not, what part of the text above would be in a separate document?
BPF psABI should look like:
https://raw.githubusercontent.com/wiki/hjl-tools/x86-psABI/x86-64-psABI-1.0.pdf
Ours will be shorter, hopefully.
We haven't defined a bunch of things yet. Like how to pass 6th argument.
Quoted 3 lines
BPF psABI should look like:
https://raw.githubusercontent.com/wiki/hjl-tools/x86-psABI/x86-64-psABI-1.0.pdf
LaTeX sources: https://gitlab.com/x86-psABIs/x86-64-ABI