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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL