package btf

import "github.com/cilium/ebpf/internal/btf"

Package btf handles data encoded according to the BPF Type Format.

The canonical documentation lives in the Linux kernel repository and is available at https://www.kernel.org/doc/html/latest/bpf/btf.html

The API is very much unstable. You should only use this via the main ebpf library.

Index ¶

• Variables
• func ProgramAppend(s, other *Program) error
• func ProgramFuncInfos(s *Program) (recordSize uint32, bytes []byte, err error)
• func ProgramLineInfos(s *Program) (recordSize uint32, bytes []byte, err error)
• func Sizeof(typ Type) (int, error)
• type Array
• func (arr *Array) String() string
• type COREFixup
• func (f COREFixup) String() string
• type COREFixups
• func ProgramFixups(s *Program, target *Spec) (COREFixups, error)
• func (fs COREFixups) Apply(insns asm.Instructions) (asm.Instructions, error)
• type COREKind
• func (k COREKind) String() string
• type Const
• func (c *Const) String() string
• type Datasec
• func (ds *Datasec) String() string
• type Enum
• func (e *Enum) String() string
• type EnumValue
• type Func
• func (f *Func) String() string
• type FuncLinkage
• func (i FuncLinkage) String() string
• type FuncParam
• type FuncProto
• func (fp *FuncProto) String() string
• type Fwd
• func (f *Fwd) String() string
• type FwdKind
• func (fk FwdKind) String() string
• type Handle
• func NewHandle(spec *Spec) (*Handle, error)
• func (h *Handle) Close() error
• func (h *Handle) FD() int
• type Int
• func (i *Int) String() string
• type IntEncoding
• type Map
• func NewMap(spec *Spec, key Type, value Type) Map
• type Member
• type Name
• type Pointer
• func (p *Pointer) String() string
• type Program
• type Restrict
• func (r *Restrict) String() string
• type Spec
• func LoadKernelSpec() (*Spec, error)
• func LoadSpecFromReader(rd io.ReaderAt) (*Spec, error)
• func MapSpec(m *Map) *Spec
• func ProgramSpec(s *Program) *Spec
• func (s *Spec) Datasec(name string) (*Map, error)
• func (s *Spec) FindType(name string, typ Type) error
• func (s *Spec) Program(name string, length uint64) (*Program, error)
• type Struct
• func (s *Struct) String() string
• type Type
• func MapKey(m *Map) Type
• func MapValue(m *Map) Type
• type TypeID
• func (tid TypeID) ID() TypeID
• type Typedef
• func (td *Typedef) String() string
• type Union
• func (u *Union) String() string
• type Var
• func (v *Var) String() string
• type VarLinkage
• func (i VarLinkage) String() string
• type VarSecinfo
• type Void
• func (v *Void) ID() TypeID
• func (v *Void) String() string
• type Volatile
• func (v *Volatile) String() string

Examples ¶

• Spec.FindType
• Type (ValidTypes)

Variables ¶

var (
	ErrNotSupported   = internal.ErrNotSupported
	ErrNotFound       = errors.New("not found")
	ErrNoExtendedInfo = errors.New("no extended info")
)

Errors returned by BTF functions.

Functions ¶

func ProgramAppend ¶

func ProgramAppend(s, other *Program) error

ProgramAppend the information from other to the Program.

This is a free function instead of a method to hide it from users of package ebpf.

func ProgramFuncInfos ¶

func ProgramFuncInfos(s *Program) (recordSize uint32, bytes []byte, err error)

ProgramFuncInfos returns the binary form of BTF function infos.

This is a free function instead of a method to hide it from users of package ebpf.

func ProgramLineInfos ¶

func ProgramLineInfos(s *Program) (recordSize uint32, bytes []byte, err error)

ProgramLineInfos returns the binary form of BTF line infos.

This is a free function instead of a method to hide it from users of package ebpf.

func Sizeof ¶

func Sizeof(typ Type) (int, error)

Sizeof returns the size of a type in bytes.

Returns an error if the size can't be computed.

Types ¶

type Array ¶

type Array struct {
	TypeID
	Type   Type
	Nelems uint32
}

Array is an array with a fixed number of elements.

func (*Array) String ¶

func (arr *Array) String() string

type COREFixup ¶

type COREFixup struct {
	Kind   COREKind
	Local  uint32
	Target uint32
	Poison bool
}

COREFixup is the result of computing a CO-RE relocation for a target.

func (COREFixup) String ¶

func (f COREFixup) String() string

type COREFixups ¶

type COREFixups map[uint64]COREFixup

func ProgramFixups ¶

func ProgramFixups(s *Program, target *Spec) (COREFixups, error)

ProgramFixups returns the changes required to adjust the program to the target.

