gas/doc/c-bpf.texi

   1 @c Copyright (C) 2019-2023 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 * BPF Pseudo-C Syntax::         Alternative Pseudo-C Assembly Syntax
  23 @end menu
  24
  25 @node BPF Options
  26 @section Options
  27 @cindex BPF options (none)
  28 @cindex options for BPF (none)
  29
  30 @c man begin OPTIONS
  31 @table @gcctabopt
  32
  33 @cindex @option{-EB} command-line option, BPF
  34 @item -EB
  35 This option specifies that the assembler should emit big-endian eBPF.
  36
  37 @cindex @option{-EL} command-line option, BPF
  38 @item -EL
  39 This option specifies that the assembler should emit little-endian
  40 eBPF.
  41 @end table
  42
  43 Note that if no endianness option is specified in the command line,
  44 the host endianness is used.
  45 @c man end
  46
  47 @node BPF Syntax
  48 @section Syntax
  49 @menu
  50 * BPF-Chars::                Special Characters
  51 * BPF-Regs::                 Register Names
  52 * BPF-Pseudo-Maps::          Pseudo map fds
  53 @end menu
  54
  55 @node BPF-Chars
  56 @subsection Special Characters
  57
  58 @cindex line comment character, BPF
  59 @cindex BPF line comment character
  60 The presence of a @samp{;} on a line indicates the start of a comment
  61 that extends to the end of the current line.  If a @samp{#} appears as
  62 the first character of a line, the whole line is treated as a comment.
  63
  64 @cindex statement separator, BPF
  65 Statements and assembly directives are separated by newlines.
  66
  67 @node BPF-Regs
  68 @subsection Register Names
  69
  70 @cindex BPF register names
  71 @cindex register names, BPF
  72 The eBPF processor provides ten general-purpose 64-bit registers,
  73 which are read-write, and a read-only frame pointer register:
  74
  75 @table @samp
  76 @item %r0 .. %r9
  77 General-purpose registers.
  78 @item %r10
  79 Frame pointer register.
  80 @end table
  81
  82 Some registers have additional names, to reflect their role in the
  83 eBPF ABI:
  84
  85 @table @samp
  86 @item %a
  87 This is @samp{%r0}.
  88 @item %ctx
  89 This is @samp{%r6}.
  90 @item %fp
  91 This is @samp{%r10}.
  92 @end table
  93
  94 @node BPF-Pseudo-Maps
  95 @subsection Pseudo Maps
  96
  97 @cindex pseudo map fd, BPF
  98 The @samp{LDDW} instruction can take a literal pseudo map file
  99 descriptor as its second argument.  This uses the syntax
 100 @samp{%map_fd(N)} where @samp{N} is a signed number.
 101
 102 For example, to load the address of the pseudo map with file
 103 descriptor @samp{2} in register @samp{r1} we would do:
 104
 105 @smallexample
 106         lddw %r1, %map_fd(2)
 107 @end smallexample
 108
 109 @node BPF Directives
 110 @section Machine Directives
 111
 112 @cindex machine directives, BPF
 113
 114 The BPF version of @code{@value{AS}} supports the following additional
 115 machine directives:
 116
 117 @table @code
 118 @cindex @code{half} directive, BPF
 119 @item .word
 120 The @code{.half} directive produces a 16 bit value.
 121
 122 @cindex @code{word} directive, BPF
 123 @item .word
 124 The @code{.word} directive produces a 32 bit value.
 125
 126 @cindex @code{dword} directive, BPF
 127 @item .dword
 128 The @code{.dword} directive produces a 64 bit value.
 129 @end table
 130
 131 @node BPF Opcodes
 132 @section Opcodes
 133
 134 @cindex BPF opcodes
 135 @cindex opcodes for BPF
 136 In the instruction descriptions below the following field descriptors
 137 are used:
 138
 139 @table @code
 140 @item %d
 141 Destination general-purpose register whose role is to be destination
 142 of an operation.
 143 @item %s
 144 Source general-purpose register whose role is to be the source of an
 145 operation.
 146 @item disp16
 147 16-bit signed PC-relative offset, measured in number of 64-bit words,
 148 minus one.
 149 @item disp32
 150 32-bit signed PC-relative offset, measured in number of 64-bit words,
 151 minus one.
 152 @item offset16
 153 Signed 16-bit immediate.
 154 @item imm32
 155 Signed 32-bit immediate.
 156 @item imm64
 157 Signed 64-bit immediate.
 158 @end table
 159
 160 @subsubsection Arithmetic instructions
 161
 162 The destination register in these instructions act like an
 163 accumulator.
 164
 165 @table @code
 166 @item add %d, (%s|imm32)
 167 64-bit arithmetic addition.
 168 @item sub %d, (%s|imm32)
 169 64-bit arithmetic subtraction.
 170 @item mul %d, (%s|imm32)
 171 64-bit arithmetic multiplication.
 172 @item div %d, (%s|imm32)
 173 64-bit arithmetic integer division.
 174 @item mod %d, (%s|imm32)
 175 64-bit integer remainder.
 176 @item and %d, (%s|imm32)
 177 64-bit bit-wise ``and'' operation.
 178 @item or %d, (%s|imm32)
 179 64-bit bit-wise ``or'' operation.
 180 @item xor %d, (%s|imm32)
 181 64-bit bit-wise exclusive-or operation.
 182 @item lsh %d, (%s|imm32)
 183 64-bit left shift, by @code{%s} or @code{imm32} bits.
 184 @item rsh %d, (%s|imm32)
 185 64-bit right logical shift, by @code{%s} or @code{imm32} bits.
 186 @item arsh %d, (%s|imm32)
 187 64-bit right arithmetic shift, by @code{%s} or @code{imm32} bits.
 188 @item neg %d
 189 64-bit arithmetic negation.
 190 @item mov %d, (%s|imm32)
 191 Move the 64-bit value of @code{%s} in @code{%d}, or load @code{imm32}
 192 in @code{%d}.
 193 @end table
 194
 195 @subsubsection 32-bit arithmetic instructions
 196
 197 The destination register in these instructions act as an accumulator.
 198
 199 @table @code
 200 @item add32 %d, (%s|imm32)
 201 32-bit arithmetic addition.
 202 @item sub32 %d, (%s|imm32)
 203 32-bit arithmetic subtraction.
 204 @item mul32 %d, (%s|imm32)
 205 32-bit arithmetic multiplication.
 206 @item div32 %d, (%s|imm32)
 207 32-bit arithmetic integer division.
 208 @item mod32 %d, (%s|imm32)
 209 32-bit integer remainder.
 210 @item and32 %d, (%s|imm32)
 211 32-bit bit-wise ``and'' operation.
 212 @item or32 %d, (%s|imm32)
 213 32-bit bit-wise ``or'' operation.
 214 @item xor32 %d, (%s|imm32)
 215 32-bit bit-wise exclusive-or operation.
 216 @item lsh32 %d, (%s|imm32)
 217 32-bit left shift, by @code{%s} or @code{imm32} bits.
 218 @item rsh32 %d, (%s|imm32)
 219 32-bit right logical shift, by @code{%s} or @code{imm32} bits.
 220 @item arsh32 %d, (%s|imm32)
 221 32-bit right arithmetic shift, by @code{%s} or @code{imm32} bits.
 222 @item neg32 %d
 223 32-bit arithmetic negation.
 224 @item mov32 %d, (%s|imm32)
 225 Move the 32-bit value of @code{%s} in @code{%d}, or load @code{imm32}
 226 in @code{%d}.
 227 @end table
 228
 229 @subsubsection Endianness conversion instructions
 230
 231 @table @code
 232 @item endle %d, (16|32|64)
 233 Convert the 16-bit, 32-bit or 64-bit value in @code{%d} to
 234 little-endian.
 235 @item endbe %d, (16|32|64)
 236 Convert the 16-bit, 32-bit or 64-bit value in @code{%d} to big-endian.
 237 @end table
 238
 239 @subsubsection 64-bit load and pseudo maps
 240
 241 @table @code
 242 @item lddw %d, imm64
 243 Load the given signed 64-bit immediate, or pseudo map descriptor, to
 244 the destination register @code{%d}.
 245 @item lddw %d, %map_fd(N)
 246 Load the address of the given pseudo map fd @emph{N} to the
 247 destination register @code{%d}.
 248 @end table
 249
 250 @subsubsection Load instructions for socket filters
 251
 252 The following instructions are intended to be used in socket filters,
 253 and are therefore not general-purpose: they make assumptions on the
 254 contents of several registers.  See the file
 255 @file{Documentation/networking/filter.txt} in the Linux kernel source
 256 tree for more information.
 257
 258 Absolute loads:
 259
 260 @table @code
 261 @item ldabsdw imm32
 262 Absolute 64-bit load.
 263 @item ldabsw imm32
 264 Absolute 32-bit load.
 265 @item ldabsh imm32
 266 Absolute 16-bit load.
 267 @item ldabsb imm32
 268 Absolute 8-bit load.
 269 @end table
 270
 271 Indirect loads:
 272
 273 @table @code
 274 @item ldinddw %s, imm32
 275 Indirect 64-bit load.
 276 @item ldindw %s, imm32
 277 Indirect 32-bit load.
 278 @item ldindh %s, imm32
 279 Indirect 16-bit load.
 280 @item ldindb %s, imm32
 281 Indirect 8-bit load.
 282 @end table
 283
 284 @subsubsection Generic load/store instructions
 285
 286 General-purpose load and store instructions are provided for several
 287 word sizes.
 288
 289 Load to register instructions:
 290
 291 @table @code
 292 @item ldxdw %d, [%s+offset16]
 293 Generic 64-bit load.
 294 @item ldxw %d, [%s+offset16]
 295 Generic 32-bit load.
 296 @item ldxh %d, [%s+offset16]
 297 Generic 16-bit load.
 298 @item ldxb %d, [%s+offset16]
 299 Generic 8-bit load.
 300 @end table
 301
 302 Store from register instructions:
 303
 304 @table @code
 305 @item stxdw [%d+offset16], %s
 306 Generic 64-bit store.
 307 @item stxw [%d+offset16], %s
 308 Generic 32-bit store.
 309 @item stxh [%d+offset16], %s
 310 Generic 16-bit store.
 311 @item stxb [%d+offset16], %s
 312 Generic 8-bit store.
 313 @end table
 314
 315 Store from immediates instructions:
 316
 317 @table @code
 318 @item stddw [%d+offset16], imm32
 319 Store immediate as 64-bit.
 320 @item stdw [%d+offset16], imm32
 321 Store immediate as 32-bit.
 322 @item stdh [%d+offset16], imm32
 323 Store immediate as 16-bit.
 324 @item stdb [%d+offset16], imm32
 325 Store immediate as 8-bit.
 326 @end table
 327
 328 @subsubsection Jump instructions
 329
 330 eBPF provides the following compare-and-jump instructions, which
 331 compare the values of the two given registers, or the values of a
 332 register and an immediate, and perform a branch in case the comparison
 333 holds true.
 334
 335 @table @code
 336 @item ja %d,(%s|imm32),disp16
 337 Jump-always.
 338 @item jeq %d,(%s|imm32),disp16
 339 Jump if equal, unsigned.
 340 @item jgt %d,(%s|imm32),disp16
 341 Jump if greater, unsigned.
 342 @item jge %d,(%s|imm32),disp16
 343 Jump if greater or equal.
 344 @item jlt %d,(%s|imm32),disp16
 345 Jump if lesser.
 346 @item jle %d,(%s|imm32),disp16
 347 Jump if lesser or equal.
 348 @item jset %d,(%s|imm32),disp16
 349 Jump if signed equal.
 350 @item jne %d,(%s|imm32),disp16
 351 Jump if not equal.
 352 @item jsgt %d,(%s|imm32),disp16
 353 Jump if signed greater.
 354 @item jsge %d,(%s|imm32),disp16
 355 Jump if signed greater or equal.
 356 @item jslt %d,(%s|imm32),disp16
 357 Jump if signed lesser.
 358 @item jsle %d,(%s|imm32),disp16
 359 Jump if signed lesser or equal.
 360 @end table
 361
 362 A call instruction is provided in order to perform calls to other eBPF
 363 functions, or to external kernel helpers:
 364
 365 @table @code
 366 @item call (disp32|imm32)
 367 Jump and link to the offset @emph{disp32}, or to the kernel helper
 368 function identified by @emph{imm32}.
 369 @end table
 370
 371 Finally:
 372
 373 @table @code
 374 @item exit
 375 Terminate the eBPF program.
 376 @end table
 377
 378 @subsubsection Atomic instructions
 379
 380 Atomic exchange-and-add instructions are provided in two flavors: one
 381 for swapping 64-bit quantities and another for 32-bit quantities.
 382
 383 @table @code
 384 @item xadddw [%d+offset16],%s
 385 Exchange-and-add a 64-bit value at the specified location.
 386 @item xaddw [%d+offset16],%s
 387 Exchange-and-add a 32-bit value at the specified location.
 388 @end table
 389
 390 @node BPF Pseudo-C Syntax
 391 @section BPF Pseudo-C Syntax
 392
 393 This assembler supports another syntax to denote BPF instructions,
 394 which is an alternative to the normal looking syntax documented above.
 395 This alternatative syntax, which we call @dfn{pseudo-C syntax}, is
 396 supported by the LLVM/clang integrated assembler.
 397
 398 This syntax is very unconventional, but we need to support it in order
 399 to support inline assembly in existing BPF programs.
 400
 401 Note that the assembler is able to parse sources in which both
 402 syntaxes coexist: some instructions can use the usual assembly like
 403 syntax, whereas some other instructions in the same file can use the
 404 pseudo-C syntax.
 405
 406 @subsubsection Pseudo-C Register Names
 407
 408 All BPF registers are 64-bit long.  However, in the Pseudo-C syntax
 409 registers can be referred using different names, which actually
 410 reflect the kind of instruction they appear on:
 411
 412 @table @samp
 413 @item r0..r9
 414 General-purpose register in an instruction that operates on its value
 415 as if it was a 64-bit value.
 416 @item w0..w9
 417 General-purpose register in an instruction that operates on its value
 418 as if it was a 32-bit value.
 419 @end table
 420
 421 @noindent
 422 Note that in the Pseudo-C syntax register names are not preceded by
 423 @code{%} characters.
 424
 425 @subsubsection Arithmetic instructions
 426
 427 In all the instructions below, the operations are 64-bit or 32-bit
 428 depending on the names used to refer to the registers.  For example
 429 @code{r3 += r2} will perform 64-bit addition, whereas @code{w3 += w2}
 430 will perform 32-bit addition.  Mixing register prefixes is an error,
 431 for example @code{r3 += w2}.
 432
 433 @table @code
 434 @item dst_reg += (imm32|src_reg)
 435 Arithmetic addition.
 436 @item dst_reg -= (imm32|src_reg)
 437 Arithmetic subtraction.
 438 @item dst_reg *= (imm32|src_reg)
 439 Arithmetic multiplication.
 440 @item dst_reg /= (imm32|src_reg)
 441 Arithmetic integer unsigned division.
 442 @item dst_reg %= (imm32|src_reg)
 443 Arithmetic integer unsigned remainder.
 444 @item dst_reg &= (imm32|src_reg)
 445 Bit-wise ``and'' operation.
 446 @item dst_reg |= (imm32|src_reg)
 447 Bit-wise ``or'' operation.
 448 @item dst_reg ^= (imm32|src_reg)
 449 Bit-wise exclusive-or operation.
 450 @item dst_reg <<= (imm32|src_reg)
 451 Left shift, by whatever specified number of bits.
 452 @item dst_reg >>= (imm32|src_reg)
 453 Right logical shift, by whatever specified number of bits.
 454 @item dst_reg s>>= (imm32|src_reg)
 455 Right arithmetic shift, by whatever specified number of bits.
 456 @item dst_reg = (imm32|src_reg)
 457 Move the value in @code{imm32} or @code{src_reg} in @code{dst_reg}.
 458 @item dst_reg = -dst_reg
 459 Arithmetic negation.
 460 @end table
 461
 462 @subsubsection Endianness conversion instructions
 463
 464 @table @code
 465 @item dst_reg = le16 src_reg
 466 Convert the 16-bit value in @code{src_reg} to little-endian.
 467 @item dst_reg = le32 src_reg
 468 Convert the 32-bit value in @code{src_reg} to little-endian.
 469 @item dst_reg = le64 src_reg
 470 Convert the 64-bit value in @code{src_reg} to little-endian.
 471 @item dst_reg = be16 src_reg
 472 Convert the 16-bit value in @code{src_reg} to big-endian.
 473 @item dst_reg = be32 src_reg
 474 Convert the 32-bit value in @code{src_reg} to big-endian.
 475 @item dst_reg = be64 src_reg
 476 Convert the 64-bit value in @code{src_reg} to big-endian.
 477 @end table
 478
 479 @subsubsection 64-bit load and pseudo maps
 480
 481 @table @code
 482 @item dst_reg = imm64 ll
 483 Load the given signed 64-bit immediate, or pseudo map descriptor, to
 484 the destination register @code{dst_reg}.
 485 @end table
 486
 487 @subsubsection Load instructions for socket filters
 488
 489 @table @code
 490 @item r0 = *(u8 *)skb[imm32]
 491 Absolute 8-bit load.
 492 @item r0 = *(u16 *)skb[imm32]
 493 Absolute 16-bit load.
 494 @item r0 = *(u32 *)skb[imm32]
 495 Absolute 32-bit load.
 496 @item r0 = *(u64 *)skb[imm32]
 497 Absolute 64-bit load.
 498 @item r0 = *(u8 *)skb[src_reg + imm32]
 499 Indirect 8-bit load.
 500 @item r0 = *(u16 *)skb[src_reg + imm32]
 501 Indirect 16-bit load.
 502 @item r0 = *(u32 *)skb[src_reg + imm32]
 503 Indirect 32-bit load.
 504 @item r0 = *(u64 *)skb[src_reg + imm32]
 505 Indirect 64-bit load.
 506 @end table
 507
 508 @subsubsection Generic load/store instructions
 509
 510 @table @code
 511 @item dst_reg = *(u8 *)(src_reg + offset16)
 512 Generic 8-bit load.
 513 @item dst_reg = *(u16 *)(src_reg + offset16)
 514 Generic 16-bit load.
 515 @item dst_reg = *(u32 *)(src_reg + offset16)
 516 Generic 32-bit load.
 517 @item dst_reg = *(u64 *)(src_reg + offset16)
 518 Generic 64-bit load.
 519 @c XXX stb
 520 @c NO PSEUDOC-SYNTAX
 521 @c XXX sth
 522 @c NO PSEUDOC-SYNTAX
 523 @c XXX stw
 524 @c NO PSEUDOC-SYNTAX
 525 @c XXX stdw
 526 @c NO PSEUDOC-SYNTAX
 527 @item *(u8 *)(dst_reg + offset16) = src_reg
 528 Generic 8-bit store.
 529 @item *(u16 *)(dst_reg + offset16) = src_reg
 530 Generic 16-bit store.
 531 @item *(u32 *)(dst_reg + offset16) = src_reg
 532 Generic 32-bit store.
 533 @item *(u64 *)(dst_reg + offset16) = src_reg
 534 Generic 64-bit store.
 535 @end table
 536
 537 @subsubsection Jump instructions
 538
 539 @table @code
 540 @item goto disp16
 541 Jump-always.
 542 @item if dst_reg == (imm32|src_reg) goto disp16
 543 Jump if equal.
 544 @item if dst_reg & (imm32|src_reg) goto disp16
 545 Jump if signed equal.
 546 @item if dst_reg != (imm32|src_reg) goto disp16
 547 Jump if not equal.
 548 @item if dst_reg > (imm32|src_reg) goto disp16
 549 Jump if bigger, unsigned.
 550 @item if dst_reg < (imm32|src_reg) goto disp16
 551 Jump if smaller, unsigned.
 552 @item if dst_reg >= (imm32|src_reg) goto disp16
 553 Jump if bigger or equal, unsigned.
 554 @item if dst_reg <= (imm32|src_reg) goto disp16
 555 Jump if smaller or equal, unsigned.
 556 @item if dst_reg s> (imm32|src_reg) goto disp16
 557 Jump if bigger, signed.
 558 @item if dst_reg s< (imm32|src_reg) goto disp16
 559 Jump if smaller, signed.
 560 @item if dst_reg s>= (imm32|src_reg) goto disp16
 561 Jump if bigger or equal, signed.
 562 @item if dst_reg s<= (imm32|src_reg) goto disp16
 563 Jump if smaller or equal, signed.
 564 @item call imm32
 565 Jump and link.
 566 @item exit
 567 Terminate the eBPF program.
 568 @end table
 569
 570 @subsubsection Atomic instructions
 571
 572 @table @code
 573 @item lock *(u64 *)(dst_reg + offset16) += src_reg
 574 Exchange-and-add a 64-bit value at the specified location.
 575 @item lock *(u32 *)(dst_reg + offset16) += src_reg
 576 Exchange-and-add a 32-bit value at the specified location.
 577 @end table