| Message ID | 20230728185852.3572290-1-yonghong.song@linux.dev (mailing list archive) |
|---|---|
| State | Superseded |
| Delegated to: | BPF |
| Headers | show |
| Series | [bpf-next] docs/bpf: Improve documentation for cpu=v4 instructions | expand |
| Context | Check | Description |
|---|---|---|
| bpf/vmtest-bpf-next-VM_Test-1 | success | Logs for ShellCheck |
| bpf/vmtest-bpf-next-PR | success | PR summary |
| bpf/vmtest-bpf-next-VM_Test-2 | success | Logs for build for aarch64 with gcc |
| bpf/vmtest-bpf-next-VM_Test-4 | success | Logs for build for x86_64 with gcc |
| bpf/vmtest-bpf-next-VM_Test-5 | success | Logs for build for x86_64 with llvm-16 |
| bpf/vmtest-bpf-next-VM_Test-6 | success | Logs for set-matrix |
| bpf/vmtest-bpf-next-VM_Test-3 | success | Logs for build for s390x with gcc |
| bpf/vmtest-bpf-next-VM_Test-7 | success | Logs for test_maps on aarch64 with gcc |
| bpf/vmtest-bpf-next-VM_Test-9 | success | Logs for test_maps on x86_64 with gcc |
| bpf/vmtest-bpf-next-VM_Test-10 | success | Logs for test_maps on x86_64 with llvm-16 |
| bpf/vmtest-bpf-next-VM_Test-13 | success | Logs for test_progs on x86_64 with gcc |
| bpf/vmtest-bpf-next-VM_Test-14 | success | Logs for test_progs on x86_64 with llvm-16 |
| bpf/vmtest-bpf-next-VM_Test-15 | success | Logs for test_progs_no_alu32 on aarch64 with gcc |
| bpf/vmtest-bpf-next-VM_Test-17 | success | Logs for test_progs_no_alu32 on x86_64 with gcc |
| bpf/vmtest-bpf-next-VM_Test-18 | success | Logs for test_progs_no_alu32 on x86_64 with llvm-16 |
| bpf/vmtest-bpf-next-VM_Test-19 | success | Logs for test_progs_no_alu32_parallel on aarch64 with gcc |
| bpf/vmtest-bpf-next-VM_Test-20 | success | Logs for test_progs_no_alu32_parallel on x86_64 with gcc |
| bpf/vmtest-bpf-next-VM_Test-21 | success | Logs for test_progs_no_alu32_parallel on x86_64 with llvm-16 |
| bpf/vmtest-bpf-next-VM_Test-22 | success | Logs for test_progs_parallel on aarch64 with gcc |
| bpf/vmtest-bpf-next-VM_Test-23 | success | Logs for test_progs_parallel on x86_64 with gcc |
| bpf/vmtest-bpf-next-VM_Test-24 | success | Logs for test_progs_parallel on x86_64 with llvm-16 |
| bpf/vmtest-bpf-next-VM_Test-25 | success | Logs for test_verifier on aarch64 with gcc |
| bpf/vmtest-bpf-next-VM_Test-26 | success | Logs for test_verifier on s390x with gcc |
| bpf/vmtest-bpf-next-VM_Test-27 | success | Logs for test_verifier on x86_64 with gcc |
| bpf/vmtest-bpf-next-VM_Test-28 | success | Logs for test_verifier on x86_64 with llvm-16 |
| bpf/vmtest-bpf-next-VM_Test-29 | success | Logs for veristat |
| bpf/vmtest-bpf-next-VM_Test-11 | success | Logs for test_progs on aarch64 with gcc |
| bpf/vmtest-bpf-next-VM_Test-12 | fail | Logs for test_progs on s390x with gcc |
| bpf/vmtest-bpf-next-VM_Test-8 | success | Logs for test_maps on s390x with gcc |
| bpf/vmtest-bpf-next-VM_Test-16 | success | Logs for test_progs_no_alu32 on s390x with gcc |
| netdev/tree_selection | success | Clearly marked for bpf-next |
| netdev/apply | success | Patch already applied to bpf-next |
On Fri, Jul 28, 2023 at 11:58:52AM -0700, Yonghong Song wrote: > Improve documentation for cpu=v4 instructions based on > David's suggestions. > > Cc: bpf@ietf.org > Suggested-by: David Vernet <void@manifault.com> > Signed-off-by: Yonghong Song <yonghong.song@linux.dev> LGTM, thanks Yonghong. Just left one nit below. Acked-by: David Vernet <void@manifault.com> > --- > .../bpf/standardization/instruction-set.rst | 54 +++++++++++-------- > 1 file changed, 32 insertions(+), 22 deletions(-) > > diff --git a/Documentation/bpf/standardization/instruction-set.rst b/Documentation/bpf/standardization/instruction-set.rst > index 23e880a83a1f..95079a53a35b 100644 > --- a/Documentation/bpf/standardization/instruction-set.rst > +++ b/Documentation/bpf/standardization/instruction-set.rst > @@ -174,7 +174,7 @@ BPF_MOV 0xb0 0 dst = src > BPF_MOVSX 0xb0 8/16/32 dst = (s8,s16,s32)src > BPF_ARSH 0xc0 0 sign extending dst >>= (src & mask) > BPF_END 0xd0 0 byte swap operations (see `Byte swap instructions`_ below) > -======== ===== ============ ========================================================== > +======== ===== ======= ========================================================== > > Underflow and overflow are allowed during arithmetic operations, meaning > the 64-bit or 32-bit value will wrap. If eBPF program execution would > @@ -201,26 +201,32 @@ where '(u32)' indicates that the upper 32 bits are zeroed. > > dst = dst ^ imm32 > > -Note that most instructions have instruction offset of 0. But three instructions > -(BPF_SDIV, BPF_SMOD, BPF_MOVSX) have non-zero offset. > +Note that most instructions have instruction offset of 0. Only three instructions > +(``BPF_SDIV``, ``BPF_SMOD``, ``BPF_MOVSX``) have a non-zero offset. > > The devision and modulo operations support both unsigned and signed flavors. > -For unsigned operation (BPF_DIV and BPF_MOD), for ``BPF_ALU``, 'imm' is first > -interpreted as an unsigned 32-bit value, whereas for ``BPF_ALU64``, 'imm' is > -first sign extended to 64 bits and the result interpreted as an unsigned 64-bit > -value. For signed operation (BPF_SDIV and BPF_SMOD), for ``BPF_ALU``, 'imm' is > -interpreted as a signed value. For ``BPF_ALU64``, the 'imm' is sign extended > -from 32 to 64 and interpreted as a signed 64-bit value. > > -Instruction BPF_MOVSX does move operation with sign extension. > -``BPF_ALU | MOVSX`` sign extendes 8-bit and 16-bit into 32-bit and upper 32-bit are zeroed. > -``BPF_ALU64 | MOVSX`` sign extends 8-bit, 16-bit and 32-bit into 64-bit. > +For unsigned operations (``BPF_DIV`` and ``BPF_MOD``), for ``BPF_ALU``, > +'imm' is interpreted as a 32-bit unsigned value. For ``BPF_ALU64``, > +'imm' is first sign extended from 32 to 64 bits, and then interpreted as > +a 64-bit unsigned value. > + > +For signed operations (``BPF_SDIV`` and ``BPF_SMOD``), for ``BPF_ALU``, > +'imm' is interpreted as a 32-bit signed value. For ``BPF_ALU64``, 'imm' > +is first sign extended from 32 to 64 bits, and then interpreted as a > +64-bit signed value. > + > +The ``BPF_MOVSX`` instruction does a move operation with sign extension. > +``BPF_ALU | BPF_MOVSX`` sign extends 8-bit and 16-bit operands into 32 > +bit operands, and zeroes the remaining upper 32 bits. > +``BPF_ALU64 | BPF_MOVSX`` sign extends 8-bit, 16-bit, and 32-bit > +operands into 64 bit operands. > > Shift operations use a mask of 0x3F (63) for 64-bit operations and 0x1F (31) > for 32-bit operations. > > Byte swap instructions > -~~~~~~~~~~~~~~~~~~~~~~ > +---------------------- > > The byte swap instructions use instruction classes of ``BPF_ALU`` and ``BPF_ALU64`` > and a 4-bit 'code' field of ``BPF_END``. > @@ -228,16 +234,17 @@ and a 4-bit 'code' field of ``BPF_END``. > The byte swap instructions operate on the destination register > only and do not use a separate source register or immediate value. > > -For ``BPF_ALU``, the 1-bit source operand field in the opcode is used to select what byte > -order the operation convert from or to. For ``BPF_ALU64``, the 1-bit source operand > -field in the opcode is not used and must be 0. > +For ``BPF_ALU``, the 1-bit source operand field in the opcode is used to > +select what byte order the operation converts from or to. For > +``BPF_ALU64``, the 1-bit source operand field in the opcode is reserved > +and must be set to 0. > > ========= ========= ===== ================================================= > class source value description > ========= ========= ===== ================================================= > BPF_ALU BPF_TO_LE 0x00 convert between host byte order and little endian > BPF_ALU BPF_TO_BE 0x08 convert between host byte order and big endian > -BPF_ALU64 BPF_TO_LE 0x00 do byte swap unconditionally > +BPF_ALU64 Reserved 0x00 do byte swap unconditionally > ========= ========= ===== ================================================= > > The 'imm' field encodes the width of the swap operations. The following widths > @@ -305,9 +312,12 @@ where 's>=' indicates a signed '>=' comparison. > > where 'imm' means the branch offset comes from insn 'imm' field. > > -Note there are two flavors of BPF_JA instrions. BPF_JMP class permits 16-bit jump offset while > -BPF_JMP32 permits 32-bit jump offset. A >16bit conditional jmp can be converted to a <16bit > -conditional jmp plus a 32-bit unconditional jump. > +Note that there are two flavors of ``BPF_JA`` instructions. The > +``BPF_JMP`` class permits a 16-bit jump offset specified by 'offset' s/by 'offset'/by the 'offset' > +field, whereas the ``BPF_JMP32`` class permits a 32-bit jump offset > +specified by the 'imm' field. A > 16-bit conditional jump may be > +converted to a < 16-bit conditional jump plus a 32-bit unconditional > +jump. > > Helper functions > ~~~~~~~~~~~~~~~~ > @@ -385,7 +395,7 @@ instructions that transfer data between a register and memory. > dst = *(unsigned size *) (src + offset) > > Where size is one of: ``BPF_B``, ``BPF_H``, ``BPF_W``, or ``BPF_DW`` and > -'unsigned size' is one of u8, u16, u32 and u64. > +'unsigned size' is one of u8, u16, u32 or u64. > > The ``BPF_MEMSX`` mode modifier is used to encode sign-extension load > instructions that transfer data between a register and memory. > @@ -395,7 +405,7 @@ instructions that transfer data between a register and memory. > dst = *(signed size *) (src + offset) > > Where size is one of: ``BPF_B``, ``BPF_H`` or ``BPF_W``, and > -'signed size' is one of s8, s16 and s32. > +'signed size' is one of s8, s16 or s32. > > Atomic operations > ----------------- > -- > 2.34.1 >
diff --git a/Documentation/bpf/standardization/instruction-set.rst b/Documentation/bpf/standardization/instruction-set.rst index 23e880a83a1f..95079a53a35b 100644 --- a/Documentation/bpf/standardization/instruction-set.rst +++ b/Documentation/bpf/standardization/instruction-set.rst @@ -174,7 +174,7 @@ BPF_MOV 0xb0 0 dst = src BPF_MOVSX 0xb0 8/16/32 dst = (s8,s16,s32)src BPF_ARSH 0xc0 0 sign extending dst >>= (src & mask) BPF_END 0xd0 0 byte swap operations (see `Byte swap instructions`_ below) -======== ===== ============ ========================================================== +======== ===== ======= ========================================================== Underflow and overflow are allowed during arithmetic operations, meaning the 64-bit or 32-bit value will wrap. If eBPF program execution would @@ -201,26 +201,32 @@ where '(u32)' indicates that the upper 32 bits are zeroed. dst = dst ^ imm32 -Note that most instructions have instruction offset of 0. But three instructions -(BPF_SDIV, BPF_SMOD, BPF_MOVSX) have non-zero offset. +Note that most instructions have instruction offset of 0. Only three instructions +(``BPF_SDIV``, ``BPF_SMOD``, ``BPF_MOVSX``) have a non-zero offset. The devision and modulo operations support both unsigned and signed flavors. -For unsigned operation (BPF_DIV and BPF_MOD), for ``BPF_ALU``, 'imm' is first -interpreted as an unsigned 32-bit value, whereas for ``BPF_ALU64``, 'imm' is -first sign extended to 64 bits and the result interpreted as an unsigned 64-bit -value. For signed operation (BPF_SDIV and BPF_SMOD), for ``BPF_ALU``, 'imm' is -interpreted as a signed value. For ``BPF_ALU64``, the 'imm' is sign extended -from 32 to 64 and interpreted as a signed 64-bit value. -Instruction BPF_MOVSX does move operation with sign extension. -``BPF_ALU | MOVSX`` sign extendes 8-bit and 16-bit into 32-bit and upper 32-bit are zeroed. -``BPF_ALU64 | MOVSX`` sign extends 8-bit, 16-bit and 32-bit into 64-bit. +For unsigned operations (``BPF_DIV`` and ``BPF_MOD``), for ``BPF_ALU``, +'imm' is interpreted as a 32-bit unsigned value. For ``BPF_ALU64``, +'imm' is first sign extended from 32 to 64 bits, and then interpreted as +a 64-bit unsigned value. + +For signed operations (``BPF_SDIV`` and ``BPF_SMOD``), for ``BPF_ALU``, +'imm' is interpreted as a 32-bit signed value. For ``BPF_ALU64``, 'imm' +is first sign extended from 32 to 64 bits, and then interpreted as a +64-bit signed value. + +The ``BPF_MOVSX`` instruction does a move operation with sign extension. +``BPF_ALU | BPF_MOVSX`` sign extends 8-bit and 16-bit operands into 32 +bit operands, and zeroes the remaining upper 32 bits. +``BPF_ALU64 | BPF_MOVSX`` sign extends 8-bit, 16-bit, and 32-bit +operands into 64 bit operands. Shift operations use a mask of 0x3F (63) for 64-bit operations and 0x1F (31) for 32-bit operations. Byte swap instructions -~~~~~~~~~~~~~~~~~~~~~~ +---------------------- The byte swap instructions use instruction classes of ``BPF_ALU`` and ``BPF_ALU64`` and a 4-bit 'code' field of ``BPF_END``. @@ -228,16 +234,17 @@ and a 4-bit 'code' field of ``BPF_END``. The byte swap instructions operate on the destination register only and do not use a separate source register or immediate value. -For ``BPF_ALU``, the 1-bit source operand field in the opcode is used to select what byte -order the operation convert from or to. For ``BPF_ALU64``, the 1-bit source operand -field in the opcode is not used and must be 0. +For ``BPF_ALU``, the 1-bit source operand field in the opcode is used to +select what byte order the operation converts from or to. For +``BPF_ALU64``, the 1-bit source operand field in the opcode is reserved +and must be set to 0. ========= ========= ===== ================================================= class source value description ========= ========= ===== ================================================= BPF_ALU BPF_TO_LE 0x00 convert between host byte order and little endian BPF_ALU BPF_TO_BE 0x08 convert between host byte order and big endian -BPF_ALU64 BPF_TO_LE 0x00 do byte swap unconditionally +BPF_ALU64 Reserved 0x00 do byte swap unconditionally ========= ========= ===== ================================================= The 'imm' field encodes the width of the swap operations. The following widths @@ -305,9 +312,12 @@ where 's>=' indicates a signed '>=' comparison. where 'imm' means the branch offset comes from insn 'imm' field. -Note there are two flavors of BPF_JA instrions. BPF_JMP class permits 16-bit jump offset while -BPF_JMP32 permits 32-bit jump offset. A >16bit conditional jmp can be converted to a <16bit -conditional jmp plus a 32-bit unconditional jump. +Note that there are two flavors of ``BPF_JA`` instructions. The +``BPF_JMP`` class permits a 16-bit jump offset specified by 'offset' +field, whereas the ``BPF_JMP32`` class permits a 32-bit jump offset +specified by the 'imm' field. A > 16-bit conditional jump may be +converted to a < 16-bit conditional jump plus a 32-bit unconditional +jump. Helper functions ~~~~~~~~~~~~~~~~ @@ -385,7 +395,7 @@ instructions that transfer data between a register and memory. dst = *(unsigned size *) (src + offset) Where size is one of: ``BPF_B``, ``BPF_H``, ``BPF_W``, or ``BPF_DW`` and -'unsigned size' is one of u8, u16, u32 and u64. +'unsigned size' is one of u8, u16, u32 or u64. The ``BPF_MEMSX`` mode modifier is used to encode sign-extension load instructions that transfer data between a register and memory. @@ -395,7 +405,7 @@ instructions that transfer data between a register and memory. dst = *(signed size *) (src + offset) Where size is one of: ``BPF_B``, ``BPF_H`` or ``BPF_W``, and -'signed size' is one of s8, s16 and s32. +'signed size' is one of s8, s16 or s32. Atomic operations -----------------
Improve documentation for cpu=v4 instructions based on David's suggestions. Cc: bpf@ietf.org Suggested-by: David Vernet <void@manifault.com> Signed-off-by: Yonghong Song <yonghong.song@linux.dev> --- .../bpf/standardization/instruction-set.rst | 54 +++++++++++-------- 1 file changed, 32 insertions(+), 22 deletions(-)