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
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
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 ``BPF_ADD | BPF_X | BPF_ALU`` means::
117 dst_reg = (u32) dst_reg + (u32) src_reg;
119 ``BPF_ADD | BPF_X | BPF_ALU64`` means::
121 dst_reg = dst_reg + src_reg
123 ``BPF_XOR | BPF_K | BPF_ALU`` means::
125 dst_reg = (u32) dst_reg ^ (u32) imm32
127 ``BPF_XOR | BPF_K | BPF_ALU64`` means::
129 dst_reg = dst_reg ^ imm32
132 Byte swap instructions
133 ~~~~~~~~~~~~~~~~~~~~~~
135 The byte swap instructions use an instruction class of ``BPF_ALU`` and a 4-bit
136 'code' field of ``BPF_END``.
138 The byte swap instructions operate on the destination register
139 only and do not use a separate source register or immediate value.
141 The 1-bit source operand field in the opcode is used to select what byte
142 order the operation convert from or to:
144 ========= ===== =================================================
145 source value description
146 ========= ===== =================================================
147 BPF_TO_LE 0x00 convert between host byte order and little endian
148 BPF_TO_BE 0x08 convert between host byte order and big endian
149 ========= ===== =================================================
151 The 'imm' field encodes the width of the swap operations. The following widths
152 are supported: 16, 32 and 64.
156 ``BPF_ALU | BPF_TO_LE | BPF_END`` with imm = 16 means::
158 dst_reg = htole16(dst_reg)
160 ``BPF_ALU | BPF_TO_BE | BPF_END`` with imm = 64 means::
162 dst_reg = htobe64(dst_reg)
167 ``BPF_JMP32`` uses 32-bit wide operands while ``BPF_JMP`` uses 64-bit wide operands for
168 otherwise identical operations.
169 The 'code' field encodes the operation as below:
171 ======== ===== ========================= ============
172 code value description notes
173 ======== ===== ========================= ============
174 BPF_JA 0x00 PC += off BPF_JMP only
175 BPF_JEQ 0x10 PC += off if dst == src
176 BPF_JGT 0x20 PC += off if dst > src unsigned
177 BPF_JGE 0x30 PC += off if dst >= src unsigned
178 BPF_JSET 0x40 PC += off if dst & src
179 BPF_JNE 0x50 PC += off if dst != src
180 BPF_JSGT 0x60 PC += off if dst > src signed
181 BPF_JSGE 0x70 PC += off if dst >= src signed
182 BPF_CALL 0x80 function call
183 BPF_EXIT 0x90 function / program return BPF_JMP only
184 BPF_JLT 0xa0 PC += off if dst < src unsigned
185 BPF_JLE 0xb0 PC += off if dst <= src unsigned
186 BPF_JSLT 0xc0 PC += off if dst < src signed
187 BPF_JSLE 0xd0 PC += off if dst <= src signed
188 ======== ===== ========================= ============
190 The eBPF program needs to store the return value into register R0 before doing a
194 Load and store instructions
195 ===========================
197 For load and store instructions (``BPF_LD``, ``BPF_LDX``, ``BPF_ST``, and ``BPF_STX``), the
198 8-bit 'opcode' field is divided as:
200 ============ ====== =================
201 3 bits (MSB) 2 bits 3 bits (LSB)
202 ============ ====== =================
203 mode size instruction class
204 ============ ====== =================
206 The mode modifier is one of:
208 ============= ===== ==================================== =============
209 mode modifier value description reference
210 ============= ===== ==================================== =============
211 BPF_IMM 0x00 64-bit immediate instructions `64-bit immediate instructions`_
212 BPF_ABS 0x20 legacy BPF packet access (absolute) `Legacy BPF Packet access instructions`_
213 BPF_IND 0x40 legacy BPF packet access (indirect) `Legacy BPF Packet access instructions`_
214 BPF_MEM 0x60 regular load and store operations `Regular load and store operations`_
215 BPF_ATOMIC 0xc0 atomic operations `Atomic operations`_
216 ============= ===== ==================================== =============
218 The size modifier is one of:
220 ============= ===== =====================
221 size modifier value description
222 ============= ===== =====================
223 BPF_W 0x00 word (4 bytes)
224 BPF_H 0x08 half word (2 bytes)
226 BPF_DW 0x18 double word (8 bytes)
227 ============= ===== =====================
229 Regular load and store operations
230 ---------------------------------
232 The ``BPF_MEM`` mode modifier is used to encode regular load and store
233 instructions that transfer data between a register and memory.
235 ``BPF_MEM | <size> | BPF_STX`` means::
237 *(size *) (dst_reg + off) = src_reg
239 ``BPF_MEM | <size> | BPF_ST`` means::
241 *(size *) (dst_reg + off) = imm32
243 ``BPF_MEM | <size> | BPF_LDX`` means::
245 dst_reg = *(size *) (src_reg + off)
247 Where size is one of: ``BPF_B``, ``BPF_H``, ``BPF_W``, or ``BPF_DW``.
252 Atomic operations are operations that operate on memory and can not be
253 interrupted or corrupted by other access to the same memory region
254 by other eBPF programs or means outside of this specification.
256 All atomic operations supported by eBPF are encoded as store operations
257 that use the ``BPF_ATOMIC`` mode modifier as follows:
259 * ``BPF_ATOMIC | BPF_W | BPF_STX`` for 32-bit operations
260 * ``BPF_ATOMIC | BPF_DW | BPF_STX`` for 64-bit operations
261 * 8-bit and 16-bit wide atomic operations are not supported.
263 The 'imm' field is used to encode the actual atomic operation.
264 Simple atomic operation use a subset of the values defined to encode
265 arithmetic operations in the 'imm' field to encode the atomic operation:
267 ======== ===== ===========
268 imm value description
269 ======== ===== ===========
270 BPF_ADD 0x00 atomic add
271 BPF_OR 0x40 atomic or
272 BPF_AND 0x50 atomic and
273 BPF_XOR 0xa0 atomic xor
274 ======== ===== ===========
277 ``BPF_ATOMIC | BPF_W | BPF_STX`` with 'imm' = BPF_ADD means::
279 *(u32 *)(dst_reg + off16) += src_reg
281 ``BPF_ATOMIC | BPF_DW | BPF_STX`` with 'imm' = BPF ADD means::
283 *(u64 *)(dst_reg + off16) += src_reg
285 In addition to the simple atomic operations, there also is a modifier and
286 two complex atomic operations:
288 =========== ================ ===========================
289 imm value description
290 =========== ================ ===========================
291 BPF_FETCH 0x01 modifier: return old value
292 BPF_XCHG 0xe0 | BPF_FETCH atomic exchange
293 BPF_CMPXCHG 0xf0 | BPF_FETCH atomic compare and exchange
294 =========== ================ ===========================
296 The ``BPF_FETCH`` modifier is optional for simple atomic operations, and
297 always set for the complex atomic operations. If the ``BPF_FETCH`` flag
298 is set, then the operation also overwrites ``src_reg`` with the value that
299 was in memory before it was modified.
301 The ``BPF_XCHG`` operation atomically exchanges ``src_reg`` with the value
302 addressed by ``dst_reg + off``.
304 The ``BPF_CMPXCHG`` operation atomically compares the value addressed by
305 ``dst_reg + off`` with ``R0``. If they match, the value addressed by
306 ``dst_reg + off`` is replaced with ``src_reg``. In either case, the
307 value that was at ``dst_reg + off`` before the operation is zero-extended
308 and loaded back to ``R0``.
310 64-bit immediate instructions
311 -----------------------------
313 Instructions with the ``BPF_IMM`` 'mode' modifier use the wide instruction
314 encoding for an extra imm64 value.
316 There is currently only one such instruction.
318 ``BPF_LD | BPF_DW | BPF_IMM`` means::
323 Legacy BPF Packet access instructions
324 -------------------------------------
326 eBPF previously introduced special instructions for access to packet data that were
327 carried over from classic BPF. However, these instructions are
328 deprecated and should no longer be used.