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 Documentation conventions
  11 =========================
  12
  13 For brevity, this document uses the type notion "u64", "u32", etc.
  14 to mean an unsigned integer whose width is the specified number of bits,
  15 and "s32", etc. to mean a signed integer of the specified number of bits.
  16
  17 Registers and calling convention
  18 ================================
  19
  20 eBPF has 10 general purpose registers and a read-only frame pointer register,
  21 all of which are 64-bits wide.
  22
  23 The eBPF calling convention is defined as:
  24
  25 * R0: return value from function calls, and exit value for eBPF programs
  26 * R1 - R5: arguments for function calls
  27 * R6 - R9: callee saved registers that function calls will preserve
  28 * R10: read-only frame pointer to access stack
  29
  30 R0 - R5 are scratch registers and eBPF programs needs to spill/fill them if
  31 necessary across calls.
  32
  33 Instruction encoding
  34 ====================
  35
  36 eBPF has two instruction encodings:
  37
  38 * the basic instruction encoding, which uses 64 bits to encode an instruction
  39 * the wide instruction encoding, which appends a second 64-bit immediate (i.e.,
  40   constant) value after the basic instruction for a total of 128 bits.
  41
  42 The fields conforming an encoded basic instruction are stored in the
  43 following order::
  44
  45   opcode:8 src_reg:4 dst_reg:4 offset:16 imm:32 // In little-endian BPF.
  46   opcode:8 dst_reg:4 src_reg:4 offset:16 imm:32 // In big-endian BPF.
  47
  48 **imm**
  49   signed integer immediate value
  50
  51 **offset**
  52   signed integer offset used with pointer arithmetic
  53
  54 **src_reg**
  55   the source register number (0-10), except where otherwise specified
  56   (`64-bit immediate instructions`_ reuse this field for other purposes)
  57
  58 **dst_reg**
  59   destination register number (0-10)
  60
  61 **opcode**
  62   operation to perform
  63
  64 Note that the contents of multi-byte fields ('imm' and 'offset') are
  65 stored using big-endian byte ordering in big-endian BPF and
  66 little-endian byte ordering in little-endian BPF.
  67
  68 For example::
  69
  70   opcode                  offset imm          assembly
  71          src_reg dst_reg
  72   07     0       1        00 00  44 33 22 11  r1 += 0x11223344 // little
  73          dst_reg src_reg
  74   07     1       0        00 00  11 22 33 44  r1 += 0x11223344 // big
  75
  76 Note that most instructions do not use all of the fields.
  77 Unused fields shall be cleared to zero.
  78
  79 As discussed below in `64-bit immediate instructions`_, a 64-bit immediate
  80 instruction uses a 64-bit immediate value that is constructed as follows.
  81 The 64 bits following the basic instruction contain a pseudo instruction
  82 using the same format but with opcode, dst_reg, src_reg, and offset all set to zero,
  83 and imm containing the high 32 bits of the immediate value.
  84
  85 This is depicted in the following figure::
  86
  87         basic_instruction
  88   .-----------------------------.
  89   |                             |
  90   code:8 regs:8 offset:16 imm:32 unused:32 imm:32
  91                                  |              |
  92                                  '--------------'
  93                                 pseudo instruction
  94
  95 Thus the 64-bit immediate value is constructed as follows:
  96
  97   imm64 = (next_imm << 32) | imm
  98
  99 where 'next_imm' refers to the imm value of the pseudo instruction
 100 following the basic instruction.  The unused bytes in the pseudo
 101 instruction are reserved and shall be cleared to zero.
 102
 103 Instruction classes
 104 -------------------
 105
 106 The three LSB bits of the 'opcode' field store the instruction class:
 107
 108 =========  =====  ===============================  ===================================
 109 class      value  description                      reference
 110 =========  =====  ===============================  ===================================
 111 BPF_LD     0x00   non-standard load operations     `Load and store instructions`_
 112 BPF_LDX    0x01   load into register operations    `Load and store instructions`_
 113 BPF_ST     0x02   store from immediate operations  `Load and store instructions`_
 114 BPF_STX    0x03   store from register operations   `Load and store instructions`_
 115 BPF_ALU    0x04   32-bit arithmetic operations     `Arithmetic and jump instructions`_
 116 BPF_JMP    0x05   64-bit jump operations           `Arithmetic and jump instructions`_
 117 BPF_JMP32  0x06   32-bit jump operations           `Arithmetic and jump instructions`_
 118 BPF_ALU64  0x07   64-bit arithmetic operations     `Arithmetic and jump instructions`_
 119 =========  =====  ===============================  ===================================
 120
 121 Arithmetic and jump instructions
 122 ================================
 123
 124 For arithmetic and jump instructions (``BPF_ALU``, ``BPF_ALU64``, ``BPF_JMP`` and
 125 ``BPF_JMP32``), the 8-bit 'opcode' field is divided into three parts:
 126
 127 ==============  ======  =================
 128 4 bits (MSB)    1 bit   3 bits (LSB)
 129 ==============  ======  =================
 130 code            source  instruction class
 131 ==============  ======  =================
 132
 133 **code**
 134   the operation code, whose meaning varies by instruction class
 135
 136 **source**
 137   the source operand location, which unless otherwise specified is one of:
 138
 139   ======  =====  ==============================================
 140   source  value  description
 141   ======  =====  ==============================================
 142   BPF_K   0x00   use 32-bit 'imm' value as source operand
 143   BPF_X   0x08   use 'src_reg' register value as source operand
 144   ======  =====  ==============================================
 145
 146 **instruction class**
 147   the instruction class (see `Instruction classes`_)
 148
 149 Arithmetic instructions
 150 -----------------------
 151
 152 ``BPF_ALU`` uses 32-bit wide operands while ``BPF_ALU64`` uses 64-bit wide operands for
 153 otherwise identical operations.
 154 The 'code' field encodes the operation as below, where 'src' and 'dst' refer
 155 to the values of the source and destination registers, respectively.
 156
 157 ========  =====  ==========================================================
 158 code      value  description
 159 ========  =====  ==========================================================
 160 BPF_ADD   0x00   dst += src
 161 BPF_SUB   0x10   dst -= src
 162 BPF_MUL   0x20   dst \*= src
 163 BPF_DIV   0x30   dst = (src != 0) ? (dst / src) : 0
 164 BPF_OR    0x40   dst \|= src
 165 BPF_AND   0x50   dst &= src
 166 BPF_LSH   0x60   dst <<= src
 167 BPF_RSH   0x70   dst >>= src
 168 BPF_NEG   0x80   dst = ~src
 169 BPF_MOD   0x90   dst = (src != 0) ? (dst % src) : dst
 170 BPF_XOR   0xa0   dst ^= src
 171 BPF_MOV   0xb0   dst = src
 172 BPF_ARSH  0xc0   sign extending shift right
 173 BPF_END   0xd0   byte swap operations (see `Byte swap instructions`_ below)
 174 ========  =====  ==========================================================
 175
 176 Underflow and overflow are allowed during arithmetic operations, meaning
 177 the 64-bit or 32-bit value will wrap. If eBPF program execution would
 178 result in division by zero, the destination register is instead set to zero.
 179 If execution would result in modulo by zero, for ``BPF_ALU64`` the value of
 180 the destination register is unchanged whereas for ``BPF_ALU`` the upper
 181 32 bits of the destination register are zeroed.
 182
 183 ``BPF_ADD | BPF_X | BPF_ALU`` means::
 184
 185   dst = (u32) ((u32) dst + (u32) src)
 186
 187 where '(u32)' indicates that the upper 32 bits are zeroed.
 188
 189 ``BPF_ADD | BPF_X | BPF_ALU64`` means::
 190
 191   dst = dst + src
 192
 193 ``BPF_XOR | BPF_K | BPF_ALU`` means::
 194
 195   dst = (u32) dst ^ (u32) imm32
 196
 197 ``BPF_XOR | BPF_K | BPF_ALU64`` means::
 198
 199   dst = dst ^ imm32
 200
 201 Also note that the division and modulo operations are unsigned. Thus, for
 202 ``BPF_ALU``, 'imm' is first interpreted as an unsigned 32-bit value, whereas
 203 for ``BPF_ALU64``, 'imm' is first sign extended to 64 bits and the result
 204 interpreted as an unsigned 64-bit value. There are no instructions for
 205 signed division or modulo.
 206
 207 Byte swap instructions
 208 ~~~~~~~~~~~~~~~~~~~~~~
 209
 210 The byte swap instructions use an instruction class of ``BPF_ALU`` and a 4-bit
 211 'code' field of ``BPF_END``.
 212
 213 The byte swap instructions operate on the destination register
 214 only and do not use a separate source register or immediate value.
 215
 216 The 1-bit source operand field in the opcode is used to select what byte
 217 order the operation convert from or to:
 218
 219 =========  =====  =================================================
 220 source     value  description
 221 =========  =====  =================================================
 222 BPF_TO_LE  0x00   convert between host byte order and little endian
 223 BPF_TO_BE  0x08   convert between host byte order and big endian
 224 =========  =====  =================================================
 225
 226 The 'imm' field encodes the width of the swap operations.  The following widths
 227 are supported: 16, 32 and 64.
 228
 229 Examples:
 230
 231 ``BPF_ALU | BPF_TO_LE | BPF_END`` with imm = 16 means::
 232
 233   dst = htole16(dst)
 234
 235 ``BPF_ALU | BPF_TO_BE | BPF_END`` with imm = 64 means::
 236
 237   dst = htobe64(dst)
 238
 239 Jump instructions
 240 -----------------
 241
 242 ``BPF_JMP32`` uses 32-bit wide operands while ``BPF_JMP`` uses 64-bit wide operands for
 243 otherwise identical operations.
 244 The 'code' field encodes the operation as below:
 245
 246 ========  =====  ===  ===========================================  =========================================
 247 code      value  src  description                                  notes
 248 ========  =====  ===  ===========================================  =========================================
 249 BPF_JA    0x0    0x0  PC += offset                                 BPF_JMP only
 250 BPF_JEQ   0x1    any  PC += offset if dst == src
 251 BPF_JGT   0x2    any  PC += offset if dst > src                    unsigned
 252 BPF_JGE   0x3    any  PC += offset if dst >= src                   unsigned
 253 BPF_JSET  0x4    any  PC += offset if dst & src
 254 BPF_JNE   0x5    any  PC += offset if dst != src
 255 BPF_JSGT  0x6    any  PC += offset if dst > src                    signed
 256 BPF_JSGE  0x7    any  PC += offset if dst >= src                   signed
 257 BPF_CALL  0x8    0x0  call helper function by address              see `Helper functions`_
 258 BPF_CALL  0x8    0x1  call PC += offset                            see `Program-local functions`_
 259 BPF_CALL  0x8    0x2  call helper function by BTF ID               see `Helper functions`_
 260 BPF_EXIT  0x9    0x0  return                                       BPF_JMP only
 261 BPF_JLT   0xa    any  PC += offset if dst < src                    unsigned
 262 BPF_JLE   0xb    any  PC += offset if dst <= src                   unsigned
 263 BPF_JSLT  0xc    any  PC += offset if dst < src                    signed
 264 BPF_JSLE  0xd    any  PC += offset if dst <= src                   signed
 265 ========  =====  ===  ===========================================  =========================================
 266
 267 The eBPF program needs to store the return value into register R0 before doing a
 268 ``BPF_EXIT``.
 269
 270 Example:
 271
 272 ``BPF_JSGE | BPF_X | BPF_JMP32`` (0x7e) means::
 273
 274   if (s32)dst s>= (s32)src goto +offset
 275
 276 where 's>=' indicates a signed '>=' comparison.
 277
 278 Helper functions
 279 ~~~~~~~~~~~~~~~~
 280
 281 Helper functions are a concept whereby BPF programs can call into a
 282 set of function calls exposed by the underlying platform.
 283
 284 Historically, each helper function was identified by an address
 285 encoded in the imm field.  The available helper functions may differ
 286 for each program type, but address values are unique across all program types.
 287
 288 Platforms that support the BPF Type Format (BTF) support identifying
 289 a helper function by a BTF ID encoded in the imm field, where the BTF ID
 290 identifies the helper name and type.
 291
 292 Program-local functions
 293 ~~~~~~~~~~~~~~~~~~~~~~~
 294 Program-local functions are functions exposed by the same BPF program as the
 295 caller, and are referenced by offset from the call instruction, similar to
 296 ``BPF_JA``.  A ``BPF_EXIT`` within the program-local function will return to
 297 the caller.
 298
 299 Load and store instructions
 300 ===========================
 301
 302 For load and store instructions (``BPF_LD``, ``BPF_LDX``, ``BPF_ST``, and ``BPF_STX``), the
 303 8-bit 'opcode' field is divided as:
 304
 305 ============  ======  =================
 306 3 bits (MSB)  2 bits  3 bits (LSB)
 307 ============  ======  =================
 308 mode          size    instruction class
 309 ============  ======  =================
 310
 311 The mode modifier is one of:
 312
 313   =============  =====  ====================================  =============
 314   mode modifier  value  description                           reference
 315   =============  =====  ====================================  =============
 316   BPF_IMM        0x00   64-bit immediate instructions         `64-bit immediate instructions`_
 317   BPF_ABS        0x20   legacy BPF packet access (absolute)   `Legacy BPF Packet access instructions`_
 318   BPF_IND        0x40   legacy BPF packet access (indirect)   `Legacy BPF Packet access instructions`_
 319   BPF_MEM        0x60   regular load and store operations     `Regular load and store operations`_
 320   BPF_ATOMIC     0xc0   atomic operations                     `Atomic operations`_
 321   =============  =====  ====================================  =============
 322
 323 The size modifier is one of:
 324
 325   =============  =====  =====================
 326   size modifier  value  description
 327   =============  =====  =====================
 328   BPF_W          0x00   word        (4 bytes)
 329   BPF_H          0x08   half word   (2 bytes)
 330   BPF_B          0x10   byte
 331   BPF_DW         0x18   double word (8 bytes)
 332   =============  =====  =====================
 333
 334 Regular load and store operations
 335 ---------------------------------
 336
 337 The ``BPF_MEM`` mode modifier is used to encode regular load and store
 338 instructions that transfer data between a register and memory.
 339
 340 ``BPF_MEM | <size> | BPF_STX`` means::
 341
 342   *(size *) (dst + offset) = src
 343
 344 ``BPF_MEM | <size> | BPF_ST`` means::
 345
 346   *(size *) (dst + offset) = imm32
 347
 348 ``BPF_MEM | <size> | BPF_LDX`` means::
 349
 350   dst = *(size *) (src + offset)
 351
 352 Where size is one of: ``BPF_B``, ``BPF_H``, ``BPF_W``, or ``BPF_DW``.
 353
 354 Atomic operations
 355 -----------------
 356
 357 Atomic operations are operations that operate on memory and can not be
 358 interrupted or corrupted by other access to the same memory region
 359 by other eBPF programs or means outside of this specification.
 360
 361 All atomic operations supported by eBPF are encoded as store operations
 362 that use the ``BPF_ATOMIC`` mode modifier as follows:
 363
 364 * ``BPF_ATOMIC | BPF_W | BPF_STX`` for 32-bit operations
 365 * ``BPF_ATOMIC | BPF_DW | BPF_STX`` for 64-bit operations
 366 * 8-bit and 16-bit wide atomic operations are not supported.
 367
 368 The 'imm' field is used to encode the actual atomic operation.
 369 Simple atomic operation use a subset of the values defined to encode
 370 arithmetic operations in the 'imm' field to encode the atomic operation:
 371
 372 ========  =====  ===========
 373 imm       value  description
 374 ========  =====  ===========
 375 BPF_ADD   0x00   atomic add
 376 BPF_OR    0x40   atomic or
 377 BPF_AND   0x50   atomic and
 378 BPF_XOR   0xa0   atomic xor
 379 ========  =====  ===========
 380
 381
 382 ``BPF_ATOMIC | BPF_W  | BPF_STX`` with 'imm' = BPF_ADD means::
 383
 384   *(u32 *)(dst + offset) += src
 385
 386 ``BPF_ATOMIC | BPF_DW | BPF_STX`` with 'imm' = BPF ADD means::
 387
 388   *(u64 *)(dst + offset) += src
 389
 390 In addition to the simple atomic operations, there also is a modifier and
 391 two complex atomic operations:
 392
 393 ===========  ================  ===========================
 394 imm          value             description
 395 ===========  ================  ===========================
 396 BPF_FETCH    0x01              modifier: return old value
 397 BPF_XCHG     0xe0 | BPF_FETCH  atomic exchange
 398 BPF_CMPXCHG  0xf0 | BPF_FETCH  atomic compare and exchange
 399 ===========  ================  ===========================
 400
 401 The ``BPF_FETCH`` modifier is optional for simple atomic operations, and
 402 always set for the complex atomic operations.  If the ``BPF_FETCH`` flag
 403 is set, then the operation also overwrites ``src`` with the value that
 404 was in memory before it was modified.
 405
 406 The ``BPF_XCHG`` operation atomically exchanges ``src`` with the value
 407 addressed by ``dst + offset``.
 408
 409 The ``BPF_CMPXCHG`` operation atomically compares the value addressed by
 410 ``dst + offset`` with ``R0``. If they match, the value addressed by
 411 ``dst + offset`` is replaced with ``src``. In either case, the
 412 value that was at ``dst + offset`` before the operation is zero-extended
 413 and loaded back to ``R0``.
 414
 415 64-bit immediate instructions
 416 -----------------------------
 417
 418 Instructions with the ``BPF_IMM`` 'mode' modifier use the wide instruction
 419 encoding defined in `Instruction encoding`_, and use the 'src' field of the
 420 basic instruction to hold an opcode subtype.
 421
 422 The following table defines a set of ``BPF_IMM | BPF_DW | BPF_LD`` instructions
 423 with opcode subtypes in the 'src' field, using new terms such as "map"
 424 defined further below:
 425
 426 =========================  ======  ===  =========================================  ===========  ==============
 427 opcode construction        opcode  src  pseudocode                                 imm type     dst type
 428 =========================  ======  ===  =========================================  ===========  ==============
 429 BPF_IMM | BPF_DW | BPF_LD  0x18    0x0  dst = imm64                                integer      integer
 430 BPF_IMM | BPF_DW | BPF_LD  0x18    0x1  dst = map_by_fd(imm)                       map fd       map
 431 BPF_IMM | BPF_DW | BPF_LD  0x18    0x2  dst = map_val(map_by_fd(imm)) + next_imm   map fd       data pointer
 432 BPF_IMM | BPF_DW | BPF_LD  0x18    0x3  dst = var_addr(imm)                        variable id  data pointer
 433 BPF_IMM | BPF_DW | BPF_LD  0x18    0x4  dst = code_addr(imm)                       integer      code pointer
 434 BPF_IMM | BPF_DW | BPF_LD  0x18    0x5  dst = map_by_idx(imm)                      map index    map
 435 BPF_IMM | BPF_DW | BPF_LD  0x18    0x6  dst = map_val(map_by_idx(imm)) + next_imm  map index    data pointer
 436 =========================  ======  ===  =========================================  ===========  ==============
 437
 438 where
 439
 440 * map_by_fd(imm) means to convert a 32-bit file descriptor into an address of a map (see `Maps`_)
 441 * map_by_idx(imm) means to convert a 32-bit index into an address of a map
 442 * map_val(map) gets the address of the first value in a given map
 443 * var_addr(imm) gets the address of a platform variable (see `Platform Variables`_) with a given id
 444 * code_addr(imm) gets the address of the instruction at a specified relative offset in number of (64-bit) instructions
 445 * the 'imm type' can be used by disassemblers for display
 446 * the 'dst type' can be used for verification and JIT compilation purposes
 447
 448 Maps
 449 ~~~~
 450
 451 Maps are shared memory regions accessible by eBPF programs on some platforms.
 452 A map can have various semantics as defined in a separate document, and may or
 453 may not have a single contiguous memory region, but the 'map_val(map)' is
 454 currently only defined for maps that do have a single contiguous memory region.
 455
 456 Each map can have a file descriptor (fd) if supported by the platform, where
 457 'map_by_fd(imm)' means to get the map with the specified file descriptor. Each
 458 BPF program can also be defined to use a set of maps associated with the
 459 program at load time, and 'map_by_idx(imm)' means to get the map with the given
 460 index in the set associated with the BPF program containing the instruction.
 461
 462 Platform Variables
 463 ~~~~~~~~~~~~~~~~~~
 464
 465 Platform variables are memory regions, identified by integer ids, exposed by
 466 the runtime and accessible by BPF programs on some platforms.  The
 467 'var_addr(imm)' operation means to get the address of the memory region
 468 identified by the given id.
 469
 470 Legacy BPF Packet access instructions
 471 -------------------------------------
 472
 473 eBPF previously introduced special instructions for access to packet data that were
 474 carried over from classic BPF. However, these instructions are
 475 deprecated and should no longer be used.