ebpf

package module
v0.1.0 Latest Latest
Warning

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

 Go to latest Published: Nov 3, 2018 License: Apache-2.0 Imports: 4 Imported by: 0

README

ebpf

import "acln.ro/ebpf"

eBPF package for Go. Currently under active development.

See documentation at https://godoc.org/acln.ro/ebpf.

Documentation

Index

Constants

View Source 
const (
	// K specifies the 32 bit immediate as the source operand.
	K = iota << 3

	// X specifies the source register as the source operand.
	X
)

Source operands.

View Source 
const MaxInstructions = 4096

MaxInstructions is the maximum number of instructions in a BPF or eBPF program.

Variables

This section is empty.

Functions

func IsExist 

func IsExist(err error) bool

IsExist returns a boolean indicating whether err reports that an object (e.g. an entry in a map) already exists.

func IsNotExist 

func IsNotExist(err error) bool

IsNotExist returns a boolean indicating whether err is reports that an object (e.g. an entry in a map) does not exist.

func IsTooBig 

func IsTooBig(err error) bool

IsTooBig returns a boolean indicating whether err is known to report that a map has reached its size limit.

Types

type ALUOp 

type ALUOp uint8

ALUOp specifies an ALU operation. 

const (
	ADD ALUOp = iota << 4
	SUB
	MUL
	DIV
	OR
	AND
	LSH
	RSH
	NEG
	MOD
	XOR
	MOV  // eBPF only
	ARSH // eBPF only
	END  // eBPF only
)

Valid ALU operations.

type AddressMode 

type AddressMode uint8

AddressMode is the addres mode of a load or store instruction. 

const (
	IMM AddressMode = iota << 5
	ABS
	IND
	MEM
	LEN
	MSH
	XADD // eBPF only
)

Valid address modes.

type Array 

type Array struct {
	NumElements uint32
	ValueSize   uint32
	ObjectName  string
	// contains filtered or unexported fields
}

Array configures an eBPF array.

Arrays are allocated up-front and have a fixed number of elements. Indexes are 4 bytes wide.

Unlike Hashmaps, updates to a given slot in an array are not atomic.

ObjectName names the array. Names longer than 15 bytes are truncated.

func (*Array) Close 

func (a *Array) Close() error

Close destroys the array and releases the associated file descriptor. After a call to Close, future method calls on the Array will return errors.

func (*Array) Init 

func (a *Array) Init() error

Init initializes the array.

func (*Array) Lookup 

func (a *Array) Lookup(i uint32, v []byte) error

Lookup looks up the value at index i and stores it in v. If there is an error, it will be of type *MapOpError. If the index i is out of bounds, Lookup returns an error.

func (*Array) Set 

func (a *Array) Set(i uint32, v []byte) error

Set sets the value at the given index. If there is an error, it will be of type *MapOpError. If the index i is out of bounds, Set returns an error. Note that unlike Set, Create or Update for hashmaps, Set for arrays is not atomic by default.

type Assembler 

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

An Assembler assembles eBPF instructions.

func (*Assembler) ALU32Imm 

func (a *Assembler) ALU32Imm(op ALUOp, dst Register, imm int32)

ALU32Imm emits a 32 bit ALU instruction on a register and a 32 bit immediate. Schematically: 

dst = int32(dst) <op> imm

After the operation, dst is zero-extended into 64-bit.

func (*Assembler) ALU32Reg 

func (a *Assembler) ALU32Reg(op ALUOp, dst, src Register)

ALU32Reg emits a 32 bit ALU instruction on registers. Schematically: 

dst = int32(dst) <op> int32(src)

After the operation, dst is zero-extended into 64-bit.

func (*Assembler) ALU64Imm 

func (a *Assembler) ALU64Imm(op ALUOp, dst Register, imm int32)

ALU64Imm emits a 64 bit ALU instruction on a register and a 32 bit immediate. Schematically: 

dst = dst <op> int64(imm)

func (*Assembler) ALU64Reg 

func (a *Assembler) ALU64Reg(op ALUOp, dst, src Register)

ALU64Reg emits a 64 bit ALU instruction on registers. 

dst = dst <op> src

func (*Assembler) Assemble 

func (a *Assembler) Assemble() []uint64

Assemble assembles the code and returns the raw instructions.

func (*Assembler) AtomicAdd32 

