1*869ffda3Schristos@c Copyright (C) 2019-2020 Free Software Foundation, Inc. 2*869ffda3Schristos@c This is part of the GAS manual. 3*869ffda3Schristos@c For copying conditions, see the file as.texinfo. 4*869ffda3Schristos 5*869ffda3Schristos@ifset GENERIC 6*869ffda3Schristos@page 7*869ffda3Schristos@node BPF-Dependent 8*869ffda3Schristos@chapter BPF Dependent Features 9*869ffda3Schristos@end ifset 10*869ffda3Schristos 11*869ffda3Schristos@ifclear GENERIC 12*869ffda3Schristos@node Machine Dependencies 13*869ffda3Schristos@chapter BPF Dependent Features 14*869ffda3Schristos@end ifclear 15*869ffda3Schristos 16*869ffda3Schristos@cindex BPF support 17*869ffda3Schristos@menu 18*869ffda3Schristos* BPF Options:: Options 19*869ffda3Schristos* BPF Syntax:: Syntax 20*869ffda3Schristos* BPF Directives:: Machine Directives 21*869ffda3Schristos* BPF Opcodes:: Opcodes 22*869ffda3Schristos@end menu 23*869ffda3Schristos 24*869ffda3Schristos@node BPF Options 25*869ffda3Schristos@section Options 26*869ffda3Schristos@cindex BPF options (none) 27*869ffda3Schristos@cindex options for BPF (none) 28*869ffda3Schristos 29*869ffda3Schristos@c man begin OPTIONS 30*869ffda3Schristos@table @gcctabopt 31*869ffda3Schristos 32*869ffda3Schristos@cindex @option{-EB} command-line option, BPF 33*869ffda3Schristos@item -EB 34*869ffda3SchristosThis option specifies that the assembler should emit big-endian eBPF. 35*869ffda3Schristos 36*869ffda3Schristos@cindex @option{-EL} command-line option, BPF 37*869ffda3Schristos@item -EL 38*869ffda3SchristosThis option specifies that the assembler should emit little-endian 39*869ffda3SchristoseBPF. 40*869ffda3Schristos@end table 41*869ffda3Schristos 42*869ffda3SchristosNote that if no endianness option is specified in the command line, 43*869ffda3Schristosthe host endianness is used. 44*869ffda3Schristos@c man end 45*869ffda3Schristos 46*869ffda3Schristos@node BPF Syntax 47*869ffda3Schristos@section Syntax 48*869ffda3Schristos@menu 49*869ffda3Schristos* BPF-Chars:: Special Characters 50*869ffda3Schristos* BPF-Regs:: Register Names 51*869ffda3Schristos* BPF-Pseudo-Maps:: Pseudo map fds 52*869ffda3Schristos@end menu 53*869ffda3Schristos 54*869ffda3Schristos@node BPF-Chars 55*869ffda3Schristos@subsection Special Characters 56*869ffda3Schristos 57*869ffda3Schristos@cindex line comment character, BPF 58*869ffda3Schristos@cindex BPF line comment character 59*869ffda3SchristosThe presence of a @samp{;} on a line indicates the start of a comment 60*869ffda3Schristosthat extends to the end of the current line. If a @samp{#} appears as 61*869ffda3Schristosthe first character of a line, the whole line is treated as a comment. 62*869ffda3Schristos 63*869ffda3Schristos@cindex statement separator, BPF 64*869ffda3SchristosStatements and assembly directives are separated by newlines. 65*869ffda3Schristos 66*869ffda3Schristos@node BPF-Regs 67*869ffda3Schristos@subsection Register Names 68*869ffda3Schristos 69*869ffda3Schristos@cindex BPF register names 70*869ffda3Schristos@cindex register names, BPF 71*869ffda3SchristosThe eBPF processor provides ten general-purpose 64-bit registers, 72*869ffda3Schristoswhich are read-write, and a read-only frame pointer register: 73*869ffda3Schristos 74*869ffda3Schristos@table @samp 75*869ffda3Schristos@item %r0 .. %r9 76*869ffda3SchristosGeneral-purpose registers. 77*869ffda3Schristos@item %r10 78*869ffda3SchristosFrame pointer register. 79*869ffda3Schristos@end table 80*869ffda3Schristos 81*869ffda3SchristosSome registers have additional names, to reflect their role in the 82*869ffda3SchristoseBPF ABI: 83*869ffda3Schristos 84*869ffda3Schristos@table @samp 85*869ffda3Schristos@item %a 86*869ffda3SchristosThis is @samp{%r0}. 87*869ffda3Schristos@item %ctx 88*869ffda3SchristosThis is @samp{%r6}. 89*869ffda3Schristos@item %fp 90*869ffda3SchristosThis is @samp{%r10}. 91*869ffda3Schristos@end table 92*869ffda3Schristos 93*869ffda3Schristos@node BPF-Pseudo-Maps 94*869ffda3Schristos@subsection Pseudo Maps 95*869ffda3Schristos 96*869ffda3Schristos@cindex pseudo map fd, BPF 97*869ffda3SchristosThe @samp{LDDW} instruction can take a literal pseudo map file 98*869ffda3Schristosdescriptor as its second argument. This uses the syntax 99*869ffda3Schristos@samp{%map_fd(N)} where @samp{N} is a signed number. 100*869ffda3Schristos 101*869ffda3SchristosFor example, to load the address of the pseudo map with file 102*869ffda3Schristosdescriptor @samp{2} in register @samp{r1} we would do: 103*869ffda3Schristos 104*869ffda3Schristos@smallexample 105*869ffda3Schristos lddw %r1, %map_fd(2) 106*869ffda3Schristos@end smallexample 107*869ffda3Schristos 108*869ffda3Schristos@node BPF Directives 109*869ffda3Schristos@section Machine Directives 110*869ffda3Schristos 111*869ffda3Schristos@cindex machine directives, BPF 112*869ffda3Schristos 113*869ffda3SchristosThe BPF version of @code{@value{AS}} supports the following additional 114*869ffda3Schristosmachine directives: 115*869ffda3Schristos 116*869ffda3Schristos@table @code 117*869ffda3Schristos@cindex @code{half} directive, BPF 118*869ffda3Schristos@item .word 119*869ffda3SchristosThe @code{.half} directive produces a 16 bit value. 120*869ffda3Schristos 121*869ffda3Schristos@cindex @code{word} directive, BPF 122*869ffda3Schristos@item .word 123*869ffda3SchristosThe @code{.word} directive produces a 32 bit value. 124*869ffda3Schristos 125*869ffda3Schristos@cindex @code{dword} directive, BPF 126*869ffda3Schristos@item .dword 127*869ffda3SchristosThe @code{.dword} directive produces a 64 bit value. 128*869ffda3Schristos@end table 129*869ffda3Schristos 130*869ffda3Schristos@node BPF Opcodes 131*869ffda3Schristos@section Opcodes 132*869ffda3Schristos 133*869ffda3Schristos@cindex BPF opcodes 134*869ffda3Schristos@cindex opcodes for BPF 135*869ffda3SchristosIn the instruction descriptions below the following field descriptors 136*869ffda3Schristosare used: 137*869ffda3Schristos 138*869ffda3Schristos@table @code 139*869ffda3Schristos@item %d 140*869ffda3SchristosDestination general-purpose register whose role is to be destination 141*869ffda3Schristosof an operation. 142*869ffda3Schristos@item %s 143*869ffda3SchristosSource general-purpose register whose role is to be the source of an 144*869ffda3Schristosoperation. 145*869ffda3Schristos@item disp16 146*869ffda3Schristos16-bit signed PC-relative offset, measured in number of 64-bit words, 147*869ffda3Schristosminus one. 148*869ffda3Schristos@item disp32 149*869ffda3Schristos32-bit signed PC-relative offset, measured in number of 64-bit words, 150*869ffda3Schristosminus one. 151*869ffda3Schristos@item offset16 152*869ffda3SchristosSigned 16-bit immediate. 153*869ffda3Schristos@item imm32 154*869ffda3SchristosSigned 32-bit immediate. 155*869ffda3Schristos@item imm64 156*869ffda3SchristosSigned 64-bit immediate. 157*869ffda3Schristos@end table 158*869ffda3Schristos 159*869ffda3Schristos@subsubsection Arithmetic instructions 160*869ffda3Schristos 161*869ffda3SchristosThe destination register in these instructions act like an 162*869ffda3Schristosaccumulator. 163*869ffda3Schristos 164*869ffda3Schristos@table @code 165*869ffda3Schristos@item add %d, (%s|imm32) 166*869ffda3Schristos64-bit arithmetic addition. 167*869ffda3Schristos@item sub %d, (%s|imm32) 168*869ffda3Schristos64-bit arithmetic subtraction. 169*869ffda3Schristos@item mul %d, (%s|imm32) 170*869ffda3Schristos64-bit arithmetic multiplication. 171*869ffda3Schristos@item div %d, (%s|imm32) 172*869ffda3Schristos64-bit arithmetic integer division. 173*869ffda3Schristos@item mod %d, (%s|imm32) 174*869ffda3Schristos64-bit integer remainder. 175*869ffda3Schristos@item and %d, (%s|imm32) 176*869ffda3Schristos64-bit bit-wise ``and'' operation. 177*869ffda3Schristos@item or %d, (%s|imm32) 178*869ffda3Schristos64-bit bit-wise ``or'' operation. 179*869ffda3Schristos@item xor %d, (%s|imm32) 180*869ffda3Schristos64-bit bit-wise exclusive-or operation. 181*869ffda3Schristos@item lsh %d, (%s|imm32) 182*869ffda3Schristos64-bit left shift, by @code{%s} or @code{imm32} bits. 183*869ffda3Schristos@item rsh %d, (%s|imm32) 184*869ffda3Schristos64-bit right logical shift, by @code{%s} or @code{imm32} bits. 185*869ffda3Schristos@item arsh %d, (%s|imm32) 186*869ffda3Schristos64-bit right arithmetic shift, by @code{%s} or @code{imm32} bits. 187*869ffda3Schristos@item neg %d 188*869ffda3Schristos64-bit arithmetic negation. 189*869ffda3Schristos@item mov %d, (%s|imm32) 190*869ffda3SchristosMove the 64-bit value of @code{%s} in @code{%d}, or load @code{imm32} 191*869ffda3Schristosin @code{%d}. 192*869ffda3Schristos@end table 193*869ffda3Schristos 194*869ffda3Schristos@subsubsection 32-bit arithmetic instructions 195*869ffda3Schristos 196*869ffda3SchristosThe destination register in these instructions act as an accumulator. 197*869ffda3Schristos 198*869ffda3Schristos@table @code 199*869ffda3Schristos@item add32 %d, (%s|imm32) 200*869ffda3Schristos32-bit arithmetic addition. 201*869ffda3Schristos@item sub32 %d, (%s|imm32) 202*869ffda3Schristos32-bit arithmetic subtraction. 203*869ffda3Schristos@item mul32 %d, (%s|imm32) 204*869ffda3Schristos32-bit arithmetic multiplication. 205*869ffda3Schristos@item div32 %d, (%s|imm32) 206*869ffda3Schristos32-bit arithmetic integer division. 207*869ffda3Schristos@item mod32 %d, (%s|imm32) 208*869ffda3Schristos32-bit integer remainder. 209*869ffda3Schristos@item and32 %d, (%s|imm32) 210*869ffda3Schristos32-bit bit-wise ``and'' operation. 211*869ffda3Schristos@item or32 %d, (%s|imm32) 212*869ffda3Schristos32-bit bit-wise ``or'' operation. 213*869ffda3Schristos@item xor32 %d, (%s|imm32) 214*869ffda3Schristos32-bit bit-wise exclusive-or operation. 215*869ffda3Schristos@item lsh32 %d, (%s|imm32) 216*869ffda3Schristos32-bit left shift, by @code{%s} or @code{imm32} bits. 217*869ffda3Schristos@item rsh32 %d, (%s|imm32) 218*869ffda3Schristos32-bit right logical shift, by @code{%s} or @code{imm32} bits. 219*869ffda3Schristos@item arsh32 %d, (%s|imm32) 220*869ffda3Schristos32-bit right arithmetic shift, by @code{%s} or @code{imm32} bits. 221*869ffda3Schristos@item neg32 %d 222*869ffda3Schristos32-bit arithmetic negation. 223*869ffda3Schristos@item mov32 %d, (%s|imm32) 224*869ffda3SchristosMove the 32-bit value of @code{%s} in @code{%d}, or load @code{imm32} 225*869ffda3Schristosin @code{%d}. 226*869ffda3Schristos@end table 227*869ffda3Schristos 228*869ffda3Schristos@subsubsection Endianness conversion instructions 229*869ffda3Schristos 230*869ffda3Schristos@table @code 231*869ffda3Schristos@item endle %d, (8|16|32) 232*869ffda3SchristosConvert the 8-bit, 16-bit or 32-bit value in @code{%d} to 233*869ffda3Schristoslittle-endian. 234*869ffda3Schristos@item endbe %d, (8|16|32) 235*869ffda3SchristosConvert the 8-bit, 16-bit or 32-bit value in @code{%d} to big-endian. 236*869ffda3Schristos@end table 237*869ffda3Schristos 238*869ffda3Schristos@subsubsection 64-bit load and pseudo maps 239*869ffda3Schristos 240*869ffda3Schristos@table @code 241*869ffda3Schristos@item lddw %d, imm64 242*869ffda3SchristosLoad the given signed 64-bit immediate, or pseudo map descriptor, to 243*869ffda3Schristosthe destination register @code{%d}. 244*869ffda3Schristos@item lddw %d, %map_fd(N) 245*869ffda3SchristosLoad the address of the given pseudo map fd @emph{N} to the 246*869ffda3Schristosdestination register @code{%d}. 247*869ffda3Schristos@end table 248*869ffda3Schristos 249*869ffda3Schristos@subsubsection Load instructions for socket filters 250*869ffda3Schristos 251*869ffda3SchristosThe following instructions are intended to be used in socket filters, 252*869ffda3Schristosand are therefore not general-purpose: they make assumptions on the 253*869ffda3Schristoscontents of several registers. See the file 254*869ffda3Schristos@file{Documentation/networking/filter.txt} in the Linux kernel source 255*869ffda3Schristostree for more information. 256*869ffda3Schristos 257*869ffda3SchristosAbsolute loads: 258*869ffda3Schristos 259*869ffda3Schristos@table @code 260*869ffda3Schristos@item ldabsdw imm32 261*869ffda3SchristosAbsolute 64-bit load. 262*869ffda3Schristos@item ldabsw imm32 263*869ffda3SchristosAbsolute 32-bit load. 264*869ffda3Schristos@item ldabsh imm32 265*869ffda3SchristosAbsolute 16-bit load. 266*869ffda3Schristos@item ldabsb imm32 267*869ffda3SchristosAbsolute 8-bit load. 268*869ffda3Schristos@end table 269*869ffda3Schristos 270*869ffda3SchristosIndirect loads: 271*869ffda3Schristos 272*869ffda3Schristos@table @code 273*869ffda3Schristos@item ldinddw %s, imm32 274*869ffda3SchristosIndirect 64-bit load. 275*869ffda3Schristos@item ldindw %s, imm32 276*869ffda3SchristosIndirect 32-bit load. 277*869ffda3Schristos@item ldindh %s, imm32 278*869ffda3SchristosIndirect 16-bit load. 279*869ffda3Schristos@item ldindb %s, imm32 280*869ffda3SchristosIndirect 8-bit load. 281*869ffda3Schristos@end table 282*869ffda3Schristos 283*869ffda3Schristos@subsubsection Generic load/store instructions 284*869ffda3Schristos 285*869ffda3SchristosGeneral-purpose load and store instructions are provided for several 286*869ffda3Schristosword sizes. 287*869ffda3Schristos 288*869ffda3SchristosLoad to register instructions: 289*869ffda3Schristos 290*869ffda3Schristos@table @code 291*869ffda3Schristos@item ldxdw %d, [%s+offset16] 292*869ffda3SchristosGeneric 64-bit load. 293*869ffda3Schristos@item ldxw %d, [%s+offset16] 294*869ffda3SchristosGeneric 32-bit load. 295*869ffda3Schristos@item ldxh %d, [%s+offset16] 296*869ffda3SchristosGeneric 16-bit load. 297*869ffda3Schristos@item ldxb %d, [%s+offset16] 298*869ffda3SchristosGeneric 8-bit load. 299*869ffda3Schristos@end table 300*869ffda3Schristos 301*869ffda3SchristosStore from register instructions: 302*869ffda3Schristos 303*869ffda3Schristos@table @code 304*869ffda3Schristos@item stxdw [%d+offset16], %s 305*869ffda3SchristosGeneric 64-bit store. 306*869ffda3Schristos@item stxw [%d+offset16], %s 307*869ffda3SchristosGeneric 32-bit store. 308*869ffda3Schristos@item stxh [%d+offset16], %s 309*869ffda3SchristosGeneric 16-bit store. 310*869ffda3Schristos@item stxb [%d+offset16], %s 311*869ffda3SchristosGeneric 8-bit store. 312*869ffda3Schristos@end table 313*869ffda3Schristos 314*869ffda3SchristosStore from immediates instructions: 315*869ffda3Schristos 316*869ffda3Schristos@table @code 317*869ffda3Schristos@item stddw [%d+offset16], imm32 318*869ffda3SchristosStore immediate as 64-bit. 319*869ffda3Schristos@item stdw [%d+offset16], imm32 320*869ffda3SchristosStore immediate as 32-bit. 321*869ffda3Schristos@item stdh [%d+offset16], imm32 322*869ffda3SchristosStore immediate as 16-bit. 323*869ffda3Schristos@item stdb [%d+offset16], imm32 324*869ffda3SchristosStore immediate as 8-bit. 325*869ffda3Schristos@end table 326*869ffda3Schristos 327*869ffda3Schristos@subsubsection Jump instructions 328*869ffda3Schristos 329*869ffda3SchristoseBPF provides the following compare-and-jump instructions, which 330*869ffda3Schristoscompare the values of the two given registers, or the values of a 331*869ffda3Schristosregister and an immediate, and perform a branch in case the comparison 332*869ffda3Schristosholds true. 333*869ffda3Schristos 334*869ffda3Schristos@table @code 335*869ffda3Schristos@item ja %d,(%s|imm32),disp16 336*869ffda3SchristosJump-always. 337*869ffda3Schristos@item jeq %d,(%s|imm32),disp16 338*869ffda3SchristosJump if equal. 339*869ffda3Schristos@item jgt %d,(%s|imm32),disp16 340*869ffda3SchristosJump if greater. 341*869ffda3Schristos@item jge %d,(%s|imm32),disp16 342*869ffda3SchristosJump if greater or equal. 343*869ffda3Schristos@item jlt %d,(%s|imm32),disp16 344*869ffda3SchristosJump if lesser. 345*869ffda3Schristos@item jle %d,(%s|imm32),disp16 346*869ffda3SchristosJump if lesser or equal. 347*869ffda3Schristos@item jset %d,(%s|imm32),disp16 348*869ffda3SchristosJump if signed equal. 349*869ffda3Schristos@item jne %d,(%s|imm32),disp16 350*869ffda3SchristosJump if not equal. 351*869ffda3Schristos@item jsgt %d,(%s|imm32),disp16 352*869ffda3SchristosJump if signed greater. 353*869ffda3Schristos@item jsge %d,(%s|imm32),disp16 354*869ffda3SchristosJump if signed greater or equal. 355*869ffda3Schristos@item jslt %d,(%s|imm32),disp16 356*869ffda3SchristosJump if signed lesser. 357*869ffda3Schristos@item jsle %d,(%s|imm32),disp16 358*869ffda3SchristosJump if signed lesser or equal. 359*869ffda3Schristos@end table 360*869ffda3Schristos 361*869ffda3SchristosA call instruction is provided in order to perform calls to other eBPF 362*869ffda3Schristosfunctions, or to external kernel helpers: 363*869ffda3Schristos 364*869ffda3Schristos@table @code 365*869ffda3Schristos@item call (disp32|imm32) 366*869ffda3SchristosJump and link to the offset @emph{disp32}, or to the kernel helper 367*869ffda3Schristosfunction identified by @emph{imm32}. 368*869ffda3Schristos@end table 369*869ffda3Schristos 370*869ffda3SchristosFinally: 371*869ffda3Schristos 372*869ffda3Schristos@table @code 373*869ffda3Schristos@item exit 374*869ffda3SchristosTerminate the eBPF program. 375*869ffda3Schristos@end table 376*869ffda3Schristos 377*869ffda3Schristos@subsubsection Atomic instructions 378*869ffda3Schristos 379*869ffda3SchristosAtomic exchange-and-add instructions are provided in two flavors: one 380*869ffda3Schristosfor swapping 64-bit quantities and another for 32-bit quantities. 381*869ffda3Schristos 382*869ffda3Schristos@table @code 383*869ffda3Schristos@item xadddw [%d+offset16],%s 384*869ffda3SchristosExchange-and-add a 64-bit value at the specified location. 385*869ffda3Schristos@item xaddw [%d+offset16],%s 386*869ffda3SchristosExchange-and-add a 32-bit value at the specified location. 387*869ffda3Schristos@end table 388