btf

package
v0.0.0-...-14c22a9 Latest Latest
Warning

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

 Go to latest Published: May 10, 2022 License: MIT Imports: 18 Imported by: 1

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

Constants

This section is empty.

Variables

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

Errors returned by BTF functions.

View Source 
var FuncInfoSize = uint32(binary.Size(bpfFuncInfo{}))

The size of a FuncInfo in BTF wire format.

View Source 
var LineInfoSize = uint32(binary.Size(bpfLineInfo{}))

Functions

func LoadSpecAndExtInfosFromReader 

func LoadSpecAndExtInfosFromReader(rd io.ReaderAt) (*Spec, *ExtInfos, error)

LoadSpecAndExtInfosFromReader reads from an ELF.

ExtInfos may be nil if the ELF doesn't contain section metadta. Returns ErrNotFound if the ELF contains no BTF.

func MarshalExtInfos 

func MarshalExtInfos(insns asm.Instructions, typeID func(Type) (TypeID, error)) (funcInfos, lineInfos []byte, _ error)

MarshalExtInfos encodes function and line info embedded in insns into kernel wire format.

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 {
	Type   Type
	Nelems uint32
}

Array is an array with a fixed number of elements.

func (*Array) Format 

func (arr *Array) Format(fs fmt.State, verb rune)

func (*Array) TypeName 

func (arr *Array) TypeName() string

type COREFixup 

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

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

func CORERelocate 

func CORERelocate(local, target *Spec, relos []*CORERelocation) ([]COREFixup, error)

CORERelocate calculates the difference in types between local and target.

Returns a list of fixups which can be applied to instructions to make them match the target type(s).

Fixups are returned in the order of relos, e.g. fixup[i] is the solution for relos[i].

func (*COREFixup) Apply 

func (f *COREFixup) Apply(ins *asm.Instruction) error

func (*COREFixup) String 

func (f *COREFixup) String() string

type CORERelocation 

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

func CORERelocationMetadata 

func CORERelocationMetadata(ins *asm.Instruction) *CORERelocation

type Const 

type Const struct {
	Type Type
}

Const is a qualifier.

func (*Const) Format 

func (c *Const) Format(fs fmt.State, verb rune)

func (*Const) TypeName 

func (c *Const) TypeName() string

type Datasec 

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

Datasec is a global program section containing data.

func (*Datasec) Format 

func (ds *Datasec) Format(fs fmt.State, verb rune)

func (*Datasec) TypeName 

func (ds *Datasec) TypeName() string

type Enum 

type Enum struct {
	Name   string
	Values []EnumValue
}

Enum lists possible values.

func (*Enum) Format 

func (e *Enum) Format(fs fmt.State, verb rune)

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 ExtInfos 

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

ExtInfos contains ELF section metadata.

func (*ExtInfos) Assign 

func (ei *ExtInfos) Assign(insns asm.Instructions, section string)

Assign per-section metadata from BTF to a section's instructions.

type Float 

type Float struct {
	Name string

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

Float is a float of a given length.

func (*Float) Format 

func (f *Float) Format(fs fmt.State, verb rune)

func (*Float) TypeName 

func (f *Float) TypeName() string

type Func 

type Func struct {
	Name    string
	Type    Type
	Linkage FuncLinkage
}

Func is a function definition.

func FuncMetadata 

func FuncMetadata(ins *asm.Instruction) *Func

func (*Func) Format 

func (f *Func) Format(fs fmt.State, verb rune)

func (*Func) TypeName 

func (f *Func) TypeName() 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 string
	Type Type
}

type FuncProto 

type FuncProto struct {
	Return Type
	Params []FuncParam
}

FuncProto is a function declaration.

func (*FuncProto) Format 

func (fp *FuncProto) Format(fs fmt.State, verb rune)

func (*FuncProto) TypeName 

func (fp *FuncProto) TypeName() string

type Fwd 

type Fwd struct {
	Name string
	Kind FwdKind
}

Fwd is a forward declaration of a Type.

func (*Fwd) Format 