This is a free function instead of a method to hide it from users of package ebpf.

func (COREFixups) Apply ¶

func (fs COREFixups) Apply(insns asm.Instructions) (asm.Instructions, error)

Apply a set of CO-RE relocations to a BPF program.

type COREKind ¶

type COREKind uint32

COREKind is the type of CO-RE relocation

func (COREKind) String ¶

func (k COREKind) String() string

type Const ¶

type Const struct {
	TypeID
	Type Type
}

Const is a qualifier.

func (*Const) String ¶

func (c *Const) String() string

type Datasec ¶

type Datasec struct {
	TypeID
	Name
	Size uint32
	Vars []VarSecinfo
}

Datasec is a global program section containing data.

func (*Datasec) String ¶

func (ds *Datasec) String() string

type Enum ¶

type Enum struct {
	TypeID
	Name
	Values []EnumValue
}

Enum lists possible values.

func (*Enum) String ¶

func (e *Enum) String() string

type EnumValue ¶

type EnumValue struct {
	Name
	Value int32
}

EnumValue is part of an Enum

Is is not a valid Type

type Func ¶

type Func struct {
	TypeID
	Name
	Type    Type
	Linkage FuncLinkage
}

Func is a function definition.

func (*Func) String ¶

func (f *Func) String() string

type FuncLinkage ¶

type FuncLinkage int

FuncLinkage describes BTF function linkage metadata.

const (
	StaticFunc FuncLinkage = iota // static
	GlobalFunc                    // global
	ExternFunc                    // extern
)

Equivalent of enum btf_func_linkage.

func (FuncLinkage) String ¶

func (i FuncLinkage) String() string

type FuncParam ¶

type FuncParam struct {
	Name
	Type Type
}

type FuncProto ¶

type FuncProto struct {
	TypeID
	Return Type
	Params []FuncParam
}

FuncProto is a function declaration.

func (*FuncProto) String ¶

func (fp *FuncProto) String() string

type Fwd ¶

type Fwd struct {
	TypeID
	Name
	Kind FwdKind
}

Fwd is a forward declaration of a Type.

func (*Fwd) String ¶

func (f *Fwd) String() string

type FwdKind ¶

type FwdKind int

FwdKind is the type of forward declaration.

const (
	FwdStruct FwdKind = iota
	FwdUnion
)

Valid types of forward declaration.

func (FwdKind) String ¶

func (fk FwdKind) String() string

type Handle ¶

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

Handle is a reference to BTF loaded into the kernel.

func NewHandle ¶

func NewHandle(spec *Spec) (*Handle, error)

NewHandle loads BTF into the kernel.

Returns ErrNotSupported if BTF is not supported.

func (*Handle) Close ¶

func (h *Handle) Close() error

Close destroys the handle.

Subsequent calls to FD will return an invalid value.

func (*Handle) FD ¶

func (h *Handle) FD() int

FD returns the file descriptor for the handle.

type Int ¶

type Int struct {
	TypeID
	Name

	// The size of the integer in bytes.
	Size     uint32
	Encoding IntEncoding
	// Offset is the starting bit offset. Currently always 0.
	// See https://www.kernel.org/doc/html/latest/bpf/btf.html#btf-kind-int
	Offset uint32
	Bits   byte
}

Int is an integer of a given length.

func (*Int) String ¶

func (i *Int) String() string

type IntEncoding ¶

type IntEncoding byte

const (
	Signed IntEncoding = 1 << iota
	Char
	Bool
)

type Map ¶

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

Map is the BTF for a map.

func NewMap ¶

func NewMap(spec *Spec, key Type, value Type) Map

NewMap returns a new Map containing the given values. The key and value arguments are initialized to Void if nil values are given.

type Member ¶

type Member struct {
	Name
	Type Type
	// Offset is the bit offset of this member
	Offset       uint32
	BitfieldSize uint32
}

Member is part of a Struct or Union.

It is not a valid Type.

type Name ¶

type Name string

Name identifies a type.

Anonymous types have an empty name.

type Pointer ¶

type Pointer struct {
	TypeID
	Target Type
}

Pointer is a pointer to another type.

func (*Pointer) String ¶

func (p *Pointer) String() string

type Program ¶

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

Program is the BTF information for a stream of instructions.

type Restrict ¶

type Restrict struct {
	TypeID
	Type Type
}

Restrict is a qualifier.

func (*Restrict) String ¶

func (r *Restrict) String() string

type Spec ¶

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

Spec represents decoded BTF.

func LoadKernelSpec ¶

func LoadKernelSpec() (*Spec, error)

LoadKernelSpec returns the current kernel's BTF information.

Requires a >= 5.5 kernel with CONFIG_DEBUG_INFO_BTF enabled. Returns ErrNotSupported if BTF is not enabled.

