Documentation/bpf/instruction-set.rst

   1 .. contents::
   2 .. sectnum::
   3
   4 ========================================
   5 eBPF Instruction Set Specification, v1.0
   6 ========================================
   7
   8 This document specifies version 1.0 of the eBPF instruction set.
   9
  10
  11 Registers and calling convention
  12 ================================
  13
  14 eBPF has 10 general purpose registers and a read-only frame pointer register,
  15 all of which are 64-bits wide.
  16
  17 The eBPF calling convention is defined as:
  18
  19 * R0: return value from function calls, and exit value for eBPF programs
  20 * R1 - R5: arguments for function calls
  21 * R6 - R9: callee saved registers that function calls will preserve
  22 * R10: read-only frame pointer to access stack
  23
  24 R0 - R5 are scratch registers and eBPF programs needs to spill/fill them if
  25 necessary across calls.
  26
  27 Instruction encoding
  28 ====================
  29
  30 eBPF has two instruction encodings:
  31
  32 * the basic instruction encoding, which uses 64 bits to encode an instruction
  33 * the wide instruction encoding, which appends a second 64-bit immediate value
  34   (imm64) after the basic instruction for a total of 128 bits.
  35
  36 The basic instruction encoding looks as follows:
  37
  38 =============  =======  ===============  ====================  ============
  39 32 bits (MSB)  16 bits  4 bits           4 bits                8 bits (LSB)
  40 =============  =======  ===============  ====================  ============
  41 immediate      offset   source register  destination register  opcode
  42 =============  =======  ===============  ====================  ============
  43
  44 Note that most instructions do not use all of the fields.
  45 Unused fields shall be cleared to zero.
  46
  47 Instruction classes
  48 -------------------
  49
  50 The three LSB bits of the 'opcode' field store the instruction class:
  51
  52 =========  =====  ===============================  ===================================
  53 class      value  description                      reference
  54 =========  =====  ===============================  ===================================
  55 BPF_LD     0x00   non-standard load operations     `Load and store instructions`_
  56 BPF_LDX    0x01   load into register operations    `Load and store instructions`_
  57 BPF_ST     0x02   store from immediate operations  `Load and store instructions`_
  58 BPF_STX    0x03   store from register operations   `Load and store instructions`_
  59 BPF_ALU    0x04   32-bit arithmetic operations     `Arithmetic and jump instructions`_
  60 BPF_JMP    0x05   64-bit jump operations           `Arithmetic and jump instructions`_
  61 BPF_JMP32  0x06   32-bit jump operations           `Arithmetic and jump instructions`_
  62 BPF_ALU64  0x07   64-bit arithmetic operations     `Arithmetic and jump instructions`_
  63 =========  =====  ===============================  ===================================
  64
  65 Arithmetic and jump instructions
  66 ================================
  67
  68 For arithmetic and jump instructions (``BPF_ALU``, ``BPF_ALU64``, ``BPF_JMP`` and
  69 ``BPF_JMP32``), the 8-bit 'opcode' field is divided into three parts:
  70
  71 ==============  ======  =================
  72 4 bits (MSB)    1 bit   3 bits (LSB)
  73 ==============  ======  =================
  74 operation code  source  instruction class
  75 ==============  ======  =================
  76
  77 The 4th bit encodes the source operand:
  78
  79   ======  =====  ========================================
  80   source  value  description
  81   ======  =====  ========================================
  82   BPF_K   0x00   use 32-bit immediate as source operand
  83   BPF_X   0x08   use 'src_reg' register as source operand
  84   ======  =====  ========================================
  85
  86 The four MSB bits store the operation code.
  87
  88
  89 Arithmetic instructions
  90 -----------------------
  91
  92 ``BPF_ALU`` uses 32-bit wide operands while ``BPF_ALU64`` uses 64-bit wide operands for
  93 otherwise identical operations.
  94 The 'code' field encodes the operation as below:
  95
  96 ========  =====  ==========================================================
  97 code      value  description
  98 ========  =====  ==========================================================
  99 BPF_ADD   0x00   dst += src
 100 BPF_SUB   0x10   dst -= src
 101 BPF_MUL   0x20   dst \*= src
 102 BPF_DIV   0x30   dst /= src
 103 BPF_OR    0x40   dst \|= src
 104 BPF_AND   0x50   dst &= src
 105 BPF_LSH   0x60   dst <<= src
 106 BPF_RSH   0x70   dst >>= src
 107 BPF_NEG   0x80   dst = ~src
 108 BPF_MOD   0x90   dst %= src
 109 BPF_XOR   0xa0   dst ^= src
 110 BPF_MOV   0xb0   dst = src
 111 BPF_ARSH  0xc0   sign extending shift right
 112 BPF_END   0xd0   byte swap operations (see `Byte swap instructions`_ below)
 113 ========  =====  ==========================================================
 114
 115 ``BPF_ADD | BPF_X | BPF_ALU`` means::
 116
 117   dst_reg = (u32) dst_reg + (u32) src_reg;
 118
 119 ``BPF_ADD | BPF_X | BPF_ALU64`` means::
 120
 121   dst_reg = dst_reg + src_reg
 122
 123 ``BPF_XOR | BPF_K | BPF_ALU`` means::
 124
 125   src_reg = (u32) src_reg ^ (u32) imm32
 126
 127 ``BPF_XOR | BPF_K | BPF_ALU64`` means::
 128
 129   src_reg = src_reg ^ imm32
 130
 131
 132 Byte swap instructions
 133 ~~~~~~~~~~~~~~~~~~~~~~
 134
 135 The byte swap instructions use an instruction class of ``BPF_ALU`` and a 4-bit
 136 'code' field of ``BPF_END``.
 137
 138 The byte swap instructions operate on the destination register
 139 only and do not use a separate source register or immediate value.
 140
 141 The 1-bit source operand field in the opcode is used to select what byte
 142 order the operation convert from or to:
 143
 144 =========  =====  =================================================
 145 source     value  description
 146 =========  =====  =================================================
 147 BPF_TO_LE  0x00   convert between host byte order and little endian
 148 BPF_TO_BE  0x08   convert between host byte order and big endian
 149 =========  =====  =================================================
 150
 151 The 'imm' field encodes the width of the swap operations.  The following widths
 152 are supported: 16, 32 and 64.
 153
 154 Examples:
 155
 156 ``BPF_ALU | BPF_TO_LE | BPF_END`` with imm = 16 means::
 157
 158   dst_reg = htole16(dst_reg)
 159
 160 ``BPF_ALU | BPF_TO_BE | BPF_END`` with imm = 64 means::
 161
 162   dst_reg = htobe64(dst_reg)
 163
 164 Jump instructions
 165 -----------------
 166
 167 ``BPF_JMP32`` uses 32-bit wide operands while ``BPF_JMP`` uses 64-bit wide operands for
 168 otherwise identical operations.
 169 The 'code' field encodes the operation as below:
 170
 171 ========  =====  =========================  ============
 172 code      value  description                notes
 173 ========  =====  =========================  ============
 174 BPF_JA    0x00   PC += off                  BPF_JMP only
 175 BPF_JEQ   0x10   PC += off if dst == src
 176 BPF_JGT   0x20   PC += off if dst > src     unsigned
 177 BPF_JGE   0x30   PC += off if dst >= src    unsigned
 178 BPF_JSET  0x40   PC += off if dst & src
 179 BPF_JNE   0x50   PC += off if dst != src
 180 BPF_JSGT  0x60   PC += off if dst > src     signed
 181 BPF_JSGE  0x70   PC += off if dst >= src    signed
 182 BPF_CALL  0x80   function call
 183 BPF_EXIT  0x90   function / program return  BPF_JMP only
 184 BPF_JLT   0xa0   PC += off if dst < src     unsigned
 185 BPF_JLE   0xb0   PC += off if dst <= src    unsigned
 186 BPF_JSLT  0xc0   PC += off if dst < src     signed
 187 BPF_JSLE  0xd0   PC += off if dst <= src    signed
 188 ========  =====  =========================  ============
 189
 190 The eBPF program needs to store the return value into register R0 before doing a
 191 BPF_EXIT.
 192
 193
 194 Load and store instructions
 195 ===========================
 196
 197 For load and store instructions (``BPF_LD``, ``BPF_LDX``, ``BPF_ST``, and ``BPF_STX``), the
 198 8-bit 'opcode' field is divided as:
 199
 200 ============  ======  =================
 201 3 bits (MSB)  2 bits  3 bits (LSB)
 202 ============  ======  =================
 203 mode          size    instruction class
 204 ============  ======  =================
 205
 206 The mode modifier is one of:
 207
 208   =============  =====  ====================================  =============
 209   mode modifier  value  description                           reference
 210   =============  =====  ====================================  =============
 211   BPF_IMM        0x00   64-bit immediate instructions         `64-bit immediate instructions`_
 212   BPF_ABS        0x20   legacy BPF packet access (absolute)   `Legacy BPF Packet access instructions`_
 213   BPF_IND        0x40   legacy BPF packet access (indirect)   `Legacy BPF Packet access instructions`_
 214   BPF_MEM        0x60   regular load and store operations     `Regular load and store operations`_
 215   BPF_ATOMIC     0xc0   atomic operations                     `Atomic operations`_
 216   =============  =====  ====================================  =============
 217
 218 The size modifier is one of:
 219
 220   =============  =====  =====================
 221   size modifier  value  description
 222   =============  =====  =====================
 223   BPF_W          0x00   word        (4 bytes)
 224   BPF_H          0x08   half word   (2 bytes)
 225   BPF_B          0x10   byte
 226   BPF_DW         0x18   double word (8 bytes)
 227   =============  =====  =====================
 228
 229 Regular load and store operations
 230 ---------------------------------
 231
 232 The ``BPF_MEM`` mode modifier is used to encode regular load and store
 233 instructions that transfer data between a register and memory.
 234
 235 ``BPF_MEM | <size> | BPF_STX`` means::
 236
 237   *(size *) (dst_reg + off) = src_reg
 238
 239 ``BPF_MEM | <size> | BPF_ST`` means::
 240
 241   *(size *) (dst_reg + off) = imm32
 242
 243 ``BPF_MEM | <size> | BPF_LDX`` means::
 244
 245   dst_reg = *(size *) (src_reg + off)
 246
 247 Where size is one of: ``BPF_B``, ``BPF_H``, ``BPF_W``, or ``BPF_DW``.
 248
 249 Atomic operations
 250 -----------------
 251
 252 Atomic operations are operations that operate on memory and can not be
 253 interrupted or corrupted by other access to the same memory region
 254 by other eBPF programs or means outside of this specification.
 255
 256 All atomic operations supported by eBPF are encoded as store operations
 257 that use the ``BPF_ATOMIC`` mode modifier as follows:
 258
 259 * ``BPF_ATOMIC | BPF_W | BPF_STX`` for 32-bit operations
 260 * ``BPF_ATOMIC | BPF_DW | BPF_STX`` for 64-bit operations
 261 * 8-bit and 16-bit wide atomic operations are not supported.
 262
 263 The 'imm' field is used to encode the actual atomic operation.
 264 Simple atomic operation use a subset of the values defined to encode
 265 arithmetic operations in the 'imm' field to encode the atomic operation:
 266
 267 ========  =====  ===========
 268 imm       value  description
 269 ========  =====  ===========
 270 BPF_ADD   0x00   atomic add
 271 BPF_OR    0x40   atomic or
 272 BPF_AND   0x50   atomic and
 273 BPF_XOR   0xa0   atomic xor
 274 ========  =====  ===========
 275
 276
 277 ``BPF_ATOMIC | BPF_W  | BPF_STX`` with 'imm' = BPF_ADD means::
 278
 279   *(u32 *)(dst_reg + off16) += src_reg
 280
 281 ``BPF_ATOMIC | BPF_DW | BPF_STX`` with 'imm' = BPF ADD means::
 282
 283   *(u64 *)(dst_reg + off16) += src_reg
 284
 285 In addition to the simple atomic operations, there also is a modifier and
 286 two complex atomic operations:
 287
 288 ===========  ================  ===========================
 289 imm          value             description
 290 ===========  ================  ===========================
 291 BPF_FETCH    0x01              modifier: return old value
 292 BPF_XCHG     0xe0 | BPF_FETCH  atomic exchange
 293 BPF_CMPXCHG  0xf0 | BPF_FETCH  atomic compare and exchange
 294 ===========  ================  ===========================
 295
 296 The ``BPF_FETCH`` modifier is optional for simple atomic operations, and
 297 always set for the complex atomic operations.  If the ``BPF_FETCH`` flag
 298 is set, then the operation also overwrites ``src_reg`` with the value that
 299 was in memory before it was modified.
 300
 301 The ``BPF_XCHG`` operation atomically exchanges ``src_reg`` with the value
 302 addressed by ``dst_reg + off``.
 303
 304 The ``BPF_CMPXCHG`` operation atomically compares the value addressed by
 305 ``dst_reg + off`` with ``R0``. If they match, the value addressed by
 306 ``dst_reg + off`` is replaced with ``src_reg``. In either case, the
 307 value that was at ``dst_reg + off`` before the operation is zero-extended
 308 and loaded back to ``R0``.
 309
 310 64-bit immediate instructions
 311 -----------------------------
 312
 313 Instructions with the ``BPF_IMM`` 'mode' modifier use the wide instruction
 314 encoding for an extra imm64 value.
 315
 316 There is currently only one such instruction.
 317
 318 ``BPF_LD | BPF_DW | BPF_IMM`` means::
 319
 320   dst_reg = imm64
 321
 322
 323 Legacy BPF Packet access instructions
 324 -------------------------------------
 325
 326 eBPF previously introduced special instructions for access to packet data that were
 327 carried over from classic BPF. However, these instructions are
 328 deprecated and should no longer be used.