func (a *Assembler) AtomicAdd32(dst, src Register, offset int16)

AtomicAdd32 emits a 32-bit atomic add to a memory location. Schematically: 

*(uint32 *)(dst + offset) += uint32(src)

func (*Assembler) AtomicAdd64 

func (a *Assembler) AtomicAdd64(dst, src Register, offset int16)

AtomicAdd64 emits a 64-bit atomic add to a memory location. Schematically: 

*(uint64 *)(dst + offset) += src

func (*Assembler) Call 

func (a *Assembler) Call(fn KernelFunction)

Call emits a function call instruction. Schematically:

func (*Assembler) Exit 

func (a *Assembler) Exit()

Exit emits a program exit instruction.

func (*Assembler) JumpImm 

func (a *Assembler) JumpImm(cond JumpCondition, dst Register, imm int32, offset int16)

JumpImm emits a conditional jump against an immediate. Schematically: 

if dst <op> imm { goto pc + offset }

func (*Assembler) JumpReg 

func (a *Assembler) JumpReg(cond JumpCondition, dst, src Register, offset int16)

JumpReg emits a conditional jump against registers. Schematically: 

if dst <op> src { goto pc + offset }

func (*Assembler) LoadAbs 

func (a *Assembler) LoadAbs(w InstructionWidth, imm int32)

LoadAbs emits the special 'direct packet access' instruction. Schematically: 

R0 = *(uintw *)(skb->data + imm)

func (*Assembler) LoadImm64 

func (a *Assembler) LoadImm64(dst Register, imm uint64)

LoadImm64 emits the special 'load 64 bit immediate' instruction, which loads a 64 bit immediate into dst.

func (*Assembler) LoadMapFD 

func (a *Assembler) LoadMapFD(dst Register, fd uint32)

LoadMapFD loads a map file descriptor into dst.

func (*Assembler) MemLoad 

func (a *Assembler) MemLoad(w InstructionWidth, dst, src Register, offset int16)

MemLoad emits a memory load. Schematically: 

dst = *(uintw *)(src + offset)

func (*Assembler) MemStoreImm 

func (a *Assembler) MemStoreImm(w InstructionWidth, dst Register, offset int16, imm int32)

MemStoreImm emits a memory store from an immediate. Schematically: 

*(uintw *)(dst + offset) = imm

func (*Assembler) MemStoreReg 

func (a *Assembler) MemStoreReg(w InstructionWidth, dst, src Register, offset int16)

MemStoreReg emits a memory store from a register. Schematically: 

*(uintw *)(dst + offset) = src

func (*Assembler) Mov32Imm 

func (a *Assembler) Mov32Imm(dst Register, imm int32)

Mov32Imm emits a move of a 32 bit immediate into a register. Schematically: 

dst = imm

After the operation, dst is zero-extended into 64-bit.

func (*Assembler) Mov32Reg 

func (a *Assembler) Mov32Reg(dst, src Register)

Mov32Reg emits a move on 32-bit subregisters. Schematically: 

dst = int32(src)

After the operation, dst is zero-extended into 64-bit.

func (*Assembler) Mov64Imm 

func (a *Assembler) Mov64Imm(dst Register, imm int32)

Mov64Imm emits a 64 bit move of a 32 bit immediate into a register. Schematically: 

dst = imm

func (*Assembler) Mov64Reg 

func (a *Assembler) Mov64Reg(dst, src Register)

Mov64Reg emits a move on 64-bit registers. Schematically: 

dst = src

func (*Assembler) Raw 

func (a *Assembler) Raw(ins Instruction)

Raw emits a raw instruction to the stream.

type AttachType 

type AttachType uint32

AttachType describes the attach type of an eBPF program. 

const (
	AttachTypeCGroupInetIngress AttachType = iota
	AttachTypeCGroupInetEgress
	AttachTypeCGroupInetSockCreate
	AttachTypeCGroupSockOps
	AttachTypeSKSKBStreamParser
	AttachTypeSKSKBStreamVerdict
	AttachTypeCGroupDevice
	AttachTypeSKMsgVerdict
	AttachTypeCGroupInet4Bind
	AttachTypeCGroupInet6Bind
	AttachTypeCGroupInet4Connect
	AttachTypeCGroupInet6Connect
	AttachTypeCGroupInet4PostBind
	AttachTypeCGroupInet6PostBind
	AttachTypeCGroupUDP4SendMsg
	AttachTypeCGroupUDP6SendMsg
	AttachTypeLIRCMode2
)

