~ [ source navigation ] ~ [ diff markup ] ~ [ identifier search ] ~

TOMOYO Linux Cross Reference
Linux/Documentation/bpf/standardization/instruction-set.rst

Version: ~ [ linux-6.12-rc7 ] ~ [ linux-6.11.7 ] ~ [ linux-6.10.14 ] ~ [ linux-6.9.12 ] ~ [ linux-6.8.12 ] ~ [ linux-6.7.12 ] ~ [ linux-6.6.60 ] ~ [ linux-6.5.13 ] ~ [ linux-6.4.16 ] ~ [ linux-6.3.13 ] ~ [ linux-6.2.16 ] ~ [ linux-6.1.116 ] ~ [ linux-6.0.19 ] ~ [ linux-5.19.17 ] ~ [ linux-5.18.19 ] ~ [ linux-5.17.15 ] ~ [ linux-5.16.20 ] ~ [ linux-5.15.171 ] ~ [ linux-5.14.21 ] ~ [ linux-5.13.19 ] ~ [ linux-5.12.19 ] ~ [ linux-5.11.22 ] ~ [ linux-5.10.229 ] ~ [ linux-5.9.16 ] ~ [ linux-5.8.18 ] ~ [ linux-5.7.19 ] ~ [ linux-5.6.19 ] ~ [ linux-5.5.19 ] ~ [ linux-5.4.285 ] ~ [ linux-5.3.18 ] ~ [ linux-5.2.21 ] ~ [ linux-5.1.21 ] ~ [ linux-5.0.21 ] ~ [ linux-4.20.17 ] ~ [ linux-4.19.323 ] ~ [ linux-4.18.20 ] ~ [ linux-4.17.19 ] ~ [ linux-4.16.18 ] ~ [ linux-4.15.18 ] ~ [ linux-4.14.336 ] ~ [ linux-4.13.16 ] ~ [ linux-4.12.14 ] ~ [ linux-4.11.12 ] ~ [ linux-4.10.17 ] ~ [ linux-4.9.337 ] ~ [ linux-4.4.302 ] ~ [ linux-3.10.108 ] ~ [ linux-2.6.32.71 ] ~ [ linux-2.6.0 ] ~ [ linux-2.4.37.11 ] ~ [ unix-v6-master ] ~ [ ccs-tools-1.8.12 ] ~ [ policy-sample ] ~
Architecture: ~ [ i386 ] ~ [ alpha ] ~ [ m68k ] ~ [ mips ] ~ [ ppc ] ~ [ sparc ] ~ [ sparc64 ] ~

Diff markup