func (f *Fwd) Format(fs fmt.State, verb rune)

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 {
	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) Format 

func (i *Int) Format(fs fmt.State, verb rune)

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

func (IntEncoding) String 

func (ie IntEncoding) String() string

type Line 

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

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

func (*Line) FileName 

func (li *Line) FileName() string

func (*Line) Line 

func (li *Line) Line() string

func (*Line) LineColumn 

func (li *Line) LineColumn() uint32

func (*Line) LineNumber 

func (li *Line) LineNumber() uint32

func (*Line) String 

func (li *Line) String() string

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 {
	Target Type
}

Pointer is a pointer to another type.

func (*Pointer) Format 

func (p *Pointer) Format(fs fmt.State, verb rune)

func (*Pointer) TypeName 

func (p *Pointer) TypeName() string

type Restrict 

type Restrict struct {
	Type Type
}

Restrict is a qualifier.

func (*Restrict) Format 

func (r *Restrict) Format(fs fmt.State, verb rune)

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 LoadKernelSpecWithoutCache 

func LoadKernelSpecWithoutCache() (*Spec, error)

LoadKernelSpecWithoutCache attempts to load the raw vmlinux BTF blob at /sys/kernel/btf/vmlinux and falls back to scanning the file system for vmlinux ELFs.

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. ExtInfos may be nil.

func (*Spec) AnyTypeByName 

func (s *Spec) AnyTypeByName(name string) (Type, error)

AnyTypeByName returns a Type with the given name.

Returns an error if multiple types of that name exist.

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

func (*Spec) TypeID 

func (s *Spec) TypeID(typ Type) (TypeID, error)

TypeID returns the ID for a given Type.

Returns an error wrapping ErrNoFound if the type isn't part of the Spec.

type Struct 

type Struct struct {
	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) Format 

func (s *Struct) Format(fs fmt.State, verb rune)

func (*Struct) TypeName 

func (s *Struct) TypeName() string

type Transformer 

type Transformer func(Type) Type

Transformer modifies a given Type and returns the result.

For example, UnderlyingType removes any qualifiers or typedefs from a type. See the example on Copy for how to use a transform.

type Type 

type Type interface {
	// Type can be formatted using the %s and %v verbs. %s outputs only the
	// identity of the type, without any detail. %v outputs additional detail.
	//
	// Use the '+' flag to include the address of the type.
	//
	// Use the width to specify how many levels of detail to output, for example
	// %1v will output detail for the root type and a short description of its
	// children. %2v would output details of the root type and its children
	// as well as a short description of the grandchildren.
	fmt.Formatter

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

Type represents a type described by BTF.

func Copy 

func Copy(typ Type, transform Transformer) Type

Copy a Type recursively.

typ may form a cycle. If transform is not nil, it is called with the to be copied type, and the returned value is copied instead.

func UnderlyingType 

func UnderlyingType(typ Type) Type

UnderlyingType skips qualifiers and Typedefs.

type TypeID 

type TypeID uint32

TypeID identifies a type in a BTF section.

type Typedef 

type Typedef struct {
	Name string
	Type Type
}

Typedef is an alias of a Type.

func (*Typedef) Format 

func (td *Typedef) Format(fs fmt.State, verb rune)

func (*Typedef) TypeName 

func (td *Typedef) TypeName() string

type Union 

type Union struct {
	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) Format 

func (u *Union) Format(fs fmt.State, verb rune)

func (*Union) TypeName 

func (u *Union) TypeName() string

type Var 

type Var struct {
	Name    string
	Type    Type
	Linkage VarLinkage
}

Var is a global variable.

func (*Var) Format 

func (v *Var) Format(fs fmt.State, verb rune)

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) Format 

func (v *Void) Format(fs fmt.State, verb rune)

func (*Void) TypeName 

func (v *Void) TypeName() string

type Volatile 

type Volatile struct {
	Type Type
}

Volatile is a qualifier.

func (*Volatile) Format 

func (v *Volatile) Format(fs fmt.State, verb rune)

func (*Volatile) TypeName 

func (v *Volatile) TypeName() string

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.