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: Dave Thaler <dthaler1968@gmail.com>
Link: https://lore.kernel.org/r/20240524164618.18894-1-dthaler1968@gmail.com
Signed-off-by: Alexei Starovoitov <ast@kernel.org>

1 files changed, 102 insertions, 82 deletions

diff --git a/Documentation/bpf/standardization/instruction-set.rst b/Documentation/bpf/standardization/instruction-set.rst
index 6b11d1109f12..1602454fe7cf 100644
--- a/Documentation/bpf/standardization/instruction-set.rst
+++ b/Documentation/bpf/standardization/instruction-set.rst
@@ -32,7 +32,7 @@ Types
 This document refers to integer types with the notation `SN` to specify
 a type's signedness (`S`) and bit width (`N`), respectively.
 
-.. table:: Meaning of signedness notation.
+.. table:: Meaning of signedness notation
 
   ==== =========
   S    Meaning
@@ -41,7 +41,7 @@ a type's signedness (`S`) and bit width (`N`), respectively.
   s    signed
   ==== =========
 
-.. table:: Meaning of bit-width notation.
+.. table:: Meaning of bit-width notation
 
   ===== =========
   N     Bit width
@@ -263,18 +263,20 @@ Instruction classes
 
 The three least significant bits of the 'opcode' field store the instruction class:
 
