Commit | Line | Data |
---|---|---|
b3adc24a | 1 | @c Copyright (C) 2019-2020 Free Software Foundation, Inc. |
f8861f5d JM |
2 | @c This is part of the GAS manual. |
3 | @c For copying conditions, see the file as.texinfo. | |
4 | ||
5 | @ifset GENERIC | |
6 | @page | |
7 | @node BPF-Dependent | |
8 | @chapter BPF Dependent Features | |
9 | @end ifset | |
10 | ||
11 | @ifclear GENERIC | |
12 | @node Machine Dependencies | |
13 | @chapter BPF Dependent Features | |
14 | @end ifclear | |
15 | ||
16 | @cindex BPF support | |
17 | @menu | |
18 | * BPF Options:: Options | |
19 | * BPF Syntax:: Syntax | |
e0b989a6 | 20 | * BPF Directives:: Machine Directives |
f8861f5d JM |
21 | * BPF Opcodes:: Opcodes |
22 | @end menu | |
23 | ||
24 | @node BPF Options | |
25 | @section Options | |
26 | @cindex BPF options (none) | |
27 | @cindex options for BPF (none) | |
28 | ||
29 | @c man begin OPTIONS | |
30 | @table @gcctabopt | |
31 | ||
32 | @cindex @option{-EB} command-line option, BPF | |
33 | @item -EB | |
34 | This option specifies that the assembler should emit big-endian eBPF. | |
35 | ||
36 | @cindex @option{-EL} command-line option, BPF | |
37 | @item -EL | |
38 | This option specifies that the assembler should emit little-endian | |
39 | eBPF. | |
40 | @end table | |
41 | ||
42 | Note that if no endianness option is specified in the command line, | |
43 | the host endianness is used. | |
44 | @c man end | |
45 | ||
46 | @node BPF Syntax | |
47 | @section Syntax | |
48 | @menu | |
49 | * BPF-Chars:: Special Characters | |
50 | * BPF-Regs:: Register Names | |
51 | * BPF-Pseudo-Maps:: Pseudo map fds | |
52 | @end menu | |
53 | ||
54 | @node BPF-Chars | |
55 | @subsection Special Characters | |
56 | ||
57 | @cindex line comment character, BPF | |
58 | @cindex BPF line comment character | |
59 | The presence of a @samp{;} on a line indicates the start of a comment | |
60 | that extends to the end of the current line. If a @samp{#} appears as | |
61 | the first character of a line, the whole line is treated as a comment. | |
62 | ||
63 | @cindex statement separator, BPF | |
64 | Statements and assembly directives are separated by newlines. | |
65 | ||
66 | @node BPF-Regs | |
67 | @subsection Register Names | |
68 | ||
69 | @cindex BPF register names | |
70 | @cindex register names, BPF | |
71 | The eBPF processor provides ten general-purpose 64-bit registers, | |
72 | which are read-write, and a read-only frame pointer register: | |
73 | ||
74 | @table @samp | |
75 | @item %r0 .. %r9 | |
76 | General-purpose registers. | |
77 | @item %r10 | |
78 | Frame pointer register. | |
79 | @end table | |
80 | ||
81 | Some registers have additional names, to reflect their role in the | |
82 | eBPF ABI: | |
83 | ||
84 | @table @samp | |
85 | @item %a | |
86 | This is @samp{%r0}. | |
87 | @item %ctx | |
88 | This is @samp{%r6}. | |
89 | @item %fp | |
90 | This is @samp{%r10}. | |
91 | @end table | |
92 | ||
93 | @node BPF-Pseudo-Maps | |
94 | @subsection Pseudo Maps | |
95 | ||
96 | @cindex pseudo map fd, BPF | |
97 | The @samp{LDDW} instruction can take a literal pseudo map file | |
98 | descriptor as its second argument. This uses the syntax | |
99 | @samp{%map_fd(N)} where @samp{N} is a signed number. | |
100 | ||
101 | For example, to load the address of the pseudo map with file | |
102 | descriptor @samp{2} in register @samp{r1} we would do: | |
103 | ||
104 | @smallexample | |
105 | lddw %r1, %map_fd(2) | |
106 | @end smallexample | |
107 | ||
e0b989a6 JM |
108 | @node BPF Directives |
109 | @section Machine Directives | |
110 | ||
111 | @cindex machine directives, BPF | |
112 | ||
113 | The BPF version of @code{@value{AS}} supports the following additional | |
114 | machine directives: | |
115 | ||
116 | @table @code | |
117 | @cindex @code{half} directive, BPF | |
118 | @item .word | |
119 | The @code{.half} directive produces a 16 bit value. | |
120 | ||
121 | @cindex @code{word} directive, BPF | |
122 | @item .word | |
123 | The @code{.word} directive produces a 32 bit value. | |
124 | ||
125 | @cindex @code{dword} directive, BPF | |
126 | @item .dword | |
127 | The @code{.dword} directive produces a 64 bit value. | |
128 | @end table | |
129 | ||
f8861f5d JM |
130 | @node BPF Opcodes |
131 | @section Opcodes | |
132 | ||
133 | @cindex BPF opcodes | |
134 | @cindex opcodes for BPF | |
135 | In the instruction descriptions below the following field descriptors | |
136 | are used: | |
137 | ||
138 | @table @code | |
139 | @item %d | |
140 | Destination general-purpose register whose role is to be destination | |
141 | of an operation. | |
142 | @item %s | |
143 | Source general-purpose register whose role is to be the source of an | |
144 | operation. | |
145 | @item disp16 | |
146 | 16-bit signed PC-relative offset, measured in number of 64-bit words, | |
147 | minus one. | |
148 | @item disp32 | |
149 | 32-bit signed PC-relative offset, measured in number of 64-bit words, | |
150 | minus one. | |
151 | @item offset16 | |
152 | Signed 16-bit immediate. | |
153 | @item imm32 | |
154 | Signed 32-bit immediate. | |
155 | @item imm64 | |
156 | Signed 64-bit immediate. | |
157 | @end table | |
158 | ||
159 | @subsubsection Arithmetic instructions | |
160 | ||
161 | The destination register in these instructions act like an | |
162 | accumulator. | |
163 | ||
164 | @table @code | |
165 | @item add %d, (%s|imm32) | |
166 | 64-bit arithmetic addition. | |
167 | @item sub %d, (%s|imm32) | |
168 | 64-bit arithmetic subtraction. | |
169 | @item mul %d, (%s|imm32) | |
170 | 64-bit arithmetic multiplication. | |
171 | @item div %d, (%s|imm32) | |
172 | 64-bit arithmetic integer division. | |
173 | @item mod %d, (%s|imm32) | |
174 | 64-bit integer remainder. | |
175 | @item and %d, (%s|imm32) | |
176 | 64-bit bit-wise ``and'' operation. | |
177 | @item or %d, (%s|imm32) | |
178 | 64-bit bit-wise ``or'' operation. | |
179 | @item xor %d, (%s|imm32) | |
180 | 64-bit bit-wise exclusive-or operation. | |
181 | @item lsh %d, (%s|imm32) | |
182 | 64-bit left shift, by @code{%s} or @code{imm32} bits. | |
183 | @item rsh %d, (%s|imm32) | |
184 | 64-bit right logical shift, by @code{%s} or @code{imm32} bits. | |
185 | @item arsh %d, (%s|imm32) | |
186 | 64-bit right arithmetic shift, by @code{%s} or @code{imm32} bits. | |
187 | @item neg %d | |
188 | 64-bit arithmetic negation. | |
189 | @item mov %d, (%s|imm32) | |
190 | Move the 64-bit value of @code{%s} in @code{%d}, or load @code{imm32} | |
191 | in @code{%d}. | |
192 | @end table | |
193 | ||
194 | @subsubsection 32-bit arithmetic instructions | |
195 | ||
196 | The destination register in these instructions act as an accumulator. | |
197 | ||
198 | @table @code | |
199 | @item add32 %d, (%s|imm32) | |
200 | 32-bit arithmetic addition. | |
201 | @item sub32 %d, (%s|imm32) | |
202 | 32-bit arithmetic subtraction. | |
203 | @item mul32 %d, (%s|imm32) | |
204 | 32-bit arithmetic multiplication. | |
205 | @item div32 %d, (%s|imm32) | |
206 | 32-bit arithmetic integer division. | |
207 | @item mod32 %d, (%s|imm32) | |
208 | 32-bit integer remainder. | |
209 | @item and32 %d, (%s|imm32) | |
210 | 32-bit bit-wise ``and'' operation. | |
211 | @item or32 %d, (%s|imm32) | |
212 | 32-bit bit-wise ``or'' operation. | |
213 | @item xor32 %d, (%s|imm32) | |
214 | 32-bit bit-wise exclusive-or operation. | |
215 | @item lsh32 %d, (%s|imm32) | |
216 | 32-bit left shift, by @code{%s} or @code{imm32} bits. | |
217 | @item rsh32 %d, (%s|imm32) | |
218 | 32-bit right logical shift, by @code{%s} or @code{imm32} bits. | |
219 | @item arsh32 %d, (%s|imm32) | |
220 | 32-bit right arithmetic shift, by @code{%s} or @code{imm32} bits. | |
221 | @item neg32 %d | |
222 | 32-bit arithmetic negation. | |
223 | @item mov32 %d, (%s|imm32) | |
224 | Move the 32-bit value of @code{%s} in @code{%d}, or load @code{imm32} | |
225 | in @code{%d}. | |
226 | @end table | |
227 | ||
228 | @subsubsection Endianness conversion instructions | |
229 | ||
230 | @table @code | |
231 | @item endle %d, (8|16|32) | |
232 | Convert the 8-bit, 16-bit or 32-bit value in @code{%d} to | |
233 | little-endian. | |
234 | @item endbe %d, (8|16|32) | |
235 | Convert the 8-bit, 16-bit or 32-bit value in @code{%d} to big-endian. | |
236 | @end table | |
237 | ||
238 | @subsubsection 64-bit load and pseudo maps | |
239 | ||
240 | @table @code | |
241 | @item lddw %d, imm64 | |
242 | Load the given signed 64-bit immediate, or pseudo map descriptor, to | |
243 | the destination register @code{%d}. | |
244 | @item lddw %d, %map_fd(N) | |
245 | Load the address of the given pseudo map fd @emph{N} to the | |
246 | destination register @code{%d}. | |
247 | @end table | |
248 | ||
249 | @subsubsection Load instructions for socket filters | |
250 | ||
251 | The following instructions are intended to be used in socket filters, | |
252 | and are therefore not general-purpose: they make assumptions on the | |
253 | contents of several registers. See the file | |
254 | @file{Documentation/networking/filter.txt} in the Linux kernel source | |
255 | tree for more information. | |
256 | ||
257 | Absolute loads: | |
258 | ||
259 | @table @code | |
3719fd55 | 260 | @item ldabsdw imm32 |
f8861f5d | 261 | Absolute 64-bit load. |
3719fd55 | 262 | @item ldabsw imm32 |
f8861f5d | 263 | Absolute 32-bit load. |
3719fd55 | 264 | @item ldabsh imm32 |
f8861f5d | 265 | Absolute 16-bit load. |
3719fd55 | 266 | @item ldabsb imm32 |
f8861f5d JM |
267 | Absolute 8-bit load. |
268 | @end table | |
269 | ||
270 | Indirect loads: | |
271 | ||
272 | @table @code | |
3719fd55 | 273 | @item ldinddw %s, imm32 |
f8861f5d | 274 | Indirect 64-bit load. |
3719fd55 | 275 | @item ldindw %s, imm32 |
f8861f5d | 276 | Indirect 32-bit load. |
3719fd55 | 277 | @item ldindh %s, imm32 |
f8861f5d | 278 | Indirect 16-bit load. |
3719fd55 | 279 | @item ldindb %s, imm32 |
f8861f5d JM |
280 | Indirect 8-bit load. |
281 | @end table | |
282 | ||
283 | @subsubsection Generic load/store instructions | |
284 | ||
285 | General-purpose load and store instructions are provided for several | |
286 | word sizes. | |
287 | ||
288 | Load to register instructions: | |
289 | ||
290 | @table @code | |
291 | @item ldxdw %d, [%s+offset16] | |
292 | Generic 64-bit load. | |
293 | @item ldxw %d, [%s+offset16] | |
294 | Generic 32-bit load. | |
295 | @item ldxh %d, [%s+offset16] | |
296 | Generic 16-bit load. | |
297 | @item ldxb %d, [%s+offset16] | |
298 | Generic 8-bit load. | |
299 | @end table | |
300 | ||
301 | Store from register instructions: | |
302 | ||
303 | @table @code | |
304 | @item stxdw [%d+offset16], %s | |
305 | Generic 64-bit store. | |
306 | @item stxw [%d+offset16], %s | |
307 | Generic 32-bit store. | |
308 | @item stxh [%d+offset16], %s | |
309 | Generic 16-bit store. | |
310 | @item stxb [%d+offset16], %s | |
311 | Generic 8-bit store. | |
312 | @end table | |
313 | ||
314 | Store from immediates instructions: | |
315 | ||
316 | @table @code | |
317 | @item stddw [%d+offset16], imm32 | |
318 | Store immediate as 64-bit. | |
319 | @item stdw [%d+offset16], imm32 | |
320 | Store immediate as 32-bit. | |
321 | @item stdh [%d+offset16], imm32 | |
322 | Store immediate as 16-bit. | |
323 | @item stdb [%d+offset16], imm32 | |
324 | Store immediate as 8-bit. | |
325 | @end table | |
326 | ||
327 | @subsubsection Jump instructions | |
328 | ||
329 | eBPF provides the following compare-and-jump instructions, which | |
330 | compare the values of the two given registers, or the values of a | |
331 | register and an immediate, and perform a branch in case the comparison | |
332 | holds true. | |
333 | ||
334 | @table @code | |
335 | @item ja %d,(%s|imm32),disp16 | |
336 | Jump-always. | |
337 | @item jeq %d,(%s|imm32),disp16 | |
338 | Jump if equal. | |
339 | @item jgt %d,(%s|imm32),disp16 | |
340 | Jump if greater. | |
341 | @item jge %d,(%s|imm32),disp16 | |
342 | Jump if greater or equal. | |
343 | @item jlt %d,(%s|imm32),disp16 | |
344 | Jump if lesser. | |
345 | @item jle %d,(%s|imm32),disp16 | |
346 | Jump if lesser or equal. | |
347 | @item jset %d,(%s|imm32),disp16 | |
348 | Jump if signed equal. | |
349 | @item jne %d,(%s|imm32),disp16 | |
350 | Jump if not equal. | |
351 | @item jsgt %d,(%s|imm32),disp16 | |
352 | Jump if signed greater. | |
353 | @item jsge %d,(%s|imm32),disp16 | |
354 | Jump if signed greater or equal. | |
355 | @item jslt %d,(%s|imm32),disp16 | |
356 | Jump if signed lesser. | |
357 | @item jsle %d,(%s|imm32),disp16 | |
358 | Jump if signed lesser or equal. | |
359 | @end table | |
360 | ||
361 | A call instruction is provided in order to perform calls to other eBPF | |
362 | functions, or to external kernel helpers: | |
363 | ||
364 | @table @code | |
365 | @item call (disp32|imm32) | |
366 | Jump and link to the offset @emph{disp32}, or to the kernel helper | |
367 | function identified by @emph{imm32}. | |
368 | @end table | |
369 | ||
370 | Finally: | |
371 | ||
372 | @table @code | |
373 | @item exit | |
374 | Terminate the eBPF program. | |
375 | @end table | |
376 | ||
377 | @subsubsection Atomic instructions | |
378 | ||
379 | Atomic exchange-and-add instructions are provided in two flavors: one | |
380 | for swapping 64-bit quantities and another for 32-bit quantities. | |
381 | ||
382 | @table @code | |
383 | @item xadddw [%d+offset16],%s | |
384 | Exchange-and-add a 64-bit value at the specified location. | |
385 | @item xaddw [%d+offset16],%s | |
386 | Exchange-and-add a 32-bit value at the specified location. | |
387 | @end table |