1 @c Copyright (C) 2019 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 Opcodes:: Opcodes
25 @cindex BPF options (none)
26 @cindex options for BPF (none)
31 @cindex @option{-EB} command-line option, BPF
33 This option specifies that the assembler should emit big-endian eBPF.
35 @cindex @option{-EL} command-line option, BPF
37 This option specifies that the assembler should emit little-endian
41 Note that if no endianness option is specified in the command line,
42 the host endianness is used.
48 * BPF-Chars:: Special Characters
49 * BPF-Regs:: Register Names
50 * BPF-Pseudo-Maps:: Pseudo map fds
54 @subsection Special Characters
56 @cindex line comment character, BPF
57 @cindex BPF line comment character
58 The presence of a @samp{;} on a line indicates the start of a comment
59 that extends to the end of the current line. If a @samp{#} appears as
60 the first character of a line, the whole line is treated as a comment.
62 @cindex statement separator, BPF
63 Statements and assembly directives are separated by newlines.
66 @subsection Register Names
68 @cindex BPF register names
69 @cindex register names, BPF
70 The eBPF processor provides ten general-purpose 64-bit registers,
71 which are read-write, and a read-only frame pointer register:
75 General-purpose registers.
77 Frame pointer register.
80 Some registers have additional names, to reflect their role in the
93 @subsection Pseudo Maps
95 @cindex pseudo map fd, BPF
96 The @samp{LDDW} instruction can take a literal pseudo map file
97 descriptor as its second argument. This uses the syntax
98 @samp{%map_fd(N)} where @samp{N} is a signed number.
100 For example, to load the address of the pseudo map with file
101 descriptor @samp{2} in register @samp{r1} we would do:
111 @cindex opcodes for BPF
112 In the instruction descriptions below the following field descriptors
117 Destination general-purpose register whose role is to be destination
120 Source general-purpose register whose role is to be the source of an
123 16-bit signed PC-relative offset, measured in number of 64-bit words,
126 32-bit signed PC-relative offset, measured in number of 64-bit words,
129 Signed 16-bit immediate.
131 Signed 32-bit immediate.
133 Signed 64-bit immediate.
136 @subsubsection Arithmetic instructions
138 The destination register in these instructions act like an
142 @item add %d, (%s|imm32)
143 64-bit arithmetic addition.
144 @item sub %d, (%s|imm32)
145 64-bit arithmetic subtraction.
146 @item mul %d, (%s|imm32)
147 64-bit arithmetic multiplication.
148 @item div %d, (%s|imm32)
149 64-bit arithmetic integer division.
150 @item mod %d, (%s|imm32)
151 64-bit integer remainder.
152 @item and %d, (%s|imm32)
153 64-bit bit-wise ``and'' operation.
154 @item or %d, (%s|imm32)
155 64-bit bit-wise ``or'' operation.
156 @item xor %d, (%s|imm32)
157 64-bit bit-wise exclusive-or operation.
158 @item lsh %d, (%s|imm32)
159 64-bit left shift, by @code{%s} or @code{imm32} bits.
160 @item rsh %d, (%s|imm32)
161 64-bit right logical shift, by @code{%s} or @code{imm32} bits.
162 @item arsh %d, (%s|imm32)
163 64-bit right arithmetic shift, by @code{%s} or @code{imm32} bits.
165 64-bit arithmetic negation.
166 @item mov %d, (%s|imm32)
167 Move the 64-bit value of @code{%s} in @code{%d}, or load @code{imm32}
171 @subsubsection 32-bit arithmetic instructions
173 The destination register in these instructions act as an accumulator.
176 @item add32 %d, (%s|imm32)
177 32-bit arithmetic addition.
178 @item sub32 %d, (%s|imm32)
179 32-bit arithmetic subtraction.
180 @item mul32 %d, (%s|imm32)
181 32-bit arithmetic multiplication.
182 @item div32 %d, (%s|imm32)
183 32-bit arithmetic integer division.
184 @item mod32 %d, (%s|imm32)
185 32-bit integer remainder.
186 @item and32 %d, (%s|imm32)
187 32-bit bit-wise ``and'' operation.
188 @item or32 %d, (%s|imm32)
189 32-bit bit-wise ``or'' operation.
190 @item xor32 %d, (%s|imm32)
191 32-bit bit-wise exclusive-or operation.
192 @item lsh32 %d, (%s|imm32)
193 32-bit left shift, by @code{%s} or @code{imm32} bits.
194 @item rsh32 %d, (%s|imm32)
195 32-bit right logical shift, by @code{%s} or @code{imm32} bits.
196 @item arsh32 %d, (%s|imm32)
197 32-bit right arithmetic shift, by @code{%s} or @code{imm32} bits.
199 32-bit arithmetic negation.
200 @item mov32 %d, (%s|imm32)
201 Move the 32-bit value of @code{%s} in @code{%d}, or load @code{imm32}
205 @subsubsection Endianness conversion instructions
208 @item endle %d, (8|16|32)
209 Convert the 8-bit, 16-bit or 32-bit value in @code{%d} to
211 @item endbe %d, (8|16|32)
212 Convert the 8-bit, 16-bit or 32-bit value in @code{%d} to big-endian.
215 @subsubsection 64-bit load and pseudo maps
219 Load the given signed 64-bit immediate, or pseudo map descriptor, to
220 the destination register @code{%d}.
221 @item lddw %d, %map_fd(N)
222 Load the address of the given pseudo map fd @emph{N} to the
223 destination register @code{%d}.
226 @subsubsection Load instructions for socket filters
228 The following instructions are intended to be used in socket filters,
229 and are therefore not general-purpose: they make assumptions on the
230 contents of several registers. See the file
231 @file{Documentation/networking/filter.txt} in the Linux kernel source
232 tree for more information.
237 @item ldabsdw %d, %s, imm32
238 Absolute 64-bit load.
239 @item ldabsw %d, %s, imm32
240 Absolute 32-bit load.
241 @item ldabsh %d, %s, imm32
242 Absolute 16-bit load.
243 @item ldabsb %d, %s, imm32
250 @item ldinddw %d, %s, imm32
251 Indirect 64-bit load.
252 @item ldindw %d, %s, imm32
253 Indirect 32-bit load.
254 @item ldindh %d, %s, imm32
255 Indirect 16-bit load.
256 @item ldindb %d, %s, imm32
260 @subsubsection Generic load/store instructions
262 General-purpose load and store instructions are provided for several
265 Load to register instructions:
268 @item ldxdw %d, [%s+offset16]
270 @item ldxw %d, [%s+offset16]
272 @item ldxh %d, [%s+offset16]
274 @item ldxb %d, [%s+offset16]
278 Store from register instructions:
281 @item stxdw [%d+offset16], %s
282 Generic 64-bit store.
283 @item stxw [%d+offset16], %s
284 Generic 32-bit store.
285 @item stxh [%d+offset16], %s
286 Generic 16-bit store.
287 @item stxb [%d+offset16], %s
291 Store from immediates instructions:
294 @item stddw [%d+offset16], imm32
295 Store immediate as 64-bit.
296 @item stdw [%d+offset16], imm32
297 Store immediate as 32-bit.
298 @item stdh [%d+offset16], imm32
299 Store immediate as 16-bit.
300 @item stdb [%d+offset16], imm32
301 Store immediate as 8-bit.
304 @subsubsection Jump instructions
306 eBPF provides the following compare-and-jump instructions, which
307 compare the values of the two given registers, or the values of a
308 register and an immediate, and perform a branch in case the comparison
312 @item ja %d,(%s|imm32),disp16
314 @item jeq %d,(%s|imm32),disp16
316 @item jgt %d,(%s|imm32),disp16
318 @item jge %d,(%s|imm32),disp16
319 Jump if greater or equal.
320 @item jlt %d,(%s|imm32),disp16
322 @item jle %d,(%s|imm32),disp16
323 Jump if lesser or equal.
324 @item jset %d,(%s|imm32),disp16
325 Jump if signed equal.
326 @item jne %d,(%s|imm32),disp16
328 @item jsgt %d,(%s|imm32),disp16
329 Jump if signed greater.
330 @item jsge %d,(%s|imm32),disp16
331 Jump if signed greater or equal.
332 @item jslt %d,(%s|imm32),disp16
333 Jump if signed lesser.
334 @item jsle %d,(%s|imm32),disp16
335 Jump if signed lesser or equal.
338 A call instruction is provided in order to perform calls to other eBPF
339 functions, or to external kernel helpers:
342 @item call (disp32|imm32)
343 Jump and link to the offset @emph{disp32}, or to the kernel helper
344 function identified by @emph{imm32}.
351 Terminate the eBPF program.
354 @subsubsection Atomic instructions
356 Atomic exchange-and-add instructions are provided in two flavors: one
357 for swapping 64-bit quantities and another for 32-bit quantities.
360 @item xadddw [%d+offset16],%s
361 Exchange-and-add a 64-bit value at the specified location.
362 @item xaddw [%d+offset16],%s
363 Exchange-and-add a 32-bit value at the specified location.