Skip to content

L
linux
Commit 6a6d8b6f authored by Dave Thaler's avatar Dave Thaler Committed by Alexei Starovoitov
Browse files
Options

bpf, docs: Add table captions 

As suggested by Ines Robles in his IETF GENART review at
https://datatracker.ietf.org/doc/review-ietf-bpf-isa-02-genart-lc-robles-2024-05-16/Signed-off-by: default avatarDave Thaler <dthaler1968@gmail.com>
Link: https://lore.kernel.org/r/20240524164618.18894-1-dthaler1968@gmail.comSigned-off-by: default avatarAlexei Starovoitov <ast@kernel.org>
parent 4e1215d9
Hide whitespace changes
Inline Side-by-side
Showing with 102 additions and 82 deletions
Documentation/bpf/standardization/instruction-set.rst
View file @ 6a6d8b6f
...@@ -32,7 +32,7 @@ Types ...@@ -32,7 +32,7 @@ Types
This document refers to integer types with the notation `SN` to specify This document refers to integer types with the notation `SN` to specify
a type's signedness (`S`) and bit width (`N`), respectively. a type's signedness (`S`) and bit width (`N`), respectively.
.. table:: Meaning of signedness notation. .. table:: Meaning of signedness notation
==== ========= ==== =========
S Meaning S Meaning
...@@ -41,7 +41,7 @@ a type's signedness (`S`) and bit width (`N`), respectively. ...@@ -41,7 +41,7 @@ a type's signedness (`S`) and bit width (`N`), respectively.
s signed s signed
==== ========= ==== =========
.. table:: Meaning of bit-width notation. .. table:: Meaning of bit-width notation
===== ========= ===== =========
N Bit width N Bit width
...@@ -263,18 +263,20 @@ Instruction classes ...@@ -263,18 +263,20 @@ Instruction classes
The three least significant bits of the 'opcode' field store the instruction class: The three least significant bits of the 'opcode' field store the instruction class:
===== ===== =============================== =================================== .. table:: Instruction class
class value description reference
===== ===== =============================== =================================== ===== ===== =============================== ===================================
LD 0x0 non-standard load operations `Load and store instructions`_ class value description reference
LDX 0x1 load into register operations `Load and store instructions`_ ===== ===== =============================== ===================================
ST 0x2 store from immediate operations `Load and store instructions`_ LD 0x0 non-standard load operations `Load and store instructions`_
STX 0x3 store from register operations `Load and store instructions`_ LDX 0x1 load into register operations `Load and store instructions`_
ALU 0x4 32-bit arithmetic operations `Arithmetic and jump instructions`_ ST 0x2 store from immediate operations `Load and store instructions`_
JMP 0x5 64-bit jump operations `Arithmetic and jump instructions`_ STX 0x3 store from register operations `Load and store instructions`_
JMP32 0x6 32-bit jump operations `Arithmetic and jump instructions`_ ALU 0x4 32-bit arithmetic operations `Arithmetic and jump instructions`_
ALU64 0x7 64-bit arithmetic operations `Arithmetic and jump instructions`_ JMP 0x5 64-bit jump operations `Arithmetic and jump instructions`_
===== ===== =============================== =================================== JMP32 0x6 32-bit jump operations `Arithmetic and jump instructions`_
ALU64 0x7 64-bit arithmetic operations `Arithmetic and jump instructions`_
===== ===== =============================== ===================================
Arithmetic and jump instructions Arithmetic and jump instructions
================================ ================================
...@@ -292,6 +294,8 @@ For arithmetic and jump instructions (``ALU``, ``ALU64``, ``JMP`` and ...@@ -292,6 +294,8 @@ For arithmetic and jump instructions (``ALU``, ``ALU64``, ``JMP`` and
**s (source)** **s (source)**
the source operand location, which unless otherwise specified is one of: the source operand location, which unless otherwise specified is one of:
.. table:: Source operand location
====== ===== ============================================== ====== ===== ==============================================
source value description source value description
====== ===== ============================================== ====== ===== ==============================================
...@@ -312,27 +316,29 @@ The 'code' field encodes the operation as below, where 'src' refers to the ...@@ -312,27 +316,29 @@ The 'code' field encodes the operation as below, where 'src' refers to the
the source operand and 'dst' refers to the value of the destination the source operand and 'dst' refers to the value of the destination
register. register.
===== ===== ======= ========================================================== .. table:: Arithmetic instructions
name code offset description
===== ===== ======= ========================================================== ===== ===== ======= ==========================================================
ADD 0x0 0 dst += src name code offset description
SUB 0x1 0 dst -= src ===== ===== ======= ==========================================================
MUL 0x2 0 dst \*= src ADD 0x0 0 dst += src
DIV 0x3 0 dst = (src != 0) ? (dst / src) : 0 SUB 0x1 0 dst -= src
SDIV 0x3 1 dst = (src != 0) ? (dst s/ src) : 0 MUL 0x2 0 dst \*= src
OR 0x4 0 dst \|= src DIV 0x3 0 dst = (src != 0) ? (dst / src) : 0
AND 0x5 0 dst &= src SDIV 0x3 1 dst = (src != 0) ? (dst s/ src) : 0
LSH 0x6 0 dst <<= (src & mask) OR 0x4 0 dst \|= src
RSH 0x7 0 dst >>= (src & mask) AND 0x5 0 dst &= src
NEG 0x8 0 dst = -dst LSH 0x6 0 dst <<= (src & mask)
MOD 0x9 0 dst = (src != 0) ? (dst % src) : dst RSH 0x7 0 dst >>= (src & mask)
SMOD 0x9 1 dst = (src != 0) ? (dst s% src) : dst NEG 0x8 0 dst = -dst
XOR 0xa 0 dst ^= src MOD 0x9 0 dst = (src != 0) ? (dst % src) : dst
MOV 0xb 0 dst = src SMOD 0x9 1 dst = (src != 0) ? (dst s% src) : dst
MOVSX 0xb 8/16/32 dst = (s8,s16,s32)src XOR 0xa 0 dst ^= src
ARSH 0xc 0 :term:`sign extending<Sign Extend>` dst >>= (src & mask) MOV 0xb 0 dst = src
END 0xd 0 byte swap operations (see `Byte swap instructions`_ below) MOVSX 0xb 8/16/32 dst = (s8,s16,s32)src
===== ===== ======= ========================================================== ARSH 0xc 0 :term:`sign extending<Sign Extend>` dst >>= (src & mask)
END 0xd 0 byte swap operations (see `Byte swap instructions`_ below)
===== ===== ======= ==========================================================
Underflow and overflow are allowed during arithmetic operations, meaning Underflow and overflow are allowed during arithmetic operations, meaning
the 64-bit or 32-bit value will wrap. If BPF program execution would the 64-bit or 32-bit value will wrap. If BPF program execution would
...@@ -426,13 +432,15 @@ select what byte order the operation converts from or to. For ...@@ -426,13 +432,15 @@ select what byte order the operation converts from or to. For
``ALU64``, the 1-bit source operand field in the opcode is reserved ``ALU64``, the 1-bit source operand field in the opcode is reserved
and MUST be set to 0. and MUST be set to 0.
===== ======== ===== ================================================= .. table:: Byte swap instructions
class source value description
===== ======== ===== ================================================= ===== ======== ===== =================================================
ALU TO_LE 0 convert between host byte order and little endian class source value description
ALU TO_BE 1 convert between host byte order and big endian ===== ======== ===== =================================================
ALU64 Reserved 0 do byte swap unconditionally ALU TO_LE 0 convert between host byte order and little endian
===== ======== ===== ================================================= ALU TO_BE 1 convert between host byte order and big endian
ALU64 Reserved 0 do byte swap unconditionally
===== ======== ===== =================================================
The 'imm' field encodes the width of the swap operations. The following widths The 'imm' field encodes the width of the swap operations. The following widths
are supported: 16, 32 and 64. Width 64 operations belong to the base64 are supported: 16, 32 and 64. Width 64 operations belong to the base64
...@@ -468,27 +476,29 @@ otherwise identical operations, and indicates the base64 conformance ...@@ -468,27 +476,29 @@ otherwise identical operations, and indicates the base64 conformance
group unless otherwise specified. group unless otherwise specified.
The 'code' field encodes the operation as below: The 'code' field encodes the operation as below:
======== ===== ======= ================================= =================================================== .. table:: Jump instructions
code value src_reg description notes
======== ===== ======= ================================= =================================================== ======== ===== ======= ================================= ===================================================
JA 0x0 0x0 PC += offset {JA, K, JMP} only code value src_reg description notes
JA 0x0 0x0 PC += imm {JA, K, JMP32} only ======== ===== ======= ================================= ===================================================
JEQ 0x1 any PC += offset if dst == src JA 0x0 0x0 PC += offset {JA, K, JMP} only
JGT 0x2 any PC += offset if dst > src unsigned JA 0x0 0x0 PC += imm {JA, K, JMP32} only
JGE 0x3 any PC += offset if dst >= src unsigned JEQ 0x1 any PC += offset if dst == src
JSET 0x4 any PC += offset if dst & src JGT 0x2 any PC += offset if dst > src unsigned
JNE 0x5 any PC += offset if dst != src JGE 0x3 any PC += offset if dst >= src unsigned
JSGT 0x6 any PC += offset if dst > src signed JSET 0x4 any PC += offset if dst & src
JSGE 0x7 any PC += offset if dst >= src signed JNE 0x5 any PC += offset if dst != src
CALL 0x8 0x0 call helper function by static ID {CALL, K, JMP} only, see `Helper functions`_ JSGT 0x6 any PC += offset if dst > src signed
CALL 0x8 0x1 call PC += imm {CALL, K, JMP} only, see `Program-local functions`_ JSGE 0x7 any PC += offset if dst >= src signed
CALL 0x8 0x2 call helper function by BTF ID {CALL, K, JMP} only, see `Helper functions`_ CALL 0x8 0x0 call helper function by static ID {CALL, K, JMP} only, see `Helper functions`_
EXIT 0x9 0x0 return {CALL, K, JMP} only CALL 0x8 0x1 call PC += imm {CALL, K, JMP} only, see `Program-local functions`_
JLT 0xa any PC += offset if dst < src unsigned CALL 0x8 0x2 call helper function by BTF ID {CALL, K, JMP} only, see `Helper functions`_
JLE 0xb any PC += offset if dst <= src unsigned EXIT 0x9 0x0 return {CALL, K, JMP} only
JSLT 0xc any PC += offset if dst < src signed JLT 0xa any PC += offset if dst < src unsigned
JSLE 0xd any PC += offset if dst <= src signed JLE 0xb any PC += offset if dst <= src unsigned
======== ===== ======= ================================= =================================================== JSLT 0xc any PC += offset if dst < src signed
JSLE 0xd any PC += offset if dst <= src signed
======== ===== ======= ================================= ===================================================
where 'PC' denotes the program counter, and the offset to increment by where 'PC' denotes the program counter, and the offset to increment by
is in units of 64-bit instructions relative to the instruction following is in units of 64-bit instructions relative to the instruction following
...@@ -559,6 +569,8 @@ For load and store instructions (``LD``, ``LDX``, ``ST``, and ``STX``), the ...@@ -559,6 +569,8 @@ For load and store instructions (``LD``, ``LDX``, ``ST``, and ``STX``), the
**mode** **mode**
The mode modifier is one of: The mode modifier is one of:
.. table:: Mode modifier
============= ===== ==================================== ============= ============= ===== ==================================== =============
mode modifier value description reference mode modifier value description reference
============= ===== ==================================== ============= ============= ===== ==================================== =============
...@@ -573,6 +585,8 @@ For load and store instructions (``LD``, ``LDX``, ``ST``, and ``STX``), the ...@@ -573,6 +585,8 @@ For load and store instructions (``LD``, ``LDX``, ``ST``, and ``STX``), the
**sz (size)** **sz (size)**
The size modifier is one of: The size modifier is one of:
.. table:: Size modifier
==== ===== ===================== ==== ===== =====================
size value description size value description
==== ===== ===================== ==== ===== =====================
...@@ -641,14 +655,16 @@ The 'imm' field is used to encode the actual atomic operation. ...@@ -641,14 +655,16 @@ The 'imm' field is used to encode the actual atomic operation.
Simple atomic operation use a subset of the values defined to encode Simple atomic operation use a subset of the values defined to encode
arithmetic operations in the 'imm' field to encode the atomic operation: arithmetic operations in the 'imm' field to encode the atomic operation:
======== ===== =========== .. table:: Simple atomic operations
imm value description
======== ===== =========== ======== ===== ===========
ADD 0x00 atomic add imm value description
OR 0x40 atomic or ======== ===== ===========
AND 0x50 atomic and ADD 0x00 atomic add
XOR 0xa0 atomic xor OR 0x40 atomic or
======== ===== =========== AND 0x50 atomic and
XOR 0xa0 atomic xor
======== ===== ===========
``{ATOMIC, W, STX}`` with 'imm' = ADD means:: ``{ATOMIC, W, STX}`` with 'imm' = ADD means::
...@@ -662,6 +678,8 @@ XOR 0xa0 atomic xor ...@@ -662,6 +678,8 @@ XOR 0xa0 atomic xor
In addition to the simple atomic operations, there also is a modifier and In addition to the simple atomic operations, there also is a modifier and
two complex atomic operations: two complex atomic operations:
.. table:: Complex atomic operations
=========== ================ =========================== =========== ================ ===========================
imm value description imm value description
=========== ================ =========================== =========== ================ ===========================
...@@ -695,17 +713,19 @@ The following table defines a set of ``{IMM, DW, LD}`` instructions ...@@ -695,17 +713,19 @@ The following table defines a set of ``{IMM, DW, LD}`` instructions
with opcode subtypes in the 'src_reg' field, using new terms such as "map" with opcode subtypes in the 'src_reg' field, using new terms such as "map"
defined further below: defined further below:
======= ========================================= =========== ============== .. table:: 64-bit immediate instructions
src_reg pseudocode imm type dst type
======= ========================================= =========== ============== ======= ========================================= =========== ==============
0x0 dst = (next_imm << 32) | imm integer integer src_reg pseudocode imm type dst type
0x1 dst = map_by_fd(imm) map fd map ======= ========================================= =========== ==============
0x2 dst = map_val(map_by_fd(imm)) + next_imm map fd data address 0x0 dst = (next_imm << 32) | imm integer integer
0x3 dst = var_addr(imm) variable id data address 0x1 dst = map_by_fd(imm) map fd map
0x4 dst = code_addr(imm) integer code address 0x2 dst = map_val(map_by_fd(imm)) + next_imm map fd data address
0x5 dst = map_by_idx(imm) map index map 0x3 dst = var_addr(imm) variable id data address
0x6 dst = map_val(map_by_idx(imm)) + next_imm map index data address 0x4 dst = code_addr(imm) integer code address
======= ========================================= =========== ============== 0x5 dst = map_by_idx(imm) map index map
0x6 dst = map_val(map_by_idx(imm)) + next_imm map index data address
======= ========================================= =========== ==============
where where
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment
GitLab Nexedi Edition | About GitLab | About Nexedi | 沪ICP备2021021310号-2 | 沪ICP备2021021310号-7