-=====  =====  ===============================  ===================================
-class  value  description                      reference
-=====  =====  ===============================  ===================================
-LD     0x0    non-standard load operations     `Load and store instructions`_
-LDX    0x1    load into register operations    `Load and store instructions`_
-ST     0x2    store from immediate operations  `Load and store instructions`_
-STX    0x3    store from register operations   `Load and store instructions`_
-ALU    0x4    32-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`_
-=====  =====  ===============================  ===================================
+.. table:: Instruction class
+
+  =====  =====  ===============================  ===================================
+  class  value  description                      reference
+  =====  =====  ===============================  ===================================
+  LD     0x0    non-standard load operations     `Load and store instructions`_
+  LDX    0x1    load into register operations    `Load and store instructions`_
+  ST     0x2    store from immediate operations  `Load and store instructions`_
+  STX    0x3    store from register operations   `Load and store instructions`_
+  ALU    0x4    32-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
 ================================
@@ -292,6 +294,8 @@ For arithmetic and jump instructions (``ALU``, ``ALU64``, ``JMP`` and
 **s (source)**
   the source operand location, which unless otherwise specified is one of:
 
+  .. table:: Source operand location
+
   ======  =====  ==============================================
   source  value  description
   ======  =====  ==============================================
@@ -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
 register.
 
-=====  =====  =======  ==========================================================
-name   code   offset   description
-=====  =====  =======  ==========================================================
-ADD    0x0    0        dst += src
-SUB    0x1    0        dst -= src
-MUL    0x2    0        dst \*= src
-DIV    0x3    0        dst = (src != 0) ? (dst / src) : 0
-SDIV   0x3    1        dst = (src != 0) ? (dst s/ src) : 0
-OR     0x4    0        dst \|= src
-AND    0x5    0        dst &= src
-LSH    0x6    0        dst <<= (src & mask)
-RSH    0x7    0        dst >>= (src & mask)
-NEG    0x8    0        dst = -dst
-MOD    0x9    0        dst = (src != 0) ? (dst % src) : dst
-SMOD   0x9    1        dst = (src != 0) ? (dst s% src) : dst
-XOR    0xa    0        dst ^= src
-MOV    0xb    0        dst = src
-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)
-=====  =====  =======  ==========================================================
+.. table:: Arithmetic instructions
+
+  =====  =====  =======  ==========================================================
+  name   code   offset   description
+  =====  =====  =======  ==========================================================
+  ADD    0x0    0        dst += src
+  SUB    0x1    0        dst -= src
+  MUL    0x2    0        dst \*= src
+  DIV    0x3    0        dst = (src != 0) ? (dst / src) : 0
+  SDIV   0x3    1        dst = (src != 0) ? (dst s/ src) : 0
+  OR     0x4    0        dst \|= src
+  AND    0x5    0        dst &= src
+  LSH    0x6    0        dst <<= (src & mask)
+  RSH    0x7    0        dst >>= (src & mask)
+  NEG    0x8    0        dst = -dst
+  MOD    0x9    0        dst = (src != 0) ? (dst % src) : dst
+  SMOD   0x9    1        dst = (src != 0) ? (dst s% src) : dst
+  XOR    0xa    0        dst ^= src
+  MOV    0xb    0        dst = src
+  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
 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
 ``ALU64``, the 1-bit source operand field in the opcode is reserved
 and MUST be set to 0.
 
-=====  ========  =====  =================================================
-class  source    value  description
-=====  ========  =====  =================================================
-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
-=====  ========  =====  =================================================
+.. table:: Byte swap instructions
+
+  =====  ========  =====  =================================================
+  class  source    value  description
+  =====  ========  =====  =================================================
+  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
 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
 group unless otherwise specified.
 The 'code' field encodes the operation as below:
 
-========  =====  =======  =================================  ===================================================
-code      value  src_reg  description                        notes
-========  =====  =======  =================================  ===================================================
-JA        0x0    0x0      PC += offset                       {JA, K, JMP} only
-JA        0x0    0x0      PC += imm                          {JA, K, JMP32} only
-JEQ       0x1    any      PC += offset if dst == src
-JGT       0x2    any      PC += offset if dst > src          unsigned
-JGE       0x3    any      PC += offset if dst >= src         unsigned
-JSET      0x4    any      PC += offset if dst & src
-JNE       0x5    any      PC += offset if dst != src
-JSGT      0x6    any      PC += offset if dst > src          signed
-JSGE      0x7    any      PC += offset if dst >= src         signed
-CALL      0x8    0x0      call helper function by static ID  {CALL, K, JMP} only, see `Helper functions`_
-CALL      0x8    0x1      call PC += imm                     {CALL, K, JMP} only, see `Program-local functions`_
-CALL      0x8    0x2      call helper function by BTF ID     {CALL, K, JMP} only, see `Helper functions`_
-EXIT      0x9    0x0      return                             {CALL, K, JMP} only
-JLT       0xa    any      PC += offset if dst < src          unsigned
-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
-========  =====  =======  =================================  ===================================================
+.. table:: Jump instructions
+
+  ========  =====  =======  =================================  ===================================================
+  code      value  src_reg  description                        notes
+  ========  =====  =======  =================================  ===================================================
+  JA        0x0    0x0      PC += offset                       {JA, K, JMP} only
+  JA        0x0    0x0      PC += imm                          {JA, K, JMP32} only
+  JEQ       0x1    any      PC += offset if dst == src
+  JGT       0x2    any      PC += offset if dst > src          unsigned
+  JGE       0x3    any      PC += offset if dst >= src         unsigned
+  JSET      0x4    any      PC += offset if dst & src
+  JNE       0x5    any      PC += offset if dst != src
+  JSGT      0x6    any      PC += offset if dst > src          signed
+  JSGE      0x7    any      PC += offset if dst >= src         signed
+  CALL      0x8    0x0      call helper function by static ID  {CALL, K, JMP} only, see `Helper functions`_
+  CALL      0x8    0x1      call PC += imm                     {CALL, K, JMP} only, see `Program-local functions`_
+  CALL      0x8    0x2      call helper function by BTF ID     {CALL, K, JMP} only, see `Helper functions`_
+  EXIT      0x9    0x0      return                             {CALL, K, JMP} only
+  JLT       0xa    any      PC += offset if dst < src          unsigned
+  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
 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
 **mode**
   The mode modifier is one of:
 
+  .. table:: Mode modifier
+
     =============  =====  ====================================  =============
     mode modifier  value  description                           reference
     =============  =====  ====================================  =============
@@ -573,6 +585,8 @@ For load and store instructions (``LD``, ``LDX``, ``ST``, and ``STX``), the
 **sz (size)**
   The size modifier is one of:
 
+  .. table:: Size modifier
+
     ====  =====  =====================
     size  value  description
     ====  =====  =====================
@@ -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
 arithmetic operations in the 'imm' field to encode the atomic operation:
 
-========  =====  ===========
-imm       value  description
-========  =====  ===========
-ADD       0x00   atomic add
-OR        0x40   atomic or
-AND       0x50   atomic and
-XOR       0xa0   atomic xor
-========  =====  ===========
+.. table:: Simple atomic operations
+
+  ========  =====  ===========
+  imm       value  description
+  ========  =====  ===========
+  ADD       0x00   atomic add
+  OR        0x40   atomic or
+  AND       0x50   atomic and
+  XOR       0xa0   atomic xor
+  ========  =====  ===========
 
 
 ``{ATOMIC, W, STX}`` with 'imm' = ADD means::
@@ -662,6 +678,8 @@ XOR       0xa0   atomic xor
 In addition to the simple atomic operations, there also is a modifier and
 two complex atomic operations:
 
+.. table:: Complex atomic operations
+
 ===========  ================  ===========================
 imm          value             description
 ===========  ================  ===========================
@@ -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"
 defined further below:
 
-=======  =========================================  ===========  ==============
-src_reg  pseudocode                                 imm type     dst type
-=======  =========================================  ===========  ==============
-0x0      dst = (next_imm << 32) | imm               integer      integer
-0x1      dst = map_by_fd(imm)                       map fd       map
-0x2      dst = map_val(map_by_fd(imm)) + next_imm   map fd       data address
-0x3      dst = var_addr(imm)                        variable id  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
-=======  =========================================  ===========  ==============
+.. table:: 64-bit immediate instructions
+
+  =======  =========================================  ===========  ==============
+  src_reg  pseudocode                                 imm type     dst type
+  =======  =========================================  ===========  ==============
+  0x0      dst = (next_imm << 32) | imm               integer      integer
+  0x1      dst = map_by_fd(imm)                       map fd       map
+  0x2      dst = map_val(map_by_fd(imm)) + next_imm   map fd       data address
+  0x3      dst = var_addr(imm)                        variable id  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