Commit 5a8921ba authored by Dave Thaler's avatar Dave Thaler Committed by Alexei Starovoitov
Browse files

bpf, docs: Add TOC and fix formatting. 



Add TOC and fix formatting.

Signed-off-by: default avatarDave Thaler <dthaler@microsoft.com>
Link: https://lore.kernel.org/r/20220927185958.14995-5-dthaler1968@googlemail.com


Signed-off-by: default avatarAlexei Starovoitov <ast@kernel.org>
parent ee159bdb

Documentation/bpf/instruction-set.rst

+136 −132
Original line number Diff line number Diff line 
.. contents::

.. sectnum::



========================================

eBPF Instruction Set Specification, v1.0

========================================



This document specifies version 1.0 of the eBPF instruction set.



====================

eBPF Instruction Set

====================



Registers and calling convention

================================
@@ -44,24 +49,24 @@ Instruction classes 


The three LSB bits of the 'opcode' field store the instruction class:



  =========  =====  ===============================

  class      value  description

  =========  =====  ===============================

  BPF_LD     0x00   non-standard load operations

  BPF_LDX    0x01   load into register operations

  BPF_ST     0x02   store from immediate operations

  BPF_STX    0x03   store from register operations

  BPF_ALU    0x04   32-bit arithmetic operations

  BPF_JMP    0x05   64-bit jump operations

  BPF_JMP32  0x06   32-bit jump operations

  BPF_ALU64  0x07   64-bit arithmetic operations

  =========  =====  ===============================

=========  =====  ===============================  ===================================

class      value  description                      reference

=========  =====  ===============================  ===================================

BPF_LD     0x00   non-standard load operations     `Load and store instructions`_

BPF_LDX    0x01   load into register operations    `Load and store instructions`_

BPF_ST     0x02   store from immediate operations  `Load and store instructions`_

BPF_STX    0x03   store from register operations   `Load and store instructions`_

BPF_ALU    0x04   32-bit arithmetic operations     `Arithmetic and jump instructions`_

BPF_JMP    0x05   64-bit jump operations           `Arithmetic and jump instructions`_

BPF_JMP32  0x06   32-bit jump operations           `Arithmetic and jump instructions`_

BPF_ALU64  0x07   64-bit arithmetic operations     `Arithmetic and jump instructions`_

=========  =====  ===============================  ===================================



Arithmetic and jump instructions

================================



For arithmetic and jump instructions (BPF_ALU, BPF_ALU64, BPF_JMP and

BPF_JMP32), the 8-bit 'opcode' field is divided into three parts:

For arithmetic and jump instructions (``BPF_ALU``, ``BPF_ALU64``, ``BPF_JMP`` and

``BPF_JMP32``), the 8-bit 'opcode' field is divided into three parts:



==============  ======  =================

4 bits (MSB)    1 bit   3 bits (LSB)
@@ -84,13 +89,13 @@ The four MSB bits store the operation code. 
Arithmetic instructions

-----------------------



BPF_ALU uses 32-bit wide operands while BPF_ALU64 uses 64-bit wide operands for

``BPF_ALU`` uses 32-bit wide operands while ``BPF_ALU64`` uses 64-bit wide operands for

otherwise identical operations.

The code field encodes the operation as below:

The 'code' field encodes the operation as below:



  ========  =====  =================================================

========  =====  ==========================================================

code      value  description

  ========  =====  =================================================

========  =====  ==========================================================

BPF_ADD   0x00   dst += src

BPF_SUB   0x10   dst -= src

BPF_MUL   0x20   dst \*= src
@@ -104,31 +109,31 @@ The code field encodes the operation as below: 
BPF_XOR   0xa0   dst ^= src

BPF_MOV   0xb0   dst = src

BPF_ARSH  0xc0   sign extending shift right

  BPF_END   0xd0   byte swap operations (see separate section below)

  ========  =====  =================================================

BPF_END   0xd0   byte swap operations (see `Byte swap instructions`_ below)

========  =====  ==========================================================



BPF_ADD | BPF_X | BPF_ALU means::

``BPF_ADD | BPF_X | BPF_ALU`` means::



  dst_reg = (u32) dst_reg + (u32) src_reg;



BPF_ADD | BPF_X | BPF_ALU64 means::

``BPF_ADD | BPF_X | BPF_ALU64`` means::



  dst_reg = dst_reg + src_reg



BPF_XOR | BPF_K | BPF_ALU means::

``BPF_XOR | BPF_K | BPF_ALU`` means::



  src_reg = (u32) src_reg ^ (u32) imm32



