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.
57 @cindex @option{-mno-relax} command-line options, BPF
59 This option tells the assembler to not relax instructions.
62 Note that if no endianness option is specified in the command line,
63 the host endianness is used.
66 @node BPF Special Characters
67 @section BPF Special Characters
69 @cindex line comment character, BPF
70 @cindex BPF line comment character
71 The presence of a @samp{#} on a line indicates the start of a comment
72 that extends to the end of the current line.
74 @cindex block comments, BPF
75 @cindex BPF block comments
76 The presence of the @samp{/*} sequence indicates the beginning of a
77 block (multi-line) comment, whose contents span until the next
78 @samp{*/} sequence. It is not possible to nest block comments.
80 @cindex statement separator, BPF
81 Statements and assembly directives are separated by newlines and
85 @section BPF Registers
87 @cindex BPF register names
88 @cindex register names, BPF
89 The eBPF processor provides ten general-purpose 64-bit registers,
90 which are read-write, and a read-only frame pointer register:
97 General-purpose registers.
100 Read-only frame pointer register.
103 All BPF registers are 64-bit long. However, in the Pseudo-C syntax
104 registers can be referred using different names, which actually
105 reflect the kind of instruction they appear on:
112 General-purpose register in an instruction that operates on its value
113 as if it was a 64-bit value.
115 General-purpose register in an instruction that operates on its value
116 as if it was a 32-bit value.
118 Read-only frame pointer register.
122 Note that in the Pseudo-C syntax register names are not preceded by
123 @code{%} characters. A consequence of that is that in contexts like
124 instruction operands, where both register names and expressions
125 involving symbols are expected, there is no way to disambiguate
126 between them. In order to keep things simple, this assembler does not
127 allow to refer to symbols whose names collide with register names in
128 instruction operands.
131 @section BPF Directives
133 @cindex machine directives, BPF
135 The BPF version of @code{@value{AS}} supports the following additional
139 @cindex @code{half} directive, BPF
141 The @code{.half} directive produces a 16 bit value.
143 @cindex @code{word} directive, BPF
145 The @code{.word} directive produces a 32 bit value.
147 @cindex @code{dword} directive, BPF
149 The @code{.dword} directive produces a 64 bit value.
152 @node BPF Instructions
153 @section BPF Instructions
156 @cindex opcodes for BPF
157 In the instruction descriptions below the following field descriptors
162 Destination general-purpose register whose role is to be the
163 destination of an operation.
165 Source general-purpose register whose role is to be the source of an
168 16-bit signed PC-relative offset, measured in number of 64-bit words,
171 32-bit signed PC-relative offset, measured in number of 64-bit words,
174 Signed 16-bit immediate representing an offset in bytes.
176 Signed 16-bit immediate representing a displacement to a target,
177 measured in number of 64-bit words @emph{minus one}.
179 Signed 32-bit immediate representing a displacement to a target,
180 measured in number of 64-bit words @emph{minus one}.
182 Signed 32-bit immediate.
184 Signed 64-bit immediate.
188 Note that the assembler allows to express the value for an immediate
189 using any numerical literal whose two's complement encoding fits in
190 the immediate field. For example, @code{-2}, @code{0xfffffffe} and
191 @code{4294967294} all denote the same encoded 32-bit immediate, whose
192 value may be then interpreted by different instructions as either as a
193 negative or a positive number.
195 @subsection Arithmetic instructions
197 The destination register in these instructions act like an
200 Note that in pseudoc syntax these instructions should use @code{r}
208 64-bit arithmetic addition.
214 64-bit arithmetic subtraction.
220 64-bit arithmetic multiplication.
226 64-bit arithmetic integer division.
232 64-bit integer remainder.
238 64-bit bit-wise ``and'' operation.
244 64-bit bit-wise ``or'' operation.
250 64-bit bit-wise exclusive-or operation.
256 64-bit left shift, by @code{rs} or @code{imm32} bits.
262 64-bit right logical shift, by @code{rs} or @code{imm32} bits.
265 @itemx arsh rd, imm32
268 64-bit right arithmetic shift, by @code{rs} or @code{imm32} bits.
272 64-bit arithmetic negation.
278 Move the 64-bit value of @code{rs} in @code{rd}, or load @code{imm32}
283 Move the sign-extended 8-bit value in @code{rs} to @code{rd}.
285 @item movs rd, rs, 16
287 Move the sign-extended 16-bit value in @code{rs} to @code{rd}.
289 @item movs rd, rs, 32
291 Move the sign-extended 32-bit value in @code{rs} to @code{rd}.
294 @subsection 32-bit arithmetic instructions
296 The destination register in these instructions act as an accumulator.
298 Note that in pseudoc syntax these instructions should use @code{w}
299 registers. It is not allowed to mix @code{w} and @code{r} registers
300 in the same instruction.
304 @itemx add32 rd, imm32
307 32-bit arithmetic addition.
310 @itemx sub32 rd, imm32
313 32-bit arithmetic subtraction.
316 @itemx mul32 rd, imm32
319 32-bit arithmetic multiplication.
322 @itemx div32 rd, imm32
325 32-bit arithmetic integer division.
328 @itemx mod32 rd, imm32
331 32-bit integer remainder.
334 @itemx and32 rd, imm32
337 32-bit bit-wise ``and'' operation.
340 @itemx or32 rd, imm32
343 32-bit bit-wise ``or'' operation.
346 @itemx xor32 rd, imm32
349 32-bit bit-wise exclusive-or operation.
352 @itemx lsh32 rd, imm32
355 32-bit left shift, by @code{rs} or @code{imm32} bits.
358 @itemx rsh32 rd, imm32
361 32-bit right logical shift, by @code{rs} or @code{imm32} bits.
364 @itemx arsh32 rd, imm32
367 32-bit right arithmetic shift, by @code{rs} or @code{imm32} bits.
371 32-bit arithmetic negation.
374 @itemx mov32 rd, imm32
377 Move the 32-bit value of @code{rs} in @code{rd}, or load @code{imm32}
380 @item mov32s rd, rs, 8
382 Move the sign-extended 8-bit value in @code{rs} to @code{rd}.
384 @item mov32s rd, rs, 16
386 Move the sign-extended 16-bit value in @code{rs} to @code{rd}.
388 @item mov32s rd, rs, 32
390 Move the sign-extended 32-bit value in @code{rs} to @code{rd}.
393 @subsection Endianness conversion instructions
402 Convert the 16-bit, 32-bit or 64-bit value in @code{rd} to
403 little-endian and store it back in @code{rd}.
410 Convert the 16-bit, 32-bit or 64-bit value in @code{rd} to big-endian
411 and store it back in @code{rd}.
414 @subsection Byte swap instructions
418 @itemx rd = bswap16 rd
419 Swap the least-significant 16-bit word in @code{rd} with the
420 most-significant 16-bit word.
423 @itemx rd = bswap32 rd
424 Swap the least-significant 32-bit word in @code{rd} with the
425 most-significant 32-bit word.
428 @itemx rd = bswap64 rd
429 Swap the least-significant 64-bit word in @code{rd} with the
430 most-significant 64-bit word.
434 @subsection 64-bit load and pseudo maps
439 Load the given signed 64-bit immediate to the destination register
443 @subsection Load instructions for socket filters
445 The following instructions are intended to be used in socket filters,
446 and are therefore not general-purpose: they make assumptions on the
447 contents of several registers. See the file
448 @file{Documentation/networking/filter.txt} in the Linux kernel source
449 tree for more information.
455 @itemx r0 = *(u64 *) skb[imm32]
456 Absolute 64-bit load.
459 @itemx r0 = *(u32 *) skb[imm32]
460 Absolute 32-bit load.
463 @itemx r0 = *(u16 *) skb[imm32]
464 Absolute 16-bit load.
467 @itemx r0 = *(u8 *) skb[imm32]
474 @item ldinddw rs, imm32
475 @itemx r0 = *(u64 *) skb[rs + imm32]
476 Indirect 64-bit load.
478 @item ldindw rs, imm32
479 @itemx r0 = *(u32 *) skb[rs + imm32]
480 Indirect 32-bit load.
482 @item ldindh rs, imm32
483 @itemx r0 = *(u16 *) skb[rs + imm32]
484 Indirect 16-bit load.
486 @item ldindb %s, imm32
487 @itemx r0 = *(u8 *) skb[rs + imm32]
491 @subsection Generic load/store instructions
493 General-purpose load and store instructions are provided for several
496 Load to register instructions:
499 @item ldxdw rd, [rs + offset16]
500 @itemx rd = *(u64 *) (rs + offset16)
503 @item ldxw rd, [rs + offset16]
504 @itemx rd = *(u32 *) (rs + offset16)
507 @item ldxh rd, [rs + offset16]
508 @itemx rd = *(u16 *) (rs + offset16)
511 @item ldxb rd, [rs + offset16]
512 @itemx rd = *(u8 *) (rs + offset16)
516 Signed load to register instructions:
519 @item ldxsdw rd, [rs + offset16]
520 @itemx rd = *(s64 *) (rs + offset16)
521 Generic 64-bit signed load.
523 @item ldxsw rd, [rs + offset16]
524 @itemx rd = *(s32 *) (rs + offset16)
525 Generic 32-bit signed load.
527 @item ldxsh rd, [rs + offset16]
528 @itemx rd = *(s16 *) (rs + offset16)
529 Generic 16-bit signed load.
531 @item ldxsb rd, [rs + offset16]
532 @itemx rd = *(s8 *) (rs + offset16)
533 Generic 8-bit signed load.
536 Store from register instructions:
539 @item stxdw [rd + offset16], %s
540 @itemx *(u64 *) (rd + offset16)
541 Generic 64-bit store.
543 @item stxw [rd + offset16], %s
544 @itemx *(u32 *) (rd + offset16)
545 Generic 32-bit store.
547 @item stxh [rd + offset16], %s
548 @itemx *(u16 *) (rd + offset16)
549 Generic 16-bit store.
551 @item stxb [rd + offset16], %s
552 @itemx *(u8 *) (rd + offset16)
556 Store from immediates instructions:
559 @item stdw [rd + offset16], imm32
560 @itemx *(u64 *) (rd + offset16) = imm32
561 Store immediate as 64-bit.
563 @item stw [rd + offset16], imm32
564 @itemx *(u32 *) (rd + offset16) = imm32
565 Store immediate as 32-bit.
567 @item sth [rd + offset16], imm32
568 @itemx *(u16 *) (rd + offset16) = imm32
569 Store immediate as 16-bit.
571 @item stb [rd + offset16], imm32
572 @itemx *(u8 *) (rd + offset16) = imm32
573 Store immediate as 8-bit.
576 @subsection Jump instructions
578 eBPF provides the following compare-and-jump instructions, which
579 compare the values of the two given registers, or the values of a
580 register and an immediate, and perform a branch in case the comparison
590 Jump-always, long range.
592 @item jeq rd, rs, disp16
593 @itemx jeq rd, imm32, disp16
594 @itemx if rd == rs goto disp16
595 @itemx if rd == imm32 goto disp16
596 Jump if equal, unsigned.
598 @item jgt rd, rs, disp16
599 @itemx jgt rd, imm32, disp16
600 @itemx if rd > rs goto disp16
601 @itemx if rd > imm32 goto disp16
602 Jump if greater, unsigned.
604 @item jge rd, rs, disp16
605 @itemx jge rd, imm32, disp16
606 @itemx if rd >= rs goto disp16
607 @itemx if rd >= imm32 goto disp16
608 Jump if greater or equal.
610 @item jlt rd, rs, disp16
611 @itemx jlt rd, imm32, disp16
612 @itemx if rd < rs goto disp16
613 @itemx if rd < imm32 goto disp16
616 @item jle rd , rs, disp16
617 @itemx jle rd, imm32, disp16
618 @itemx if rd <= rs goto disp16
619 @itemx if rd <= imm32 goto disp16
620 Jump if lesser or equal.
622 @item jset rd, rs, disp16
623 @itemx jset rd, imm32, disp16
624 @itemx if rd & rs goto disp16
625 @itemx if rd & imm32 goto disp16
626 Jump if signed equal.
628 @item jne rd, rs, disp16
629 @itemx jne rd, imm32, disp16
630 @itemx if rd != rs goto disp16
631 @itemx if rd != imm32 goto disp16
634 @item jsgt rd, rs, disp16
635 @itemx jsgt rd, imm32, disp16
636 @itemx if rd s> rs goto disp16
637 @itemx if rd s> imm32 goto disp16
638 Jump if signed greater.
640 @item jsge rd, rs, disp16
641 @itemx jsge rd, imm32, disp16
642 @itemx if rd s>= rd goto disp16
643 @itemx if rd s>= imm32 goto disp16
644 Jump if signed greater or equal.
646 @item jslt rd, rs, disp16
647 @itemx jslt rd, imm32, disp16
648 @itemx if rd s< rs goto disp16
649 @itemx if rd s< imm32 goto disp16
650 Jump if signed lesser.
652 @item jsle rd, rs, disp16
653 @itemx jsle rd, imm32, disp16
654 @itemx if rd s<= rs goto disp16
655 @itemx if rd s<= imm32 goto disp16
656 Jump if signed lesser or equal.
659 A call instruction is provided in order to perform calls to other eBPF
660 functions, or to external kernel helpers:
665 Jump and link to the offset @emph{disp32}, or to the kernel helper
666 function identified by @emph{imm32}.
673 Terminate the eBPF program.
676 @subsection 32-bit jump instructions
678 eBPF provides the following compare-and-jump instructions, which
679 compare the 32-bit values of the two given registers, or the values of
680 a register and an immediate, and perform a branch in case the
681 comparison holds true.
683 These instructions are only available in BPF v3 or later.
686 @item jeq32 rd, rs, disp16
687 @itemx jeq32 rd, imm32, disp16
688 @itemx if rd == rs goto disp16
689 @itemx if rd == imm32 goto disp16
690 Jump if equal, unsigned.
692 @item jgt32 rd, rs, disp16
693 @itemx jgt32 rd, imm32, disp16
694 @itemx if rd > rs goto disp16
695 @itemx if rd > imm32 goto disp16
696 Jump if greater, unsigned.
698 @item jge32 rd, rs, disp16
699 @itemx jge32 rd, imm32, disp16
700 @itemx if rd >= rs goto disp16
701 @itemx if rd >= imm32 goto disp16
702 Jump if greater or equal.
704 @item jlt32 rd, rs, disp16
705 @itemx jlt32 rd, imm32, disp16
706 @itemx if rd < rs goto disp16
707 @itemx if rd < imm32 goto disp16
710 @item jle32 rd , rs, disp16
711 @itemx jle32 rd, imm32, disp16
712 @itemx if rd <= rs goto disp16
713 @itemx if rd <= imm32 goto disp16
714 Jump if lesser or equal.
716 @item jset32 rd, rs, disp16
717 @itemx jset32 rd, imm32, disp16
718 @itemx if rd & rs goto disp16
719 @itemx if rd & imm32 goto disp16
720 Jump if signed equal.
722 @item jne32 rd, rs, disp16
723 @itemx jne32 rd, imm32, disp16
724 @itemx if rd != rs goto disp16
725 @itemx if rd != imm32 goto disp16
728 @item jsgt32 rd, rs, disp16
729 @itemx jsgt32 rd, imm32, disp16
730 @itemx if rd s> rs goto disp16
731 @itemx if rd s> imm32 goto disp16
732 Jump if signed greater.
734 @item jsge32 rd, rs, disp16
735 @itemx jsge32 rd, imm32, disp16
736 @itemx if rd s>= rd goto disp16
737 @itemx if rd s>= imm32 goto disp16
738 Jump if signed greater or equal.
740 @item jslt32 rd, rs, disp16
741 @itemx jslt32 rd, imm32, disp16
742 @itemx if rd s< rs goto disp16
743 @itemx if rd s< imm32 goto disp16
744 Jump if signed lesser.
746 @item jsle32 rd, rs, disp16
747 @itemx jsle32 rd, imm32, disp16
748 @itemx if rd s<= rs goto disp16
749 @itemx if rd s<= imm32 goto disp16
750 Jump if signed lesser or equal.
753 @subsection Atomic instructions
755 Atomic exchange instructions are provided in two flavors: one for
756 compare-and-swap, one for unconditional exchange.
759 @item acmp [rd + offset16], rs
760 @itemx r0 = cmpxchg_64 (rd + offset16, r0, rs)
761 Atomic compare-and-swap. Compares value in @code{r0} to value
762 addressed by @code{rd + offset16}. On match, the value addressed by
763 @code{rd + offset16} is replaced with the value in @code{rs}.
764 Regardless, the value that was at @code{rd + offset16} is
765 zero-extended and loaded into @code{r0}.
767 @item axchg [rd + offset16], rs
768 @itemx rs = xchg_64 (rd + offset16, rs)
769 Atomic exchange. Atomically exchanges the value in @code{rs} with
770 the value addressed by @code{rd + offset16}.
774 The following instructions provide atomic arithmetic operations.
777 @item aadd [rd + offset16], rs
778 @itemx lock *(u64 *)(rd + offset16) = rs
779 Atomic add instruction.
781 @item aor [rd + offset16], rs
782 @itemx lock *(u64 *) (rd + offset16) |= rs
783 Atomic or instruction.
785 @item aand [rd + offset16], rs
786 @itemx lock *(u64 *) (rd + offset16) &= rs
787 Atomic and instruction.
789 @item axor [rd + offset16], rs
790 @itemx lock *(u64 *) (rd + offset16) ^= rs
791 Atomic xor instruction.
795 The following variants perform fetching before the atomic operation.
798 @item afadd [rd + offset16], rs
799 @itemx rs = atomic_fetch_add ((u64 *)(rd + offset16), rs)
800 Atomic fetch-and-add instruction.
802 @item afor [rd + offset16], rs
803 @itemx rs = atomic_fetch_or ((u64 *)(rd + offset16), rs)
804 Atomic fetch-and-or instruction.
806 @item afand [rd + offset16], rs
807 @itemx rs = atomic_fetch_and ((u64 *)(rd + offset16), rs)
808 Atomic fetch-and-and instruction.
810 @item afxor [rd + offset16], rs
811 @itemx rs = atomic_fetch_xor ((u64 *)(rd + offset16), rs)
812 Atomic fetch-and-or instruction.
815 The above instructions were introduced in the V3 of the BPF
816 instruction set. The following instruction is supported for backwards
820 @item xadddw [rd + offset16], rs
821 Alias to @code{aadd}.
824 @subsection 32-bit atomic instructions
826 32-bit atomic exchange instructions are provided in two flavors: one
827 for compare-and-swap, one for unconditional exchange.
830 @item acmp32 [rd + offset16], rs
831 @itemx w0 = cmpxchg32_32 (rd + offset16, w0, ws)
832 Atomic compare-and-swap. Compares value in @code{w0} to value
833 addressed by @code{rd + offset16}. On match, the value addressed by
834 @code{rd + offset16} is replaced with the value in @code{ws}.
835 Regardless, the value that was at @code{rd + offset16} is
836 zero-extended and loaded into @code{w0}.
838 @item axchg [rd + offset16], rs
839 @itemx ws = xchg32_32 (rd + offset16, ws)
840 Atomic exchange. Atomically exchanges the value in @code{ws} with
841 the value addressed by @code{rd + offset16}.
845 The following instructions provide 32-bit atomic arithmetic operations.
848 @item aadd32 [rd + offset16], rs
849 @itemx lock *(u32 *)(rd + offset16) = rs
850 Atomic add instruction.
852 @item aor32 [rd + offset16], rs
853 @itemx lock *(u32 *) (rd + offset16) |= rs
854 Atomic or instruction.
856 @item aand32 [rd + offset16], rs
857 @itemx lock *(u32 *) (rd + offset16) &= rs
858 Atomic and instruction.
860 @item axor32 [rd + offset16], rs
861 @itemx lock *(u32 *) (rd + offset16) ^= rs
862 Atomic xor instruction
866 The following variants perform fetching before the atomic operation.
869 @item afadd32 [dr + offset16], rs
870 @itemx ws = atomic_fetch_add ((u32 *)(rd + offset16), ws)
871 Atomic fetch-and-add instruction.
873 @item afor32 [dr + offset16], rs
874 @itemx ws = atomic_fetch_or ((u32 *)(rd + offset16), ws)
875 Atomic fetch-and-or instruction.
877 @item afand32 [dr + offset16], rs
878 @itemx ws = atomic_fetch_and ((u32 *)(rd + offset16), ws)
879 Atomic fetch-and-and instruction.
881 @item afxor32 [dr + offset16], rs
882 @itemx ws = atomic_fetch_xor ((u32 *)(rd + offset16), ws)
883 Atomic fetch-and-or instruction
886 The above instructions were introduced in the V3 of the BPF
887 instruction set. The following instruction is supported for backwards
891 @item xaddw [rd + offset16], rs
892 Alias to @code{aadd32}.