gitee.com/ks-custle/core-gm@v0.0.0-20230922171213-b83bdd97b62c/net/bpf/doc.go (about)

     1  // Copyright 2016 The Go Authors. All rights reserved.
     2  // Use of this source code is governed by a BSD-style
     3  // license that can be found in the LICENSE file.
     4  
     5  /*
     6  Package bpf implements marshaling and unmarshaling of programs for the
     7  Berkeley Packet Filter virtual machine, and provides a Go implementation
     8  of the virtual machine.
     9  
    10  BPF's main use is to specify a packet filter for network taps, so that
    11  the kernel doesn't have to expensively copy every packet it sees to
    12  userspace. However, it's been repurposed to other areas where running
    13  user code in-kernel is needed. For example, Linux's seccomp uses BPF
    14  to apply security policies to system calls. For simplicity, this
    15  documentation refers only to packets, but other uses of BPF have their
    16  own data payloads.
    17  
    18  BPF programs run in a restricted virtual machine. It has almost no
    19  access to kernel functions, and while conditional branches are
    20  allowed, they can only jump forwards, to guarantee that there are no
    21  infinite loops.
    22  
    23  # The virtual machine
    24  
    25  The BPF VM is an accumulator machine. Its main register, called
    26  register A, is an implicit source and destination in all arithmetic
    27  and logic operations. The machine also has 16 scratch registers for
    28  temporary storage, and an indirection register (register X) for
    29  indirect memory access. All registers are 32 bits wide.
    30  
    31  Each run of a BPF program is given one packet, which is placed in the
    32  VM's read-only "main memory". LoadAbsolute and LoadIndirect
    33  instructions can fetch up to 32 bits at a time into register A for
    34  examination.
    35  
    36  The goal of a BPF program is to produce and return a verdict (uint32),
    37  which tells the kernel what to do with the packet. In the context of
    38  packet filtering, the returned value is the number of bytes of the
    39  packet to forward to userspace, or 0 to ignore the packet. Other
    40  contexts like seccomp define their own return values.
    41  
    42  In order to simplify programs, attempts to read past the end of the
    43  packet terminate the program execution with a verdict of 0 (ignore
    44  packet). This means that the vast majority of BPF programs don't need
    45  to do any explicit bounds checking.
    46  
    47  In addition to the bytes of the packet, some BPF programs have access
    48  to extensions, which are essentially calls to kernel utility
    49  functions. Currently, the only extensions supported by this package
    50  are the Linux packet filter extensions.
    51  
    52  # Examples
    53  
    54  This packet filter selects all ARP packets.
    55  
    56  	bpf.Assemble([]bpf.Instruction{
    57  		// Load "EtherType" field from the ethernet header.
    58  		bpf.LoadAbsolute{Off: 12, Size: 2},
    59  		// Skip over the next instruction if EtherType is not ARP.
    60  		bpf.JumpIf{Cond: bpf.JumpNotEqual, Val: 0x0806, SkipTrue: 1},
    61  		// Verdict is "send up to 4k of the packet to userspace."
    62  		bpf.RetConstant{Val: 4096},
    63  		// Verdict is "ignore packet."
    64  		bpf.RetConstant{Val: 0},
    65  	})
    66  
    67  This packet filter captures a random 1% sample of traffic.
    68  
    69  	bpf.Assemble([]bpf.Instruction{
    70  		// Get a 32-bit random number from the Linux kernel.
    71  		bpf.LoadExtension{Num: bpf.ExtRand},
    72  		// 1% dice roll?
    73  		bpf.JumpIf{Cond: bpf.JumpLessThan, Val: 2^32/100, SkipFalse: 1},
    74  		// Capture.
    75  		bpf.RetConstant{Val: 4096},
    76  		// Ignore.
    77  		bpf.RetConstant{Val: 0},
    78  	})
    79  */
    80  package bpf // import "gitee.com/ks-custle/core-gm/net/bpf"