4 ========================================
5 eBPF Instruction Set Specification, v1.0
6 ========================================
8 This document specifies version 1.0 of the eBPF instruction set.
11 Registers and calling convention
12 ================================
14 eBPF has 10 general purpose registers and a read-only frame pointer register,
15 all of which are 64-bits wide.
17 The eBPF calling convention is defined as:
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
24 R0 - R5 are scratch registers and eBPF programs needs to spill/fill them if
25 necessary across calls.
30 eBPF has two instruction encodings:
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.
36 The basic instruction encoding looks as follows:
38 ============= ======= =============== ==================== ============
39 32 bits (MSB) 16 bits 4 bits 4 bits 8 bits (LSB)
40 ============= ======= =============== ==================== ============
41 immediate offset source register destination register opcode
42 ============= ======= =============== ==================== ============
44 Note that most instructions do not use all of the fields.
45 Unused fields shall be cleared to zero.
50 The three LSB bits of the 'opcode' field store the instruction class:
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 ========= ===== =============================== ===================================
65 Arithmetic and jump instructions
66 ================================
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:
71 ============== ====== =================
72 4 bits (MSB) 1 bit 3 bits (LSB)
73 ============== ====== =================
74 operation code source instruction class
75 ============== ====== =================
77 The 4th bit encodes the source operand:
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 ====== ===== ========================================
86 The four MSB bits store the operation code.
89 Arithmetic instructions
90 -----------------------
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:
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 ======== ===== ==========================================================
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.
122 ``BPF_ADD | BPF_X | BPF_ALU`` means::
124 dst_reg = (u32) dst_reg + (u32) src_reg;
126 ``BPF_ADD | BPF_X | BPF_ALU64`` means::
128 dst_reg = dst_reg + src_reg
130 ``BPF_XOR | BPF_K | BPF_ALU`` means::
132 src_reg = (u32) src_reg ^ (u32) imm32
134 ``BPF_XOR | BPF_K | BPF_ALU64`` means::
136 src_reg = src_reg ^ imm32
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.
144 Byte swap instructions
145 ~~~~~~~~~~~~~~~~~~~~~~
147 The byte swap instructions use an instruction class of ``BPF_ALU`` and a 4-bit
148 'code' field of ``BPF_END``.
150 The byte swap instructions operate on the destination register
151 only and do not use a separate source register or immediate value.
153 The 1-bit source operand field in the opcode is used to select what byte
154 order the operation convert from or to:
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 ========= ===== =================================================
163 The 'imm' field encodes the width of the swap operations. The following widths
164 are supported: 16, 32 and 64.
168 ``BPF_ALU | BPF_TO_LE | BPF_END`` with imm = 16 means::
170 dst_reg = htole16(dst_reg)
172 ``BPF_ALU | BPF_TO_BE | BPF_END`` with imm = 64 means::
174 dst_reg = htobe64(dst_reg)
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:
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 ======== ===== ========================= ============
202 The eBPF program needs to store the return value into register R0 before doing a
206 Load and store instructions
207 ===========================
209 For load and store instructions (``BPF_LD``, ``BPF_LDX``, ``BPF_ST``, and ``BPF_STX``), the
210 8-bit 'opcode' field is divided as:
212 ============ ====== =================
213 3 bits (MSB) 2 bits 3 bits (LSB)
214 ============ ====== =================
215 mode size instruction class
216 ============ ====== =================
218 The mode modifier is one of:
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 ============= ===== ==================================== =============
230 The size modifier is one of:
232 ============= ===== =====================
233 size modifier value description
234 ============= ===== =====================
235 BPF_W 0x00 word (4 bytes)
236 BPF_H 0x08 half word (2 bytes)
238 BPF_DW 0x18 double word (8 bytes)
239 ============= ===== =====================
241 Regular load and store operations
242 ---------------------------------
244 The ``BPF_MEM`` mode modifier is used to encode regular load and store
245 instructions that transfer data between a register and memory.
247 ``BPF_MEM | <size> | BPF_STX`` means::
249 *(size *) (dst_reg + off) = src_reg
251 ``BPF_MEM | <size> | BPF_ST`` means::
253 *(size *) (dst_reg + off) = imm32
255 ``BPF_MEM | <size> | BPF_LDX`` means::
257 dst_reg = *(size *) (src_reg + off)
259 Where size is one of: ``BPF_B``, ``BPF_H``, ``BPF_W``, or ``BPF_DW``.
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.
268 All atomic operations supported by eBPF are encoded as store operations
269 that use the ``BPF_ATOMIC`` mode modifier as follows:
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.
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:
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 ======== ===== ===========
289 ``BPF_ATOMIC | BPF_W | BPF_STX`` with 'imm' = BPF_ADD means::
291 *(u32 *)(dst_reg + off16) += src_reg
293 ``BPF_ATOMIC | BPF_DW | BPF_STX`` with 'imm' = BPF ADD means::
295 *(u64 *)(dst_reg + off16) += src_reg
297 In addition to the simple atomic operations, there also is a modifier and
298 two complex atomic operations:
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 =========== ================ ===========================
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.
313 The ``BPF_XCHG`` operation atomically exchanges ``src_reg`` with the value
314 addressed by ``dst_reg + off``.
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``.
322 64-bit immediate instructions
323 -----------------------------
325 Instructions with the ``BPF_IMM`` 'mode' modifier use the wide instruction
326 encoding for an extra imm64 value.
328 There is currently only one such instruction.
330 ``BPF_LD | BPF_DW | BPF_IMM`` means::
335 Legacy BPF Packet access instructions
336 -------------------------------------
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.