bpf

package
v0.0.0-...-957f62e Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Nov 10, 2023 License: Apache-2.0, MIT Imports: 6 Imported by: 0

Documentation

Overview

Package bpf provides tools for working with Berkeley Packet Filter (BPF) programs. More information on BPF can be found at https://www.freebsd.org/cgi/man.cgi?bpf(4)

Index

Constants

View Source 
const (
	// MaxInstructions is the maximum number of instructions in a BPF program,
	// and is equal to Linux's BPF_MAXINSNS.
	MaxInstructions = 4096

	// ScratchMemRegisters is the number of M registers in a BPF virtual machine,
	// and is equal to Linux's BPF_MEMWORDS.
	ScratchMemRegisters = 16
)
View Source 
const (
	// Instruction class, stored in bits 0-2.
	Ld   = 0x00 // load into A
	Ldx  = 0x01 // load into X
	St   = 0x02 // store from A
	Stx  = 0x03 // store from X
	Alu  = 0x04 // arithmetic
	Jmp  = 0x05 // jump
	Ret  = 0x06 // return
	Misc = 0x07

	// Size of a load, stored in bits 3-4.
	W = 0x00 // 32 bits
	H = 0x08 // 16 bits
	B = 0x10 // 8 bits

	// Source operand for a load, stored in bits 5-7.
	// Address mode numbers in the comments come from Linux's
	// Documentation/networking/filter.txt.
	Imm = 0x00 // immediate value K (mode 4)
	Abs = 0x20 // data in input at byte offset K (mode 1)
	Ind = 0x40 // data in input at byte offset X+K (mode 2)
	Mem = 0x60 // M[K] (mode 3)
	Len = 0x80 // length of the input in bytes ("BPF extension len")
	Msh = 0xa0 // 4 * lower nibble of input at byte offset K (mode 5)

	// Source operands for arithmetic, jump, and return instructions.
	// Arithmetic and jump instructions can use K or X as source operands.
	// Return instructions can use K or A as source operands.
	K = 0x00 // still mode 4
	X = 0x08 // mode 0
	A = 0x10 // mode 9

	// Arithmetic instructions, stored in bits 4-7.
	Add = 0x00
	Sub = 0x10 // A - src
	Mul = 0x20
	Div = 0x30 // A / src
	Or  = 0x40
	And = 0x50
	Lsh = 0x60 // A << src
	Rsh = 0x70 // A >> src
	Neg = 0x80 // -A (src ignored)
	Mod = 0x90 // A % src
	Xor = 0xa0

	// Jump instructions, stored in bits 4-7.
	Ja   = 0x00 // unconditional (uses K for jump offset)
	Jeq  = 0x10 // if A == src
	Jgt  = 0x20 // if A > src
	Jge  = 0x30 // if A >= src
	Jset = 0x40 // if (A & src) != 0

	// Miscellaneous instructions, stored in bits 3-7.
	Tax = 0x00 // A = X
	Txa = 0x80 // X = A

)

Parts of a linux.BPFInstruction.OpCode. Compare to the Linux kernel's include/uapi/linux/filter.h.

In the comments below:

  • A, X, and M[] are BPF virtual machine registers.

  • K refers to the instruction field linux.BPFInstruction.K.

  • Bits are counted from the LSB position.

View Source 
const (
	// DivisionByZero indicates that a program contains, or executed, a
	// division or modulo by zero.
	DivisionByZero = iota

	// InvalidEndOfProgram indicates that the last instruction of a program is
	// not a return.
	InvalidEndOfProgram

	// InvalidInstructionCount indicates that a program has zero instructions
	// or more than MaxInstructions instructions.
	InvalidInstructionCount

	// InvalidJumpTarget indicates that a program contains a jump whose target
	// is outside of the program's bounds.
	InvalidJumpTarget

	// InvalidLoad indicates that a program executed an invalid load of input
	// data.
	InvalidLoad

	// InvalidOpcode indicates that a program contains an instruction with an
	// invalid opcode.
	InvalidOpcode

	// InvalidRegister indicates that a program contains a load from, or store
	// to, a non-existent M register (index >= ScratchMemRegisters).
	InvalidRegister
)

Possible values for ProgramError.Code.

Variables

This section is empty.

Functions

func Decode 

func Decode(inst linux.BPFInstruction) (string, error)

Decode translates a single BPF instruction into text format.

func DecodeInstructions 

func DecodeInstructions(instns []linux.BPFInstruction) (string, error)

DecodeInstructions translates an array of BPF instructions into text format.

func DecodeProgram 

func DecodeProgram(p Program) (string, error)

DecodeProgram translates a compiled BPF program into text format.

func Exec 

func Exec(p Program, in Input) (uint32, error)

Exec executes a BPF program over the given input and returns its return value.

func Jump 

func Jump(code uint16, k uint32, jt, jf uint8) linux.BPFInstruction

Jump returns a linux.BPFInstruction representing a BPF jump instruction.

func Stmt 

func Stmt(code uint16, k uint32) linux.BPFInstruction

