package btf

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

Errors returned by BTF functions.

Functions ¶

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

func (*Array) TypeName ¶

func (arr *Array) TypeName() 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 (COREFixups) Apply ¶

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

Apply returns a copy of insns with CO-RE relocations applied.

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

func (*Const) TypeName ¶

func (c *Const) TypeName() string

type CoreRelo ¶

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

type CoreRelos ¶

type CoreRelos []CoreRelo

type Datasec ¶

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

Datasec is a global program section containing data.

func (*Datasec) String ¶

func (ds *Datasec) String() string

func (*Datasec) TypeName ¶

func (ds *Datasec) TypeName() string

type Enum ¶

type Enum struct {
	TypeID
	Name   string
	Values []EnumValue
}

Enum lists possible values.

func (*Enum) String ¶

func (e *Enum) String() string

func (*Enum) TypeName ¶

func (e *Enum) TypeName() string

type EnumValue ¶

type EnumValue struct {
	Name  string
	Value int32
}

EnumValue is part of an Enum

Is is not a valid Type

type Float ¶

type Float struct {
	TypeID
	Name string

	// The size of the float in bytes.
	Size uint32
}

Float is a float of a given length.

func (*Float) String ¶

func (f *Float) String() string

func (*Float) TypeName ¶

func (f *Float) TypeName() string

type Func ¶

type Func struct {
	TypeID
	Name    string
	Type    Type
	Linkage FuncLinkage
}

Func is a function definition.

func (*Func) String ¶

func (f *Func) String() string

func (*Func) TypeName ¶

func (f *Func) TypeName() string

type FuncInfo ¶

type FuncInfo struct {
	// Instruction offset of the function within an ELF section.
	// Always zero after parsing a funcinfo from an ELF, instruction streams
	// are split on function boundaries.
	InsnOff uint32
	TypeID  TypeID
}

FuncInfo represents the location and type ID of a function in a BPF ELF.

func (FuncInfo) Marshal ¶

func (fi FuncInfo) Marshal(w io.Writer, offset uint64) error

Marshal writes the binary representation of the FuncInfo to w. The function offset is converted from bytes to instructions.

func (FuncInfo) Name ¶

func (fi FuncInfo) Name(spec *Spec) (string, error)

Name looks up the FuncInfo's corresponding function name in the given spec.

type FuncInfos ¶

type FuncInfos []FuncInfo

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 string
	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

func (*FuncProto) TypeName ¶

func (fp *FuncProto) TypeName() string

type Fwd ¶

type Fwd struct {
	TypeID
	Name string
	Kind FwdKind
}

Fwd is a forward declaration of a Type.

func (*Fwd) String ¶

func (f *Fwd) String() string

func (*Fwd) TypeName ¶

func (f *Fwd) TypeName() 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 GoFormatter ¶

type GoFormatter struct {

	// Types present in this map are referred to using the given name if they
	// are encountered when outputting another type.
	Names map[Type]string

	// Identifier is called for each field of struct-like types. By default the
	// field name is used as is.
	Identifier func(string) string

	// EnumIdentifier is called for each element of an enum. By default the
	// name of the enum type is concatenated with Identifier(element).
	EnumIdentifier func(name, element string) string
	// contains filtered or unexported fields
}

GoFormatter converts a Type to Go syntax.

A zero GoFormatter is valid to use.

func (*GoFormatter) TypeDeclaration ¶

func (gf *GoFormatter) TypeDeclaration(name string, typ Type) (string, error)

TypeDeclaration generates a Go type declaration for a BTF 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 NewHandleFromID ¶

func NewHandleFromID(id ID) (*Handle, error)

NewHandleFromID returns the BTF handle for a given id.

Returns ErrNotExist, if there is no BTF with the given id.

Requires CAP_SYS_ADMIN.

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.

func (*Handle) Spec ¶

func (h *Handle) Spec() *Spec

Spec returns the Spec that defined the BTF loaded into the kernel.

type ID ¶

type ID uint32

ID represents the unique ID of a BTF object.

type Int ¶

