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
119 @section BPF Directives
121 @cindex machine directives, BPF
123 The BPF version of @code{@value{AS}} supports the following additional
127 @cindex @code{half} directive, BPF
129 The @code{.half} directive produces a 16 bit value.
131 @cindex @code{word} directive, BPF
133 The @code{.word} directive produces a 32 bit value.
135 @cindex @code{dword} directive, BPF
137 The @code{.dword} directive produces a 64 bit value.
140 @node BPF Instructions
141 @section BPF Instructions
144 @cindex opcodes for BPF
145 In the instruction descriptions below the following field descriptors
150 Destination general-purpose register whose role is to be the
151 destination of an operation.
153 Source general-purpose register whose role is to be the source of an
156 16-bit signed PC-relative offset, measured in number of 64-bit words,
159 32-bit signed PC-relative offset, measured in number of 64-bit words,
162 Signed 16-bit immediate representing an offset in bytes.
164 Signed 16-bit immediate representing a displacement to a target,
165 measured in number of 64-bit words @emph{minus one}.
167 Signed 32-bit immediate representing a displacement to a target,
168 measured in number of 64-bit words @emph{minus one}.
170 Signed 32-bit immediate.
172 Signed 64-bit immediate.
175 @subsection Arithmetic instructions
177 The destination register in these instructions act like an
180 Note that in pseudoc syntax these instructions should use @code{r}
188 64-bit arithmetic addition.
194 64-bit arithmetic subtraction.
200 64-bit arithmetic multiplication.
206 64-bit arithmetic integer division.
212 64-bit integer remainder.
218 64-bit bit-wise ``and'' operation.
224 64-bit bit-wise ``or'' operation.
230 64-bit bit-wise exclusive-or operation.
236 64-bit left shift, by @code{rs} or @code{imm32} bits.
242 64-bit right logical shift, by @code{rs} or @code{imm32} bits.
245 @itemx arsh rd, imm32
248 64-bit right arithmetic shift, by @code{rs} or @code{imm32} bits.
254 64-bit arithmetic negation.
256 Note that in the @code{rd = - imm32} syntax there must be at least
257 one white space between @code{-} and @code{imm32}. Otherwise the
258 instruction is parsed as a @code{mov rd, imm32} instruction with a
259 negative 32-bit immediate. This is a consequence of a syntactic
260 ambiguity in the pseudoc syntax.
266 Move the 64-bit value of @code{rs} in @code{rd}, or load @code{imm32}
271 Move the sign-extended 8-bit value in @code{rs} to @code{rd}.
273 @item movs rd, rs, 16
275 Move the sign-extended 16-bit value in @code{rs} to @code{rd}.
277 @item movs rd, rs, 32
279 Move the sign-extended 32-bit value in @code{rs} to @code{rd}.
282 @subsection 32-bit arithmetic instructions
284 The destination register in these instructions act as an accumulator.
286 Note that in pseudoc syntax these instructions should use @code{w}
287 registers. It is not allowed to mix @code{w} and @code{r} registers
288 in the same instruction.
292 @itemx add32 rd, imm32
295 32-bit arithmetic addition.
298 @itemx sub32 rd, imm32
301 32-bit arithmetic subtraction.
304 @itemx mul32 rd, imm32
307 32-bit arithmetic multiplication.
310 @itemx div32 rd, imm32
313 32-bit arithmetic integer division.
316 @itemx mod32 rd, imm32
319 32-bit integer remainder.
322 @itemx and32 rd, imm32
325 32-bit bit-wise ``and'' operation.
328 @itemx or32 rd, imm32
331 32-bit bit-wise ``or'' operation.
334 @itemx xor32 rd, imm32
337 32-bit bit-wise exclusive-or operation.
340 @itemx lsh32 rd, imm32
343 32-bit left shift, by @code{rs} or @code{imm32} bits.
346 @itemx rsh32 rd, imm32
349 32-bit right logical shift, by @code{rs} or @code{imm32} bits.
352 @itemx arsh32 rd, imm32
355 32-bit right arithmetic shift, by @code{rs} or @code{imm32} bits.
358 @itemx neg32 rd, imm32
361 32-bit arithmetic negation.
363 Note that in the @code{rd = - imm32} syntax there must be at least
364 one white space between @code{-} and @code{imm32}. Otherwise the
365 instruction is parsed as a @code{mov32 rd, imm32} instruction with a
366 negative 32-bit immediate. This is a consequence of a syntactic
367 ambiguity in the pseudoc syntax.
370 @itemx mov32 rd, imm32
373 Move the 32-bit value of @code{rs} in @code{rd}, or load @code{imm32}
376 @item mov32s rd, rs, 8
378 Move the sign-extended 8-bit value in @code{rs} to @code{rd}.
380 @item mov32s rd, rs, 16
382 Move the sign-extended 16-bit value in @code{rs} to @code{rd}.
384 @item mov32s rd, rs, 32
386 Move the sign-extended 32-bit value in @code{rs} to @code{rd}.
389 @subsection Endianness conversion instructions
398 Convert the 16-bit, 32-bit or 64-bit value in @code{rd} to
399 little-endian and store it back in @code{rd}.
406 Convert the 16-bit, 32-bit or 64-bit value in @code{rd} to big-endian
407 and store it back in @code{rd}.
410 @subsection Byte swap instructions
414 @itemx rd = bswap16 rd
415 Swap the least-significant 16-bit word in @code{rd} with the
416 most-significant 16-bit word.
419 @itemx rd = bswap32 rd
420 Swap the least-significant 32-bit word in @code{rd} with the
421 most-significant 32-bit word.
424 @itemx rd = bswap64 rd
425 Swap the least-significant 64-bit word in @code{rd} with the
426 most-significant 64-bit word.
430 @subsection 64-bit load and pseudo maps
435 Load the given signed 64-bit immediate to the destination register
439 @subsection Load instructions for socket filters
441 The following instructions are intended to be used in socket filters,
442 and are therefore not general-purpose: they make assumptions on the
443 contents of several registers. See the file
444 @file{Documentation/networking/filter.txt} in the Linux kernel source
445 tree for more information.
451 @itemx r0 = *(u64 *) skb[imm32]
452 Absolute 64-bit load.
455 @itemx r0 = *(u32 *) skb[imm32]
456 Absolute 32-bit load.
459 @itemx r0 = *(u16 *) skb[imm32]
460 Absolute 16-bit load.
463 @itemx r0 = *(u8 *) skb[imm32]
470 @item ldinddw rs, imm32
471 @itemx r0 = *(u64 *) skb[rs + imm32]
472 Indirect 64-bit load.
474 @item ldindw rs, imm32
475 @itemx r0 = *(u32 *) skb[rs + imm32]
476 Indirect 32-bit load.
478 @item ldindh rs, imm32
479 @itemx r0 = *(u16 *) skb[rs + imm32]
480 Indirect 16-bit load.
482 @item ldindb %s, imm32
483 @itemx r0 = *(u8 *) skb[rs + imm32]
487 @subsection Generic load/store instructions
489 General-purpose load and store instructions are provided for several
492 Load to register instructions:
495 @item ldxdw rd, [rs + offset16]
496 @itemx rd = *(u64 *) (rs + offset16)
499 @item ldxw rd, [rs + offset16]
500 @itemx rd = *(u32 *) (rs + offset16)
503 @item ldxh rd, [rs + offset16]
504 @itemx rd = *(u16 *) (rs + offset16)
507 @item ldxb rd, [rs + offset16]
508 @itemx rd = *(u8 *) (rs + offset16)
512 Signed load to register instructions:
515 @item ldxsdw rd, [rs + offset16]
516 @itemx rd = *(s64 *) (rs + offset16)
517 Generic 64-bit signed load.
519 @item ldxsw rd, [rs + offset16]
520 @itemx rd = *(s32 *) (rs + offset16)
521 Generic 32-bit signed load.
523 @item ldxsh rd, [rs + offset16]
524 @itemx rd = *(s16 *) (rs + offset16)
525 Generic 16-bit signed load.
527 @item ldxsb rd, [rs + offset16]
528 @itemx rd = *(s8 *) (rs + offset16)
529 Generic 8-bit signed load.
532 Store from register instructions:
535 @item stxdw [rd + offset16], %s
536 @itemx *(u64 *) (rd + offset16)
537 Generic 64-bit store.
539 @item stxw [rd + offset16], %s
540 @itemx *(u32 *) (rd + offset16)
541 Generic 32-bit store.
543 @item stxh [rd + offset16], %s
544 @itemx *(u16 *) (rd + offset16)
545 Generic 16-bit store.
547 @item stxb [rd + offset16], %s
548 @itemx *(u8 *) (rd + offset16)
552 Store from immediates instructions:
555 @item stdw [rd + offset16], imm32
556 @itemx *(u64 *) (rd + offset16) = imm32
557 Store immediate as 64-bit.
559 @item stw [rd + offset16], imm32
560 @itemx *(u32 *) (rd + offset16) = imm32
561 Store immediate as 32-bit.
563 @item sth [rd + offset16], imm32
564 @itemx *(u16 *) (rd + offset16) = imm32
565 Store immediate as 16-bit.
567 @item stb [rd + offset16], imm32
568 @itemx *(u8 *) (rd + offset16) = imm32
569 Store immediate as 8-bit.
572 @subsection Jump instructions
574 eBPF provides the following compare-and-jump instructions, which
575 compare the values of the two given registers, or the values of a
576 register and an immediate, and perform a branch in case the comparison
586 Jump-always, long range.
588 @item jeq rd, rs, disp16
589 @itemx jeq rd, imm32, disp16
590 @itemx if rd == rs goto disp16
591 @itemx if rd == imm32 goto disp16
592 Jump if equal, unsigned.
594 @item jgt rd, rs, disp16
595 @itemx jgt rd, imm32, disp16
596 @itemx if rd > rs goto disp16
597 @itemx if rd > imm32 goto disp16
598 Jump if greater, unsigned.
600 @item jge rd, rs, disp16
601 @itemx jge rd, imm32, disp16
602 @itemx if rd >= rs goto disp16
603 @itemx if rd >= imm32 goto disp16
604 Jump if greater or equal.
606 @item jlt rd, rs, disp16
607 @itemx jlt rd, imm32, disp16
608 @itemx if rd < rs goto disp16
609 @itemx if rd < imm32 goto disp16
612 @item jle rd , rs, disp16
613 @itemx jle rd, imm32, disp16
614 @itemx if rd <= rs goto disp16
615 @itemx if rd <= imm32 goto disp16
616 Jump if lesser or equal.
618 @item jset rd, rs, disp16
619 @itemx jset rd, imm32, disp16
620 @itemx if rd & rs goto disp16
621 @itemx if rd & imm32 goto disp16
622 Jump if signed equal.
624 @item jne rd, rs, disp16
625 @itemx jne rd, imm32, disp16
626 @itemx if rd != rs goto disp16
627 @itemx if rd != imm32 goto disp16
630 @item jsgt rd, rs, disp16
631 @itemx jsgt rd, imm32, disp16
632 @itemx if rd s> rs goto disp16
633 @itemx if rd s> imm32 goto disp16
634 Jump if signed greater.
636 @item jsge rd, rs, disp16
637 @itemx jsge rd, imm32, disp16
638 @itemx if rd s>= rd goto disp16
639 @itemx if rd s>= imm32 goto disp16
640 Jump if signed greater or equal.
642 @item jslt rd, rs, disp16
643 @itemx jslt rd, imm32, disp16
644 @itemx if rd s< rs goto disp16
645 @itemx if rd s< imm32 goto disp16
646 Jump if signed lesser.
648 @item jsle rd, rs, disp16
649 @itemx jsle rd, imm32, disp16
650 @itemx if rd s<= rs goto disp16
651 @itemx if rd s<= imm32 goto disp16
652 Jump if signed lesser or equal.
655 A call instruction is provided in order to perform calls to other eBPF
656 functions, or to external kernel helpers:
661 Jump and link to the offset @emph{disp32}, or to the kernel helper
662 function identified by @emph{imm32}.
669 Terminate the eBPF program.
672 @subsection 32-bit jump instructions
674 eBPF provides the following compare-and-jump instructions, which
675 compare the 32-bit values of the two given registers, or the values of
676 a register and an immediate, and perform a branch in case the
677 comparison holds true.
679 These instructions are only available in BPF v3 or later.
682 @item jeq32 rd, rs, disp16
683 @itemx jeq32 rd, imm32, disp16
684 @itemx if rd == rs goto disp16
685 @itemx if rd == imm32 goto disp16
686 Jump if equal, unsigned.
688 @item jgt32 rd, rs, disp16
689 @itemx jgt32 rd, imm32, disp16
690 @itemx if rd > rs goto disp16
691 @itemx if rd > imm32 goto disp16
692 Jump if greater, unsigned.
694 @item jge32 rd, rs, disp16
695 @itemx jge32 rd, imm32, disp16
696 @itemx if rd >= rs goto disp16
697 @itemx if rd >= imm32 goto disp16
698 Jump if greater or equal.
700 @item jlt32 rd, rs, disp16
701 @itemx jlt32 rd, imm32, disp16
702 @itemx if rd < rs goto disp16
703 @itemx if rd < imm32 goto disp16
706 @item jle32 rd , rs, disp16
707 @itemx jle32 rd, imm32, disp16
708 @itemx if rd <= rs goto disp16
709 @itemx if rd <= imm32 goto disp16
710 Jump if lesser or equal.
712 @item jset32 rd, rs, disp16
713 @itemx jset32 rd, imm32, disp16
714 @itemx if rd & rs goto disp16
715 @itemx if rd & imm32 goto disp16
716 Jump if signed equal.
718 @item jne32 rd, rs, disp16
719 @itemx jne32 rd, imm32, disp16
720 @itemx if rd != rs goto disp16
721 @itemx if rd != imm32 goto disp16
724 @item jsgt32 rd, rs, disp16
725 @itemx jsgt32 rd, imm32, disp16
726 @itemx if rd s> rs goto disp16
727 @itemx if rd s> imm32 goto disp16
728 Jump if signed greater.
730 @item jsge32 rd, rs, disp16
731 @itemx jsge32 rd, imm32, disp16
732 @itemx if rd s>= rd goto disp16
733 @itemx if rd s>= imm32 goto disp16
734 Jump if signed greater or equal.
736 @item jslt32 rd, rs, disp16
737 @itemx jslt32 rd, imm32, disp16
738 @itemx if rd s< rs goto disp16
739 @itemx if rd s< imm32 goto disp16
740 Jump if signed lesser.
742 @item jsle32 rd, rs, disp16
743 @itemx jsle32 rd, imm32, disp16
744 @itemx if rd s<= rs goto disp16
745 @itemx if rd s<= imm32 goto disp16
746 Jump if signed lesser or equal.
749 @subsection Atomic instructions
751 Atomic exchange instructions are provided in two flavors: one for
752 compare-and-swap, one for unconditional exchange.
755 @item acmp [rd + offset16], rs
756 @itemx r0 = cmpxchg_64 (rd + offset16, r0, rs)
757 Atomic compare-and-swap. Compares value in @code{r0} to value
758 addressed by @code{rd + offset16}. On match, the value addressed by
759 @code{rd + offset16} is replaced with the value in @code{rs}.
760 Regardless, the value that was at @code{rd + offset16} is
761 zero-extended and loaded into @code{r0}.
763 @item axchg [rd + offset16], rs
764 @itemx rs = xchg_64 (rd + offset16, rs)
765 Atomic exchange. Atomically exchanges the value in @code{rs} with
766 the value addressed by @code{rd + offset16}.
770 The following instructions provide atomic arithmetic operations.
773 @item aadd [rd + offset16], rs
774 @itemx lock *(u64 *)(rd + offset16) = rs
775 Atomic add instruction.
777 @item aor [rd + offset16], rs
778 @itemx lock *(u64 *) (rd + offset16) |= rs
779 Atomic or instruction.
781 @item aand [rd + offset16], rs
782 @itemx lock *(u64 *) (rd + offset16) &= rs
783 Atomic and instruction.
785 @item axor [rd + offset16], rs
786 @itemx lock *(u64 *) (rd + offset16) ^= rs
787 Atomic xor instruction.
791 The following variants perform fetching before the atomic operation.
794 @item afadd [rd + offset16], rs
795 @itemx rs = atomic_fetch_add ((u64 *)(rd + offset16), rs)
796 Atomic fetch-and-add instruction.
798 @item afor [rd + offset16], rs
799 @itemx rs = atomic_fetch_or ((u64 *)(rd + offset16), rs)
800 Atomic fetch-and-or instruction.
802 @item afand [rd + offset16], rs
803 @itemx rs = atomic_fetch_and ((u64 *)(rd + offset16), rs)
804 Atomic fetch-and-and instruction.
806 @item afxor [rd + offset16], rs
807 @itemx rs = atomic_fetch_xor ((u64 *)(rd + offset16), rs)
808 Atomic fetch-and-or instruction.
811 The above instructions were introduced in the V3 of the BPF
812 instruction set. The following instruction is supported for backwards
816 @item xadddw [rd + offset16], rs
817 Alias to @code{aadd}.
820 @subsection 32-bit atomic instructions
822 32-bit atomic exchange instructions are provided in two flavors: one
823 for compare-and-swap, one for unconditional exchange.
826 @item acmp32 [rd + offset16], rs
827 @itemx w0 = cmpxchg32_32 (rd + offset16, w0, ws)
828 Atomic compare-and-swap. Compares value in @code{w0} to value
829 addressed by @code{rd + offset16}. On match, the value addressed by
830 @code{rd + offset16} is replaced with the value in @code{ws}.
831 Regardless, the value that was at @code{rd + offset16} is
832 zero-extended and loaded into @code{w0}.
834 @item axchg [rd + offset16], rs
835 @itemx ws = xchg32_32 (rd + offset16, ws)
836 Atomic exchange. Atomically exchanges the value in @code{ws} with
837 the value addressed by @code{rd + offset16}.
841 The following instructions provide 32-bit atomic arithmetic operations.
844 @item aadd32 [rd + offset16], rs
845 @itemx lock *(u32 *)(rd + offset16) = rs
846 Atomic add instruction.
848 @item aor32 [rd + offset16], rs
849 @itemx lock *(u32 *) (rd + offset16) |= rs
850 Atomic or instruction.
852 @item aand32 [rd + offset16], rs
853 @itemx lock *(u32 *) (rd + offset16) &= rs
854 Atomic and instruction.
856 @item axor32 [rd + offset16], rs
857 @itemx lock *(u32 *) (rd + offset16) ^= rs
858 Atomic xor instruction
862 The following variants perform fetching before the atomic operation.
865 @item afadd32 [dr + offset16], rs
866 @itemx ws = atomic_fetch_add ((u32 *)(rd + offset16), ws)
867 Atomic fetch-and-add instruction.
869 @item afor32 [dr + offset16], rs
870 @itemx ws = atomic_fetch_or ((u32 *)(rd + offset16), ws)
871 Atomic fetch-and-or instruction.
873 @item afand32 [dr + offset16], rs
874 @itemx ws = atomic_fetch_and ((u32 *)(rd + offset16), ws)
875 Atomic fetch-and-and instruction.
877 @item afxor32 [dr + offset16], rs
878 @itemx ws = atomic_fetch_xor ((u32 *)(rd + offset16), ws)
879 Atomic fetch-and-or instruction
882 The above instructions were introduced in the V3 of the BPF
883 instruction set. The following instruction is supported for backwards
887 @item xaddw [rd + offset16], rs
888 Alias to @code{aadd32}.