gas/doc/c-bpf.texi

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