Commit ced33f2c authored by Yonghong Song's avatar Yonghong Song Committed by Daniel Borkmann
Browse files

docs/bpf: 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.

Signed-off-by: default avatarYonghong Song <yonghong.song@linux.dev>
Signed-off-by: default avatarDaniel Borkmann <daniel@iogearbox.net>
Acked-by: default avatarDave Thaler <dthaler1968@gmail.com>
Link: https://lore.kernel.org/bpf/20240127194629.737589-1-yonghong.song@linux.dev
parent efaa47db

Documentation/bpf/standardization/instruction-set.rst

+4 −9
Original line number Diff line number Diff line
@@ -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