Improve documentation of 64-bit immediate instructions
Subsystems (3)
Yonghong Song
reviewerPATCH 1/1 Improve documentation of 64-bit immediate instructions
For 64-bit immediate instruction, 'BPF_IMM | BPF_DW | BPF_LD' and src_reg=[0-6], the current documentation describes the 64-bit immediate is constructed by
imm64 = (next_imm << 32) | imm
But actually imm64 is only used when src_reg=0. For all other variants (src_reg != 0), 'imm' and 'next_imm' have separate special encoding requirement and imm64 cannot be easily used to describe instruction semantics.
This patch clarifies that 64-bit immediate instructions use two 32-bit immediate values instead of a 64-bit immediate value, so later describing individual 64-bit immediate instructions becomes less confusing.
--- .../bpf/standardization/instruction-set.rst | 13 ++++--------- 1 file changed, 4 insertions(+), 9 deletions(-)
Documentation/bpf/standardization/instruction-set.rst +4 -9
@@ -166,7 +166,7 @@ Note that most instructions do not use all of the fields. Unused fields shall be cleared to zero. As discussed below in `64-bit immediate instructions`_, a 64-bit immediate -instruction uses a 64-bit immediate value that is constructed as follows. +instruction uses two 32-bit immediate values that are constructed as follows. The 64 bits following the basic instruction contain a pseudo instruction using the same format but with opcode, dst_reg, src_reg, and offset all set to zero, and imm containing the high 32 bits of the immediate value.
@@ -181,13 +181,8 @@ This is depicted in the following figure:: '--------------' pseudo instruction -Thus the 64-bit immediate value is constructed as follows: - - imm64 = (next_imm << 32) | imm - -where 'next_imm' refers to the imm value of the pseudo instruction -following the basic instruction. The unused bytes in the pseudo -instruction are reserved and shall be cleared to zero. +Here, the imm value of the pseudo instruction is called 'next_imm'. The unused +bytes in the pseudo instruction are reserved and shall be cleared to zero. Instruction classes -------------------
@@ -590,7 +585,7 @@ defined further below: ========================= ====== === ========================================= =========== ============== opcode construction opcode src pseudocode imm type dst type ========================= ====== === ========================================= =========== ============== -BPF_IMM | BPF_DW | BPF_LD 0x18 0x0 dst = imm64 integer integer +BPF_IMM | BPF_DW | BPF_LD 0x18 0x0 dst = (next_imm << 32) | imm integer integer BPF_IMM | BPF_DW | BPF_LD 0x18 0x1 dst = map_by_fd(imm) map fd map BPF_IMM | BPF_DW | BPF_LD 0x18 0x2 dst = map_val(map_by_fd(imm)) + next_imm map fd data pointer BPF_IMM | BPF_DW | BPF_LD 0x18 0x3 dst = var_addr(imm) variable id data pointer
Signature · 1 line
2.34.1
Yonghong Song
reviewerQuoted 10 lines · Yonghong Song
For 64-bit immediate instruction, '
BPF_IMM|BPF_DW|BPF_LD' and src_reg=[0-6], the current documentation describes the 64-bit immediate is constructed by
imm64 = (next_imm<< 32) | immBut actually imm64 is only used when src_reg=0. For all other variants (
src_reg!= 0), 'imm' and 'next_imm' have separate special encoding requirement and imm64 cannot be easily used to describe instruction semantics.
Quoted 4 lines
This patch clarifies that 64-bit immediate instructions use two 32-bit immediate values instead of a 64-bit immediate value, so later describing individual 64-bit immediate instructions becomes less confusing.
Sorry, for subject, [docs/bpf] is wrong. It should be
[PATCH bpf-next] docs/bpf: Improve documentation of 64-bit immediate instructions
Quoted 45 lines
Acked-by Dave Thaler <[email protected]>Signed-off-by Yonghong Song <[email protected]>--- .../bpf/standardization/instruction-set.rst | 13 ++++--------- 1 file changed, 4 insertions(+), 9 deletions(-)Documentation/bpf/standardization/instruction-set.rst +4
-9@@ -166,7 +166,7 @@ Note that most instructions do not use all of the fields. Unused fields shall be cleared to zero. As discussed below in `64-bit immediate instructions`_, a 64-bit immediate -instruction uses a 64-bit immediate value that is constructed as follows. +instruction uses two 32-bit immediate values that are constructed as follows. The 64 bits following the basic instruction contain a pseudo instruction using the same format but with opcode, dst_reg, src_reg, and offset all set to zero, and imm containing the high 32 bits of the immediate value.@@ -181,13 +181,8 @@ This is depicted in the following figure:: '--------------' pseudo instruction -Thus the 64-bit immediate value is constructed as follows: - - imm64 = (next_imm << 32) | imm - -where 'next_imm' refers to the imm value of the pseudo instruction -following the basic instruction. The unused bytes in the pseudo -instruction are reserved and shall be cleared to zero. +Here, the imm value of the pseudo instruction is called 'next_imm'. The unused +bytes in the pseudo instruction are reserved and shall be cleared to zero. Instruction classes -------------------@@ -590,7 +585,7 @@ defined further below: ========================= ====== === ========================================= =========== ============== opcode construction opcode src pseudocode imm type dst type ========================= ====== === ========================================= =========== ============== -BPF_IMM | BPF_DW | BPF_LD 0x18 0x0 dst = imm64 integer integer +BPF_IMM | BPF_DW | BPF_LD 0x18 0x0 dst = (next_imm << 32) | imm integer integer BPF_IMM | BPF_DW | BPF_LD 0x18 0x1 dst = map_by_fd(imm) map fd map BPF_IMM | BPF_DW | BPF_LD 0x18 0x2 dst = map_val(map_by_fd(imm)) + next_imm map fd data pointer BPF_IMM | BPF_DW | BPF_LD 0x18 0x3 dst = var_addr(imm) variable id data pointer
This patch was applied to bpf/bpf-next.git (master) by Daniel Borkmann <[email protected]>:
Hello:
This patch was applied to bpf/bpf-next.git (master) by Daniel Borkmann <[email protected]>:
Quoted 11 lines · On Sat, 27 Jan 2024 11:46:29 -0800 you wrote:
For 64-bit immediate instruction, '
BPF_IMM|BPF_DW|BPF_LD' and src_reg=[0-6], the current documentation describes the 64-bit immediate is constructed by
imm64 = (next_imm<< 32) | immBut actually imm64 is only used when src_reg=0. For all other variants (
src_reg!= 0), 'imm' and 'next_imm' have separate special encoding requirement and imm64 cannot be easily used to describe instruction semantics.[...]
Here is the summary with links:
- [bpf-next,docs/bpf] Improve documentation of 64-bit immediate instructions
https://git.kernel.org/bpf/bpf-next/c/ced33f2cfa21
You are awesome, thank you!
Signature · 2 lines
Deet-doot-dot, I am a bot. https://korg.docs.kernel.org/patchwork/pwbot.html