Loading...
Note: File does not exist in v6.13.7.
1.. contents::
2.. sectnum::
3
4========================================
5eBPF Instruction Set Specification, v1.0
6========================================
7
8This document specifies version 1.0 of the eBPF instruction set.
9
10
11Registers and calling convention
12================================
13
14eBPF has 10 general purpose registers and a read-only frame pointer register,
15all of which are 64-bits wide.
16
17The eBPF calling convention is defined as:
18
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
23
24R0 - R5 are scratch registers and eBPF programs needs to spill/fill them if
25necessary across calls.
26
27Instruction encoding
28====================
29
30eBPF has two instruction encodings:
31
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.
35
36The basic instruction encoding looks as follows:
37
38============= ======= =============== ==================== ============
3932 bits (MSB) 16 bits 4 bits 4 bits 8 bits (LSB)
40============= ======= =============== ==================== ============
41immediate offset source register destination register opcode
42============= ======= =============== ==================== ============
43
44Note that most instructions do not use all of the fields.
45Unused fields shall be cleared to zero.
46
47Instruction classes
48-------------------
49
50The three LSB bits of the 'opcode' field store the instruction class:
51
52========= ===== =============================== ===================================
53class value description reference
54========= ===== =============================== ===================================
55BPF_LD 0x00 non-standard load operations `Load and store instructions`_
56BPF_LDX 0x01 load into register operations `Load and store instructions`_
57BPF_ST 0x02 store from immediate operations `Load and store instructions`_
58BPF_STX 0x03 store from register operations `Load and store instructions`_
59BPF_ALU 0x04 32-bit arithmetic operations `Arithmetic and jump instructions`_
60BPF_JMP 0x05 64-bit jump operations `Arithmetic and jump instructions`_
61BPF_JMP32 0x06 32-bit jump operations `Arithmetic and jump instructions`_
62BPF_ALU64 0x07 64-bit arithmetic operations `Arithmetic and jump instructions`_
63========= ===== =============================== ===================================
64
65Arithmetic and jump instructions
66================================
67
68For arithmetic and jump instructions (``BPF_ALU``, ``BPF_ALU64``, ``BPF_JMP`` and
69``BPF_JMP32``), the 8-bit 'opcode' field is divided into three parts:
70
71============== ====== =================
724 bits (MSB) 1 bit 3 bits (LSB)
73============== ====== =================
74operation code source instruction class
75============== ====== =================
76
77The 4th bit encodes the source operand:
78
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 ====== ===== ========================================
85
86The four MSB bits store the operation code.
87
88
89Arithmetic instructions
90-----------------------
91
92``BPF_ALU`` uses 32-bit wide operands while ``BPF_ALU64`` uses 64-bit wide operands for
93otherwise identical operations.
94The 'code' field encodes the operation as below:
95
96======== ===== ==========================================================
97code value description
98======== ===== ==========================================================
99BPF_ADD 0x00 dst += src
100BPF_SUB 0x10 dst -= src
101BPF_MUL 0x20 dst \*= src
102BPF_DIV 0x30 dst /= src
103BPF_OR 0x40 dst \|= src
104BPF_AND 0x50 dst &= src
105BPF_LSH 0x60 dst <<= src
106BPF_RSH 0x70 dst >>= src
107BPF_NEG 0x80 dst = ~src
108BPF_MOD 0x90 dst %= src
109BPF_XOR 0xa0 dst ^= src
110BPF_MOV 0xb0 dst = src
111BPF_ARSH 0xc0 sign extending shift right
112BPF_END 0xd0 byte swap operations (see `Byte swap instructions`_ below)
113======== ===== ==========================================================
114
115``BPF_ADD | BPF_X | BPF_ALU`` means::
116
117 dst_reg = (u32) dst_reg + (u32) src_reg;
118
119``BPF_ADD | BPF_X | BPF_ALU64`` means::
120
121 dst_reg = dst_reg + src_reg
122
123``BPF_XOR | BPF_K | BPF_ALU`` means::
124
125 dst_reg = (u32) dst_reg ^ (u32) imm32
126
127``BPF_XOR | BPF_K | BPF_ALU64`` means::
128
129 dst_reg = dst_reg ^ imm32
130
131
132Byte swap instructions
133~~~~~~~~~~~~~~~~~~~~~~
134
135The byte swap instructions use an instruction class of ``BPF_ALU`` and a 4-bit
136'code' field of ``BPF_END``.
137
138The byte swap instructions operate on the destination register
139only and do not use a separate source register or immediate value.
140
141The 1-bit source operand field in the opcode is used to select what byte
142order the operation convert from or to:
143
144========= ===== =================================================
145source value description
146========= ===== =================================================
147BPF_TO_LE 0x00 convert between host byte order and little endian
148BPF_TO_BE 0x08 convert between host byte order and big endian
149========= ===== =================================================
150
151The 'imm' field encodes the width of the swap operations. The following widths
152are supported: 16, 32 and 64.
153
154Examples:
155
156``BPF_ALU | BPF_TO_LE | BPF_END`` with imm = 16 means::
157
158 dst_reg = htole16(dst_reg)
159
160``BPF_ALU | BPF_TO_BE | BPF_END`` with imm = 64 means::
161
162 dst_reg = htobe64(dst_reg)
163
164Jump instructions
165-----------------
166
167``BPF_JMP32`` uses 32-bit wide operands while ``BPF_JMP`` uses 64-bit wide operands for
168otherwise identical operations.
169The 'code' field encodes the operation as below:
170
171======== ===== ========================= ============
172code value description notes
173======== ===== ========================= ============
174BPF_JA 0x00 PC += off BPF_JMP only
175BPF_JEQ 0x10 PC += off if dst == src
176BPF_JGT 0x20 PC += off if dst > src unsigned
177BPF_JGE 0x30 PC += off if dst >= src unsigned
178BPF_JSET 0x40 PC += off if dst & src
179BPF_JNE 0x50 PC += off if dst != src
180BPF_JSGT 0x60 PC += off if dst > src signed
181BPF_JSGE 0x70 PC += off if dst >= src signed
182BPF_CALL 0x80 function call
183BPF_EXIT 0x90 function / program return BPF_JMP only
184BPF_JLT 0xa0 PC += off if dst < src unsigned
185BPF_JLE 0xb0 PC += off if dst <= src unsigned
186BPF_JSLT 0xc0 PC += off if dst < src signed
187BPF_JSLE 0xd0 PC += off if dst <= src signed
188======== ===== ========================= ============
189
190The eBPF program needs to store the return value into register R0 before doing a
191BPF_EXIT.
192
193
194Load and store instructions
195===========================
196
197For load and store instructions (``BPF_LD``, ``BPF_LDX``, ``BPF_ST``, and ``BPF_STX``), the
1988-bit 'opcode' field is divided as:
199
200============ ====== =================
2013 bits (MSB) 2 bits 3 bits (LSB)
202============ ====== =================
203mode size instruction class
204============ ====== =================
205
206The mode modifier is one of:
207
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 ============= ===== ==================================== =============
217
218The size modifier is one of:
219
220 ============= ===== =====================
221 size modifier value description
222 ============= ===== =====================
223 BPF_W 0x00 word (4 bytes)
224 BPF_H 0x08 half word (2 bytes)
225 BPF_B 0x10 byte
226 BPF_DW 0x18 double word (8 bytes)
227 ============= ===== =====================
228
229Regular load and store operations
230---------------------------------
231
232The ``BPF_MEM`` mode modifier is used to encode regular load and store
233instructions that transfer data between a register and memory.
234
235``BPF_MEM | <size> | BPF_STX`` means::
236
237 *(size *) (dst_reg + off) = src_reg
238
239``BPF_MEM | <size> | BPF_ST`` means::
240
241 *(size *) (dst_reg + off) = imm32
242
243``BPF_MEM | <size> | BPF_LDX`` means::
244
245 dst_reg = *(size *) (src_reg + off)
246
247Where size is one of: ``BPF_B``, ``BPF_H``, ``BPF_W``, or ``BPF_DW``.
248
249Atomic operations
250-----------------
251
252Atomic operations are operations that operate on memory and can not be
253interrupted or corrupted by other access to the same memory region
254by other eBPF programs or means outside of this specification.
255
256All atomic operations supported by eBPF are encoded as store operations
257that use the ``BPF_ATOMIC`` mode modifier as follows:
258
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.
262
263The 'imm' field is used to encode the actual atomic operation.
264Simple atomic operation use a subset of the values defined to encode
265arithmetic operations in the 'imm' field to encode the atomic operation:
266
267======== ===== ===========
268imm value description
269======== ===== ===========
270BPF_ADD 0x00 atomic add
271BPF_OR 0x40 atomic or
272BPF_AND 0x50 atomic and
273BPF_XOR 0xa0 atomic xor
274======== ===== ===========
275
276
277``BPF_ATOMIC | BPF_W | BPF_STX`` with 'imm' = BPF_ADD means::
278
279 *(u32 *)(dst_reg + off16) += src_reg
280
281``BPF_ATOMIC | BPF_DW | BPF_STX`` with 'imm' = BPF ADD means::
282
283 *(u64 *)(dst_reg + off16) += src_reg
284
285In addition to the simple atomic operations, there also is a modifier and
286two complex atomic operations:
287
288=========== ================ ===========================
289imm value description
290=========== ================ ===========================
291BPF_FETCH 0x01 modifier: return old value
292BPF_XCHG 0xe0 | BPF_FETCH atomic exchange
293BPF_CMPXCHG 0xf0 | BPF_FETCH atomic compare and exchange
294=========== ================ ===========================
295
296The ``BPF_FETCH`` modifier is optional for simple atomic operations, and
297always set for the complex atomic operations. If the ``BPF_FETCH`` flag
298is set, then the operation also overwrites ``src_reg`` with the value that
299was in memory before it was modified.
300
301The ``BPF_XCHG`` operation atomically exchanges ``src_reg`` with the value
302addressed by ``dst_reg + off``.
303
304The ``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
307value that was at ``dst_reg + off`` before the operation is zero-extended
308and loaded back to ``R0``.
309
31064-bit immediate instructions
311-----------------------------
312
313Instructions with the ``BPF_IMM`` 'mode' modifier use the wide instruction
314encoding for an extra imm64 value.
315
316There is currently only one such instruction.
317
318``BPF_LD | BPF_DW | BPF_IMM`` means::
319
320 dst_reg = imm64
321
322
323Legacy BPF Packet access instructions
324-------------------------------------
325
326eBPF previously introduced special instructions for access to packet data that were
327carried over from classic BPF. However, these instructions are
328deprecated and should no longer be used.