btf

Documentation

Overview

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
• type Const
• type Datasec
• type Enum
• type Func
• type FuncProto
• type Fwd
• type Handle
  • func NewHandle(spec *Spec) (*Handle, error)
  • func (h *Handle) Close() error
  • func (h *Handle) FD() int
• type Int
• type Map
• type Member
• type Name
• type Pointer
• type Program
• type Restrict
• type Spec
  • 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) Map(name string) (*Map, []Member, error)
  • func (s *Spec) Program(name string, length uint64) (*Program, error)
• type Struct
• type Type
  • func MapKey(m *Map) Type
  • func MapValue(m *Map) Type
• type TypeID
  • func (tid TypeID) ID() TypeID
• type Typedef
• type Union
• type Var
• type VarSecinfo
• type Void
  • func (v Void) ID() TypeID
• type Volatile

Examples

• Spec.FindType
• Type (ValidTypes)

Variables

var (
	ErrNotSupported = internal.ErrNotSupported
)

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.

type Const

type Const struct {
	TypeID
	Type Type
}

Const is a modifier.

type Datasec

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

Datasec is a global program section containing data.

type Enum

type Enum struct {
	TypeID
	Name
}

Enum lists possible values.

type Func

type Func struct {
	TypeID
	Name
	Type Type
}

Func is a function definition.

type FuncProto

type FuncProto struct {
	TypeID
	Return Type
}

FuncProto is a function declaration.

type Fwd

type Fwd struct {
	TypeID
	Name
}

Fwd is a forward declaration of a Type.

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
}

Int is an integer of a given length.

type Map

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

Map is the BTF for a map.

type Member

type Member struct {
	Name
	Type   Type
	Offset 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.

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 modifier.

type Spec

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

Spec represents decoded BTF.

func LoadSpecFromReader

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

LoadSpecFromReader reads BTF sections from an ELF.

Returns a nil Spec and no error if no BTF was present.

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 if there is no or multiple matches.

Example

// 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) Map

func (s *Spec) Map(name string) (*Map, []Member, error)

Map finds the BTF for a map.

Returns an error if there is no BTF for the given 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 if there is no BTF.

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.

type Type

type Type interface {
	ID() TypeID
	// contains filtered or unexported methods
}

Type represents a type described by BTF.

Example (ValidTypes)

The following are valid Types.

There currently is no better way to document which types implement an interface.

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

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.

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.

type Var

type Var struct {
	TypeID
	Name
	Type Type
}

Var is a global variable.

type VarSecinfo

type VarSecinfo struct {
	Type   Type
	Offset uint32
	Size   uint32
}

VarSecinfo describes variable in a Datasec

type Void

type Void struct{}

Void is the unit type of BTF.

func (Void) ID

func (v Void) ID() TypeID

type Volatile

type Volatile struct {
	TypeID
	Type Type
}

Volatile is a modifier.