gas/doc/c-bpf.texi

   1 @c Copyright (C) 2019-2021 Free Software Foundation, Inc.
   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
  20 * BPF Directives::              Machine Directives
  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
 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
 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
 260 @item ldabsdw imm32
 261 Absolute 64-bit load.
 262 @item ldabsw imm32
 263 Absolute 32-bit load.
 264 @item ldabsh imm32
 265 Absolute 16-bit load.
 266 @item ldabsb imm32
 267 Absolute 8-bit load.
 268 @end table
 269
 270 Indirect loads:
 271
 272 @table @code
 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
 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