type Int struct {
	TypeID

	Name string

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

Int is an integer of a given length.

func (*Int) String ¶

func (i *Int) String() string

func (*Int) TypeName ¶

func (i *Int) TypeName() string

type IntEncoding ¶

type IntEncoding byte

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

func (IntEncoding) IsBool ¶

func (ie IntEncoding) IsBool() bool

func (IntEncoding) IsChar ¶

func (ie IntEncoding) IsChar() bool

func (IntEncoding) IsSigned ¶

func (ie IntEncoding) IsSigned() bool

type LineInfo ¶

type LineInfo struct {
	// Instruction offset of the function within an ELF section.
	// After parsing a LineInfo from an ELF, this offset is relative to
	// the function body instead of an ELF section.
	InsnOff     uint32
	FileNameOff uint32
	LineOff     uint32
	LineCol     uint32
}

LineInfo represents the location and contents of a single line of source code a BPF ELF was compiled from.

func (LineInfo) Marshal ¶

func (li LineInfo) Marshal(w io.Writer, offset uint64) error

Marshal writes the binary representation of the LineInfo to w. The instruction offset is converted from bytes to instructions.

type LineInfos ¶

type LineInfos []LineInfo

func (LineInfos) Marshal ¶

func (li LineInfos) Marshal(w io.Writer, off uint64) error

Marshal writes the binary representation of the LineInfos to w.

type Map ¶

type Map struct {
	Spec       *Spec
	Key, Value Type
}

Map is the BTF for a map.

type Member ¶

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

Member is part of a Struct or Union.

It is not a valid Type.

type Pointer ¶

type Pointer struct {
	TypeID
	Target Type
}

Pointer is a pointer to another type.

func (*Pointer) String ¶

func (p *Pointer) String() string

func (*Pointer) TypeName ¶

func (p *Pointer) TypeName() string

type Program ¶

type Program struct {
	FuncInfo  FuncInfo
	LineInfos LineInfos
	CoreRelos CoreRelos
	// contains filtered or unexported fields
}

Program is the BTF information for a stream of instructions.

func (*Program) Fixups ¶

func (p *Program) Fixups(target *Spec) (COREFixups, error)

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

Passing a nil target will relocate against the running kernel.

func (*Program) Spec ¶

func (p *Program) Spec() *Spec

Spec returns the BTF spec of this program.

type Restrict ¶

type Restrict struct {
	TypeID
	Type Type
}

Restrict is a qualifier.

func (*Restrict) String ¶

func (r *Restrict) String() string

func (*Restrict) TypeName ¶

func (r *Restrict) TypeName() 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 from an ELF or a raw BTF blob.

Returns ErrNotFound if reading from an ELF which contains no BTF.

func (*Spec) AnyTypesByName ¶

func (s *Spec) AnyTypesByName(name string) ([]Type, error)

AnyTypesByName returns a list of BTF Types with the given name.

If the BTF blob describes multiple compilation units like vmlinux, multiple Types with the same name and kind can exist, but might not describe the same data structure.

Returns an error wrapping ErrNotFound if no matching Type exists in the Spec.

func (*Spec) Copy ¶

func (s *Spec) Copy() *Spec

Copy creates a copy of Spec.

func (*Spec) Program ¶

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

Program finds the BTF for a specific function.

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

func (*Spec) TypeByID ¶

func (s *Spec) TypeByID(id TypeID) (Type, error)

TypeByID returns the BTF Type with the given type ID.

Returns an error wrapping ErrNotFound if a Type with the given ID does not exist in the Spec.

func (*Spec) TypeByName ¶

func (s *Spec) TypeByName(name string, typ interface{}) error

TypeByName searches for a Type with a specific name. Since multiple Types with the same name can exist, the parameter typ is taken to narrow down the search in case of a clash.

typ must be a non-nil pointer to an implementation of a Type. On success, the address of the found Type will be copied to typ.

Returns an error wrapping ErrNotFound if no matching Type exists in the Spec. If multiple candidates are found, an error is returned.

Example¶

Code:

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

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

	if err := spec.TypeByName("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)
}

type Struct ¶

type Struct struct {
	TypeID
	Name string
	// 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

func (*Struct) TypeName ¶

func (s *Struct) TypeName() string

type Type ¶

type Type interface {
	// The type ID of the Type within this BTF spec.
	ID() TypeID

	// Name of the type, empty for anonymous types and types that cannot
	// carry a name, like Void and Pointer.
	TypeName() string

	String() string
	// 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.

Code:

{
	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 Copy ¶

func Copy(typ Type) Type

Copy a Type recursively.

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 string
	Type Type
}

Typedef is an alias of a Type.

func (*Typedef) String ¶

func (td *Typedef) String() string

func (*Typedef) TypeName ¶

func (td *Typedef) TypeName() string

type Union ¶

type Union struct {
	TypeID
	Name string
	// 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

func (*Union) TypeName ¶

func (u *Union) TypeName() string

type Var ¶

type Var struct {
	TypeID
	Name    string
	Type    Type
	Linkage VarLinkage
}

Var is a global variable.

func (*Var) String ¶

func (v *Var) String() string

func (*Var) TypeName ¶

func (v *Var) TypeName() 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

func (*Void) TypeName ¶

func (v *Void) TypeName() string

type Volatile ¶

type Volatile struct {
	TypeID
	Type Type
}

Volatile is a qualifier.

func (*Volatile) String ¶

func (v *Volatile) String() string

func (*Volatile) TypeName ¶

func (v *Volatile) TypeName() string

Source Files ¶

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

Version: v0.8.0
Published: Jan 21, 2022
Platform: js/wasm
Imports: 17 packages
Last checked: now –

Tools for package owners.

?	: This menu
/	: Search site
f	: Jump to identifier
g then g	: Go to top of page
g then b	: Go to end of page
G	: Go to end of page
g then i	: Go to index
g then e	: Go to examples