Differences between /Documentation/bpf/standardization/instruction-set.rst (Version linux-6.12-rc7) and /Documentation/bpf/standardization/instruction-set.rst (Version linux-4.14.336)


  1 .. contents::                                     
  2 .. sectnum::                                      
  3                                                   
  4 ======================================            
  5 BPF Instruction Set Architecture (ISA)            
  6 ======================================            
  7                                                   
  8 eBPF, also commonly                               
  9 referred to as BPF, is a technology with origi    
 10 that can run untrusted programs in a privilege    
 11 operating system kernel. This document specifi    
 12 set architecture (ISA).                           
 13                                                   
 14 As a historical note, BPF originally stood for    
 15 but now that it can do so much more than packe    
 16 no longer makes sense. BPF is now considered a    
 17 does not stand for anything.  The original BPF    
 18 as cBPF (classic BPF) to distinguish it from t    
 19 eBPF (extended BPF).                              
 20                                                   
 21 Documentation conventions                         
 22 =========================                         
 23                                                   
 24 The key words "MUST", "MUST NOT", "REQUIRED",     
 25 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RE    
 26 "OPTIONAL" in this document are to be interpre    
 27 BCP 14 `<https://www.rfc-editor.org/info/rfc21    
 28 `<https://www.rfc-editor.org/info/rfc8174>`_      
 29 when, and only when, they appear in all capita    
 30                                                   
 31 For brevity and consistency, this document ref    
 32 of types using a shorthand syntax and refers t    
 33 mnemonic functions when describing the semanti    
 34 The range of valid values for those types and     
 35 functions are defined in the following subsect    
 36                                                   
 37 Types                                             
 38 -----                                             
 39 This document refers to integer types with the    
 40 a type's signedness (`S`) and bit width (`N`),    
 41                                                   
 42 .. table:: Meaning of signedness notation         
 43                                                   
 44   ==== =========                                  
 45   S    Meaning                                    
 46   ==== =========                                  
 47   u    unsigned                                   
 48   s    signed                                     
 49   ==== =========                                  
 50                                                   
 51 .. table:: Meaning of bit-width notation          
 52                                                   
 53   ===== =========                                 
 54   N     Bit width                                 
 55   ===== =========                                 
 56   8     8 bits                                    
 57   16    16 bits                                   
 58   32    32 bits                                   
 59   64    64 bits                                   
 60   128   128 bits                                  
 61   ===== =========                                 
 62                                                   
 63 For example, `u32` is a type whose valid value    
 64 numbers and `s16` is a type whose valid values    
 65 numbers.                                          
 66                                                   
 67 Functions                                         
 68 ---------                                         
 69                                                   
 70 The following byteswap functions are direction    
 71 the same function is used for conversion in ei    
 72 below.                                            
 73                                                   
 74 * be16: Takes an unsigned 16-bit number and co    
 75   host byte order and big-endian                  
 76   (`IEN137 <https://www.rfc-editor.org/ien/ien    
 77 * be32: Takes an unsigned 32-bit number and co    
 78   host byte order and big-endian byte order.      
 79 * be64: Takes an unsigned 64-bit number and co    
 80   host byte order and big-endian byte order.      
 81 * bswap16: Takes an unsigned 16-bit number in     
 82   format and returns the equivalent number wit    
 83   opposite endianness.                            
 84 * bswap32: Takes an unsigned 32-bit number in     
 85   format and returns the equivalent number wit    
 86   opposite endianness.                            
 87 * bswap64: Takes an unsigned 64-bit number in     
 88   format and returns the equivalent number wit    
 89   opposite endianness.                            
 90 * le16: Takes an unsigned 16-bit number and co    
 91   host byte order and little-endian byte order    
 92 * le32: Takes an unsigned 32-bit number and co    
 93   host byte order and little-endian byte order    
 94 * le64: Takes an unsigned 64-bit number and co    
 95   host byte order and little-endian byte order    
 96                                                   
 97 Definitions                                       
 98 -----------                                       
 99                                                   
100 .. glossary::                                     
101                                                   
102   Sign Extend                                     
103     To `sign extend an` ``X`` `-bit number, A,    
104                                                   
105     #. Copy all ``X`` bits from `A` to the low    
106     #. Set the value of the remaining ``Y`` -     
107        the  most-significant bit of `A`.          
108                                                   
109 .. admonition:: Example                           
110                                                   
111   Sign extend an 8-bit number ``A`` to a 16-bi    
112   ::                                              
113                                                   
114     A:          10000110                          
115     B: 11111111 10000110                          
116                                                   
117 Conformance groups                                
118 ------------------                                
119                                                   
120 An implementation does not need to support all    
121 document (e.g., deprecated instructions).  Ins    
122 groups are specified.  An implementation MUST     
123 group and MAY support additional conformance g    
124 conformance group means it MUST support all in    
125 group.                                            
126                                                   
127 The use of named conformance groups enables in    
128 that executes instructions, and tools such as     
129 instructions for the runtime.  Thus, capabilit    
130 conformance groups might be done manually by u    
131                                                   
132 Each conformance group has a short ASCII label    
133 corresponds to a set of instructions that are     
134 instruction has one or more conformance groups    
135                                                   
136 This document defines the following conformanc    
137                                                   
138 * base32: includes all instructions defined in    
139   specification unless otherwise noted.           
140 * base64: includes base32, plus instructions e    
141   as being in the base64 conformance group.       
142 * atomic32: includes 32-bit atomic operation i    
143 * atomic64: includes atomic32, plus 64-bit ato    
144 * divmul32: includes 32-bit division, multipli    
145 * divmul64: includes divmul32, plus 64-bit div    
146   and modulo instructions.                        
147 * packet: deprecated packet access instruction    
148                                                   
149 Instruction encoding                              
150 ====================                              
151                                                   
152 BPF has two instruction encodings:                
153                                                   
154 * the basic instruction encoding, which uses 6    
155 * the wide instruction encoding, which appends    
156   after the basic instruction for a total of 1    
157                                                   
158 Basic instruction encoding                        
159 --------------------------                        
160                                                   
161 A basic instruction is encoded as follows::       
162                                                   
163   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-    
164   |    opcode     |     regs      |               
165   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-    
166   |                              imm              
167   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-    
168                                                   
169 **opcode**                                        
170   operation to perform, encoded as follows::      
171                                                   
172     +-+-+-+-+-+-+-+-+                             
173     |specific |class|                             
174     +-+-+-+-+-+-+-+-+                             
175                                                   
176   **specific**                                    
177     The format of these bits varies by instruc    
178                                                   
179   **class**                                       
180     The instruction class (see `Instruction cl    
181                                                   
182 **regs**                                          
183   The source and destination register numbers,    
184   on a little-endian host::                       
185                                                   
186     +-+-+-+-+-+-+-+-+                             
187     |src_reg|dst_reg|                             
188     +-+-+-+-+-+-+-+-+                             
189                                                   
190   and as follows on a big-endian host::           
191                                                   
192     +-+-+-+-+-+-+-+-+                             
193     |dst_reg|src_reg|                             
194     +-+-+-+-+-+-+-+-+                             
195                                                   
196   **src_reg**                                     
197     the source register number (0-10), except     
198     (`64-bit immediate instructions`_ reuse th    
199                                                   
200   **dst_reg**                                     
201     destination register number (0-10), unless    
202     (future instructions might reuse this fiel    
203                                                   
204 **offset**                                        
205   signed integer offset used with pointer arit    
206   otherwise specified (some arithmetic instruc    
207   for other purposes)                             
208                                                   
209 **imm**                                           
210   signed integer immediate value                  
211                                                   
212 Note that the contents of multi-byte fields ('    
213 stored using big-endian byte ordering on big-e    
214 little-endian byte ordering on little-endian h    
215                                                   
216 For example::                                     
217                                                   
218   opcode                  offset imm              
219          src_reg dst_reg                          
220   07     0       1        00 00  44 33 22 11      
221          dst_reg src_reg                          
222   07     1       0        00 00  11 22 33 44      
223                                                   
224 Note that most instructions do not use all of     
225 Unused fields SHALL be cleared to zero.           
226                                                   
227 Wide instruction encoding                         
228 --------------------------                        
229                                                   
230 Some instructions are defined to use the wide     
231 which uses two 32-bit immediate values.  The 6    
232 the basic instruction format contain a pseudo     
233 with 'opcode', 'dst_reg', 'src_reg', and 'offs    
234                                                   
235 This is depicted in the following figure::        
236                                                   
237   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-    
238   |    opcode     |     regs      |               
239   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-    
240   |                              imm              
241   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-    
242   |                           reserved            
243   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-    
244   |                           next_imm            
245   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-    
246                                                   
247 **opcode**                                        
248   operation to perform, encoded as explained a    
249                                                   
250 **regs**                                          
251   The source and destination register numbers     
252   specified), encoded as explained above          
253                                                   
254 **offset**                                        
255   signed integer offset used with pointer arit    
256   otherwise specified                             
257                                                   
258 **imm**                                           
259   signed integer immediate value                  
260                                                   
261 **reserved**                                      
262   unused, set to zero                             
263                                                   
264 **next_imm**                                      
265   second signed integer immediate value           
266                                                   
267 Instruction classes                               
268 -------------------                               
269                                                   
270 The three least significant bits of the 'opcod    
271                                                   
272 .. table:: Instruction class                      
273                                                   
274   =====  =====  ==============================    
275   class  value  description                       
276   =====  =====  ==============================    
277   LD     0x0    non-standard load operations      
278   LDX    0x1    load into register operations     
279   ST     0x2    store from immediate operation    
280   STX    0x3    store from register operations    
281   ALU    0x4    32-bit arithmetic operations      
282   JMP    0x5    64-bit jump operations            
283   JMP32  0x6    32-bit jump operations            
284   ALU64  0x7    64-bit arithmetic operations      
285   =====  =====  ==============================    
286                                                   
287 Arithmetic and jump instructions                  
288 ================================                  
289                                                   
290 For arithmetic and jump instructions (``ALU``,    
291 ``JMP32``), the 8-bit 'opcode' field is divide    
292                                                   
293   +-+-+-+-+-+-+-+-+                               
294   |  code |s|class|                               
295   +-+-+-+-+-+-+-+-+                               
296                                                   
297 **code**                                          
298   the operation code, whose meaning varies by     
299                                                   
300 **s (source)**                                    
301   the source operand location, which unless ot    
302                                                   
303   .. table:: Source operand location              
304                                                   
305     ======  =====  ===========================    
306     source  value  description                    
307     ======  =====  ===========================    
308     K       0      use 32-bit 'imm' value as s    
309     X       1      use 'src_reg' register valu    
310     ======  =====  ===========================    
311                                                   
312 **instruction class**                             
313   the instruction class (see `Instruction clas    
314                                                   
315 Arithmetic instructions                           
316 -----------------------                           
317                                                   
318 ``ALU`` uses 32-bit wide operands while ``ALU6    
319 otherwise identical operations. ``ALU64`` inst    
320 base64 conformance group unless noted otherwis    
321 The 'code' field encodes the operation as belo    
322 the source operand and 'dst' refers to the val    
323 register.                                         
324                                                   
325 .. table:: Arithmetic instructions                
326                                                   
327   =====  =====  =======  =====================    
328   name   code   offset   description              
329   =====  =====  =======  =====================    
330   ADD    0x0    0        dst += src               
331   SUB    0x1    0        dst -= src               
332   MUL    0x2    0        dst \*= src              
333   DIV    0x3    0        dst = (src != 0) ? (d    
334   SDIV   0x3    1        dst = (src != 0) ? (d    
335   OR     0x4    0        dst \|= src              
336   AND    0x5    0        dst &= src               
337   LSH    0x6    0        dst <<= (src & mask)     
338   RSH    0x7    0        dst >>= (src & mask)     
339   NEG    0x8    0        dst = -dst               
340   MOD    0x9    0        dst = (src != 0) ? (d    
341   SMOD   0x9    1        dst = (src != 0) ? (d    
342   XOR    0xa    0        dst ^= src               
343   MOV    0xb    0        dst = src                
344   MOVSX  0xb    8/16/32  dst = (s8,s16,s32)src    
345   ARSH   0xc    0        :term:`sign extending    
346   END    0xd    0        byte swap operations     
347   =====  =====  =======  =====================    
348                                                   
349 Underflow and overflow are allowed during arit    
350 the 64-bit or 32-bit value will wrap. If BPF p    
351 result in division by zero, the destination re    
352 If execution would result in modulo by zero, f    
353 the destination register is unchanged whereas     
354 32 bits of the destination register are zeroed    
355                                                   
356 ``{ADD, X, ALU}``, where 'code' = ``ADD``, 'so    
357                                                   
358   dst = (u32) ((u32) dst + (u32) src)             
359                                                   
360 where '(u32)' indicates that the upper 32 bits    
361                                                   
362 ``{ADD, X, ALU64}`` means::                       
363                                                   
364   dst = dst + src                                 
365                                                   
366 ``{XOR, K, ALU}`` means::                         
367                                                   
368   dst = (u32) dst ^ (u32) imm                     
369                                                   
370 ``{XOR, K, ALU64}`` means::                       
371                                                   
372   dst = dst ^ imm                                 
373                                                   
374 Note that most arithmetic instructions have 'o    
375 (``SDIV``, ``SMOD``, ``MOVSX``) have a non-zer    
376                                                   
377 Division, multiplication, and modulo operation    
378 of the "divmul32" conformance group, and divis    
379 modulo operations for ``ALU64`` are part of th    
380 group.                                            
381 The division and modulo operations support bot    
382                                                   
383 For unsigned operations (``DIV`` and ``MOD``),    
384 'imm' is interpreted as a 32-bit unsigned valu    
385 'imm' is first :term:`sign extended<Sign Exten    
386 interpreted as a 64-bit unsigned value.           
387                                                   
388 For signed operations (``SDIV`` and ``SMOD``),    
389 'imm' is interpreted as a 32-bit signed value.    
390 is first :term:`sign extended<Sign Extend>` fr    
391 interpreted as a 64-bit signed value.             
392                                                   
393 Note that there are varying definitions of the    
394 when the dividend or divisor are negative, whe    
395 vary by language such that Python, Ruby, etc.     
396 etc. This specification requires that signed m    
397 (where -13 % 3 == -1) as implemented in C, Go,    
398                                                   
399    a % n = a - n * trunc(a / n)                   
400                                                   
401 The ``MOVSX`` instruction does a move operatio    
402 ``{MOVSX, X, ALU}`` :term:`sign extends<Sign E    
403 32-bit operands, and zeroes the remaining uppe    
404 ``{MOVSX, X, ALU64}`` :term:`sign extends<Sign    
405 operands into 64-bit operands.  Unlike other a    
406 ``MOVSX`` is only defined for register source     
407                                                   
408 ``{MOV, K, ALU64}`` means::                       
409                                                   
410   dst = (s64)imm                                  
411                                                   
412 ``{MOV, X, ALU}`` means::                         
413                                                   
414   dst = (u32)src                                  
415                                                   
416 ``{MOVSX, X, ALU}`` with 'offset' 8 means::       
417                                                   
418   dst = (u32)(s32)(s8)src                         
419                                                   
420                                                   
421 The ``NEG`` instruction is only defined when t    
422 (``K``).                                          
423                                                   
424 Shift operations use a mask of 0x3F (63) for 6    
425 for 32-bit operations.                            
426                                                   
427 Byte swap instructions                            
428 ----------------------                            
429                                                   
430 The byte swap instructions use instruction cla    
431 and a 4-bit 'code' field of ``END``.              
432                                                   
433 The byte swap instructions operate on the dest    
434 only and do not use a separate source register    
435                                                   
436 For ``ALU``, the 1-bit source operand field in    
437 select what byte order the operation converts     
438 ``ALU64``, the 1-bit source operand field in t    
439 and MUST be set to 0.                             
440                                                   
441 .. table:: Byte swap instructions                 
442                                                   
443   =====  ========  =====  ====================    
444   class  source    value  description             
445   =====  ========  =====  ====================    
446   ALU    LE        0      convert between host    
447   ALU    BE        1      convert between host    
448   ALU64  Reserved  0      do byte swap uncondi    
449   =====  ========  =====  ====================    
450                                                   
451 The 'imm' field encodes the width of the swap     
452 are supported: 16, 32 and 64.  Width 64 operat    
453 conformance group and other swap operations be    
454 conformance group.                                
455                                                   
456 Examples:                                         
457                                                   
458 ``{END, LE, ALU}`` with 'imm' = 16/32/64 means    
459                                                   
460   dst = le16(dst)                                 
461   dst = le32(dst)                                 
462   dst = le64(dst)                                 
463                                                   
464 ``{END, BE, ALU}`` with 'imm' = 16/32/64 means    
465                                                   
466   dst = be16(dst)                                 
467   dst = be32(dst)                                 
468   dst = be64(dst)                                 
469                                                   
470 ``{END, TO, ALU64}`` with 'imm' = 16/32/64 mea    
471                                                   
472   dst = bswap16(dst)                              
473   dst = bswap32(dst)                              
474   dst = bswap64(dst)                              
475                                                   
476 Jump instructions                                 
477 -----------------                                 
478                                                   
479 ``JMP32`` uses 32-bit wide operands and indica    
480 conformance group, while ``JMP`` uses 64-bit w    
481 otherwise identical operations, and indicates     
482 group unless otherwise specified.                 
483 The 'code' field encodes the operation as belo    
484                                                   
485 .. table:: Jump instructions                      
486                                                   
487   ========  =====  =======  ==================    
488   code      value  src_reg  description           
489   ========  =====  =======  ==================    
490   JA        0x0    0x0      PC += offset          
491   JA        0x0    0x0      PC += imm             
492   JEQ       0x1    any      PC += offset if ds    
493   JGT       0x2    any      PC += offset if ds    
494   JGE       0x3    any      PC += offset if ds    
495   JSET      0x4    any      PC += offset if ds    
496   JNE       0x5    any      PC += offset if ds    
497   JSGT      0x6    any      PC += offset if ds    
498   JSGE      0x7    any      PC += offset if ds    
499   CALL      0x8    0x0      call helper functi    
500   CALL      0x8    0x1      call PC += imm        
501   CALL      0x8    0x2      call helper functi    
502   EXIT      0x9    0x0      return                
503   JLT       0xa    any      PC += offset if ds    
504   JLE       0xb    any      PC += offset if ds    
505   JSLT      0xc    any      PC += offset if ds    
506   JSLE      0xd    any      PC += offset if ds    
507   ========  =====  =======  ==================    
508                                                   
509 where 'PC' denotes the program counter, and th    
510 is in units of 64-bit instructions relative to    
511 the jump instruction.  Thus 'PC += 1' skips ex    
512 instruction if it's a basic instruction or res    
513 if the next instruction is a 128-bit wide inst    
514                                                   
515 Example:                                          
516                                                   
517 ``{JSGE, X, JMP32}`` means::                      
518                                                   
519   if (s32)dst s>= (s32)src goto +offset           
520                                                   
521 where 's>=' indicates a signed '>=' comparison    
522                                                   
523 ``{JLE, K, JMP}`` means::                         
524                                                   
525   if dst <= (u64)(s64)imm goto +offset            
526                                                   
527 ``{JA, K, JMP32}`` means::                        
528                                                   
529   gotol +imm                                      
530                                                   
531 where 'imm' means the branch offset comes from    
532                                                   
533 Note that there are two flavors of ``JA`` inst    
534 ``JMP`` class permits a 16-bit jump offset spe    
535 field, whereas the ``JMP32`` class permits a 3    
536 specified by the 'imm' field. A > 16-bit condi    
537 converted to a < 16-bit conditional jump plus     
538 jump.                                             
539                                                   
540 All ``CALL`` and ``JA`` instructions belong to    
541 base32 conformance group.                         
542                                                   
543 Helper functions                                  
544 ~~~~~~~~~~~~~~~~                                  
545                                                   
546 Helper functions are a concept whereby BPF pro    
547 set of function calls exposed by the underlyin    
548                                                   
549 Historically, each helper function was identif    
550 encoded in the 'imm' field.  Further documenta    
551 is outside the scope of this document and stan    
552 future work, but use is widely deployed and mo    
553 found in platform-specific documentation (e.g.    
554                                                   
555 Platforms that support the BPF Type Format (BT    
556 a helper function by a BTF ID encoded in the '    
557 identifies the helper name and type.  Further     
558 is outside the scope of this document and stan    
559 future work, but use is widely deployed and mo    
560 found in platform-specific documentation (e.g.    
561                                                   
562 Program-local functions                           
563 ~~~~~~~~~~~~~~~~~~~~~~~                           
564 Program-local functions are functions exposed     
565 caller, and are referenced by offset from the     
566 instruction, similar to ``JA``.  The offset is    
567 the call instruction. An ``EXIT`` within the p    
568 return to the caller.                             
569                                                   
570 Load and store instructions                       
571 ===========================                       
572                                                   
573 For load and store instructions (``LD``, ``LDX    
574 8-bit 'opcode' field is divided as follows::      
575                                                   
576   +-+-+-+-+-+-+-+-+                               
577   |mode |sz |class|                               
578   +-+-+-+-+-+-+-+-+                               
579                                                   
580 **mode**                                          
581   The mode modifier is one of:                    
582                                                   
583   .. table:: Mode modifier                        
584                                                   
585     =============  =====  ====================    
586     mode modifier  value  description             
587     =============  =====  ====================    
588     IMM            0      64-bit immediate ins    
589     ABS            1      legacy BPF packet ac    
590     IND            2      legacy BPF packet ac    
591     MEM            3      regular load and sto    
592     MEMSX          4      sign-extension load     
593     ATOMIC         6      atomic operations       
594     =============  =====  ====================    
595                                                   
596 **sz (size)**                                     
597   The size modifier is one of:                    
598                                                   
599   .. table:: Size modifier                        
600                                                   
601     ====  =====  =====================            
602     size  value  description                      
603     ====  =====  =====================            
604     W     0      word        (4 bytes)            
605     H     1      half word   (2 bytes)            
606     B     2      byte                             
607     DW    3      double word (8 bytes)            
608     ====  =====  =====================            
609                                                   
610   Instructions using ``DW`` belong to the base    
611                                                   
612 **class**                                         
613   The instruction class (see `Instruction clas    
614                                                   
615 Regular load and store operations                 
616 ---------------------------------                 
617                                                   
618 The ``MEM`` mode modifier is used to encode re    
619 instructions that transfer data between a regi    
620                                                   
621 ``{MEM, <size>, STX}`` means::                    
622                                                   
623   *(size *) (dst + offset) = src                  
624                                                   
625 ``{MEM, <size>, ST}`` means::                     
626                                                   
627   *(size *) (dst + offset) = imm                  
628                                                   
629 ``{MEM, <size>, LDX}`` means::                    
630                                                   
631   dst = *(unsigned size *) (src + offset)         
632                                                   
633 Where '<size>' is one of: ``B``, ``H``, ``W``,    
634 'unsigned size' is one of: u8, u16, u32, or u6    
635                                                   
636 Sign-extension load operations                    
637 ------------------------------                    
638                                                   
639 The ``MEMSX`` mode modifier is used to encode     
640 instructions that transfer data between a regi    
641                                                   
642 ``{MEMSX, <size>, LDX}`` means::                  
643                                                   
644   dst = *(signed size *) (src + offset)           
645                                                   
646 Where '<size>' is one of: ``B``, ``H``, or ``W    
647 'signed size' is one of: s8, s16, or s32.         
648                                                   
649 Atomic operations                                 
650 -----------------                                 
651                                                   
652 Atomic operations are operations that operate     
653 interrupted or corrupted by other access to th    
654 by other BPF programs or means outside of this    
655                                                   
656 All atomic operations supported by BPF are enc    
657 that use the ``ATOMIC`` mode modifier as follo    
658                                                   
659 * ``{ATOMIC, W, STX}`` for 32-bit operations,     
660   part of the "atomic32" conformance group.       
661 * ``{ATOMIC, DW, STX}`` for 64-bit operations,    
662   part of the "atomic64" conformance group.       
663 * 8-bit and 16-bit wide atomic operations are     
664                                                   
665 The 'imm' field is used to encode the actual a    
666 Simple atomic operation use a subset of the va    
667 arithmetic operations in the 'imm' field to en    
668                                                   
669 .. table:: Simple atomic operations               
670                                                   
671   ========  =====  ===========                    
672   imm       value  description                    
673   ========  =====  ===========                    
674   ADD       0x00   atomic add                     
675   OR        0x40   atomic or                      
676   AND       0x50   atomic and                     
677   XOR       0xa0   atomic xor                     
678   ========  =====  ===========                    
679                                                   
680                                                   
681 ``{ATOMIC, W, STX}`` with 'imm' = ADD means::     
682                                                   
683   *(u32 *)(dst + offset) += src                   
684                                                   
685 ``{ATOMIC, DW, STX}`` with 'imm' = ADD means::    
686                                                   
687   *(u64 *)(dst + offset) += src                   
688                                                   
689 In addition to the simple atomic operations, t    
690 two complex atomic operations:                    
691                                                   
692 .. table:: Complex atomic operations              
693                                                   
694   ===========  ================  =============    
695   imm          value             description      
696   ===========  ================  =============    
697   FETCH        0x01              modifier: ret    
698   XCHG         0xe0 | FETCH      atomic exchan    
699   CMPXCHG      0xf0 | FETCH      atomic compar    
700   ===========  ================  =============    
701                                                   
702 The ``FETCH`` modifier is optional for simple     
703 always set for the complex atomic operations.     
704 is set, then the operation also overwrites ``s    
705 was in memory before it was modified.             
706                                                   
707 The ``XCHG`` operation atomically exchanges ``    
708 addressed by ``dst + offset``.                    
709                                                   
710 The ``CMPXCHG`` operation atomically compares     
711 ``dst + offset`` with ``R0``. If they match, t    
712 ``dst + offset`` is replaced with ``src``. In     
713 value that was at ``dst + offset`` before the     
714 and loaded back to ``R0``.                        
715                                                   
716 64-bit immediate instructions                     
717 -----------------------------                     
718                                                   
719 Instructions with the ``IMM`` 'mode' modifier     
720 encoding defined in `Instruction encoding`_, a    
721 basic instruction to hold an opcode subtype.      
722                                                   
723 The following table defines a set of ``{IMM, D    
724 with opcode subtypes in the 'src_reg' field, u    
725 defined further below:                            
726                                                   
727 .. table:: 64-bit immediate instructions          
728                                                   
729   =======  ===================================    
730   src_reg  pseudocode                             
731   =======  ===================================    
732   0x0      dst = (next_imm << 32) | imm           
733   0x1      dst = map_by_fd(imm)                   
734   0x2      dst = map_val(map_by_fd(imm)) + nex    
735   0x3      dst = var_addr(imm)                    
736   0x4      dst = code_addr(imm)                   
737   0x5      dst = map_by_idx(imm)                  
738   0x6      dst = map_val(map_by_idx(imm)) + ne    
739   =======  ===================================    
740                                                   
741 where                                             
742                                                   
743 * map_by_fd(imm) means to convert a 32-bit fil    
744 * map_by_idx(imm) means to convert a 32-bit in    
745 * map_val(map) gets the address of the first v    
746 * var_addr(imm) gets the address of a platform    
747 * code_addr(imm) gets the address of the instr    
748 * the 'imm type' can be used by disassemblers     
749 * the 'dst type' can be used for verification     
750                                                   
751 Maps                                              
752 ~~~~                                              
753                                                   
754 Maps are shared memory regions accessible by B    
755 A map can have various semantics as defined in    
756 may not have a single contiguous memory region    
757 currently only defined for maps that do have a    
758                                                   
759 Each map can have a file descriptor (fd) if su    
760 'map_by_fd(imm)' means to get the map with the    
761 BPF program can also be defined to use a set o    
762 program at load time, and 'map_by_idx(imm)' me    
763 index in the set associated with the BPF progr    
764                                                   
765 Platform Variables                                
766 ~~~~~~~~~~~~~~~~~~                                
767                                                   
768 Platform variables are memory regions, identif    
769 the runtime and accessible by BPF programs on     
770 'var_addr(imm)' operation means to get the add    
771 identified by the given id.                       
772                                                   
773 Legacy BPF Packet access instructions             
774 -------------------------------------             
775                                                   
776 BPF previously introduced special instructions    
777 carried over from classic BPF. These instructi    
778 class of ``LD``, a size modifier of ``W``, ``H    
779 mode modifier of ``ABS`` or ``IND``.  The 'dst    
780 set to zero, and 'src_reg' was set to zero for    
781 instructions are deprecated and SHOULD no long    
782 access instructions belong to the "packet" con    
                                                      

~ [ source navigation ] ~ [ diff markup ] ~ [ identifier search ] ~

kernel.org | git.kernel.org | LWN.net | Project Home | SVN repository | Mail admin

Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.

sflogo.php