Valid program attach types.

type Hashmap 

type Hashmap struct {
	KeySize    uint32
	ValueSize  uint32
	MaxEntries uint32
	ObjectName string
	// contains filtered or unexported fields
}

Hashmap configures a generic eBPF hash map.

Before use, a Hashmap must be initialized by using the Init method. KeySize, ValueSize and MaxEntries must be non-zero.

ObjectName names the map. Names must not contain the NULL character. Names longer than 15 bytes are truncated.

A Hashmap must not be copied after initialization. It is safe to call methods on Hashmap from multiple goroutines.

func (*Hashmap) Close 

func (h *Hashmap) Close() error

Close destroys the hashmap and releases the associated file descriptor. After a call to Close, future method calls on the Hashmap will return errors.

func (*Hashmap) Create 

func (h *Hashmap) Create(k, v []byte) error

Create creates a new entry for k in the map, and sets the value to v. If an entry for k exists in the map, Create returns an error such that IsExist(err) == true.

func (*Hashmap) Delete 

func (h *Hashmap) Delete(k []byte) error

Delete deletes the entry for k. If an entry for k does not exist in the map, Delete returns an error such that IsNotExist(err) == true.

func (*Hashmap) Init 

func (h *Hashmap) Init() error

Init initializes the hashmap.

func (*Hashmap) Iterate 

func (h *Hashmap) Iterate(fn func(k, v []byte) (stop bool), startHint []byte) error

Iterate iterates over all keys in the map and calls fn for each key-value pair. If fn returns true or the final element of the map is reached, iteration stops. fn must not retain the arguments it is called with.

startHint optionally specifies a key that does *not* exist in the map, such that Iterate can begin iteration from the first key that does. Due to the nature of BPF map iterators, on Linux kernels older than 4.12, Iterate requires a non-nil startHint. On Linux >= 4.12, startHint may be nil, but it is recommended to pass a valid one nevertheless.

func (*Hashmap) Lookup 

func (h *Hashmap) Lookup(k, v []byte) error

Lookup looks up the value for k and stores it in v. If k is not found in the map, Lookup returns an error such that IsNotExist(err) == true.

func (*Hashmap) Set 

func (h *Hashmap) Set(k, v []byte) error

Set sets the value for k to v. If an entry for k exists in the map, it will be overwritten.

func (*Hashmap) Update 

func (h *Hashmap) Update(k, v []byte) error

Update updates the entry for k to v. If an entry for k does not exist in the map, Update returns an error such that IsNotExist(err) == true.

type Instruction 

type Instruction struct {
	// Code is the operation to execute.
	Code uint8

	// Dst and Src specify the destination and source registers
	// respectively.
	Dst, Src Register

	// Off specifies the signed 16 bit offset.
	Off int16

	// Imm specifies the signed 32 bit immediate. The interpretation of
	// the immediate varies from instruction to instruction.
	Imm int32
}

Instruction specifies a raw eBPF instruction.

Note that Instruction does not pack the destination and source registers into a single 8 bit field. Therefore, it is not suitable for passing into the Linux kernel or an eBPF virtual machine directly.

func (Instruction) Pack 

func (ri Instruction) Pack() uint64

Pack packs the Dst and Src fields into 4 bits each, and performs the final assembly of the instruction, producing a RawInstruction.

type InstructionClass 

type InstructionClass uint8

InstructionClass is an eBPF instruction class. 

const (
	LD InstructionClass = iota
	LDX
	ST
	STX
	ALU
	JMP

	ALU64
)

Instruction classes.

type InstructionWidth 

type InstructionWidth uint8

InstructionWidth is the width of a load or store instruction. 

const (
	W  InstructionWidth = iota << 3 // 32 bit
	H                               // 16 bit
	B                               // 8 bit
	DW                              // 64 bit
)

Instruction widths.

type JumpCondition 

type JumpCondition uint8

JumpCondition specifies a jump condition. 

const (
	JA JumpCondition = iota << 4
	JEQ
	JGT
	JGE
	JSET
	JNE  // eBPF only
	JSGT // eBPF only
	JSGE // eBPF only
	CALL // eBPF only
	EXIT // eBPF only
	JLT  // eBPF only
	JLE  // eBPF only
	JSLT // eBPF only
	JSLE // eBPF only
)

