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{;} or a @samp{#} on a line indicates the start
72 of a comment that extends to the end of the current line.
74 @cindex statement separator, BPF
75 Statements and assembly directives are separated by newlines.
78 @section BPF Registers
80 @cindex BPF register names
81 @cindex register names, BPF
82 The eBPF processor provides ten general-purpose 64-bit registers,
83 which are read-write, and a read-only frame pointer register:
90 General-purpose registers.
93 Read-only frame pointer register.
96 All BPF registers are 64-bit long. However, in the Pseudo-C syntax
97 registers can be referred using different names, which actually
98 reflect the kind of instruction they appear on:
105 General-purpose register in an instruction that operates on its value
106 as if it was a 64-bit value.
108 General-purpose register in an instruction that operates on its value
109 as if it was a 32-bit value.
111 Read-only frame pointer register.
115 Note that in the Pseudo-C syntax register names are not preceded by
116 @code{%} characters. A consequence of that is that in contexts like
117 instruction operands, where both register names and expressions
118 involving symbols are expected, there is no way to disambiguate
119 between them. In order to keep things simple, this assembler does not
120 allow to refer to symbols whose names collide with register names in
121 instruction operands.
124 @section BPF Directives
126 @cindex machine directives, BPF
128 The BPF version of @code{@value{AS}} supports the following additional
132 @cindex @code{half} directive, BPF
134 The @code{.half} directive produces a 16 bit value.
136 @cindex @code{word} directive, BPF
138 The @code{.word} directive produces a 32 bit value.
140 @cindex @code{dword} directive, BPF
142 The @code{.dword} directive produces a 64 bit value.
145 @node BPF Instructions
146 @section BPF Instructions
149 @cindex opcodes for BPF
150 In the instruction descriptions below the following field descriptors
155 Destination general-purpose register whose role is to be the
156 destination of an operation.
158 Source general-purpose register whose role is to be the source of an
161 16-bit signed PC-relative offset, measured in number of 64-bit words,
164 32-bit signed PC-relative offset, measured in number of 64-bit words,
167 Signed 16-bit immediate representing an offset in bytes.
169 Signed 16-bit immediate representing a displacement to a target,
170 measured in number of 64-bit words @emph{minus one}.
172 Signed 32-bit immediate representing a displacement to a target,
173 measured in number of 64-bit words @emph{minus one}.
175 Signed 32-bit immediate.
177 Signed 64-bit immediate.
181 Note that the assembler allows to express the value for an immediate
182 using any numerical literal whose two's complement encoding fits in
183 the immediate field. For example, @code{-2}, @code{0xfffffffe} and
184 @code{4294967294} all denote the same encoded 32-bit immediate, whose
185 value may be then interpreted by different instructions as either as a
186 negative or a positive number.
188 @subsection Arithmetic instructions
190 The destination register in these instructions act like an
193 Note that in pseudoc syntax these instructions should use @code{r}
201 64-bit arithmetic addition.
207 64-bit arithmetic subtraction.
213 64-bit arithmetic multiplication.
219 64-bit arithmetic integer division.
225 64-bit integer remainder.
231 64-bit bit-wise ``and'' operation.
237 64-bit bit-wise ``or'' operation.
243 64-bit bit-wise exclusive-or operation.
249 64-bit left shift, by @code{rs} or @code{imm32} bits.
255 64-bit right logical shift, by @code{rs} or @code{imm32} bits.
258 @itemx arsh rd, imm32
261 64-bit right arithmetic shift, by @code{rs} or @code{imm32} bits.
265 64-bit arithmetic negation.
271 Move the 64-bit value of @code{rs} in @code{rd}, or load @code{imm32}
276 Move the sign-extended 8-bit value in @code{rs} to @code{rd}.
278 @item movs rd, rs, 16
280 Move the sign-extended 16-bit value in @code{rs} to @code{rd}.
282 @item movs rd, rs, 32
284 Move the sign-extended 32-bit value in @code{rs} to @code{rd}.
287 @subsection 32-bit arithmetic instructions
289 The destination register in these instructions act as an accumulator.
291 Note that in pseudoc syntax these instructions should use @code{w}
292 registers. It is not allowed to mix @code{w} and @code{r} registers
293 in the same instruction.
297 @itemx add32 rd, imm32
300 32-bit arithmetic addition.
303 @itemx sub32 rd, imm32
306 32-bit arithmetic subtraction.
309 @itemx mul32 rd, imm32
312 32-bit arithmetic multiplication.
315 @itemx div32 rd, imm32
318 32-bit arithmetic integer division.
321 @itemx mod32 rd, imm32
324 32-bit integer remainder.
327 @itemx and32 rd, imm32
330 32-bit bit-wise ``and'' operation.
333 @itemx or32 rd, imm32
336 32-bit bit-wise ``or'' operation.
339 @itemx xor32 rd, imm32
342 32-bit bit-wise exclusive-or operation.
345 @itemx lsh32 rd, imm32
348 32-bit left shift, by @code{rs} or @code{imm32} bits.
351 @itemx rsh32 rd, imm32
354 32-bit right logical shift, by @code{rs} or @code{imm32} bits.
357 @itemx arsh32 rd, imm32
360 32-bit right arithmetic shift, by @code{rs} or @code{imm32} bits.
364 32-bit arithmetic negation.
367 @itemx mov32 rd, imm32
370 Move the 32-bit value of @code{rs} in @code{rd}, or load @code{imm32}
373 @item mov32s rd, rs, 8
375 Move the sign-extended 8-bit value in @code{rs} to @code{rd}.
377 @item mov32s rd, rs, 16
379 Move the sign-extended 16-bit value in @code{rs} to @code{rd}.
381 @item mov32s rd, rs, 32
383 Move the sign-extended 32-bit value in @code{rs} to @code{rd}.
386 @subsection Endianness conversion instructions
395 Convert the 16-bit, 32-bit or 64-bit value in @code{rd} to
396 little-endian and store it back in @code{rd}.
403 Convert the 16-bit, 32-bit or 64-bit value in @code{rd} to big-endian
404 and store it back in @code{rd}.
407 @subsection Byte swap instructions
411 @itemx rd = bswap16 rd
412 Swap the least-significant 16-bit word in @code{rd} with the
413 most-significant 16-bit word.
416 @itemx rd = bswap32 rd
417 Swap the least-significant 32-bit word in @code{rd} with the
418 most-significant 32-bit word.
421 @itemx rd = bswap64 rd
422 Swap the least-significant 64-bit word in @code{rd} with the
423 most-significant 64-bit word.
427 @subsection 64-bit load and pseudo maps
432 Load the given signed 64-bit immediate to the destination register
436 @subsection Load instructions for socket filters
438 The following instructions are intended to be used in socket filters,
439 and are therefore not general-purpose: they make assumptions on the
440 contents of several registers. See the file
441 @file{Documentation/networking/filter.txt} in the Linux kernel source
442 tree for more information.
448 @itemx r0 = *(u64 *) skb[imm32]
449 Absolute 64-bit load.
452 @itemx r0 = *(u32 *) skb[imm32]
453 Absolute 32-bit load.
456 @itemx r0 = *(u16 *) skb[imm32]
457 Absolute 16-bit load.
460 @itemx r0 = *(u8 *) skb[imm32]
467 @item ldinddw rs, imm32
468 @itemx r0 = *(u64 *) skb[rs + imm32]
469 Indirect 64-bit load.
471 @item ldindw rs, imm32
472 @itemx r0 = *(u32 *) skb[rs + imm32]
473 Indirect 32-bit load.
475 @item ldindh rs, imm32
476 @itemx r0 = *(u16 *) skb[rs + imm32]
477 Indirect 16-bit load.
479 @item ldindb %s, imm32
480 @itemx r0 = *(u8 *) skb[rs + imm32]
484 @subsection Generic load/store instructions
486 General-purpose load and store instructions are provided for several
489 Load to register instructions:
492 @item ldxdw rd, [rs + offset16]
493 @itemx rd = *(u64 *) (rs + offset16)
496 @item ldxw rd, [rs + offset16]
497 @itemx rd = *(u32 *) (rs + offset16)
500 @item ldxh rd, [rs + offset16]
501 @itemx rd = *(u16 *) (rs + offset16)
504 @item ldxb rd, [rs + offset16]
505 @itemx rd = *(u8 *) (rs + offset16)
509 Signed load to register instructions:
512 @item ldxsdw rd, [rs + offset16]
513 @itemx rd = *(s64 *) (rs + offset16)
514 Generic 64-bit signed load.
516 @item ldxsw rd, [rs + offset16]
517 @itemx rd = *(s32 *) (rs + offset16)
518 Generic 32-bit signed load.
520 @item ldxsh rd, [rs + offset16]
521 @itemx rd = *(s16 *) (rs + offset16)
522 Generic 16-bit signed load.
524 @item ldxsb rd, [rs + offset16]
525 @itemx rd = *(s8 *) (rs + offset16)
526 Generic 8-bit signed load.
529 Store from register instructions:
532 @item stxdw [rd + offset16], %s
533 @itemx *(u64 *) (rd + offset16)
534 Generic 64-bit store.
536 @item stxw [rd + offset16], %s
537 @itemx *(u32 *) (rd + offset16)
538 Generic 32-bit store.
540 @item stxh [rd + offset16], %s
541 @itemx *(u16 *) (rd + offset16)
542 Generic 16-bit store.
544 @item stxb [rd + offset16], %s
545 @itemx *(u8 *) (rd + offset16)
549 Store from immediates instructions:
552 @item stdw [rd + offset16], imm32
553 @itemx *(u64 *) (rd + offset16) = imm32
554 Store immediate as 64-bit.
556 @item stw [rd + offset16], imm32
557 @itemx *(u32 *) (rd + offset16) = imm32
558 Store immediate as 32-bit.
560 @item sth [rd + offset16], imm32
561 @itemx *(u16 *) (rd + offset16) = imm32
562 Store immediate as 16-bit.
564 @item stb [rd + offset16], imm32
565 @itemx *(u8 *) (rd + offset16) = imm32
566 Store immediate as 8-bit.
569 @subsection Jump instructions
571 eBPF provides the following compare-and-jump instructions, which
572 compare the values of the two given registers, or the values of a
573 register and an immediate, and perform a branch in case the comparison
583 Jump-always, long range.
585 @item jeq rd, rs, disp16
586 @itemx jeq rd, imm32, disp16
587 @itemx if rd == rs goto disp16
588 @itemx if rd == imm32 goto disp16
589 Jump if equal, unsigned.
591 @item jgt rd, rs, disp16
592 @itemx jgt rd, imm32, disp16
593 @itemx if rd > rs goto disp16
594 @itemx if rd > imm32 goto disp16
595 Jump if greater, unsigned.
597 @item jge rd, rs, disp16
598 @itemx jge rd, imm32, disp16
599 @itemx if rd >= rs goto disp16
600 @itemx if rd >= imm32 goto disp16
601 Jump if greater or equal.
603 @item jlt rd, rs, disp16
604 @itemx jlt rd, imm32, disp16
605 @itemx if rd < rs goto disp16
606 @itemx if rd < imm32 goto disp16
609 @item jle rd , rs, disp16
610 @itemx jle rd, imm32, disp16
611 @itemx if rd <= rs goto disp16
612 @itemx if rd <= imm32 goto disp16
613 Jump if lesser or equal.
615 @item jset rd, rs, disp16
616 @itemx jset rd, imm32, disp16
617 @itemx if rd & rs goto disp16
618 @itemx if rd & imm32 goto disp16
619 Jump if signed equal.
621 @item jne rd, rs, disp16
622 @itemx jne rd, imm32, disp16
623 @itemx if rd != rs goto disp16
624 @itemx if rd != imm32 goto disp16
627 @item jsgt rd, rs, disp16
628 @itemx jsgt rd, imm32, disp16
629 @itemx if rd s> rs goto disp16
630 @itemx if rd s> imm32 goto disp16
631 Jump if signed greater.
633 @item jsge rd, rs, disp16
634 @itemx jsge rd, imm32, disp16
635 @itemx if rd s>= rd goto disp16
636 @itemx if rd s>= imm32 goto disp16
637 Jump if signed greater or equal.
639 @item jslt rd, rs, disp16
640 @itemx jslt rd, imm32, disp16
641 @itemx if rd s< rs goto disp16
642 @itemx if rd s< imm32 goto disp16
643 Jump if signed lesser.
645 @item jsle rd, rs, disp16
646 @itemx jsle rd, imm32, disp16
647 @itemx if rd s<= rs goto disp16
648 @itemx if rd s<= imm32 goto disp16
649 Jump if signed lesser or equal.
652 A call instruction is provided in order to perform calls to other eBPF
653 functions, or to external kernel helpers:
658 Jump and link to the offset @emph{disp32}, or to the kernel helper
659 function identified by @emph{imm32}.
666 Terminate the eBPF program.
669 @subsection 32-bit jump instructions
671 eBPF provides the following compare-and-jump instructions, which
672 compare the 32-bit values of the two given registers, or the values of
673 a register and an immediate, and perform a branch in case the
674 comparison holds true.
676 These instructions are only available in BPF v3 or later.
679 @item jeq32 rd, rs, disp16
680 @itemx jeq32 rd, imm32, disp16
681 @itemx if rd == rs goto disp16
682 @itemx if rd == imm32 goto disp16
683 Jump if equal, unsigned.
685 @item jgt32 rd, rs, disp16
686 @itemx jgt32 rd, imm32, disp16
687 @itemx if rd > rs goto disp16
688 @itemx if rd > imm32 goto disp16
689 Jump if greater, unsigned.
691 @item jge32 rd, rs, disp16
692 @itemx jge32 rd, imm32, disp16
693 @itemx if rd >= rs goto disp16
694 @itemx if rd >= imm32 goto disp16
695 Jump if greater or equal.
697 @item jlt32 rd, rs, disp16
698 @itemx jlt32 rd, imm32, disp16
699 @itemx if rd < rs goto disp16
700 @itemx if rd < imm32 goto disp16
703 @item jle32 rd , rs, disp16
704 @itemx jle32 rd, imm32, disp16
705 @itemx if rd <= rs goto disp16
706 @itemx if rd <= imm32 goto disp16
707 Jump if lesser or equal.
709 @item jset32 rd, rs, disp16
710 @itemx jset32 rd, imm32, disp16
711 @itemx if rd & rs goto disp16
712 @itemx if rd & imm32 goto disp16
713 Jump if signed equal.
715 @item jne32 rd, rs, disp16
716 @itemx jne32 rd, imm32, disp16
717 @itemx if rd != rs goto disp16
718 @itemx if rd != imm32 goto disp16
721 @item jsgt32 rd, rs, disp16
722 @itemx jsgt32 rd, imm32, disp16
723 @itemx if rd s> rs goto disp16
724 @itemx if rd s> imm32 goto disp16
725 Jump if signed greater.
727 @item jsge32 rd, rs, disp16
728 @itemx jsge32 rd, imm32, disp16
729 @itemx if rd s>= rd goto disp16
730 @itemx if rd s>= imm32 goto disp16
731 Jump if signed greater or equal.
733 @item jslt32 rd, rs, disp16
734 @itemx jslt32 rd, imm32, disp16
735 @itemx if rd s< rs goto disp16
736 @itemx if rd s< imm32 goto disp16
737 Jump if signed lesser.
739 @item jsle32 rd, rs, disp16
740 @itemx jsle32 rd, imm32, disp16
741 @itemx if rd s<= rs goto disp16
742 @itemx if rd s<= imm32 goto disp16
743 Jump if signed lesser or equal.
746 @subsection Atomic instructions
748 Atomic exchange instructions are provided in two flavors: one for
749 compare-and-swap, one for unconditional exchange.
752 @item acmp [rd + offset16], rs
753 @itemx r0 = cmpxchg_64 (rd + offset16, r0, rs)
754 Atomic compare-and-swap. Compares value in @code{r0} to value
755 addressed by @code{rd + offset16}. On match, the value addressed by
756 @code{rd + offset16} is replaced with the value in @code{rs}.
757 Regardless, the value that was at @code{rd + offset16} is
758 zero-extended and loaded into @code{r0}.
760 @item axchg [rd + offset16], rs
761 @itemx rs = xchg_64 (rd + offset16, rs)
762 Atomic exchange. Atomically exchanges the value in @code{rs} with
763 the value addressed by @code{rd + offset16}.
767 The following instructions provide atomic arithmetic operations.
770 @item aadd [rd + offset16], rs
771 @itemx lock *(u64 *)(rd + offset16) = rs
772 Atomic add instruction.
774 @item aor [rd + offset16], rs
775 @itemx lock *(u64 *) (rd + offset16) |= rs
776 Atomic or instruction.
778 @item aand [rd + offset16], rs
779 @itemx lock *(u64 *) (rd + offset16) &= rs
780 Atomic and instruction.
782 @item axor [rd + offset16], rs
783 @itemx lock *(u64 *) (rd + offset16) ^= rs
784 Atomic xor instruction.
788 The following variants perform fetching before the atomic operation.
791 @item afadd [rd + offset16], rs
792 @itemx rs = atomic_fetch_add ((u64 *)(rd + offset16), rs)
793 Atomic fetch-and-add instruction.
795 @item afor [rd + offset16], rs
796 @itemx rs = atomic_fetch_or ((u64 *)(rd + offset16), rs)
797 Atomic fetch-and-or instruction.
799 @item afand [rd + offset16], rs
800 @itemx rs = atomic_fetch_and ((u64 *)(rd + offset16), rs)
801 Atomic fetch-and-and instruction.
803 @item afxor [rd + offset16], rs
804 @itemx rs = atomic_fetch_xor ((u64 *)(rd + offset16), rs)
805 Atomic fetch-and-or instruction.
808 The above instructions were introduced in the V3 of the BPF
809 instruction set. The following instruction is supported for backwards
813 @item xadddw [rd + offset16], rs
814 Alias to @code{aadd}.
817 @subsection 32-bit atomic instructions
819 32-bit atomic exchange instructions are provided in two flavors: one
820 for compare-and-swap, one for unconditional exchange.
823 @item acmp32 [rd + offset16], rs
824 @itemx w0 = cmpxchg32_32 (rd + offset16, w0, ws)
825 Atomic compare-and-swap. Compares value in @code{w0} to value
826 addressed by @code{rd + offset16}. On match, the value addressed by
827 @code{rd + offset16} is replaced with the value in @code{ws}.
828 Regardless, the value that was at @code{rd + offset16} is
829 zero-extended and loaded into @code{w0}.
831 @item axchg [rd + offset16], rs
832 @itemx ws = xchg32_32 (rd + offset16, ws)
833 Atomic exchange. Atomically exchanges the value in @code{ws} with
834 the value addressed by @code{rd + offset16}.
838 The following instructions provide 32-bit atomic arithmetic operations.
841 @item aadd32 [rd + offset16], rs
842 @itemx lock *(u32 *)(rd + offset16) = rs
843 Atomic add instruction.
845 @item aor32 [rd + offset16], rs
846 @itemx lock *(u32 *) (rd + offset16) |= rs
847 Atomic or instruction.
849 @item aand32 [rd + offset16], rs
850 @itemx lock *(u32 *) (rd + offset16) &= rs
851 Atomic and instruction.
853 @item axor32 [rd + offset16], rs
854 @itemx lock *(u32 *) (rd + offset16) ^= rs
855 Atomic xor instruction
859 The following variants perform fetching before the atomic operation.
862 @item afadd32 [dr + offset16], rs
863 @itemx ws = atomic_fetch_add ((u32 *)(rd + offset16), ws)
864 Atomic fetch-and-add instruction.
866 @item afor32 [dr + offset16], rs
867 @itemx ws = atomic_fetch_or ((u32 *)(rd + offset16), ws)
868 Atomic fetch-and-or instruction.
870 @item afand32 [dr + offset16], rs
871 @itemx ws = atomic_fetch_and ((u32 *)(rd + offset16), ws)
872 Atomic fetch-and-and instruction.
874 @item afxor32 [dr + offset16], rs
875 @itemx ws = atomic_fetch_xor ((u32 *)(rd + offset16), ws)
876 Atomic fetch-and-or instruction
879 The above instructions were introduced in the V3 of the BPF
880 instruction set. The following instruction is supported for backwards
884 @item xaddw [rd + offset16], rs
885 Alias to @code{aadd32}.