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