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