func LoadSpecFromReader ¶

func LoadSpecFromReader(rd io.ReaderAt) (*Spec, error)

LoadSpecFromReader reads BTF sections from an ELF.

Returns ErrNotFound if the reader contains no BTF.

func MapSpec ¶

func MapSpec(m *Map) *Spec

MapSpec should be a method on Map, but is a free function to hide it from users of the ebpf package.

func ProgramSpec ¶

func ProgramSpec(s *Program) *Spec

ProgramSpec returns the Spec needed for loading function and line infos into the kernel.

This is a free function instead of a method to hide it from users of package ebpf.

func (*Spec) Datasec ¶

func (s *Spec) Datasec(name string) (*Map, error)

Datasec returns the BTF required to create maps which represent data sections.

func (*Spec) FindType ¶

func (s *Spec) FindType(name string, typ Type) error

FindType searches for a type with a specific name.

hint determines the type of the returned Type.

Returns an error wrapping ErrNotFound if no matching type exists in spec.

{
	// Acquire a Spec via one of its constructors.
	spec := new(Spec)

	// Declare a variable of the desired type
	var foo Struct

	if err := spec.FindType("foo", &foo); err != nil {
		// There is no struct with name foo, or there
		// are multiple possibilities.
	}

	// We've found struct foo
	fmt.Println(foo.Name)
}

func (*Spec) Program ¶

func (s *Spec) Program(name string, length uint64) (*Program, error)

Program finds the BTF for a specific section.

Length is the number of bytes in the raw BPF instruction stream.

Returns an error which may wrap ErrNoExtendedInfo if the Spec doesn't contain extended BTF info.

type Struct ¶

type Struct struct {
	TypeID
	Name
	// The size of the struct including padding, in bytes
	Size    uint32
	Members []Member
}

Struct is a compound type of consecutive members.

func (*Struct) String ¶

func (s *Struct) String() string

type Type ¶

type Type interface {
	ID() TypeID

	String() string
	// contains filtered or unexported methods
}

Type represents a type described by BTF.

{
	var _ Type = &Void{}
	var _ Type = &Int{}
	var _ Type = &Pointer{}
	var _ Type = &Array{}
	var _ Type = &Struct{}
	var _ Type = &Union{}
	var _ Type = &Enum{}
	var _ Type = &Fwd{}
	var _ Type = &Typedef{}
	var _ Type = &Volatile{}
	var _ Type = &Const{}
	var _ Type = &Restrict{}
	var _ Type = &Func{}
	var _ Type = &FuncProto{}
	var _ Type = &Var{}
	var _ Type = &Datasec{}
}

func MapKey ¶

func MapKey(m *Map) Type

MapKey should be a method on Map, but is a free function to hide it from users of the ebpf package.

func MapValue ¶

func MapValue(m *Map) Type

MapValue should be a method on Map, but is a free function to hide it from users of the ebpf package.

type TypeID ¶

type TypeID uint32

TypeID identifies a type in a BTF section.

func (TypeID) ID ¶

func (tid TypeID) ID() TypeID

ID implements part of the Type interface.

type Typedef ¶

type Typedef struct {
	TypeID
	Name
	Type Type
}

Typedef is an alias of a Type.

func (*Typedef) String ¶

func (td *Typedef) String() string

type Union ¶

type Union struct {
	TypeID
	Name
	// The size of the union including padding, in bytes.
	Size    uint32
	Members []Member
}

Union is a compound type where members occupy the same memory.

func (*Union) String ¶

func (u *Union) String() string

type Var ¶

type Var struct {
	TypeID
	Name
	Type    Type
	Linkage VarLinkage
}

Var is a global variable.

func (*Var) String ¶

func (v *Var) String() string

type VarLinkage ¶

type VarLinkage int

VarLinkage describes BTF variable linkage metadata.

const (
	StaticVar VarLinkage = iota // static
	GlobalVar                   // global
	ExternVar                   // extern
)

func (VarLinkage) String ¶

func (i VarLinkage) String() string

type VarSecinfo ¶

type VarSecinfo struct {
	Type   Type
	Offset uint32
	Size   uint32
}

VarSecinfo describes variable in a Datasec

It is not a valid Type.

type Void ¶

type Void struct{}

Void is the unit type of BTF.

func (*Void) ID ¶

func (v *Void) ID() TypeID

func (*Void) String ¶

func (v *Void) String() string

type Volatile ¶

type Volatile struct {
	TypeID
	Type Type
}

Volatile is a qualifier.

func (*Volatile) String ¶

func (v *Volatile) String() string

Source Files ¶

btf.go btf_types.go btf_types_string.go core.go doc.go ext_info.go strings.go types.go