1 @c Copyright (C) 2019-2020 Free Software Foundation, Inc.
2 @c This is part of the GAS manual.
3 @c For copying conditions, see the file as.texinfo.
8 @chapter BPF Dependent Features
12 @node Machine Dependencies
13 @chapter BPF Dependent Features
18 * BPF Options:: Options
20 * BPF Directives:: Machine Directives
21 * BPF Opcodes:: Opcodes
26 @cindex BPF options (none)
27 @cindex options for BPF (none)
32 @cindex @option{-EB} command-line option, BPF
34 This option specifies that the assembler should emit big-endian eBPF.
36 @cindex @option{-EL} command-line option, BPF
38 This option specifies that the assembler should emit little-endian
42 Note that if no endianness option is specified in the command line,
43 the host endianness is used.
49 * BPF-Chars:: Special Characters
50 * BPF-Regs:: Register Names
51 * BPF-Pseudo-Maps:: Pseudo map fds
55 @subsection Special Characters
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.
63 @cindex statement separator, BPF
64 Statements and assembly directives are separated by newlines.
67 @subsection Register Names
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:
76 General-purpose registers.
78 Frame pointer register.
81 Some registers have additional names, to reflect their role in the
94 @subsection Pseudo Maps
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.
101 For example, to load the address of the pseudo map with file
102 descriptor @samp{2} in register @samp{r1} we would do:
109 @section Machine Directives
111 @cindex machine directives, BPF
113 The BPF version of @code{@value{AS}} supports the following additional
117 @cindex @code{half} directive, BPF
119 The @code{.half} directive produces a 16 bit value.
121 @cindex @code{word} directive, BPF
123 The @code{.word} directive produces a 32 bit value.
125 @cindex @code{dword} directive, BPF
127 The @code{.dword} directive produces a 64 bit value.
134 @cindex opcodes for BPF
135 In the instruction descriptions below the following field descriptors
140 Destination general-purpose register whose role is to be destination
143 Source general-purpose register whose role is to be the source of an
146 16-bit signed PC-relative offset, measured in number of 64-bit words,
149 32-bit signed PC-relative offset, measured in number of 64-bit words,
152 Signed 16-bit immediate.
154 Signed 32-bit immediate.
156 Signed 64-bit immediate.
159 @subsubsection Arithmetic instructions
161 The destination register in these instructions act like an
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.
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}
194 @subsubsection 32-bit arithmetic instructions
196 The destination register in these instructions act as an accumulator.
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.
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}
228 @subsubsection Endianness conversion instructions
231 @item endle %d, (8|16|32)
232 Convert the 8-bit, 16-bit or 32-bit value in @code{%d} to
234 @item endbe %d, (8|16|32)
235 Convert the 8-bit, 16-bit or 32-bit value in @code{%d} to big-endian.
238 @subsubsection 64-bit load and pseudo maps
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}.
249 @subsubsection Load instructions for socket filters
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.
261 Absolute 64-bit load.
263 Absolute 32-bit load.
265 Absolute 16-bit load.
273 @item ldinddw %s, imm32
274 Indirect 64-bit load.
275 @item ldindw %s, imm32
276 Indirect 32-bit load.
277 @item ldindh %s, imm32
278 Indirect 16-bit load.
279 @item ldindb %s, imm32
283 @subsubsection Generic load/store instructions
285 General-purpose load and store instructions are provided for several
288 Load to register instructions:
291 @item ldxdw %d, [%s+offset16]
293 @item ldxw %d, [%s+offset16]
295 @item ldxh %d, [%s+offset16]
297 @item ldxb %d, [%s+offset16]
301 Store from register instructions:
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
314 Store from immediates instructions:
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.
327 @subsubsection Jump instructions
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
335 @item ja %d,(%s|imm32),disp16
337 @item jeq %d,(%s|imm32),disp16
339 @item jgt %d,(%s|imm32),disp16
341 @item jge %d,(%s|imm32),disp16
342 Jump if greater or equal.
343 @item jlt %d,(%s|imm32),disp16
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
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.
361 A call instruction is provided in order to perform calls to other eBPF
362 functions, or to external kernel helpers:
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}.
374 Terminate the eBPF program.
377 @subsubsection Atomic instructions
379 Atomic exchange-and-add instructions are provided in two flavors: one
380 for swapping 64-bit quantities and another for 32-bit quantities.
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.