Documentation/bpf/standardization/instruction-set.rst

   1 .. contents::
   2 .. sectnum::
   3
   4 =======================================
   5 BPF Instruction Set Specification, v1.0
   6 =======================================
   7
   8 This document specifies version 1.0 of the BPF instruction set.
   9
  10 Documentation conventions
  11 =========================
  12
  13 For brevity and consistency, this document refers to families
  14 of types using a shorthand syntax and refers to several expository,
  15 mnemonic functions when describing the semantics of instructions.
  16 The range of valid values for those types and the semantics of those
  17 functions are defined in the following subsections.
  18
  19 Types
  20 -----
  21 This document refers to integer types with the notation `SN` to specify
  22 a type's signedness (`S`) and bit width (`N`), respectively.
  23
  24 .. table:: Meaning of signedness notation.
  25
  26   ==== =========
  27   `S`  Meaning
  28   ==== =========
  29   `u`  unsigned
  30   `s`  signed
  31   ==== =========
  32
  33 .. table:: Meaning of bit-width notation.
  34
  35   ===== =========
  36   `N`   Bit width
  37   ===== =========
  38   `8`   8 bits
  39   `16`  16 bits
  40   `32`  32 bits
  41   `64`  64 bits
  42   `128` 128 bits
  43   ===== =========
  44
  45 For example, `u32` is a type whose valid values are all the 32-bit unsigned
  46 numbers and `s16` is a types whose valid values are all the 16-bit signed
  47 numbers.
  48
  49 Functions
  50 ---------
  51 * `htobe16`: Takes an unsigned 16-bit number in host-endian format and
  52   returns the equivalent number as an unsigned 16-bit number in big-endian
  53   format.
  54 * `htobe32`: Takes an unsigned 32-bit number in host-endian format and
  55   returns the equivalent number as an unsigned 32-bit number in big-endian
  56   format.
  57 * `htobe64`: Takes an unsigned 64-bit number in host-endian format and
  58   returns the equivalent number as an unsigned 64-bit number in big-endian
  59   format.
  60 * `htole16`: Takes an unsigned 16-bit number in host-endian format and
  61   returns the equivalent number as an unsigned 16-bit number in little-endian
  62   format.
  63 * `htole32`: Takes an unsigned 32-bit number in host-endian format and
  64   returns the equivalent number as an unsigned 32-bit number in little-endian
  65   format.
  66 * `htole64`: Takes an unsigned 64-bit number in host-endian format and
  67   returns the equivalent number as an unsigned 64-bit number in little-endian
  68   format.
  69 * `bswap16`: Takes an unsigned 16-bit number in either big- or little-endian
  70   format and returns the equivalent number with the same bit width but
  71   opposite endianness.
  72 * `bswap32`: Takes an unsigned 32-bit number in either big- or little-endian
  73   format and returns the equivalent number with the same bit width but
  74   opposite endianness.
  75 * `bswap64`: Takes an unsigned 64-bit number in either big- or little-endian
  76   format and returns the equivalent number with the same bit width but
  77   opposite endianness.
  78
  79
  80 Definitions
  81 -----------
  82
  83 .. glossary::
  84
  85   Sign Extend
  86     To `sign extend an` ``X`` `-bit number, A, to a` ``Y`` `-bit number, B  ,` means to
  87
  88     #. Copy all ``X`` bits from `A` to the lower ``X`` bits of `B`.
  89     #. Set the value of the remaining ``Y`` - ``X`` bits of `B` to the value of
  90        the  most-significant bit of `A`.
  91
  92 .. admonition:: Example
  93
  94   Sign extend an 8-bit number ``A`` to a 16-bit number ``B`` on a big-endian platform:
  95   ::
  96
  97     A:          10000110
  98     B: 11111111 10000110
  99
 100 Instruction encoding
 101 ====================
 102
 103 BPF has two instruction encodings:
 104
 105 * the basic instruction encoding, which uses 64 bits to encode an instruction
 106 * the wide instruction encoding, which appends a second 64-bit immediate (i.e.,
 107   constant) value after the basic instruction for a total of 128 bits.
 108
 109 The fields conforming an encoded basic instruction are stored in the
 110 following order::
 111
 112   opcode:8 src_reg:4 dst_reg:4 offset:16 imm:32 // In little-endian BPF.
 113   opcode:8 dst_reg:4 src_reg:4 offset:16 imm:32 // In big-endian BPF.
 114
 115 **imm**
 116   signed integer immediate value
 117
 118 **offset**
 119   signed integer offset used with pointer arithmetic
 120
 121 **src_reg**
 122   the source register number (0-10), except where otherwise specified
 123   (`64-bit immediate instructions`_ reuse this field for other purposes)
 124
 125 **dst_reg**
 126   destination register number (0-10)
 127
 128 **opcode**
 129   operation to perform
 130
 131 Note that the contents of multi-byte fields ('imm' and 'offset') are
 132 stored using big-endian byte ordering in big-endian BPF and
 133 little-endian byte ordering in little-endian BPF.
 134
 135 For example::
 136
 137   opcode                  offset imm          assembly
 138          src_reg dst_reg
 139   07     0       1        00 00  44 33 22 11  r1 += 0x11223344 // little
 140          dst_reg src_reg
 141   07     1       0        00 00  11 22 33 44  r1 += 0x11223344 // big
 142
 143 Note that most instructions do not use all of the fields.
 144 Unused fields shall be cleared to zero.
 145
 146 As discussed below in `64-bit immediate instructions`_, a 64-bit immediate
 147 instruction uses a 64-bit immediate value that is constructed as follows.
 148 The 64 bits following the basic instruction contain a pseudo instruction
 149 using the same format but with opcode, dst_reg, src_reg, and offset all set to zero,
 150 and imm containing the high 32 bits of the immediate value.
 151
 152 This is depicted in the following figure::
 153
 154         basic_instruction
 155   .-----------------------------.
 156   |                             |
 157   code:8 regs:8 offset:16 imm:32 unused:32 imm:32
 158                                  |              |
 159                                  '--------------'
 160                                 pseudo instruction
 161
 162 Thus the 64-bit immediate value is constructed as follows:
 163
 164   imm64 = (next_imm << 32) | imm
 165
 166 where 'next_imm' refers to the imm value of the pseudo instruction
 167 following the basic instruction.  The unused bytes in the pseudo
 168 instruction are reserved and shall be cleared to zero.
 169
 170 Instruction classes
 171 -------------------
 172
 173 The three LSB bits of the 'opcode' field store the instruction class:
 174
 175 =========  =====  ===============================  ===================================
 176 class      value  description                      reference
 177 =========  =====  ===============================  ===================================
 178 BPF_LD     0x00   non-standard load operations     `Load and store instructions`_
 179 BPF_LDX    0x01   load into register operations    `Load and store instructions`_
 180 BPF_ST     0x02   store from immediate operations  `Load and store instructions`_
 181 BPF_STX    0x03   store from register operations   `Load and store instructions`_
 182 BPF_ALU    0x04   32-bit arithmetic operations     `Arithmetic and jump instructions`_
 183 BPF_JMP    0x05   64-bit jump operations           `Arithmetic and jump instructions`_
 184 BPF_JMP32  0x06   32-bit jump operations           `Arithmetic and jump instructions`_
 185 BPF_ALU64  0x07   64-bit arithmetic operations     `Arithmetic and jump instructions`_
 186 =========  =====  ===============================  ===================================
 187
 188 Arithmetic and jump instructions
 189 ================================
 190
 191 For arithmetic and jump instructions (``BPF_ALU``, ``BPF_ALU64``, ``BPF_JMP`` and
 192 ``BPF_JMP32``), the 8-bit 'opcode' field is divided into three parts:
 193
 194 ==============  ======  =================
 195 4 bits (MSB)    1 bit   3 bits (LSB)
 196 ==============  ======  =================
 197 code            source  instruction class
 198 ==============  ======  =================
 199
 200 **code**
 201   the operation code, whose meaning varies by instruction class
 202
 203 **source**
 204   the source operand location, which unless otherwise specified is one of:
 205
 206   ======  =====  ==============================================
 207   source  value  description
 208   ======  =====  ==============================================
 209   BPF_K   0x00   use 32-bit 'imm' value as source operand
 210   BPF_X   0x08   use 'src_reg' register value as source operand
 211   ======  =====  ==============================================
 212
 213 **instruction class**
 214   the instruction class (see `Instruction classes`_)
 215
 216 Arithmetic instructions
 217 -----------------------
 218
 219 ``BPF_ALU`` uses 32-bit wide operands while ``BPF_ALU64`` uses 64-bit wide operands for
 220 otherwise identical operations.
 221 The 'code' field encodes the operation as below, where 'src' and 'dst' refer
 222 to the values of the source and destination registers, respectively.
 223
 224 =========  =====  =======  ==========================================================
 225 code       value  offset   description
 226 =========  =====  =======  ==========================================================
 227 BPF_ADD    0x00   0        dst += src
 228 BPF_SUB    0x10   0        dst -= src
 229 BPF_MUL    0x20   0        dst \*= src
 230 BPF_DIV    0x30   0        dst = (src != 0) ? (dst / src) : 0
 231 BPF_SDIV   0x30   1        dst = (src != 0) ? (dst s/ src) : 0
 232 BPF_OR     0x40   0        dst \|= src
 233 BPF_AND    0x50   0        dst &= src
 234 BPF_LSH    0x60   0        dst <<= (src & mask)
 235 BPF_RSH    0x70   0        dst >>= (src & mask)
 236 BPF_NEG    0x80   0        dst = -dst
 237 BPF_MOD    0x90   0        dst = (src != 0) ? (dst % src) : dst
 238 BPF_SMOD   0x90   1        dst = (src != 0) ? (dst s% src) : dst
 239 BPF_XOR    0xa0   0        dst ^= src
 240 BPF_MOV    0xb0   0        dst = src
 241 BPF_MOVSX  0xb0   8/16/32  dst = (s8,s16,s32)src
 242 BPF_ARSH   0xc0   0        :term:`sign extending<Sign Extend>` dst >>= (src & mask)
 243 BPF_END    0xd0   0        byte swap operations (see `Byte swap instructions`_ below)
 244 =========  =====  =======  ==========================================================
 245
 246 Underflow and overflow are allowed during arithmetic operations, meaning
 247 the 64-bit or 32-bit value will wrap. If BPF program execution would
 248 result in division by zero, the destination register is instead set to zero.
 249 If execution would result in modulo by zero, for ``BPF_ALU64`` the value of
 250 the destination register is unchanged whereas for ``BPF_ALU`` the upper
 251 32 bits of the destination register are zeroed.
 252
 253 ``BPF_ADD | BPF_X | BPF_ALU`` means::
 254
 255   dst = (u32) ((u32) dst + (u32) src)
 256
 257 where '(u32)' indicates that the upper 32 bits are zeroed.
 258
 259 ``BPF_ADD | BPF_X | BPF_ALU64`` means::
 260
 261   dst = dst + src
 262
 263 ``BPF_XOR | BPF_K | BPF_ALU`` means::
 264
 265   dst = (u32) dst ^ (u32) imm32
 266
 267 ``BPF_XOR | BPF_K | BPF_ALU64`` means::
 268
 269   dst = dst ^ imm32
 270
 271 Note that most instructions have instruction offset of 0. Only three instructions
 272 (``BPF_SDIV``, ``BPF_SMOD``, ``BPF_MOVSX``) have a non-zero offset.
 273
 274 The division and modulo operations support both unsigned and signed flavors.
 275
 276 For unsigned operations (``BPF_DIV`` and ``BPF_MOD``), for ``BPF_ALU``,
 277 'imm' is interpreted as a 32-bit unsigned value. For ``BPF_ALU64``,
 278 'imm' is first :term:`sign extended<Sign Extend>` from 32 to 64 bits, and then
 279 interpreted as a 64-bit unsigned value.
 280
 281 For signed operations (``BPF_SDIV`` and ``BPF_SMOD``), for ``BPF_ALU``,
 282 'imm' is interpreted as a 32-bit signed value. For ``BPF_ALU64``, 'imm'
 283 is first :term:`sign extended<Sign Extend>` from 32 to 64 bits, and then
 284 interpreted as a 64-bit signed value.
 285
 286 Note that there are varying definitions of the signed modulo operation
 287 when the dividend or divisor are negative, where implementations often
 288 vary by language such that Python, Ruby, etc.  differ from C, Go, Java,
 289 etc. This specification requires that signed modulo use truncated division
 290 (where -13 % 3 == -1) as implemented in C, Go, etc.:
 291
 292    a % n = a - n * trunc(a / n)
 293
 294 The ``BPF_MOVSX`` instruction does a move operation with sign extension.
 295 ``BPF_ALU | BPF_MOVSX`` :term:`sign extends<Sign Extend>` 8-bit and 16-bit operands into 32
 296 bit operands, and zeroes the remaining upper 32 bits.
 297 ``BPF_ALU64 | BPF_MOVSX`` :term:`sign extends<Sign Extend>` 8-bit, 16-bit, and 32-bit
 298 operands into 64 bit operands.
 299
 300 Shift operations use a mask of 0x3F (63) for 64-bit operations and 0x1F (31)
 301 for 32-bit operations.
 302
 303 Byte swap instructions
 304 ----------------------
 305
 306 The byte swap instructions use instruction classes of ``BPF_ALU`` and ``BPF_ALU64``
 307 and a 4-bit 'code' field of ``BPF_END``.
 308
 309 The byte swap instructions operate on the destination register
 310 only and do not use a separate source register or immediate value.
 311
 312 For ``BPF_ALU``, the 1-bit source operand field in the opcode is used to
 313 select what byte order the operation converts from or to. For
 314 ``BPF_ALU64``, the 1-bit source operand field in the opcode is reserved
 315 and must be set to 0.
 316
 317 =========  =========  =====  =================================================
 318 class      source     value  description
 319 =========  =========  =====  =================================================
 320 BPF_ALU    BPF_TO_LE  0x00   convert between host byte order and little endian
 321 BPF_ALU    BPF_TO_BE  0x08   convert between host byte order and big endian
 322 BPF_ALU64  Reserved   0x00   do byte swap unconditionally
 323 =========  =========  =====  =================================================
 324
 325 The 'imm' field encodes the width of the swap operations.  The following widths
 326 are supported: 16, 32 and 64.
 327
 328 Examples:
 329
 330 ``BPF_ALU | BPF_TO_LE | BPF_END`` with imm = 16/32/64 means::
 331
 332   dst = htole16(dst)
 333   dst = htole32(dst)
 334   dst = htole64(dst)
 335
 336 ``BPF_ALU | BPF_TO_BE | BPF_END`` with imm = 16/32/64 means::
 337
 338   dst = htobe16(dst)
 339   dst = htobe32(dst)
 340   dst = htobe64(dst)
 341
 342 ``BPF_ALU64 | BPF_TO_LE | BPF_END`` with imm = 16/32/64 means::
 343
 344   dst = bswap16(dst)
 345   dst = bswap32(dst)
 346   dst = bswap64(dst)
 347
 348 Jump instructions
 349 -----------------
 350
 351 ``BPF_JMP32`` uses 32-bit wide operands while ``BPF_JMP`` uses 64-bit wide operands for
 352 otherwise identical operations.
 353 The 'code' field encodes the operation as below:
 354
 355 ========  =====  ===  ===========================================  =========================================
 356 code      value  src  description                                  notes
 357 ========  =====  ===  ===========================================  =========================================
 358 BPF_JA    0x0    0x0  PC += offset                                 BPF_JMP class
 359 BPF_JA    0x0    0x0  PC += imm                                    BPF_JMP32 class
 360 BPF_JEQ   0x1    any  PC += offset if dst == src
 361 BPF_JGT   0x2    any  PC += offset if dst > src                    unsigned
 362 BPF_JGE   0x3    any  PC += offset if dst >= src                   unsigned
 363 BPF_JSET  0x4    any  PC += offset if dst & src
 364 BPF_JNE   0x5    any  PC += offset if dst != src
 365 BPF_JSGT  0x6    any  PC += offset if dst > src                    signed
 366 BPF_JSGE  0x7    any  PC += offset if dst >= src                   signed
 367 BPF_CALL  0x8    0x0  call helper function by address              see `Helper functions`_
 368 BPF_CALL  0x8    0x1  call PC += imm                               see `Program-local functions`_
 369 BPF_CALL  0x8    0x2  call helper function by BTF ID               see `Helper functions`_
 370 BPF_EXIT  0x9    0x0  return                                       BPF_JMP only
 371 BPF_JLT   0xa    any  PC += offset if dst < src                    unsigned
 372 BPF_JLE   0xb    any  PC += offset if dst <= src                   unsigned
 373 BPF_JSLT  0xc    any  PC += offset if dst < src                    signed
 374 BPF_JSLE  0xd    any  PC += offset if dst <= src                   signed
 375 ========  =====  ===  ===========================================  =========================================
 376
 377 The BPF program needs to store the return value into register R0 before doing a
 378 ``BPF_EXIT``.
 379
 380 Example:
 381
 382 ``BPF_JSGE | BPF_X | BPF_JMP32`` (0x7e) means::
 383
 384   if (s32)dst s>= (s32)src goto +offset
 385
 386 where 's>=' indicates a signed '>=' comparison.
 387
 388 ``BPF_JA | BPF_K | BPF_JMP32`` (0x06) means::
 389
 390   gotol +imm
 391
 392 where 'imm' means the branch offset comes from insn 'imm' field.
 393
 394 Note that there are two flavors of ``BPF_JA`` instructions. The
 395 ``BPF_JMP`` class permits a 16-bit jump offset specified by the 'offset'
 396 field, whereas the ``BPF_JMP32`` class permits a 32-bit jump offset
 397 specified by the 'imm' field. A > 16-bit conditional jump may be
 398 converted to a < 16-bit conditional jump plus a 32-bit unconditional
 399 jump.
 400
 401 Helper functions
 402 ~~~~~~~~~~~~~~~~
 403
 404 Helper functions are a concept whereby BPF programs can call into a
 405 set of function calls exposed by the underlying platform.
 406
 407 Historically, each helper function was identified by an address
 408 encoded in the imm field.  The available helper functions may differ
 409 for each program type, but address values are unique across all program types.
 410
 411 Platforms that support the BPF Type Format (BTF) support identifying
 412 a helper function by a BTF ID encoded in the imm field, where the BTF ID
 413 identifies the helper name and type.
 414
 415 Program-local functions
 416 ~~~~~~~~~~~~~~~~~~~~~~~
 417 Program-local functions are functions exposed by the same BPF program as the
 418 caller, and are referenced by offset from the call instruction, similar to
 419 ``BPF_JA``.  The offset is encoded in the imm field of the call instruction.
 420 A ``BPF_EXIT`` within the program-local function will return to the caller.
 421
 422 Load and store instructions
 423 ===========================
 424
 425 For load and store instructions (``BPF_LD``, ``BPF_LDX``, ``BPF_ST``, and ``BPF_STX``), the
 426 8-bit 'opcode' field is divided as:
 427
 428 ============  ======  =================
 429 3 bits (MSB)  2 bits  3 bits (LSB)
 430 ============  ======  =================
 431 mode          size    instruction class
 432 ============  ======  =================
 433
 434 The mode modifier is one of:
 435
 436   =============  =====  ====================================  =============
 437   mode modifier  value  description                           reference
 438   =============  =====  ====================================  =============
 439   BPF_IMM        0x00   64-bit immediate instructions         `64-bit immediate instructions`_
 440   BPF_ABS        0x20   legacy BPF packet access (absolute)   `Legacy BPF Packet access instructions`_
 441   BPF_IND        0x40   legacy BPF packet access (indirect)   `Legacy BPF Packet access instructions`_
 442   BPF_MEM        0x60   regular load and store operations     `Regular load and store operations`_
 443   BPF_MEMSX      0x80   sign-extension load operations        `Sign-extension load operations`_
 444   BPF_ATOMIC     0xc0   atomic operations                     `Atomic operations`_
 445   =============  =====  ====================================  =============
 446
 447 The size modifier is one of:
 448
 449   =============  =====  =====================
 450   size modifier  value  description
 451   =============  =====  =====================
 452   BPF_W          0x00   word        (4 bytes)
 453   BPF_H          0x08   half word   (2 bytes)
 454   BPF_B          0x10   byte
 455   BPF_DW         0x18   double word (8 bytes)
 456   =============  =====  =====================
 457
 458 Regular load and store operations
 459 ---------------------------------
 460
 461 The ``BPF_MEM`` mode modifier is used to encode regular load and store
 462 instructions that transfer data between a register and memory.
 463
 464 ``BPF_MEM | <size> | BPF_STX`` means::
 465
 466   *(size *) (dst + offset) = src
 467
 468 ``BPF_MEM | <size> | BPF_ST`` means::
 469
 470   *(size *) (dst + offset) = imm32
 471
 472 ``BPF_MEM | <size> | BPF_LDX`` means::
 473
 474   dst = *(unsigned size *) (src + offset)
 475
 476 Where size is one of: ``BPF_B``, ``BPF_H``, ``BPF_W``, or ``BPF_DW`` and
 477 'unsigned size' is one of u8, u16, u32 or u64.
 478
 479 Sign-extension load operations
 480 ------------------------------
 481
 482 The ``BPF_MEMSX`` mode modifier is used to encode :term:`sign-extension<Sign Extend>` load
 483 instructions that transfer data between a register and memory.
 484
 485 ``BPF_MEMSX | <size> | BPF_LDX`` means::
 486
 487   dst = *(signed size *) (src + offset)
 488
 489 Where size is one of: ``BPF_B``, ``BPF_H`` or ``BPF_W``, and
 490 'signed size' is one of s8, s16 or s32.
 491
 492 Atomic operations
 493 -----------------
 494
 495 Atomic operations are operations that operate on memory and can not be
 496 interrupted or corrupted by other access to the same memory region
 497 by other BPF programs or means outside of this specification.
 498
 499 All atomic operations supported by BPF are encoded as store operations
 500 that use the ``BPF_ATOMIC`` mode modifier as follows:
 501
 502 * ``BPF_ATOMIC | BPF_W | BPF_STX`` for 32-bit operations
 503 * ``BPF_ATOMIC | BPF_DW | BPF_STX`` for 64-bit operations
 504 * 8-bit and 16-bit wide atomic operations are not supported.
 505
 506 The 'imm' field is used to encode the actual atomic operation.
 507 Simple atomic operation use a subset of the values defined to encode
 508 arithmetic operations in the 'imm' field to encode the atomic operation:
 509
 510 ========  =====  ===========
 511 imm       value  description
 512 ========  =====  ===========
 513 BPF_ADD   0x00   atomic add
 514 BPF_OR    0x40   atomic or
 515 BPF_AND   0x50   atomic and
 516 BPF_XOR   0xa0   atomic xor
 517 ========  =====  ===========
 518
 519
 520 ``BPF_ATOMIC | BPF_W  | BPF_STX`` with 'imm' = BPF_ADD means::
 521
 522   *(u32 *)(dst + offset) += src
 523
 524 ``BPF_ATOMIC | BPF_DW | BPF_STX`` with 'imm' = BPF ADD means::
 525
 526   *(u64 *)(dst + offset) += src
 527
 528 In addition to the simple atomic operations, there also is a modifier and
 529 two complex atomic operations:
 530
 531 ===========  ================  ===========================
 532 imm          value             description
 533 ===========  ================  ===========================
 534 BPF_FETCH    0x01              modifier: return old value
 535 BPF_XCHG     0xe0 | BPF_FETCH  atomic exchange
 536 BPF_CMPXCHG  0xf0 | BPF_FETCH  atomic compare and exchange
 537 ===========  ================  ===========================
 538
 539 The ``BPF_FETCH`` modifier is optional for simple atomic operations, and
 540 always set for the complex atomic operations.  If the ``BPF_FETCH`` flag
 541 is set, then the operation also overwrites ``src`` with the value that
 542 was in memory before it was modified.
 543
 544 The ``BPF_XCHG`` operation atomically exchanges ``src`` with the value
 545 addressed by ``dst + offset``.
 546
 547 The ``BPF_CMPXCHG`` operation atomically compares the value addressed by
 548 ``dst + offset`` with ``R0``. If they match, the value addressed by
 549 ``dst + offset`` is replaced with ``src``. In either case, the
 550 value that was at ``dst + offset`` before the operation is zero-extended
 551 and loaded back to ``R0``.
 552
 553 64-bit immediate instructions
 554 -----------------------------
 555
 556 Instructions with the ``BPF_IMM`` 'mode' modifier use the wide instruction
 557 encoding defined in `Instruction encoding`_, and use the 'src' field of the
 558 basic instruction to hold an opcode subtype.
 559
 560 The following table defines a set of ``BPF_IMM | BPF_DW | BPF_LD`` instructions
 561 with opcode subtypes in the 'src' field, using new terms such as "map"
 562 defined further below:
 563
 564 =========================  ======  ===  =========================================  ===========  ==============
 565 opcode construction        opcode  src  pseudocode                                 imm type     dst type
 566 =========================  ======  ===  =========================================  ===========  ==============
 567 BPF_IMM | BPF_DW | BPF_LD  0x18    0x0  dst = imm64                                integer      integer
 568 BPF_IMM | BPF_DW | BPF_LD  0x18    0x1  dst = map_by_fd(imm)                       map fd       map
 569 BPF_IMM | BPF_DW | BPF_LD  0x18    0x2  dst = map_val(map_by_fd(imm)) + next_imm   map fd       data pointer
 570 BPF_IMM | BPF_DW | BPF_LD  0x18    0x3  dst = var_addr(imm)                        variable id  data pointer
 571 BPF_IMM | BPF_DW | BPF_LD  0x18    0x4  dst = code_addr(imm)                       integer      code pointer
 572 BPF_IMM | BPF_DW | BPF_LD  0x18    0x5  dst = map_by_idx(imm)                      map index    map
 573 BPF_IMM | BPF_DW | BPF_LD  0x18    0x6  dst = map_val(map_by_idx(imm)) + next_imm  map index    data pointer
 574 =========================  ======  ===  =========================================  ===========  ==============
 575
 576 where
 577
 578 * map_by_fd(imm) means to convert a 32-bit file descriptor into an address of a map (see `Maps`_)
 579 * map_by_idx(imm) means to convert a 32-bit index into an address of a map
 580 * map_val(map) gets the address of the first value in a given map
 581 * var_addr(imm) gets the address of a platform variable (see `Platform Variables`_) with a given id
 582 * code_addr(imm) gets the address of the instruction at a specified relative offset in number of (64-bit) instructions
 583 * the 'imm type' can be used by disassemblers for display
 584 * the 'dst type' can be used for verification and JIT compilation purposes
 585
 586 Maps
 587 ~~~~
 588
 589 Maps are shared memory regions accessible by BPF programs on some platforms.
 590 A map can have various semantics as defined in a separate document, and may or
 591 may not have a single contiguous memory region, but the 'map_val(map)' is
 592 currently only defined for maps that do have a single contiguous memory region.
 593
 594 Each map can have a file descriptor (fd) if supported by the platform, where
 595 'map_by_fd(imm)' means to get the map with the specified file descriptor. Each
 596 BPF program can also be defined to use a set of maps associated with the
 597 program at load time, and 'map_by_idx(imm)' means to get the map with the given
 598 index in the set associated with the BPF program containing the instruction.
 599
 600 Platform Variables
 601 ~~~~~~~~~~~~~~~~~~
 602
 603 Platform variables are memory regions, identified by integer ids, exposed by
 604 the runtime and accessible by BPF programs on some platforms.  The
 605 'var_addr(imm)' operation means to get the address of the memory region
 606 identified by the given id.
 607
 608 Legacy BPF Packet access instructions
 609 -------------------------------------
 610
 611 BPF previously introduced special instructions for access to packet data that were
 612 carried over from classic BPF. However, these instructions are
 613 deprecated and should no longer be used.