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 != 0) ? (dst / src) : 0
 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 != 0) ? (dst % src) : dst
 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 Underflow and overflow are allowed during arithmetic operations, meaning
 116 the 64-bit or 32-bit value will wrap. If eBPF program execution would
 117 result in division by zero, the destination register is instead set to zero.
 118 If execution would result in modulo by zero, for ``BPF_ALU64`` the value of
 119 the destination register is unchanged whereas for ``BPF_ALU`` the upper
 120 32 bits of the destination register are zeroed.
 121
 122 ``BPF_ADD | BPF_X | BPF_ALU`` means::
 123
 124   dst_reg = (u32) dst_reg + (u32) src_reg;
 125
 126 ``BPF_ADD | BPF_X | BPF_ALU64`` means::
 127
 128   dst_reg = dst_reg + src_reg
 129
 130 ``BPF_XOR | BPF_K | BPF_ALU`` means::
 131
 132   src_reg = (u32) src_reg ^ (u32) imm32
 133
 134 ``BPF_XOR | BPF_K | BPF_ALU64`` means::
 135
 136   src_reg = src_reg ^ imm32
 137
 138 Also note that the division and modulo operations are unsigned. Thus, for
 139 ``BPF_ALU``, 'imm' is first interpreted as an unsigned 32-bit value, whereas
 140 for ``BPF_ALU64``, 'imm' is first sign extended to 64 bits and the result
 141 interpreted as an unsigned 64-bit value. There are no instructions for
 142 signed division or modulo.
 143
 144 Byte swap instructions
 145 ~~~~~~~~~~~~~~~~~~~~~~
 146
 147 The byte swap instructions use an instruction class of ``BPF_ALU`` and a 4-bit
 148 'code' field of ``BPF_END``.
 149
 150 The byte swap instructions operate on the destination register
 151 only and do not use a separate source register or immediate value.
 152
 153 The 1-bit source operand field in the opcode is used to select what byte
 154 order the operation convert from or to:
 155
 156 =========  =====  =================================================
 157 source     value  description
 158 =========  =====  =================================================
 159 BPF_TO_LE  0x00   convert between host byte order and little endian
 160 BPF_TO_BE  0x08   convert between host byte order and big endian
 161 =========  =====  =================================================
 162
 163 The 'imm' field encodes the width of the swap operations.  The following widths
 164 are supported: 16, 32 and 64.
 165
 166 Examples:
 167
 168 ``BPF_ALU | BPF_TO_LE | BPF_END`` with imm = 16 means::
 169
 170   dst_reg = htole16(dst_reg)
 171
 172 ``BPF_ALU | BPF_TO_BE | BPF_END`` with imm = 64 means::
 173
 174   dst_reg = htobe64(dst_reg)
 175
 176 Jump instructions
 177 -----------------
 178
 179 ``BPF_JMP32`` uses 32-bit wide operands while ``BPF_JMP`` uses 64-bit wide operands for
 180 otherwise identical operations.
 181 The 'code' field encodes the operation as below:
 182
 183 ========  =====  =========================  ============
 184 code      value  description                notes
 185 ========  =====  =========================  ============
 186 BPF_JA    0x00   PC += off                  BPF_JMP only
 187 BPF_JEQ   0x10   PC += off if dst == src
 188 BPF_JGT   0x20   PC += off if dst > src     unsigned
 189 BPF_JGE   0x30   PC += off if dst >= src    unsigned
 190 BPF_JSET  0x40   PC += off if dst & src
 191 BPF_JNE   0x50   PC += off if dst != src
 192 BPF_JSGT  0x60   PC += off if dst > src     signed
 193 BPF_JSGE  0x70   PC += off if dst >= src    signed
 194 BPF_CALL  0x80   function call
 195 BPF_EXIT  0x90   function / program return  BPF_JMP only
 196 BPF_JLT   0xa0   PC += off if dst < src     unsigned
 197 BPF_JLE   0xb0   PC += off if dst <= src    unsigned
 198 BPF_JSLT  0xc0   PC += off if dst < src     signed
 199 BPF_JSLE  0xd0   PC += off if dst <= src    signed
 200 ========  =====  =========================  ============
 201
 202 The eBPF program needs to store the return value into register R0 before doing a
 203 BPF_EXIT.
 204
 205
 206 Load and store instructions
 207 ===========================
 208
 209 For load and store instructions (``BPF_LD``, ``BPF_LDX``, ``BPF_ST``, and ``BPF_STX``), the
 210 8-bit 'opcode' field is divided as:
 211
 212 ============  ======  =================
 213 3 bits (MSB)  2 bits  3 bits (LSB)
 214 ============  ======  =================
 215 mode          size    instruction class
 216 ============  ======  =================
 217
 218 The mode modifier is one of:
 219
 220   =============  =====  ====================================  =============
 221   mode modifier  value  description                           reference
 222   =============  =====  ====================================  =============
 223   BPF_IMM        0x00   64-bit immediate instructions         `64-bit immediate instructions`_
 224   BPF_ABS        0x20   legacy BPF packet access (absolute)   `Legacy BPF Packet access instructions`_
 225   BPF_IND        0x40   legacy BPF packet access (indirect)   `Legacy BPF Packet access instructions`_
 226   BPF_MEM        0x60   regular load and store operations     `Regular load and store operations`_
 227   BPF_ATOMIC     0xc0   atomic operations                     `Atomic operations`_
 228   =============  =====  ====================================  =============
 229
 230 The size modifier is one of:
 231
 232   =============  =====  =====================
 233   size modifier  value  description
 234   =============  =====  =====================
 235   BPF_W          0x00   word        (4 bytes)
 236   BPF_H          0x08   half word   (2 bytes)
 237   BPF_B          0x10   byte
 238   BPF_DW         0x18   double word (8 bytes)
 239   =============  =====  =====================
 240
 241 Regular load and store operations
 242 ---------------------------------
 243
 244 The ``BPF_MEM`` mode modifier is used to encode regular load and store
 245 instructions that transfer data between a register and memory.
 246
 247 ``BPF_MEM | <size> | BPF_STX`` means::
 248
 249   *(size *) (dst_reg + off) = src_reg
 250
 251 ``BPF_MEM | <size> | BPF_ST`` means::
 252
 253   *(size *) (dst_reg + off) = imm32
 254
 255 ``BPF_MEM | <size> | BPF_LDX`` means::
 256
 257   dst_reg = *(size *) (src_reg + off)
 258
 259 Where size is one of: ``BPF_B``, ``BPF_H``, ``BPF_W``, or ``BPF_DW``.
 260
 261 Atomic operations
 262 -----------------
 263
 264 Atomic operations are operations that operate on memory and can not be
 265 interrupted or corrupted by other access to the same memory region
 266 by other eBPF programs or means outside of this specification.
 267
 268 All atomic operations supported by eBPF are encoded as store operations
 269 that use the ``BPF_ATOMIC`` mode modifier as follows:
 270
 271 * ``BPF_ATOMIC | BPF_W | BPF_STX`` for 32-bit operations
 272 * ``BPF_ATOMIC | BPF_DW | BPF_STX`` for 64-bit operations
 273 * 8-bit and 16-bit wide atomic operations are not supported.
 274
 275 The 'imm' field is used to encode the actual atomic operation.
 276 Simple atomic operation use a subset of the values defined to encode
 277 arithmetic operations in the 'imm' field to encode the atomic operation:
 278
 279 ========  =====  ===========
 280 imm       value  description
 281 ========  =====  ===========
 282 BPF_ADD   0x00   atomic add
 283 BPF_OR    0x40   atomic or
 284 BPF_AND   0x50   atomic and
 285 BPF_XOR   0xa0   atomic xor
 286 ========  =====  ===========
 287
 288
 289 ``BPF_ATOMIC | BPF_W  | BPF_STX`` with 'imm' = BPF_ADD means::
 290
 291   *(u32 *)(dst_reg + off16) += src_reg
 292
 293 ``BPF_ATOMIC | BPF_DW | BPF_STX`` with 'imm' = BPF ADD means::
 294
 295   *(u64 *)(dst_reg + off16) += src_reg
 296
 297 In addition to the simple atomic operations, there also is a modifier and
 298 two complex atomic operations:
 299
 300 ===========  ================  ===========================
 301 imm          value             description
 302 ===========  ================  ===========================
 303 BPF_FETCH    0x01              modifier: return old value
 304 BPF_XCHG     0xe0 | BPF_FETCH  atomic exchange
 305 BPF_CMPXCHG  0xf0 | BPF_FETCH  atomic compare and exchange
 306 ===========  ================  ===========================
 307
 308 The ``BPF_FETCH`` modifier is optional for simple atomic operations, and
 309 always set for the complex atomic operations.  If the ``BPF_FETCH`` flag
 310 is set, then the operation also overwrites ``src_reg`` with the value that
 311 was in memory before it was modified.
 312
 313 The ``BPF_XCHG`` operation atomically exchanges ``src_reg`` with the value
 314 addressed by ``dst_reg + off``.
 315
 316 The ``BPF_CMPXCHG`` operation atomically compares the value addressed by
 317 ``dst_reg + off`` with ``R0``. If they match, the value addressed by
 318 ``dst_reg + off`` is replaced with ``src_reg``. In either case, the
 319 value that was at ``dst_reg + off`` before the operation is zero-extended
 320 and loaded back to ``R0``.
 321
 322 64-bit immediate instructions
 323 -----------------------------
 324
 325 Instructions with the ``BPF_IMM`` 'mode' modifier use the wide instruction
 326 encoding for an extra imm64 value.
 327
 328 There is currently only one such instruction.
 329
 330 ``BPF_LD | BPF_DW | BPF_IMM`` means::
 331
 332   dst_reg = imm64
 333
 334
 335 Legacy BPF Packet access instructions
 336 -------------------------------------
 337
 338 eBPF previously introduced special instructions for access to packet data that were
 339 carried over from classic BPF. However, these instructions are
 340 deprecated and should no longer be used.