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 108
179 **class** !! 109 The fields conforming an encoded basic instruction are stored in the
180 The instruction class (see `Instruction cl !! 110 following order::
181 111
182 **regs** !! 112 opcode:8 src_reg:4 dst_reg:4 offset:16 imm:32 // In little-endian BPF.
183 The source and destination register numbers, !! 113 opcode:8 dst_reg:4 src_reg:4 offset:16 imm:32 // In big-endian BPF.
184 on a little-endian host:: <<
185 114
186 +-+-+-+-+-+-+-+-+ !! 115 **imm**
187 |src_reg|dst_reg| !! 116 signed integer immediate value
188 +-+-+-+-+-+-+-+-+ <<
189 <<
190 and as follows on a big-endian host:: <<
191 <<
192 +-+-+-+-+-+-+-+-+ <<
193 |dst_reg|src_reg| <<
194 +-+-+-+-+-+-+-+-+ <<
195 117
196 **src_reg** !! 118 **offset**
197 the source register number (0-10), except !! 119 signed integer offset used with pointer arithmetic
198 (`64-bit immediate instructions`_ reuse th <<
199 120
200 **dst_reg** !! 121 **src_reg**
201 destination register number (0-10), unless !! 122 the source register number (0-10), except where otherwise specified
202 (future instructions might reuse this fiel !! 123 (`64-bit immediate instructions`_ reuse this field for other purposes)
203 124
204 **offset** !! 125 **dst_reg**
205 signed integer offset used with pointer arit !! 126 destination register number (0-10)
206 otherwise specified (some arithmetic instruc <<
207 for other purposes) <<
208 127
209 **imm** !! 128 **opcode**
210 signed integer immediate value !! 129 operation to perform
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 174
272 .. table:: Instruction class !! 175 ========= ===== =============================== ===================================
273 !! 176 class value description reference
274 ===== ===== ============================== !! 177 ========= ===== =============================== ===================================
275 class value description !! 178 BPF_LD 0x00 non-standard load operations `Load and store instructions`_
276 ===== ===== ============================== !! 179 BPF_LDX 0x01 load into register operations `Load and store instructions`_
277 LD 0x0 non-standard load operations !! 180 BPF_ST 0x02 store from immediate operations `Load and store instructions`_
278 LDX 0x1 load into register operations !! 181 BPF_STX 0x03 store from register operations `Load and store instructions`_
279 ST 0x2 store from immediate operation !! 182 BPF_ALU 0x04 32-bit arithmetic operations `Arithmetic and jump instructions`_
280 STX 0x3 store from register operations !! 183 BPF_JMP 0x05 64-bit jump operations `Arithmetic and jump instructions`_
281 ALU 0x4 32-bit arithmetic operations !! 184 BPF_JMP32 0x06 32-bit jump operations `Arithmetic and jump instructions`_
282 JMP 0x5 64-bit jump operations !! 185 BPF_ALU64 0x07 64-bit arithmetic operations `Arithmetic and jump instructions`_
283 JMP32 0x6 32-bit jump operations !! 186 ========= ===== =============================== ===================================
284 ALU64 0x7 64-bit arithmetic operations <<
285 ===== ===== ============================== <<
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 Note that there are varying definitions of the signed modulo operation
394 when the dividend or divisor are negative, whe 287 when the dividend or divisor are negative, where implementations often
395 vary by language such that Python, Ruby, etc. 288 vary by language such that Python, Ruby, etc. differ from C, Go, Java,
396 etc. This specification requires that signed m !! 289 etc. This specification requires that signed modulo use truncated division
397 (where -13 % 3 == -1) as implemented in C, Go, !! 290 (where -13 % 3 == -1) as implemented in C, Go, etc.:
398 291
399 a % n = a - n * trunc(a / n) 292 a % n = a - n * trunc(a / n)
400 293
401 The ``MOVSX`` instruction does a move operatio !! 294 The ``BPF_MOVSX`` instruction does a move operation with sign extension.
402 ``{MOVSX, X, ALU}`` :term:`sign extends<Sign E !! 295 ``BPF_ALU | BPF_MOVSX`` :term:`sign extends<Sign Extend>` 8-bit and 16-bit operands into 32
403 32-bit operands, and zeroes the remaining uppe !! 296 bit operands, and zeroes the remaining upper 32 bits.
404 ``{MOVSX, X, ALU64}`` :term:`sign extends<Sign !! 297 ``BPF_ALU64 | BPF_MOVSX`` :term:`sign extends<Sign Extend>` 8-bit, 16-bit, and 32-bit
405 operands into 64-bit operands. Unlike other a !! 298 operands into 64 bit operands.
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 299
424 Shift operations use a mask of 0x3F (63) for 6 300 Shift operations use a mask of 0x3F (63) for 64-bit operations and 0x1F (31)
425 for 32-bit operations. 301 for 32-bit operations.
426 302
427 Byte swap instructions 303 Byte swap instructions
428 ---------------------- 304 ----------------------
429 305
430 The byte swap instructions use instruction cla !! 306 The byte swap instructions use instruction classes of ``BPF_ALU`` and ``BPF_ALU64``
431 and a 4-bit 'code' field of ``END``. !! 307 and a 4-bit 'code' field of ``BPF_END``.
432 308
433 The byte swap instructions operate on the dest 309 The byte swap instructions operate on the destination register
434 only and do not use a separate source register 310 only and do not use a separate source register or immediate value.
435 311
436 For ``ALU``, the 1-bit source operand field in !! 312 For ``BPF_ALU``, the 1-bit source operand field in the opcode is used to
437 select what byte order the operation converts 313 select what byte order the operation converts from or to. For
438 ``ALU64``, the 1-bit source operand field in t !! 314 ``BPF_ALU64``, the 1-bit source operand field in the opcode is reserved
439 and MUST be set to 0. !! 315 and must be set to 0.
440 316
441 .. table:: Byte swap instructions !! 317 ========= ========= ===== =================================================
442 !! 318 class source value description
443 ===== ======== ===== ==================== !! 319 ========= ========= ===== =================================================
444 class source value description !! 320 BPF_ALU BPF_TO_LE 0x00 convert between host byte order and little endian
445 ===== ======== ===== ==================== !! 321 BPF_ALU BPF_TO_BE 0x08 convert between host byte order and big endian
446 ALU LE 0 convert between host !! 322 BPF_ALU64 Reserved 0x00 do byte swap unconditionally
447 ALU BE 1 convert between host !! 323 ========= ========= ===== =================================================
448 ALU64 Reserved 0 do byte swap uncondi <<
449 ===== ======== ===== ==================== <<
450 324
451 The 'imm' field encodes the width of the swap 325 The 'imm' field encodes the width of the swap operations. The following widths
452 are supported: 16, 32 and 64. Width 64 operat !! 326 are supported: 16, 32 and 64.
453 conformance group and other swap operations be <<
454 conformance group. <<
455 327
456 Examples: 328 Examples:
457 329
458 ``{END, LE, ALU}`` with 'imm' = 16/32/64 means !! 330 ``BPF_ALU | BPF_TO_LE | BPF_END`` with imm = 16/32/64 means::
459 331
460 dst = le16(dst) !! 332 dst = htole16(dst)
461 dst = le32(dst) !! 333 dst = htole32(dst)
462 dst = le64(dst) !! 334 dst = htole64(dst)
463 335
464 ``{END, BE, ALU}`` with 'imm' = 16/32/64 means !! 336 ``BPF_ALU | BPF_TO_BE | BPF_END`` with imm = 16/32/64 means::
465 337
466 dst = be16(dst) !! 338 dst = htobe16(dst)
467 dst = be32(dst) !! 339 dst = htobe32(dst)
468 dst = be64(dst) !! 340 dst = htobe64(dst)
469 341
470 ``{END, TO, ALU64}`` with 'imm' = 16/32/64 mea !! 342 ``BPF_ALU64 | BPF_TO_LE | BPF_END`` with imm = 16/32/64 means::
471 343
472 dst = bswap16(dst) 344 dst = bswap16(dst)
473 dst = bswap32(dst) 345 dst = bswap32(dst)
474 dst = bswap64(dst) 346 dst = bswap64(dst)
475 347
476 Jump instructions 348 Jump instructions
477 ----------------- 349 -----------------
478 350
479 ``JMP32`` uses 32-bit wide operands and indica !! 351 ``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 !! 352 otherwise identical operations.
481 otherwise identical operations, and indicates <<
482 group unless otherwise specified. <<
483 The 'code' field encodes the operation as belo 353 The 'code' field encodes the operation as below:
484 354
485 .. table:: Jump instructions !! 355 ======== ===== === =========================================== =========================================
>> 356 code value src description notes
>> 357 ======== ===== === =========================================== =========================================
>> 358 BPF_JA 0x0 0x0 PC += offset BPF_JMP class
>> 359 BPF_JA 0x0 0x0 PC += imm BPF_JMP32 class
>> 360 BPF_JEQ 0x1 any PC += offset if dst == src
>> 361 BPF_JGT 0x2 any PC += offset if dst > src unsigned
>> 362 BPF_JGE 0x3 any PC += offset if dst >= src unsigned
>> 363 BPF_JSET 0x4 any PC += offset if dst & src
>> 364 BPF_JNE 0x5 any PC += offset if dst != src
>> 365 BPF_JSGT 0x6 any PC += offset if dst > src signed
>> 366 BPF_JSGE 0x7 any PC += offset if dst >= src signed
>> 367 BPF_CALL 0x8 0x0 call helper function by address see `Helper functions`_
>> 368 BPF_CALL 0x8 0x1 call PC += imm see `Program-local functions`_
>> 369 BPF_CALL 0x8 0x2 call helper function by BTF ID see `Helper functions`_
>> 370 BPF_EXIT 0x9 0x0 return BPF_JMP only
>> 371 BPF_JLT 0xa any PC += offset if dst < src unsigned
>> 372 BPF_JLE 0xb any PC += offset if dst <= src unsigned
>> 373 BPF_JSLT 0xc any PC += offset if dst < src signed
>> 374 BPF_JSLE 0xd any PC += offset if dst <= src signed
>> 375 ======== ===== === =========================================== =========================================
486 376
487 ======== ===== ======= ================== !! 377 The BPF program needs to store the return value into register R0 before doing a
488 code value src_reg description !! 378 ``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 379
515 Example: 380 Example:
516 381
517 ``{JSGE, X, JMP32}`` means:: !! 382 ``BPF_JSGE | BPF_X | BPF_JMP32`` (0x7e) means::
518 383
519 if (s32)dst s>= (s32)src goto +offset 384 if (s32)dst s>= (s32)src goto +offset
520 385
521 where 's>=' indicates a signed '>=' comparison 386 where 's>=' indicates a signed '>=' comparison.
522 387
523 ``{JLE, K, JMP}`` means:: !! 388 ``BPF_JA | BPF_K | BPF_JMP32`` (0x06) means::
524 <<
525 if dst <= (u64)(s64)imm goto +offset <<
526 <<
527 ``{JA, K, JMP32}`` means:: <<
528 389
529 gotol +imm 390 gotol +imm
530 391
531 where 'imm' means the branch offset comes from !! 392 where 'imm' means the branch offset comes from insn 'imm' field.
532 393
533 Note that there are two flavors of ``JA`` inst !! 394 Note that there are two flavors of ``BPF_JA`` instructions. The
534 ``JMP`` class permits a 16-bit jump offset spe !! 395 ``BPF_JMP`` class permits a 16-bit jump offset specified by the 'offset'
535 field, whereas the ``JMP32`` class permits a 3 !! 396 field, whereas the ``BPF_JMP32`` class permits a 32-bit jump offset
536 specified by the 'imm' field. A > 16-bit condi 397 specified by the 'imm' field. A > 16-bit conditional jump may be
537 converted to a < 16-bit conditional jump plus 398 converted to a < 16-bit conditional jump plus a 32-bit unconditional
538 jump. 399 jump.
539 400
540 All ``CALL`` and ``JA`` instructions belong to <<
541 base32 conformance group. <<
542 <<
543 Helper functions 401 Helper functions
544 ~~~~~~~~~~~~~~~~ 402 ~~~~~~~~~~~~~~~~
545 403
546 Helper functions are a concept whereby BPF pro 404 Helper functions are a concept whereby BPF programs can call into a
547 set of function calls exposed by the underlyin 405 set of function calls exposed by the underlying platform.
548 406
549 Historically, each helper function was identif !! 407 Historically, each helper function was identified by an address
550 encoded in the 'imm' field. Further documenta !! 408 encoded in the imm field. The available helper functions may differ
551 is outside the scope of this document and stan !! 409 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 410
555 Platforms that support the BPF Type Format (BT 411 Platforms that support the BPF Type Format (BTF) support identifying
556 a helper function by a BTF ID encoded in the ' !! 412 a helper function by a BTF ID encoded in the imm field, where the BTF ID
557 identifies the helper name and type. Further !! 413 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 414
562 Program-local functions 415 Program-local functions
563 ~~~~~~~~~~~~~~~~~~~~~~~ 416 ~~~~~~~~~~~~~~~~~~~~~~~
564 Program-local functions are functions exposed 417 Program-local functions are functions exposed by the same BPF program as the
565 caller, and are referenced by offset from the !! 418 caller, and are referenced by offset from the call instruction, similar to
566 instruction, similar to ``JA``. The offset is !! 419 ``BPF_JA``. The offset is encoded in the imm field of the call instruction.
567 the call instruction. An ``EXIT`` within the p !! 420 A ``BPF_EXIT`` within the program-local function will return to the caller.
568 return to the caller. <<
569 421
570 Load and store instructions 422 Load and store instructions
571 =========================== 423 ===========================
572 424
573 For load and store instructions (``LD``, ``LDX !! 425 For load and store instructions (``BPF_LD``, ``BPF_LDX``, ``BPF_ST``, and ``BPF_STX``), the
574 8-bit 'opcode' field is divided as follows:: !! 426 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 427
612 **class** !! 428 ============ ====== =================
613 The instruction class (see `Instruction clas !! 429 3 bits (MSB) 2 bits 3 bits (LSB)
>> 430 ============ ====== =================
>> 431 mode size instruction class
>> 432 ============ ====== =================
>> 433
>> 434 The mode modifier is one of:
>> 435
>> 436 ============= ===== ==================================== =============
>> 437 mode modifier value description reference
>> 438 ============= ===== ==================================== =============
>> 439 BPF_IMM 0x00 64-bit immediate instructions `64-bit immediate instructions`_
>> 440 BPF_ABS 0x20 legacy BPF packet access (absolute) `Legacy BPF Packet access instructions`_
>> 441 BPF_IND 0x40 legacy BPF packet access (indirect) `Legacy BPF Packet access instructions`_
>> 442 BPF_MEM 0x60 regular load and store operations `Regular load and store operations`_
>> 443 BPF_MEMSX 0x80 sign-extension load operations `Sign-extension load operations`_
>> 444 BPF_ATOMIC 0xc0 atomic operations `Atomic operations`_
>> 445 ============= ===== ==================================== =============
>> 446
>> 447 The size modifier is one of:
>> 448
>> 449 ============= ===== =====================
>> 450 size modifier value description
>> 451 ============= ===== =====================
>> 452 BPF_W 0x00 word (4 bytes)
>> 453 BPF_H 0x08 half word (2 bytes)
>> 454 BPF_B 0x10 byte
>> 455 BPF_DW 0x18 double word (8 bytes)
>> 456 ============= ===== =====================
614 457
615 Regular load and store operations 458 Regular load and store operations
616 --------------------------------- 459 ---------------------------------
617 460
618 The ``MEM`` mode modifier is used to encode re !! 461 The ``BPF_MEM`` mode modifier is used to encode regular load and store
619 instructions that transfer data between a regi 462 instructions that transfer data between a register and memory.
620 463
621 ``{MEM, <size>, STX}`` means:: !! 464 ``BPF_MEM | <size> | BPF_STX`` means::
622 465
623 *(size *) (dst + offset) = src 466 *(size *) (dst + offset) = src
624 467
625 ``{MEM, <size>, ST}`` means:: !! 468 ``BPF_MEM | <size> | BPF_ST`` means::
626 469
627 *(size *) (dst + offset) = imm !! 470 *(size *) (dst + offset) = imm32
628 471
629 ``{MEM, <size>, LDX}`` means:: !! 472 ``BPF_MEM | <size> | BPF_LDX`` means::
630 473
631 dst = *(unsigned size *) (src + offset) 474 dst = *(unsigned size *) (src + offset)
632 475
633 Where '<size>' is one of: ``B``, ``H``, ``W``, !! 476 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 !! 477 'unsigned size' is one of u8, u16, u32 or u64.
635 478
636 Sign-extension load operations 479 Sign-extension load operations
637 ------------------------------ 480 ------------------------------
638 481
639 The ``MEMSX`` mode modifier is used to encode !! 482 The ``BPF_MEMSX`` mode modifier is used to encode :term:`sign-extension<Sign Extend>` load
640 instructions that transfer data between a regi 483 instructions that transfer data between a register and memory.
641 484
642 ``{MEMSX, <size>, LDX}`` means:: !! 485 ``BPF_MEMSX | <size> | BPF_LDX`` means::
643 486
644 dst = *(signed size *) (src + offset) 487 dst = *(signed size *) (src + offset)
645 488
646 Where '<size>' is one of: ``B``, ``H``, or ``W !! 489 Where size is one of: ``BPF_B``, ``BPF_H`` or ``BPF_W``, and
647 'signed size' is one of: s8, s16, or s32. !! 490 'signed size' is one of s8, s16 or s32.
648 491
649 Atomic operations 492 Atomic operations
650 ----------------- 493 -----------------
651 494
652 Atomic operations are operations that operate 495 Atomic operations are operations that operate on memory and can not be
653 interrupted or corrupted by other access to th 496 interrupted or corrupted by other access to the same memory region
654 by other BPF programs or means outside of this 497 by other BPF programs or means outside of this specification.
655 498
656 All atomic operations supported by BPF are enc 499 All atomic operations supported by BPF are encoded as store operations
657 that use the ``ATOMIC`` mode modifier as follo !! 500 that use the ``BPF_ATOMIC`` mode modifier as follows:
658 501
659 * ``{ATOMIC, W, STX}`` for 32-bit operations, !! 502 * ``BPF_ATOMIC | BPF_W | BPF_STX`` for 32-bit operations
660 part of the "atomic32" conformance group. !! 503 * ``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 504 * 8-bit and 16-bit wide atomic operations are not supported.
664 505
665 The 'imm' field is used to encode the actual a 506 The 'imm' field is used to encode the actual atomic operation.
666 Simple atomic operation use a subset of the va 507 Simple atomic operation use a subset of the values defined to encode
667 arithmetic operations in the 'imm' field to en 508 arithmetic operations in the 'imm' field to encode the atomic operation:
668 509
669 .. table:: Simple atomic operations !! 510 ======== ===== ===========
>> 511 imm value description
>> 512 ======== ===== ===========
>> 513 BPF_ADD 0x00 atomic add
>> 514 BPF_OR 0x40 atomic or
>> 515 BPF_AND 0x50 atomic and
>> 516 BPF_XOR 0xa0 atomic xor
>> 517 ======== ===== ===========
670 518
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 519
680 !! 520 ``BPF_ATOMIC | BPF_W | BPF_STX`` with 'imm' = BPF_ADD means::
681 ``{ATOMIC, W, STX}`` with 'imm' = ADD means:: <<
682 521
683 *(u32 *)(dst + offset) += src 522 *(u32 *)(dst + offset) += src
684 523
685 ``{ATOMIC, DW, STX}`` with 'imm' = ADD means:: !! 524 ``BPF_ATOMIC | BPF_DW | BPF_STX`` with 'imm' = BPF ADD means::
686 525
687 *(u64 *)(dst + offset) += src 526 *(u64 *)(dst + offset) += src
688 527
689 In addition to the simple atomic operations, t 528 In addition to the simple atomic operations, there also is a modifier and
690 two complex atomic operations: 529 two complex atomic operations:
691 530
692 .. table:: Complex atomic operations !! 531 =========== ================ ===========================
693 !! 532 imm value description
694 =========== ================ ============= !! 533 =========== ================ ===========================
695 imm value description !! 534 BPF_FETCH 0x01 modifier: return old value
696 =========== ================ ============= !! 535 BPF_XCHG 0xe0 | BPF_FETCH atomic exchange
697 FETCH 0x01 modifier: ret !! 536 BPF_CMPXCHG 0xf0 | BPF_FETCH atomic compare and exchange
698 XCHG 0xe0 | FETCH atomic exchan !! 537 =========== ================ ===========================
699 CMPXCHG 0xf0 | FETCH atomic compar <<
700 =========== ================ ============= <<
701 538
702 The ``FETCH`` modifier is optional for simple !! 539 The ``BPF_FETCH`` modifier is optional for simple atomic operations, and
703 always set for the complex atomic operations. !! 540 always set for the complex atomic operations. If the ``BPF_FETCH`` flag
704 is set, then the operation also overwrites ``s 541 is set, then the operation also overwrites ``src`` with the value that
705 was in memory before it was modified. 542 was in memory before it was modified.
706 543
707 The ``XCHG`` operation atomically exchanges `` !! 544 The ``BPF_XCHG`` operation atomically exchanges ``src`` with the value
708 addressed by ``dst + offset``. 545 addressed by ``dst + offset``.
709 546
710 The ``CMPXCHG`` operation atomically compares !! 547 The ``BPF_CMPXCHG`` operation atomically compares the value addressed by
711 ``dst + offset`` with ``R0``. If they match, t 548 ``dst + offset`` with ``R0``. If they match, the value addressed by
712 ``dst + offset`` is replaced with ``src``. In 549 ``dst + offset`` is replaced with ``src``. In either case, the
713 value that was at ``dst + offset`` before the 550 value that was at ``dst + offset`` before the operation is zero-extended
714 and loaded back to ``R0``. 551 and loaded back to ``R0``.
715 552
716 64-bit immediate instructions 553 64-bit immediate instructions
717 ----------------------------- 554 -----------------------------
718 555
719 Instructions with the ``IMM`` 'mode' modifier !! 556 Instructions with the ``BPF_IMM`` 'mode' modifier use the wide instruction
720 encoding defined in `Instruction encoding`_, a !! 557 encoding defined in `Instruction encoding`_, and use the 'src' field of the
721 basic instruction to hold an opcode subtype. 558 basic instruction to hold an opcode subtype.
722 559
723 The following table defines a set of ``{IMM, D !! 560 The following table defines a set of ``BPF_IMM | BPF_DW | BPF_LD`` instructions
724 with opcode subtypes in the 'src_reg' field, u !! 561 with opcode subtypes in the 'src' field, using new terms such as "map"
725 defined further below: 562 defined further below:
726 563
727 .. table:: 64-bit immediate instructions !! 564 ========================= ====== === ========================================= =========== ==============
728 !! 565 opcode construction opcode src pseudocode imm type dst type
729 ======= =================================== !! 566 ========================= ====== === ========================================= =========== ==============
730 src_reg pseudocode !! 567 BPF_IMM | BPF_DW | BPF_LD 0x18 0x0 dst = imm64 integer integer
731 ======= =================================== !! 568 BPF_IMM | BPF_DW | BPF_LD 0x18 0x1 dst = map_by_fd(imm) map fd map
732 0x0 dst = (next_imm << 32) | imm !! 569 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) !! 570 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 !! 571 BPF_IMM | BPF_DW | BPF_LD 0x18 0x4 dst = code_addr(imm) integer code pointer
735 0x3 dst = var_addr(imm) !! 572 BPF_IMM | BPF_DW | BPF_LD 0x18 0x5 dst = map_by_idx(imm) map index map
736 0x4 dst = code_addr(imm) !! 573 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) !! 574 ========================= ====== === ========================================= =========== ==============
738 0x6 dst = map_val(map_by_idx(imm)) + ne <<
739 ======= =================================== <<
740 575
741 where 576 where
742 577
743 * map_by_fd(imm) means to convert a 32-bit fil 578 * 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 579 * 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 580 * map_val(map) gets the address of the first value in a given map
746 * var_addr(imm) gets the address of a platform 581 * 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 582 * 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 583 * the 'imm type' can be used by disassemblers for display
749 * the 'dst type' can be used for verification 584 * the 'dst type' can be used for verification and JIT compilation purposes
750 585
751 Maps 586 Maps
752 ~~~~ 587 ~~~~
753 588
754 Maps are shared memory regions accessible by B 589 Maps are shared memory regions accessible by BPF programs on some platforms.
755 A map can have various semantics as defined in 590 A map can have various semantics as defined in a separate document, and may or
756 may not have a single contiguous memory region 591 may not have a single contiguous memory region, but the 'map_val(map)' is
757 currently only defined for maps that do have a 592 currently only defined for maps that do have a single contiguous memory region.
758 593
759 Each map can have a file descriptor (fd) if su 594 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 595 '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 596 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 597 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 598 index in the set associated with the BPF program containing the instruction.
764 599
765 Platform Variables 600 Platform Variables
766 ~~~~~~~~~~~~~~~~~~ 601 ~~~~~~~~~~~~~~~~~~
767 602
768 Platform variables are memory regions, identif 603 Platform variables are memory regions, identified by integer ids, exposed by
769 the runtime and accessible by BPF programs on 604 the runtime and accessible by BPF programs on some platforms. The
770 'var_addr(imm)' operation means to get the add 605 'var_addr(imm)' operation means to get the address of the memory region
771 identified by the given id. 606 identified by the given id.
772 607
773 Legacy BPF Packet access instructions 608 Legacy BPF Packet access instructions
774 ------------------------------------- 609 -------------------------------------
775 610
776 BPF previously introduced special instructions 611 BPF previously introduced special instructions for access to packet data that were
777 carried over from classic BPF. These instructi !! 612 carried over from classic BPF. However, these instructions are
778 class of ``LD``, a size modifier of ``W``, ``H !! 613 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.