1.. contents::
2.. sectnum::
3
4======================================
5BPF Instruction Set Architecture (ISA)
6======================================
7
8eBPF, also commonly
9referred to as BPF, is a technology with origins in the Linux kernel
10that can run untrusted programs in a privileged context such as an
11operating system kernel. This document specifies the BPF instruction
12set architecture (ISA).
13
14As a historical note, BPF originally stood for Berkeley Packet Filter,
15but now that it can do so much more than packet filtering, the acronym
16no longer makes sense. BPF is now considered a standalone term that
17does not stand for anything.  The original BPF is sometimes referred to
18as cBPF (classic BPF) to distinguish it from the now widely deployed
19eBPF (extended BPF).
20
21Documentation conventions
22=========================
23
24The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
25"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
26"OPTIONAL" in this document are to be interpreted as described in
27BCP 14 `<https://www.rfc-editor.org/info/rfc2119>`_
28`<https://www.rfc-editor.org/info/rfc8174>`_
29when, and only when, they appear in all capitals, as shown here.
30
31For brevity and consistency, this document refers to families
32of types using a shorthand syntax and refers to several expository,
33mnemonic functions when describing the semantics of instructions.
34The range of valid values for those types and the semantics of those
35functions are defined in the following subsections.
36
37Types
38-----
39This document refers to integer types with the notation `SN` to specify
40a type's signedness (`S`) and bit width (`N`), respectively.
41
42.. table:: Meaning of signedness notation
43
44  ==== =========
45  S    Meaning
46  ==== =========
47  u    unsigned
48  s    signed
49  ==== =========
50
51.. table:: Meaning of bit-width notation
52
53  ===== =========
54  N     Bit width
55  ===== =========
56  8     8 bits
57  16    16 bits
58  32    32 bits
59  64    64 bits
60  128   128 bits
61  ===== =========
62
63For example, `u32` is a type whose valid values are all the 32-bit unsigned
64numbers and `s16` is a type whose valid values are all the 16-bit signed
65numbers.
66
67Functions
68---------
69
70The following byteswap functions are direction-agnostic.  That is,
71the same function is used for conversion in either direction discussed
72below.
73
74* be16: Takes an unsigned 16-bit number and converts it between
75  host byte order and big-endian
76  (`IEN137 <https://www.rfc-editor.org/ien/ien137.txt>`_) byte order.
77* be32: Takes an unsigned 32-bit number and converts it between
78  host byte order and big-endian byte order.
79* be64: Takes an unsigned 64-bit number and converts it between
80  host byte order and big-endian byte order.
81* bswap16: Takes an unsigned 16-bit number in either big- or little-endian
82  format and returns the equivalent number with the same bit width but
83  opposite endianness.
84* bswap32: Takes an unsigned 32-bit number in either big- or little-endian
85  format and returns the equivalent number with the same bit width but
86  opposite endianness.
87* bswap64: Takes an unsigned 64-bit number in either big- or little-endian
88  format and returns the equivalent number with the same bit width but
89  opposite endianness.
90* le16: Takes an unsigned 16-bit number and converts it between
91  host byte order and little-endian byte order.
92* le32: Takes an unsigned 32-bit number and converts it between
93  host byte order and little-endian byte order.
94* le64: Takes an unsigned 64-bit number and converts it between
95  host byte order and little-endian byte order.
96
97Definitions
98-----------
99
100.. glossary::
101
102  Sign Extend
103    To `sign extend an` ``X`` `-bit number, A, to a` ``Y`` `-bit number, B  ,` means to
104
105    #. Copy all ``X`` bits from `A` to the lower ``X`` bits of `B`.
106    #. Set the value of the remaining ``Y`` - ``X`` bits of `B` to the value of
107       the  most-significant bit of `A`.
108
109.. admonition:: Example
110
111  Sign extend an 8-bit number ``A`` to a 16-bit number ``B`` on a big-endian platform:
112  ::
113
114    A:          10000110
115    B: 11111111 10000110
116
117Conformance groups
118------------------
119
120An implementation does not need to support all instructions specified in this
121document (e.g., deprecated instructions).  Instead, a number of conformance
122groups are specified.  An implementation MUST support the base32 conformance
123group and MAY support additional conformance groups, where supporting a
124conformance group means it MUST support all instructions in that conformance
125group.
126
127The use of named conformance groups enables interoperability between a runtime
128that executes instructions, and tools such as compilers that generate
129instructions for the runtime.  Thus, capability discovery in terms of
130conformance groups might be done manually by users or automatically by tools.
131
132Each conformance group has a short ASCII label (e.g., "base32") that
133corresponds to a set of instructions that are mandatory.  That is, each
134instruction has one or more conformance groups of which it is a member.
135
136This document defines the following conformance groups:
137
138* base32: includes all instructions defined in this
139  specification unless otherwise noted.
140* base64: includes base32, plus instructions explicitly noted
141  as being in the base64 conformance group.
142* atomic32: includes 32-bit atomic operation instructions (see `Atomic operations`_).
143* atomic64: includes atomic32, plus 64-bit atomic operation instructions.
144* divmul32: includes 32-bit division, multiplication, and modulo instructions.
145* divmul64: includes divmul32, plus 64-bit division, multiplication,
146  and modulo instructions.
147* packet: deprecated packet access instructions.
148
149Instruction encoding
150====================
151
152BPF has two instruction encodings:
153
154* the basic instruction encoding, which uses 64 bits to encode an instruction
155* the wide instruction encoding, which appends a second 64 bits
156  after the basic instruction for a total of 128 bits.
157
158Basic instruction encoding
159--------------------------
160
161A basic instruction is encoded as follows::
162
163  +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
164  |    opcode     |     regs      |            offset             |
165  +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
166  |                              imm                              |
167  +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
168
169**opcode**
170  operation to perform, encoded as follows::
171
172    +-+-+-+-+-+-+-+-+
173    |specific |class|
174    +-+-+-+-+-+-+-+-+
175
176  **specific**
177    The format of these bits varies by instruction class
178
179  **class**
180    The instruction class (see `Instruction classes`_)
181
182**regs**
183  The source and destination register numbers, encoded as follows
184  on a little-endian host::
185
186    +-+-+-+-+-+-+-+-+
187    |src_reg|dst_reg|
188    +-+-+-+-+-+-+-+-+
189
190  and as follows on a big-endian host::
191
192    +-+-+-+-+-+-+-+-+
193    |dst_reg|src_reg|
194    +-+-+-+-+-+-+-+-+
195
196  **src_reg**
197    the source register number (0-10), except where otherwise specified
198    (`64-bit immediate instructions`_ reuse this field for other purposes)
199
200  **dst_reg**
201    destination register number (0-10), unless otherwise specified
202    (future instructions might reuse this field for other purposes)
203
204**offset**
205  signed integer offset used with pointer arithmetic, except where
206  otherwise specified (some arithmetic instructions reuse this field
207  for other purposes)
208
209**imm**
210  signed integer immediate value
211
212Note that the contents of multi-byte fields ('offset' and 'imm') are
213stored using big-endian byte ordering on big-endian hosts and
214little-endian byte ordering on little-endian hosts.
215
216For example::
217
218  opcode                  offset imm          assembly
219         src_reg dst_reg
220  07     0       1        00 00  44 33 22 11  r1 += 0x11223344 // little
221         dst_reg src_reg
222  07     1       0        00 00  11 22 33 44  r1 += 0x11223344 // big
223
224Note that most instructions do not use all of the fields.
225Unused fields SHALL be cleared to zero.
226
227Wide instruction encoding
228--------------------------
229
230Some instructions are defined to use the wide instruction encoding,
231which uses two 32-bit immediate values.  The 64 bits following
232the basic instruction format contain a pseudo instruction
233with 'opcode', 'dst_reg', 'src_reg', and 'offset' all set to zero.
234
235This is depicted in the following figure::
236
237  +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
238  |    opcode     |     regs      |            offset             |
239  +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
240  |                              imm                              |
241  +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
242  |                           reserved                            |
243  +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
244  |                           next_imm                            |
245  +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
246
247**opcode**
248  operation to perform, encoded as explained above
249
250**regs**
251  The source and destination register numbers (unless otherwise
252  specified), encoded as explained above
253
254**offset**
255  signed integer offset used with pointer arithmetic, unless
256  otherwise specified
257
258**imm**
259  signed integer immediate value
260
261**reserved**
262  unused, set to zero
263
264**next_imm**
265  second signed integer immediate value
266
267Instruction classes
268-------------------
269
270The three least significant bits of the 'opcode' field store the instruction class:
271
272.. table:: Instruction class
273
274  =====  =====  ===============================  ===================================
275  class  value  description                      reference
276  =====  =====  ===============================  ===================================
277  LD     0x0    non-standard load operations     `Load and store instructions`_
278  LDX    0x1    load into register operations    `Load and store instructions`_
279  ST     0x2    store from immediate operations  `Load and store instructions`_
280  STX    0x3    store from register operations   `Load and store instructions`_
281  ALU    0x4    32-bit arithmetic operations     `Arithmetic and jump instructions`_
282  JMP    0x5    64-bit jump operations           `Arithmetic and jump instructions`_
283  JMP32  0x6    32-bit jump operations           `Arithmetic and jump instructions`_
284  ALU64  0x7    64-bit arithmetic operations     `Arithmetic and jump instructions`_
285  =====  =====  ===============================  ===================================
286
287Arithmetic and jump instructions
288================================
289
290For arithmetic and jump instructions (``ALU``, ``ALU64``, ``JMP`` and
291``JMP32``), the 8-bit 'opcode' field is divided into three parts::
292
293  +-+-+-+-+-+-+-+-+
294  |  code |s|class|
295  +-+-+-+-+-+-+-+-+
296
297**code**
298  the operation code, whose meaning varies by instruction class
299
300**s (source)**
301  the source operand location, which unless otherwise specified is one of:
302
303  .. table:: Source operand location
304
305    ======  =====  ==============================================
306    source  value  description
307    ======  =====  ==============================================
308    K       0      use 32-bit 'imm' value as source operand
309    X       1      use 'src_reg' register value as source operand
310    ======  =====  ==============================================
311
312**instruction class**
313  the instruction class (see `Instruction classes`_)
314
315Arithmetic instructions
316-----------------------
317
318``ALU`` uses 32-bit wide operands while ``ALU64`` uses 64-bit wide operands for
319otherwise identical operations. ``ALU64`` instructions belong to the
320base64 conformance group unless noted otherwise.
321The 'code' field encodes the operation as below, where 'src' refers to the
322the source operand and 'dst' refers to the value of the destination
323register.
324
325.. table:: Arithmetic instructions
326
327  =====  =====  =======  ===================================================================================
328  name   code   offset   description
329  =====  =====  =======  ===================================================================================
330  ADD    0x0    0        dst += src
331  SUB    0x1    0        dst -= src
332  MUL    0x2    0        dst \*= src
333  DIV    0x3    0        dst = (src != 0) ? (dst / src) : 0
334  SDIV   0x3    1        dst = (src == 0) ? 0 : ((src == -1 && dst == LLONG_MIN) ? LLONG_MIN : (dst s/ src))
335  OR     0x4    0        dst \|= src
336  AND    0x5    0        dst &= src
337  LSH    0x6    0        dst <<= (src & mask)
338  RSH    0x7    0        dst >>= (src & mask)
339  NEG    0x8    0        dst = -dst
340  MOD    0x9    0        dst = (src != 0) ? (dst % src) : dst
341  SMOD   0x9    1        dst = (src == 0) ? dst : ((src == -1 && dst == LLONG_MIN) ? 0: (dst s% src))
342  XOR    0xa    0        dst ^= src
343  MOV    0xb    0        dst = src
344  MOVSX  0xb    8/16/32  dst = (s8,s16,s32)src
345  ARSH   0xc    0        :term:`sign extending<Sign Extend>` dst >>= (src & mask)
346  END    0xd    0        byte swap operations (see `Byte swap instructions`_ below)
347  =====  =====  =======  ===================================================================================
348
349Underflow and overflow are allowed during arithmetic operations, meaning
350the 64-bit or 32-bit value will wrap. If BPF program execution would
351result in division by zero, the destination register is instead set to zero.
352Otherwise, for ``ALU64``, if execution would result in ``LLONG_MIN``
353dividing -1, the desination register is instead set to ``LLONG_MIN``. For
354``ALU``, if execution would result in ``INT_MIN`` dividing -1, the
355desination register is instead set to ``INT_MIN``.
356
357If execution would result in modulo by zero, for ``ALU64`` the value of
358the destination register is unchanged whereas for ``ALU`` the upper
35932 bits of the destination register are zeroed. Otherwise, for ``ALU64``,
360if execution would resuslt in ``LLONG_MIN`` modulo -1, the destination
361register is instead set to 0. For ``ALU``, if execution would result in
362``INT_MIN`` modulo -1, the destination register is instead set to 0.
363
364``{ADD, X, ALU}``, where 'code' = ``ADD``, 'source' = ``X``, and 'class' = ``ALU``, means::
365
366  dst = (u32) ((u32) dst + (u32) src)
367
368where '(u32)' indicates that the upper 32 bits are zeroed.
369
370``{ADD, X, ALU64}`` means::
371
372  dst = dst + src
373
374``{XOR, K, ALU}`` means::
375
376  dst = (u32) dst ^ (u32) imm
377
378``{XOR, K, ALU64}`` means::
379
380  dst = dst ^ imm
381
382Note that most arithmetic instructions have 'offset' set to 0. Only three instructions
383(``SDIV``, ``SMOD``, ``MOVSX``) have a non-zero 'offset'.
384
385Division, multiplication, and modulo operations for ``ALU`` are part
386of the "divmul32" conformance group, and division, multiplication, and
387modulo operations for ``ALU64`` are part of the "divmul64" conformance
388group.
389The division and modulo operations support both unsigned and signed flavors.
390
391For unsigned operations (``DIV`` and ``MOD``), for ``ALU``,
392'imm' is interpreted as a 32-bit unsigned value. For ``ALU64``,
393'imm' is first :term:`sign extended<Sign Extend>` from 32 to 64 bits, and then
394interpreted as a 64-bit unsigned value.
395
396For signed operations (``SDIV`` and ``SMOD``), for ``ALU``,
397'imm' is interpreted as a 32-bit signed value. For ``ALU64``, 'imm'
398is first :term:`sign extended<Sign Extend>` from 32 to 64 bits, and then
399interpreted as a 64-bit signed value.
400
401Note that there are varying definitions of the signed modulo operation
402when the dividend or divisor are negative, where implementations often
403vary by language such that Python, Ruby, etc.  differ from C, Go, Java,
404etc. This specification requires that signed modulo MUST use truncated division
405(where -13 % 3 == -1) as implemented in C, Go, etc.::
406
407   a % n = a - n * trunc(a / n)
408
409The ``MOVSX`` instruction does a move operation with sign extension.
410``{MOVSX, X, ALU}`` :term:`sign extends<Sign Extend>` 8-bit and 16-bit operands into
41132-bit operands, and zeroes the remaining upper 32 bits.
412``{MOVSX, X, ALU64}`` :term:`sign extends<Sign Extend>` 8-bit, 16-bit, and 32-bit
413operands into 64-bit operands.  Unlike other arithmetic instructions,
414``MOVSX`` is only defined for register source operands (``X``).
415
416``{MOV, K, ALU64}`` means::
417
418  dst = (s64)imm
419
420``{MOV, X, ALU}`` means::
421
422  dst = (u32)src
423
424``{MOVSX, X, ALU}`` with 'offset' 8 means::
425
426  dst = (u32)(s32)(s8)src
427
428
429The ``NEG`` instruction is only defined when the source bit is clear
430(``K``).
431
432Shift operations use a mask of 0x3F (63) for 64-bit operations and 0x1F (31)
433for 32-bit operations.
434
435Byte swap instructions
436----------------------
437
438The byte swap instructions use instruction classes of ``ALU`` and ``ALU64``
439and a 4-bit 'code' field of ``END``.
440
441The byte swap instructions operate on the destination register
442only and do not use a separate source register or immediate value.
443
444For ``ALU``, the 1-bit source operand field in the opcode is used to
445select what byte order the operation converts from or to. For
446``ALU64``, the 1-bit source operand field in the opcode is reserved
447and MUST be set to 0.
448
449.. table:: Byte swap instructions
450
451  =====  ========  =====  =================================================
452  class  source    value  description
453  =====  ========  =====  =================================================
454  ALU    LE        0      convert between host byte order and little endian
455  ALU    BE        1      convert between host byte order and big endian
456  ALU64  Reserved  0      do byte swap unconditionally
457  =====  ========  =====  =================================================
458
459The 'imm' field encodes the width of the swap operations.  The following widths
460are supported: 16, 32 and 64.  Width 64 operations belong to the base64
461conformance group and other swap operations belong to the base32
462conformance group.
463
464Examples:
465
466``{END, LE, ALU}`` with 'imm' = 16/32/64 means::
467
468  dst = le16(dst)
469  dst = le32(dst)
470  dst = le64(dst)
471
472``{END, BE, ALU}`` with 'imm' = 16/32/64 means::
473
474  dst = be16(dst)
475  dst = be32(dst)
476  dst = be64(dst)
477
478``{END, TO, ALU64}`` with 'imm' = 16/32/64 means::
479
480  dst = bswap16(dst)
481  dst = bswap32(dst)
482  dst = bswap64(dst)
483
484Jump instructions
485-----------------
486
487``JMP32`` uses 32-bit wide operands and indicates the base32
488conformance group, while ``JMP`` uses 64-bit wide operands for
489otherwise identical operations, and indicates the base64 conformance
490group unless otherwise specified.
491The 'code' field encodes the operation as below:
492
493.. table:: Jump instructions
494
495  ========  =====  =======  =================================  ===================================================
496  code      value  src_reg  description                        notes
497  ========  =====  =======  =================================  ===================================================
498  JA        0x0    0x0      PC += offset                       {JA, K, JMP} only
499  JA        0x0    0x0      PC += imm                          {JA, K, JMP32} only
500  JEQ       0x1    any      PC += offset if dst == src
501  JGT       0x2    any      PC += offset if dst > src          unsigned
502  JGE       0x3    any      PC += offset if dst >= src         unsigned
503  JSET      0x4    any      PC += offset if dst & src
504  JNE       0x5    any      PC += offset if dst != src
505  JSGT      0x6    any      PC += offset if dst > src          signed
506  JSGE      0x7    any      PC += offset if dst >= src         signed
507  CALL      0x8    0x0      call helper function by static ID  {CALL, K, JMP} only, see `Helper functions`_
508  CALL      0x8    0x1      call PC += imm                     {CALL, K, JMP} only, see `Program-local functions`_
509  CALL      0x8    0x2      call helper function by BTF ID     {CALL, K, JMP} only, see `Helper functions`_
510  EXIT      0x9    0x0      return                             {CALL, K, JMP} only
511  JLT       0xa    any      PC += offset if dst < src          unsigned
512  JLE       0xb    any      PC += offset if dst <= src         unsigned
513  JSLT      0xc    any      PC += offset if dst < src          signed
514  JSLE      0xd    any      PC += offset if dst <= src         signed
515  ========  =====  =======  =================================  ===================================================
516
517where 'PC' denotes the program counter, and the offset to increment by
518is in units of 64-bit instructions relative to the instruction following
519the jump instruction.  Thus 'PC += 1' skips execution of the next
520instruction if it's a basic instruction or results in undefined behavior
521if the next instruction is a 128-bit wide instruction.
522
523Example:
524
525``{JSGE, X, JMP32}`` means::
526
527  if (s32)dst s>= (s32)src goto +offset
528
529where 's>=' indicates a signed '>=' comparison.
530
531``{JLE, K, JMP}`` means::
532
533  if dst <= (u64)(s64)imm goto +offset
534
535``{JA, K, JMP32}`` means::
536
537  gotol +imm
538
539where 'imm' means the branch offset comes from the 'imm' field.
540
541Note that there are two flavors of ``JA`` instructions. The
542``JMP`` class permits a 16-bit jump offset specified by the 'offset'
543field, whereas the ``JMP32`` class permits a 32-bit jump offset
544specified by the 'imm' field. A > 16-bit conditional jump may be
545converted to a < 16-bit conditional jump plus a 32-bit unconditional
546jump.
547
548All ``CALL`` and ``JA`` instructions belong to the
549base32 conformance group.
550
551Helper functions
552~~~~~~~~~~~~~~~~
553
554Helper functions are a concept whereby BPF programs can call into a
555set of function calls exposed by the underlying platform.
556
557Historically, each helper function was identified by a static ID
558encoded in the 'imm' field.  Further documentation of helper functions
559is outside the scope of this document and standardization is left for
560future work, but use is widely deployed and more information can be
561found in platform-specific documentation (e.g., Linux kernel documentation).
562
563Platforms that support the BPF Type Format (BTF) support identifying
564a helper function by a BTF ID encoded in the 'imm' field, where the BTF ID
565identifies the helper name and type.  Further documentation of BTF
566is outside the scope of this document and standardization is left for
567future work, but use is widely deployed and more information can be
568found in platform-specific documentation (e.g., Linux kernel documentation).
569
570Program-local functions
571~~~~~~~~~~~~~~~~~~~~~~~
572Program-local functions are functions exposed by the same BPF program as the
573caller, and are referenced by offset from the instruction following the call
574instruction, similar to ``JA``.  The offset is encoded in the 'imm' field of
575the call instruction. An ``EXIT`` within the program-local function will
576return to the caller.
577
578Load and store instructions
579===========================
580
581For load and store instructions (``LD``, ``LDX``, ``ST``, and ``STX``), the
5828-bit 'opcode' field is divided as follows::
583
584  +-+-+-+-+-+-+-+-+
585  |mode |sz |class|
586  +-+-+-+-+-+-+-+-+
587
588**mode**
589  The mode modifier is one of:
590
591  .. table:: Mode modifier
592
593    =============  =====  ====================================  =============
594    mode modifier  value  description                           reference
595    =============  =====  ====================================  =============
596    IMM            0      64-bit immediate instructions         `64-bit immediate instructions`_
597    ABS            1      legacy BPF packet access (absolute)   `Legacy BPF Packet access instructions`_
598    IND            2      legacy BPF packet access (indirect)   `Legacy BPF Packet access instructions`_
599    MEM            3      regular load and store operations     `Regular load and store operations`_
600    MEMSX          4      sign-extension load operations        `Sign-extension load operations`_
601    ATOMIC         6      atomic operations                     `Atomic operations`_
602    =============  =====  ====================================  =============
603
604**sz (size)**
605  The size modifier is one of:
606
607  .. table:: Size modifier
608
609    ====  =====  =====================
610    size  value  description
611    ====  =====  =====================
612    W     0      word        (4 bytes)
613    H     1      half word   (2 bytes)
614    B     2      byte
615    DW    3      double word (8 bytes)
616    ====  =====  =====================
617
618  Instructions using ``DW`` belong to the base64 conformance group.
619
620**class**
621  The instruction class (see `Instruction classes`_)
622
623Regular load and store operations
624---------------------------------
625
626The ``MEM`` mode modifier is used to encode regular load and store
627instructions that transfer data between a register and memory.
628
629``{MEM, <size>, STX}`` means::
630
631  *(size *) (dst + offset) = src
632
633``{MEM, <size>, ST}`` means::
634
635  *(size *) (dst + offset) = imm
636
637``{MEM, <size>, LDX}`` means::
638
639  dst = *(unsigned size *) (src + offset)
640
641Where '<size>' is one of: ``B``, ``H``, ``W``, or ``DW``, and
642'unsigned size' is one of: u8, u16, u32, or u64.
643
644Sign-extension load operations
645------------------------------
646
647The ``MEMSX`` mode modifier is used to encode :term:`sign-extension<Sign Extend>` load
648instructions that transfer data between a register and memory.
649
650``{MEMSX, <size>, LDX}`` means::
651
652  dst = *(signed size *) (src + offset)
653
654Where '<size>' is one of: ``B``, ``H``, or ``W``, and
655'signed size' is one of: s8, s16, or s32.
656
657Atomic operations
658-----------------
659
660Atomic operations are operations that operate on memory and can not be
661interrupted or corrupted by other access to the same memory region
662by other BPF programs or means outside of this specification.
663
664All atomic operations supported by BPF are encoded as store operations
665that use the ``ATOMIC`` mode modifier as follows:
666
667* ``{ATOMIC, W, STX}`` for 32-bit operations, which are
668  part of the "atomic32" conformance group.
669* ``{ATOMIC, DW, STX}`` for 64-bit operations, which are
670  part of the "atomic64" conformance group.
671* 8-bit and 16-bit wide atomic operations are not supported.
672
673The 'imm' field is used to encode the actual atomic operation.
674Simple atomic operation use a subset of the values defined to encode
675arithmetic operations in the 'imm' field to encode the atomic operation:
676
677.. table:: Simple atomic operations
678
679  ========  =====  ===========
680  imm       value  description
681  ========  =====  ===========
682  ADD       0x00   atomic add
683  OR        0x40   atomic or
684  AND       0x50   atomic and
685  XOR       0xa0   atomic xor
686  ========  =====  ===========
687
688
689``{ATOMIC, W, STX}`` with 'imm' = ADD means::
690
691  *(u32 *)(dst + offset) += src
692
693``{ATOMIC, DW, STX}`` with 'imm' = ADD means::
694
695  *(u64 *)(dst + offset) += src
696
697In addition to the simple atomic operations, there also is a modifier and
698two complex atomic operations:
699
700.. table:: Complex atomic operations
701
702  ===========  ================  ===========================
703  imm          value             description
704  ===========  ================  ===========================
705  FETCH        0x01              modifier: return old value
706  XCHG         0xe0 | FETCH      atomic exchange
707  CMPXCHG      0xf0 | FETCH      atomic compare and exchange
708  ===========  ================  ===========================
709
710The ``FETCH`` modifier is optional for simple atomic operations, and
711always set for the complex atomic operations.  If the ``FETCH`` flag
712is set, then the operation also overwrites ``src`` with the value that
713was in memory before it was modified.
714
715The ``XCHG`` operation atomically exchanges ``src`` with the value
716addressed by ``dst + offset``.
717
718The ``CMPXCHG`` operation atomically compares the value addressed by
719``dst + offset`` with ``R0``. If they match, the value addressed by
720``dst + offset`` is replaced with ``src``. In either case, the
721value that was at ``dst + offset`` before the operation is zero-extended
722and loaded back to ``R0``.
723
72464-bit immediate instructions
725-----------------------------
726
727Instructions with the ``IMM`` 'mode' modifier use the wide instruction
728encoding defined in `Instruction encoding`_, and use the 'src_reg' field of the
729basic instruction to hold an opcode subtype.
730
731The following table defines a set of ``{IMM, DW, LD}`` instructions
732with opcode subtypes in the 'src_reg' field, using new terms such as "map"
733defined further below:
734
735.. table:: 64-bit immediate instructions
736
737  =======  =========================================  ===========  ==============
738  src_reg  pseudocode                                 imm type     dst type
739  =======  =========================================  ===========  ==============
740  0x0      dst = (next_imm << 32) | imm               integer      integer
741  0x1      dst = map_by_fd(imm)                       map fd       map
742  0x2      dst = map_val(map_by_fd(imm)) + next_imm   map fd       data address
743  0x3      dst = var_addr(imm)                        variable id  data address
744  0x4      dst = code_addr(imm)                       integer      code address
745  0x5      dst = map_by_idx(imm)                      map index    map
746  0x6      dst = map_val(map_by_idx(imm)) + next_imm  map index    data address
747  =======  =========================================  ===========  ==============
748
749where
750
751* map_by_fd(imm) means to convert a 32-bit file descriptor into an address of a map (see `Maps`_)
752* map_by_idx(imm) means to convert a 32-bit index into an address of a map
753* map_val(map) gets the address of the first value in a given map
754* var_addr(imm) gets the address of a platform variable (see `Platform Variables`_) with a given id
755* code_addr(imm) gets the address of the instruction at a specified relative offset in number of (64-bit) instructions
756* the 'imm type' can be used by disassemblers for display
757* the 'dst type' can be used for verification and JIT compilation purposes
758
759Maps
760~~~~
761
762Maps are shared memory regions accessible by BPF programs on some platforms.
763A map can have various semantics as defined in a separate document, and may or
764may not have a single contiguous memory region, but the 'map_val(map)' is
765currently only defined for maps that do have a single contiguous memory region.
766
767Each map can have a file descriptor (fd) if supported by the platform, where
768'map_by_fd(imm)' means to get the map with the specified file descriptor. Each
769BPF program can also be defined to use a set of maps associated with the
770program at load time, and 'map_by_idx(imm)' means to get the map with the given
771index in the set associated with the BPF program containing the instruction.
772
773Platform Variables
774~~~~~~~~~~~~~~~~~~
775
776Platform variables are memory regions, identified by integer ids, exposed by
777the runtime and accessible by BPF programs on some platforms.  The
778'var_addr(imm)' operation means to get the address of the memory region
779identified by the given id.
780
781Legacy BPF Packet access instructions
782-------------------------------------
783
784BPF previously introduced special instructions for access to packet data that were
785carried over from classic BPF. These instructions used an instruction
786class of ``LD``, a size modifier of ``W``, ``H``, or ``B``, and a
787mode modifier of ``ABS`` or ``IND``.  The 'dst_reg' and 'offset' fields were
788set to zero, and 'src_reg' was set to zero for ``ABS``.  However, these
789instructions are deprecated and SHOULD no longer be used.  All legacy packet
790access instructions belong to the "packet" conformance group.
791