Stmt returns a linux.BPFInstruction representing a BPF non-jump instruction.

Types

type Error 

type Error struct {
	// Code indicates the kind of error that occurred.
	Code int

	// PC is the program counter (index into the list of instructions) at which
	// the error occurred.
	PC int
}

Error is an error encountered while compiling or executing a BPF program.

func (Error) Error 

func (e Error) Error() string

Error implements error.Error.

type Input 

type Input interface {
	// Load32 reads 32 bits from the input starting at the given byte offset.
	Load32(off uint32) (uint32, bool)

	// Load16 reads 16 bits from the input starting at the given byte offset.
	Load16(off uint32) (uint16, bool)

	// Load8 reads 8 bits from the input starting at the given byte offset.
	Load8(off uint32) (uint8, bool)

	// Length returns the length of the input in bytes.
	Length() uint32
}

Input represents a source of input data for a BPF program. (BPF documentation sometimes refers to the input data as the "packet" due to its origins as a packet processing DSL.)

For all of Input's Load methods:

  • The second (bool) return value is true if the load succeeded and false otherwise.

  • Inputs should not assume that the loaded range falls within the input data's length. Inputs should return false if the load falls outside of the input data.

  • Inputs should not assume that the offset is correctly aligned. Inputs may choose to service or reject loads to unaligned addresses.

type InputBytes 

type InputBytes struct {
	// Data is the data accessed through the Input interface.
	Data []byte

	// Order is the byte order the data is accessed with.
	Order binary.ByteOrder
}

InputBytes implements the Input interface by providing access to a byte slice. Unaligned loads are supported.

func (InputBytes) Length 

func (i InputBytes) Length() uint32

Length implements Input.Length.

func (InputBytes) Load16 

func (i InputBytes) Load16(off uint32) (uint16, bool)

Load16 implements Input.Load16.

func (InputBytes) Load32 

func (i InputBytes) Load32(off uint32) (uint32, bool)

Load32 implements Input.Load32.

func (InputBytes) Load8 

func (i InputBytes) Load8(off uint32) (uint8, bool)

Load8 implements Input.Load8.

type Program 

type Program struct {
	// contains filtered or unexported fields
}

Program is a BPF program that has been validated for consistency.

+stateify savable

func Compile 

func Compile(insns []linux.BPFInstruction) (Program, error)

Compile performs validation on a sequence of BPF instructions before wrapping them in a Program.

func (Program) Length 

func (p Program) Length() int

Length returns the number of instructions in the program.

func (*Program) StateFields 

func (p *Program) StateFields() []string

func (*Program) StateLoad 

func (p *Program) StateLoad(stateSourceObject state.Source)

+checklocksignore

func (*Program) StateSave 

func (p *Program) StateSave(stateSinkObject state.Sink)

+checklocksignore

func (*Program) StateTypeName 

func (p *Program) StateTypeName() string

type ProgramBuilder 

type ProgramBuilder struct {
	// contains filtered or unexported fields
}

ProgramBuilder assists with building a BPF program with jump labels that are resolved to their proper offsets.

func NewProgramBuilder 

func NewProgramBuilder() *ProgramBuilder

NewProgramBuilder creates a new ProgramBuilder instance.

func (*ProgramBuilder) AddDirectJumpLabel 

func (b *ProgramBuilder) AddDirectJumpLabel(labelName string)

AddDirectJumpLabel adds a new jump to the program where is labelled.

func (*ProgramBuilder) AddJump 

func (b *ProgramBuilder) AddJump(code uint16, k uint32, jt, jf uint8)

AddJump adds a new jump to the program.

func (*ProgramBuilder) AddJumpFalseLabel 

func (b *ProgramBuilder) AddJumpFalseLabel(code uint16, k uint32, jt uint8, jfLabel string)

AddJumpFalseLabel adds a new jump to the program where 'jump if false' is a label.

func (*ProgramBuilder) AddJumpLabels 

func (b *ProgramBuilder) AddJumpLabels(code uint16, k uint32, jtLabel, jfLabel string)

AddJumpLabels adds a new jump to the program where both jump targets are labels.

func (*ProgramBuilder) AddJumpTrueLabel 

func (b *ProgramBuilder) AddJumpTrueLabel(code uint16, k uint32, jtLabel string, jf uint8)

AddJumpTrueLabel adds a new jump to the program where 'jump if true' is a label.

func (*ProgramBuilder) AddLabel 

func (b *ProgramBuilder) AddLabel(name string) error

AddLabel sets the given label name at the current location. The next instruction is executed when the any code jumps to this label. More than one label can be added to the same location.

func (*ProgramBuilder) AddStmt 

func (b *ProgramBuilder) AddStmt(code uint16, k uint32)

AddStmt adds a new statement to the program.

func (*ProgramBuilder) Instructions 

func (b *ProgramBuilder) Instructions() ([]linux.BPFInstruction, error)

Instructions returns an array of BPF instructions representing the program with all labels resolved. Return error in case label resolution failed due to an invalid program.

N.B. Partial results will be returned in the error case, which is useful for debugging.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.