BPF_XOR | BPF_K | BPF_ALU64 means::

``BPF_XOR | BPF_K | BPF_ALU64`` means::



  src_reg = src_reg ^ imm32





Byte swap instructions

----------------------

~~~~~~~~~~~~~~~~~~~~~~



The byte swap instructions use an instruction class of ``BPF_ALU`` and a 4-bit

code field of ``BPF_END``.

'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.
@@ -143,7 +148,7 @@ order the operation convert from or to: 
BPF_TO_BE  0x08   convert between host byte order and big endian

=========  =====  =================================================



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.



Examples:
@@ -159,9 +164,9 @@ Examples: 
Jump instructions

-----------------



BPF_JMP32 uses 32-bit wide operands while BPF_JMP uses 64-bit wide operands for

``BPF_JMP32`` uses 32-bit wide operands while ``BPF_JMP`` uses 64-bit wide operands for

otherwise identical operations.

The code field encodes the operation as below:

The 'code' field encodes the operation as below:



========  =====  =========================  ============

code      value  description                notes
@@ -189,7 +194,7 @@ BPF_EXIT. 
Load and store instructions

===========================



For load and store instructions (BPF_LD, BPF_LDX, BPF_ST and BPF_STX), the

For load and store instructions (``BPF_LD``, ``BPF_LDX``, ``BPF_ST``, and ``BPF_STX``), the

8-bit 'opcode' field is divided as:



============  ======  =================
@@ -198,6 +203,18 @@ For load and store instructions (BPF_LD, BPF_LDX, BPF_ST and BPF_STX), the 
mode          size    instruction class

============  ======  =================



The mode modifier is one of:



  =============  =====  ====================================  =============

  mode modifier  value  description                           reference

  =============  =====  ====================================  =============

  BPF_IMM        0x00   64-bit immediate instructions         `64-bit immediate instructions`_

  BPF_ABS        0x20   legacy BPF packet access (absolute)   `Legacy BPF Packet access instructions`_

  BPF_IND        0x40   legacy BPF packet access (indirect)   `Legacy BPF Packet access instructions`_

  BPF_MEM        0x60   regular load and store operations     `Regular load and store operations`_

  BPF_ATOMIC     0xc0   atomic operations                     `Atomic operations`_

  =============  =====  ====================================  =============



The size modifier is one of:



  =============  =====  =====================
@@ -209,19 +226,6 @@ The size modifier is one of: 
  BPF_DW         0x18   double word (8 bytes)

  =============  =====  =====================



The mode modifier is one of:



  =============  =====  ====================================

  mode modifier  value  description

  =============  =====  ====================================

  BPF_IMM        0x00   64-bit immediate instructions

  BPF_ABS        0x20   legacy BPF packet access (absolute)

  BPF_IND        0x40   legacy BPF packet access (indirect)

  BPF_MEM        0x60   regular load and store operations

  BPF_ATOMIC     0xc0   atomic operations

  =============  =====  ====================================





Regular load and store operations

---------------------------------
@@ -256,9 +260,9 @@ that use the ``BPF_ATOMIC`` mode modifier as follows: 
* ``BPF_ATOMIC | BPF_DW | BPF_STX`` for 64-bit operations

* 8-bit and 16-bit wide atomic operations are not supported.



The imm field is used to encode the actual atomic operation.

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:

arithmetic operations in the 'imm' field to encode the atomic operation:



========  =====  ===========

imm       value  description
@@ -270,11 +274,11 @@ arithmetic operations in the imm field to encode the atomic operation: 
========  =====  ===========





``BPF_ATOMIC | BPF_W  | BPF_STX`` with imm = BPF_ADD means::

``BPF_ATOMIC | BPF_W  | BPF_STX`` with 'imm' = BPF_ADD means::



  *(u32 *)(dst_reg + off16) += src_reg



``BPF_ATOMIC | BPF_DW | BPF_STX`` with imm = BPF ADD means::

``BPF_ATOMIC | BPF_DW | BPF_STX`` with 'imm' = BPF ADD means::



  *(u64 *)(dst_reg + off16) += src_reg
@@ -306,7 +310,7 @@ and loaded back to ``R0``. 
64-bit immediate instructions

-----------------------------



Instructions with the ``BPF_IMM`` mode modifier use the wide instruction

Instructions with the ``BPF_IMM`` 'mode' modifier use the wide instruction

encoding for an extra imm64 value.



There is currently only one such instruction.