Valid jump conditions.

type KernelFunction 

type KernelFunction int32

KernelFunction is a function callable by eBPF programs from inside the kernel. 

const (
	KernelFunctionUnspec KernelFunction = iota // bpf_unspec

	MapLookupElem     // bpf_map_lookup_elem
	MapUpdateElem     // bpf_map_update_elem
	MapDeleteElem     // bpf_map_delete_elem
	ProbeRead         // bpf_probe_read
	KTimeGetNS        // bpf_ktime_get_ns
	TracePrintk       // bpf_trace_printk
	GetPrandomU32     // bpf_get_prandom_u32
	GetSMPProcessorID // bpf_get_smp_processor_id
	SKBStoreBytes     // bpf_skb_store_bytes
	L3CSumReplace     // bpf_l3_csum_replace
	L4CSumReplace     // bpf_l4_csum_replace
	TailCall          // bpf_tail_call
	CloneRedirect     // bpf_clone_redirect

)

Kernel functions.

type MapOpError 

type MapOpError struct {
	Op  string
	Err error
}

MapOpError records an error caused by a map operation.

Op is the high level operation performed.

In some cases, Err is of type SyscallError.

func (*MapOpError) Cause 

func (e *MapOpError) Cause() error

Cause returns e.Err's cause, if any, or e.Err itself otherwise.

func (*MapOpError) Error 

func (e *MapOpError) Error() string

type Prog 

type Prog struct {
	Type               ProgType
	Instructions       []RawInstruction
	License            string
	LogLevel           uint32
	LogBuffer          []byte
	KernelVersion      uint32
	Flags              uint32
	ObjectName         string
	IfIndex            uint32
	ExpectedAttachType uint32
	// contains filtered or unexported fields
}

Prog configures an eBPF program.

func (*Prog) Load 

func (p *Prog) Load() error

Load loads the program into the kernel.

func (*Prog) Unload 

func (p *Prog) Unload() error

Unload unloads the program from the kernel and releases the associated file descriptor.

type ProgType 

type ProgType uint32

ProgType is the type of an eBPF program. 

const (
	ProgTypeUnspec ProgType = iota
	ProgTypeSocketFilter
	ProgTypeKProbe
	ProgTypeSchedCLS
	ProgTypeSchedACT
	ProgTypeTracepoint
	ProgTypeXDP
	ProgTypePerfEvent
	ProgTypeCGroupSKB
	ProgTypeCGroupSock
	ProgTypeLWTIn
	ProgTypeLWTOut
	ProgTypeLWTXMit
	ProgTypeSockOps
	ProgTypeSKSKB
	ProgTypeCGroupDevice
	ProgTypeSKMsg
	ProgTypeRawTracepoint
	ProgTypeCGroupSockAddr
	ProgTypeLWTSeg6Local
	ProgTypeLIRCMode2
	ProgTypeSKReusePort
)

Valid eBPF program types.

type RawInstruction 

type RawInstruction struct {
	Code uint8
	Regs uint8
	Off  int16
	Imm  int32
}

RawInstruction is an assembled eBPF instruction.

type Register 

type Register uint8

Register is an eBPF register. 

const (
	R0 Register = iota
	R1
	R2
	R3
	R4
	R5
	R6
	R7
	R8
	R9
	R10
	FP = R10

	// PseudoMapFD is used to specify a map file descriptor
	// for loading, in a 64-bit immediate load instruction.
	PseudoMapFD Register = 1

	// PseudoCall is used to specify a kernel function to call,
	// in a call instruction.
	PseudoCall Register = 1
)

Valid eBPF registers.

When calling kernel functions, R0 holds the return value, R1 - R5 are destroyed and set to unreadable, and R6 - R9 are preserved (callee-saved). R10 or FP is the read-only frame pointer.

type SyscallError 

type SyscallError struct {
	Cmd string
	Err error
}

SyscallError records an error from a bpf(2) system call.

Cmd is a string describing the bpf command executed, e.g. "BPF_CREATE_MAP".

Err is the underlying error, of type syscall.Errno.

func (*SyscallError) Cause 

func (e *SyscallError) Cause() error

Cause returns the cause of the error: e.Err.

func (*SyscallError) Error 

func (e *SyscallError) Error() string

Notes

Bugs

  • all of this is very poorly documented

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.