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.
8 @chapter BPF Dependent Features
12 @node Machine Dependencies
13 @chapter BPF Dependent Features
18 * BPF Options:: BPF specific command-line options.
19 * BPF Special Characters:: Comments and statements.
20 * BPF Registers:: Register names.
21 * BPF Directives:: Machine directives.
22 * BPF Instructions:: Machine instructions.
27 @cindex BPF options (none)
28 @cindex options for BPF (none)
33 @cindex @option{-EB} command-line option, BPF
35 This option specifies that the assembler should emit big-endian eBPF.
37 @cindex @option{-EL} command-line option, BPF
39 This option specifies that the assembler should emit little-endian
42 @cindex @option{-mdialect} command-line options, BPF
43 @item -mdialect=@var{dialect}
44 This option specifies the assembly language dialect to recognize while
45 assembling. The assembler supports @option{normal} and
48 @cindex @option{-misa-spec} command-line options, BPF
49 @item -misa-spec=@var{spec}
50 This option specifies the version of the BPF instruction set to use
51 when assembling. The BPF ISA versions supported are @option{v1} @option{v2}, @option{v3} and @option{v4}.
53 The value @option{xbpf} can be specified to recognize extra
54 instructions that are used by GCC for testing purposes. But beware
55 this is not valid BPF.
58 Note that if no endianness option is specified in the command line,
59 the host endianness is used.
62 @node BPF Special Characters
63 @section BPF Special Characters
65 @cindex line comment character, BPF
66 @cindex BPF line comment character
67 The presence of a @samp{;} on a line indicates the start of a comment
68 that extends to the end of the current line. If a @samp{#} appears as
69 the first character of a line, the whole line is treated as a comment.
71 @cindex statement separator, BPF
72 Statements and assembly directives are separated by newlines.
75 @section BPF Registers
77 @cindex BPF register names
78 @cindex register names, BPF
79 The eBPF processor provides ten general-purpose 64-bit registers,
80 which are read-write, and a read-only frame pointer register:
87 General-purpose registers.
90 Read-only frame pointer register.
93 All BPF registers are 64-bit long. However, in the Pseudo-C syntax
94 registers can be referred using different names, which actually
95 reflect the kind of instruction they appear on:
102 General-purpose register in an instruction that operates on its value
103 as if it was a 64-bit value.
105 General-purpose register in an instruction that operates on its value
106 as if it was a 32-bit value.
108 Read-only frame pointer register.
112 Note that in the Pseudo-C syntax register names are not preceded by
116 @section BPF Directives
118 @cindex machine directives, BPF
120 The BPF version of @code{@value{AS}} supports the following additional
124 @cindex @code{half} directive, BPF
126 The @code{.half} directive produces a 16 bit value.
128 @cindex @code{word} directive, BPF
130 The @code{.word} directive produces a 32 bit value.
132 @cindex @code{dword} directive, BPF
134 The @code{.dword} directive produces a 64 bit value.
137 @node BPF Instructions
138 @section BPF Instructions
141 @cindex opcodes for BPF
142 In the instruction descriptions below the following field descriptors
147 Destination general-purpose register whose role is to be the
148 destination of an operation.
150 Source general-purpose register whose role is to be the source of an
153 16-bit signed PC-relative offset, measured in number of 64-bit words,
156 32-bit signed PC-relative offset, measured in number of 64-bit words,
159 Signed 16-bit immediate representing an offset in bytes.
161 Signed 16-bit immediate representing a displacement to a target,
162 measured in number of 64-bit words @emph{minus one}.
164 Signed 32-bit immediate.
166 Signed 64-bit immediate.
169 @subsection Arithmetic instructions
171 The destination register in these instructions act like an
174 Note that in pseudoc syntax these instructions should use @code{r}
182 64-bit arithmetic addition.
188 64-bit arithmetic subtraction.
194 64-bit arithmetic multiplication.
200 64-bit arithmetic integer division.
206 64-bit integer remainder.
212 64-bit bit-wise ``and'' operation.
218 64-bit bit-wise ``or'' operation.
224 64-bit bit-wise exclusive-or operation.
230 64-bit left shift, by @code{rs} or @code{imm32} bits.
236 64-bit right logical shift, by @code{rs} or @code{imm32} bits.
239 @itemx arsh rd, imm32
242 64-bit right arithmetic shift, by @code{rs} or @code{imm32} bits.
248 64-bit arithmetic negation.
250 Note that in the @code{rd = - imm32} syntax there must be at least
251 one white space between @code{-} and @code{imm32}. Otherwise the
252 instruction is parsed as a @code{mov rd, imm32} instruction with a
253 negative 32-bit immediate. This is a consequence of a syntactic
254 ambiguity in the pseudoc syntax.
260 Move the 64-bit value of @code{rs} in @code{rd}, or load @code{imm32}
265 Move the sign-extended 8-bit value in @code{rs} to @code{rd}.
267 @item movs rd, rs, 16
268 @itemx rd s= (i16) rs
269 Move the sign-extended 16-bit value in @code{rs} to @code{rd}.
271 @item movs rd, rs, 32
272 @itemx rd s= (i32) rs
273 Move the sign-extended 32-bit value in @code{rs} to @code{rd}.
276 @subsection 32-bit arithmetic instructions
278 The destination register in these instructions act as an accumulator.
280 Note that in pseudoc syntax these instructions should use @code{w}
281 registers. It is not allowed to mix @code{w} and @code{r} registers
282 in the same instruction.
286 @itemx add32 rd, imm32
289 32-bit arithmetic addition.
292 @itemx sub32 rd, imm32
295 32-bit arithmetic subtraction.
298 @itemx mul32 rd, imm32
301 32-bit arithmetic multiplication.
304 @itemx div32 rd, imm32
307 32-bit arithmetic integer division.
310 @itemx mod32 rd, imm32
313 32-bit integer remainder.
316 @itemx and32 rd, imm32
319 32-bit bit-wise ``and'' operation.
322 @itemx or32 rd, imm32
325 32-bit bit-wise ``or'' operation.
328 @itemx xor32 rd, imm32
331 32-bit bit-wise exclusive-or operation.
334 @itemx lsh32 rd, imm32
337 32-bit left shift, by @code{rs} or @code{imm32} bits.
340 @itemx rsh32 rd, imm32
343 32-bit right logical shift, by @code{rs} or @code{imm32} bits.
346 @itemx arsh32 rd, imm32
349 32-bit right arithmetic shift, by @code{rs} or @code{imm32} bits.
352 @itemx neg32 rd, imm32
355 32-bit arithmetic negation.
357 Note that in the @code{rd = - imm32} syntax there must be at least
358 one white space between @code{-} and @code{imm32}. Otherwise the
359 instruction is parsed as a @code{mov32 rd, imm32} instruction with a
360 negative 32-bit immediate. This is a consequence of a syntactic
361 ambiguity in the pseudoc syntax.
364 @itemx mov32 rd, imm32
367 Move the 32-bit value of @code{rs} in @code{rd}, or load @code{imm32}
370 @item mov32s rd, rs, 8
372 Move the sign-extended 8-bit value in @code{rs} to @code{rd}.
374 @item mov32s rd, rs, 16
375 @itemx rd s= (i16) rs
376 Move the sign-extended 16-bit value in @code{rs} to @code{rd}.
378 @item mov32s rd, rs, 32
379 @itemx rd s= (i32) rs
380 Move the sign-extended 32-bit value in @code{rs} to @code{rd}.
383 @subsection Endianness conversion instructions
392 Convert the 16-bit, 32-bit or 64-bit value in @code{rd} to
393 little-endian and store it back in @code{rd}.
400 Convert the 16-bit, 32-bit or 64-bit value in @code{rd} to big-endian
401 and store it back in @code{rd}.
404 @subsection 64-bit load and pseudo maps
409 Load the given signed 64-bit immediate to the destination register
413 @subsection Load instructions for socket filters
415 The following instructions are intended to be used in socket filters,
416 and are therefore not general-purpose: they make assumptions on the
417 contents of several registers. See the file
418 @file{Documentation/networking/filter.txt} in the Linux kernel source
419 tree for more information.
425 @itemx r0 = *(u64 *) skb[imm32]
426 Absolute 64-bit load.
429 @itemx r0 = *(u32 *) skb[imm32]
430 Absolute 32-bit load.
433 @itemx r0 = *(u16 *) skb[imm32]
434 Absolute 16-bit load.
437 @itemx r0 = *(u8 *) skb[imm32]
444 @item ldinddw rs, imm32
445 @itemx r0 = *(u64 *) skb[rs + imm32]
446 Indirect 64-bit load.
448 @item ldindw rs, imm32
449 @itemx r0 = *(u32 *) skb[rs + imm32]
450 Indirect 32-bit load.
452 @item ldindh rs, imm32
453 @itemx r0 = *(u16 *) skb[rs + imm32]
454 Indirect 16-bit load.
456 @item ldindb %s, imm32
457 @itemx r0 = *(u8 *) skb[rs + imm32]
461 @subsection Generic load/store instructions
463 General-purpose load and store instructions are provided for several
466 Load to register instructions:
469 @item ldxdw rd, [rs + offset16]
470 @itemx rd = *(u64 *) (rs + offset16)
473 @item ldxw rd, [rs + offset16]
474 @itemx rd = *(u32 *) (rs + offset16)
477 @item ldxh rd, [rs + offset16]
478 @itemx rd = *(u16 *) (rs + offset16)
481 @item ldxb rd, [rs + offset16]
482 @itemx rd = *(u8 *) (rs + offset16)
486 Store from register instructions:
489 @item stxdw [rd + offset16], %s
490 @itemx *(u64 *) (rd + offset16)
491 Generic 64-bit store.
493 @item stxw [rd + offset16], %s
494 @itemx *(u32 *) (rd + offset16)
495 Generic 32-bit store.
497 @item stxh [rd + offset16], %s
498 @itemx *(u16 *) (rd + offset16)
499 Generic 16-bit store.
501 @item stxb [rd + offset16], %s
502 @itemx *(u8 *) (rd + offset16)
506 Store from immediates instructions:
509 @item stdw [rd + offset16], imm32
510 @itemx *(u64 *) (rd + offset16) = imm32
511 Store immediate as 64-bit.
513 @item stw [rd + offset16], imm32
514 @itemx *(u32 *) (rd + offset16) = imm32
515 Store immediate as 32-bit.
517 @item sth [rd + offset16], imm32
518 @itemx *(u16 *) (rd + offset16) = imm32
519 Store immediate as 16-bit.
521 @item stb [rd + offset16], imm32
522 @itemx *(u8 *) (rd + offset16) = imm32
523 Store immediate as 8-bit.
526 @subsection Jump instructions
528 eBPF provides the following compare-and-jump instructions, which
529 compare the values of the two given registers, or the values of a
530 register and an immediate, and perform a branch in case the comparison
538 @item jeq rd, rs, disp16
539 @itemx jeq rd, imm32, disp16
540 @itemx if rd == rs goto disp16
541 @itemx if rd == imm32 goto disp16
542 Jump if equal, unsigned.
544 @item jgt rd, rs, disp16
545 @itemx jgt rd, imm32, disp16
546 @itemx if rd > rs goto disp16
547 @itemx if rd > imm32 goto disp16
548 Jump if greater, unsigned.
550 @item jge rd, rs, disp16
551 @itemx jge rd, imm32, disp16
552 @itemx if rd >= rs goto disp16
553 @itemx if rd >= imm32 goto disp16
554 Jump if greater or equal.
556 @item jlt rd, rs, disp16
557 @itemx jlt rd, imm32, disp16
558 @itemx if rd < rs goto disp16
559 @itemx if rd < imm32 goto disp16
562 @item jle rd , rs, disp16
563 @itemx jle rd, imm32, disp16
564 @itemx if rd <= rs goto disp16
565 @itemx if rd <= imm32 goto disp16
566 Jump if lesser or equal.
568 @item jset rd, rs, disp16
569 @itemx jset rd, imm32, disp16
570 @itemx if rd & rs goto disp16
571 @itemx if rd & imm32 goto disp16
572 Jump if signed equal.
574 @item jne rd, rs, disp16
575 @itemx jne rd, imm32, disp16
576 @itemx if rd != rs goto disp16
577 @itemx if rd != imm32 goto disp16
580 @item jsgt rd, rs, disp16
581 @itemx jsgt rd, imm32, disp16
582 @itemx if rd s> rs goto disp16
583 @itemx if rd s> imm32 goto disp16
584 Jump if signed greater.
586 @item jsge rd, rs, disp16
587 @itemx jsge rd, imm32, disp16
588 @itemx if rd s>= rd goto disp16
589 @itemx if rd s>= imm32 goto disp16
590 Jump if signed greater or equal.
592 @item jslt rd, rs, disp16
593 @itemx jslt rd, imm32, disp16
594 @itemx if rd s< rs goto disp16
595 @itemx if rd s< imm32 goto disp16
596 Jump if signed lesser.
598 @item jsle rd, rs, disp16
599 @itemx jsle rd, imm32, disp16
600 @itemx if rd s<= rs goto disp16
601 @itemx if rd s<= imm32 goto disp16
602 Jump if signed lesser or equal.
605 A call instruction is provided in order to perform calls to other eBPF
606 functions, or to external kernel helpers:
611 Jump and link to the offset @emph{disp32}, or to the kernel helper
612 function identified by @emph{imm32}.
619 Terminate the eBPF program.
622 @subsection 32-bit jump instructions
624 eBPF provides the following compare-and-jump instructions, which
625 compare the 32-bit values of the two given registers, or the values of
626 a register and an immediate, and perform a branch in case the
627 comparison holds true.
629 These instructions are only available in BPF v3 or later.
632 @item jeq32 rd, rs, disp16
633 @itemx jeq32 rd, imm32, disp16
634 @itemx if rd == rs goto disp16
635 @itemx if rd == imm32 goto disp16
636 Jump if equal, unsigned.
638 @item jgt32 rd, rs, disp16
639 @itemx jgt32 rd, imm32, disp16
640 @itemx if rd > rs goto disp16
641 @itemx if rd > imm32 goto disp16
642 Jump if greater, unsigned.
644 @item jge32 rd, rs, disp16
645 @itemx jge32 rd, imm32, disp16
646 @itemx if rd >= rs goto disp16
647 @itemx if rd >= imm32 goto disp16
648 Jump if greater or equal.
650 @item jlt32 rd, rs, disp16
651 @itemx jlt32 rd, imm32, disp16
652 @itemx if rd < rs goto disp16
653 @itemx if rd < imm32 goto disp16
656 @item jle32 rd , rs, disp16
657 @itemx jle32 rd, imm32, disp16
658 @itemx if rd <= rs goto disp16
659 @itemx if rd <= imm32 goto disp16
660 Jump if lesser or equal.
662 @item jset32 rd, rs, disp16
663 @itemx jset32 rd, imm32, disp16
664 @itemx if rd & rs goto disp16
665 @itemx if rd & imm32 goto disp16
666 Jump if signed equal.
668 @item jne32 rd, rs, disp16
669 @itemx jne32 rd, imm32, disp16
670 @itemx if rd != rs goto disp16
671 @itemx if rd != imm32 goto disp16
674 @item jsgt32 rd, rs, disp16
675 @itemx jsgt32 rd, imm32, disp16
676 @itemx if rd s> rs goto disp16
677 @itemx if rd s> imm32 goto disp16
678 Jump if signed greater.
680 @item jsge32 rd, rs, disp16
681 @itemx jsge32 rd, imm32, disp16
682 @itemx if rd s>= rd goto disp16
683 @itemx if rd s>= imm32 goto disp16
684 Jump if signed greater or equal.
686 @item jslt32 rd, rs, disp16
687 @itemx jslt32 rd, imm32, disp16
688 @itemx if rd s< rs goto disp16
689 @itemx if rd s< imm32 goto disp16
690 Jump if signed lesser.
692 @item jsle32 rd, rs, disp16
693 @itemx jsle32 rd, imm32, disp16
694 @itemx if rd s<= rs goto disp16
695 @itemx if rd s<= imm32 goto disp16
696 Jump if signed lesser or equal.
699 @subsection Atomic instructions
701 Atomic exchange-and-add instructions are provided in two flavors: one
702 for swapping 64-bit quantities and another for 32-bit quantities.
705 @item aadd [rd + offset16], rs
706 @itemx *(u64 *)(rd + offset16) = rs
707 Atomic add instruction.
709 @item aor [rd + offset16], rs
710 @itemx *(u64 *) (rd + offset16) |= rs
711 Atomic or instruction.
713 @item aand [rd + offset16], rs
714 @itemx *(u64 *) (rd + offset16) &= rs
715 Atomic and instruction.
717 @item axor [rd + offset16], rs
718 @itemx *(u64 *) (rd + offset16) ^= rs
719 Atomic xor instruction
720 @item xaddw [%d+offset16],%s
721 Exchange-and-add a 32-bit value at the specified location.
725 The following variants perform fetching before the atomic operation.
728 @item afadd [dr + offset16], rs
730 Atomic fetch-and-add instruction.
732 @item afor [dr + offset16], rs
734 Atomic fetch-and-or instruction.
736 @item afand [dr + offset16], rs
738 Atomic fetch-and-and instruction.
740 @item afxor [dr + offset16], rs
742 Atomic fetch-and-or instruction
745 The above instructions were introduced in the V3 of the BPF
746 instruction set. The following instruction is supported for backwards
750 @item xadddw [rd + offset16], rs
751 Alias to @code{aadd}.
754 @subsection 32-bit atomic instructions
756 Atomic exchange-and-add instructions are provided in two flavors: one
757 for swapping 32-bit quantities and another for 32-bit quantities.
760 @item aadd32 [rd + offset16], rs
761 @itemx *(u32 *)(rd + offset16) = rs
762 Atomic add instruction.
764 @item aor32 [rd + offset16], rs
765 @itemx *(u32 *) (rd + offset16) |= rs
766 Atomic or instruction.
768 @item aand32 [rd + offset16], rs
769 @itemx *(u32 *) (rd + offset16) &= rs
770 Atomic and instruction.
772 @item axor32 [rd + offset16], rs
773 @itemx *(u32 *) (rd + offset16) ^= rs
774 Atomic xor instruction
778 The following variants perform fetching before the atomic operation.
781 @item afadd32 [dr + offset16], rs
783 Atomic fetch-and-add instruction.
785 @item afor32 [dr + offset16], rs
787 Atomic fetch-and-or instruction.
789 @item afand32 [dr + offset16], rs
791 Atomic fetch-and-and instruction.
793 @item afxor32 [dr + offset16], rs
795 Atomic fetch-and-or instruction
798 The above instructions were introduced in the V3 of the BPF
799 instruction set. The following instruction is supported for backwards
803 @item xaddw [rd + offset16], rs
804 Alias to @code{aadd32}.