Errors returned by BTF functions.
var (
ErrNotSupported = internal.ErrNotSupported
ErrNotFound = errors.New("not found")
ErrNoExtendedInfo = errors.New("no extended info")
)
The size of a FuncInfo in BTF wire format.
var FuncInfoSize = uint32(binary.Size(bpfFuncInfo{}))
var LineInfoSize = uint32(binary.Size(bpfLineInfo{}))
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(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(typ Type) (int, error)
Sizeof returns the size of a type in bytes.
Returns an error if the size can't be computed.
Array is an array with a fixed number of elements.
type Array struct {
Index Type
Type Type
Nelems uint32
}
func (arr *Array) Format(fs fmt.State, verb rune)
func (arr *Array) TypeName() string
A value in bits.
type Bits uint32
func (b Bits) Bytes() uint32
Bytes converts a bit value into bytes.
COREFixup is the result of computing a CO-RE relocation for a target.
type COREFixup struct {
// contains filtered or unexported fields
}
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 (f *COREFixup) Apply(ins *asm.Instruction) error
func (f *COREFixup) String() string
type CORERelocation struct {
// contains filtered or unexported fields
}
func CORERelocationMetadata(ins *asm.Instruction) *CORERelocation
Const is a qualifier.
type Const struct {
Type Type
}
func (c *Const) Format(fs fmt.State, verb rune)
func (c *Const) TypeName() string
Datasec is a global program section containing data.
type Datasec struct {
Name string
Size uint32
Vars []VarSecinfo
}
func (ds *Datasec) Format(fs fmt.State, verb rune)
func (ds *Datasec) TypeName() string
Enum lists possible values.
type Enum struct {
Name string
// Size of the enum value in bytes.
Size uint32
Values []EnumValue
}
func (e *Enum) Format(fs fmt.State, verb rune)
func (e *Enum) TypeName() string
EnumValue is part of an Enum
Is is not a valid Type
type EnumValue struct {
Name string
Value int32
}
ExtInfos contains ELF section metadata.
type ExtInfos struct {
// contains filtered or unexported fields
}
func (ei *ExtInfos) Assign(insns asm.Instructions, section string)
Assign per-section metadata from BTF to a section's instructions.
Float is a float of a given length.
type Float struct {
Name string
// The size of the float in bytes.
Size uint32
}
func (f *Float) Format(fs fmt.State, verb rune)
func (f *Float) TypeName() string
Func is a function definition.
type Func struct {
Name string
Type Type
Linkage FuncLinkage
}
func FuncMetadata(ins *asm.Instruction) *Func
func (f *Func) Format(fs fmt.State, verb rune)
func (f *Func) TypeName() string
FuncLinkage describes BTF function linkage metadata.
type FuncLinkage int
Equivalent of enum btf_func_linkage.
const (
StaticFunc FuncLinkage = iota // static
GlobalFunc // global
ExternFunc // extern
)
func (i FuncLinkage) String() string
type FuncParam struct {
Name string
Type Type
}
FuncProto is a function declaration.
type FuncProto struct {
Return Type
Params []FuncParam
}
func (fp *FuncProto) Format(fs fmt.State, verb rune)
func (fp *FuncProto) TypeName() string
Fwd is a forward declaration of a Type.
type Fwd struct {
Name string
Kind FwdKind
}
func (f *Fwd) Format(fs fmt.State, verb rune)
func (f *Fwd) TypeName() string
FwdKind is the type of forward declaration.
type FwdKind int
Valid types of forward declaration.
const (
FwdStruct FwdKind = iota
FwdUnion
)
func (fk FwdKind) String() string
GoFormatter converts a Type to Go syntax.
A zero GoFormatter is valid to use.
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
}
func (gf *GoFormatter) TypeDeclaration(name string, typ Type) (string, error)
TypeDeclaration generates a Go type declaration for a BTF type.
Handle is a reference to BTF loaded into the kernel.
type Handle struct {
// contains filtered or unexported fields
}
func NewHandle(spec *Spec) (*Handle, error)
NewHandle loads BTF into the kernel.
Returns ErrNotSupported if BTF is not supported.
func NewHandleFromID(id ID) (*Handle, error)
NewHandleFromID returns the BTF handle for a given id.
Prefer calling [ebpf.Program.Handle] or [ebpf.Map.Handle] if possible.
Returns ErrNotExist, if there is no BTF with the given id.
Requires CAP_SYS_ADMIN.
func (h *Handle) Close() error
Close destroys the handle.
Subsequent calls to FD will return an invalid value.
func (h *Handle) FD() int
FD returns the file descriptor for the handle.
func (h *Handle) Info() (*HandleInfo, error)
Info returns metadata about the handle.
func (h *Handle) Spec(base *Spec) (*Spec, error)
Spec parses the kernel BTF into Go types.
base is used to decode split BTF and may be nil.
HandleInfo describes a Handle.
type HandleInfo struct {
// ID of this handle in the kernel. The ID is only valid as long as the
// associated handle is kept alive.
ID ID
// Name is an identifying name for the BTF, currently only used by the
// kernel.
Name string
// IsKernel is true if the BTF originated with the kernel and not
// userspace.
IsKernel bool
// contains filtered or unexported fields
}
func (i *HandleInfo) IsModule() bool
IsModule returns true if the BTF is for a kernel module.
func (i *HandleInfo) IsVmlinux() bool
IsModule returns true if the BTF is for the kernel itself.
HandleIterator allows enumerating BTF blobs loaded into the kernel.
type HandleIterator struct {
// The ID of the last retrieved handle. Only valid after a call to Next.
ID ID
// contains filtered or unexported fields
}
▹ Example
func (it *HandleIterator) Err() error
Err returns an error if iteration failed for some reason.
func (it *HandleIterator) Next(handle **Handle) bool
Next retrieves a handle for the next BTF blob.
Handle.Close is called if *handle is non-nil to avoid leaking fds.
Returns true if another BTF blob was found. Call HandleIterator.Err after the function returns false.
ID represents the unique ID of a BTF object.
type ID = sys.BTFID
Int is an integer of a given length.
See https://www.kernel.org/doc/html/latest/bpf/btf.html#btf-kind-int
type Int struct {
Name string
// The size of the integer in bytes.
Size uint32
Encoding IntEncoding
}
func (i *Int) Format(fs fmt.State, verb rune)
func (i *Int) TypeName() string
type IntEncoding byte
const (
Signed IntEncoding = 1 << iota
Char
Bool
)
func (ie IntEncoding) IsBool() bool
func (ie IntEncoding) IsChar() bool
func (ie IntEncoding) IsSigned() bool
func (ie IntEncoding) String() string
Line represents the location and contents of a single line of source code a BPF ELF was compiled from.
type Line struct {
// contains filtered or unexported fields
}
func (li *Line) FileName() string
func (li *Line) Line() string
func (li *Line) LineColumn() uint32
func (li *Line) LineNumber() uint32
func (li *Line) String() string
Member is part of a Struct or Union.
It is not a valid Type.
type Member struct {
Name string
Type Type
Offset Bits
BitfieldSize Bits
}
Pointer is a pointer to another type.
type Pointer struct {
Target Type
}
func (p *Pointer) Format(fs fmt.State, verb rune)
func (p *Pointer) TypeName() string
Restrict is a qualifier.
type Restrict struct {
Type Type
}
func (r *Restrict) Format(fs fmt.State, verb rune)
func (r *Restrict) TypeName() string
Spec represents decoded BTF.
type Spec struct {
// contains filtered or unexported fields
}
func LoadKernelSpec() (*Spec, error)
LoadKernelSpec returns the current kernel's BTF information.
Defaults to /sys/kernel/btf/vmlinux and falls back to scanning the file system for vmlinux ELFs. Returns an error wrapping ErrNotSupported if BTF is not enabled.
func LoadSpec(file string) (*Spec, error)
LoadSpec opens file and calls LoadSpecFromReader on it.
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 LoadSplitSpecFromReader(r io.ReaderAt, base *Spec) (*Spec, error)
LoadSplitSpecFromReader loads split BTF from a reader.
Types from base are used to resolve references in the split BTF. The returned Spec only contains types from the split BTF, not from the base.
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 (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 (s *Spec) Copy() *Spec
Copy creates a copy of Spec.
func (s *Spec) Iterate() *TypesIterator
Iterate returns the types iterator.
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 (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
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.
Struct is a compound type of consecutive members.
type Struct struct {
Name string
// The size of the struct including padding, in bytes
Size uint32
Members []Member
}
func (s *Struct) Format(fs fmt.State, verb rune)
func (s *Struct) TypeName() string
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 Transformer func(Type) Type
Type represents a type described by BTF.
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
}
▹ Example (ValidTypes)
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.
▹ Example (StripQualifiers)
func UnderlyingType(typ Type) Type
UnderlyingType skips qualifiers and Typedefs.
TypeID identifies a type in a BTF section.
type TypeID uint32
Typedef is an alias of a Type.
type Typedef struct {
Name string
Type Type
}
func (td *Typedef) Format(fs fmt.State, verb rune)
func (td *Typedef) TypeName() string
TypesIterator iterates over types of a given spec.
type TypesIterator struct {
// The last visited type in the spec.
Type Type
// contains filtered or unexported fields
}
func (iter *TypesIterator) Next() bool
Next returns true as long as there are any remaining types.
Union is a compound type where members occupy the same memory.
type Union struct {
Name string
// The size of the union including padding, in bytes.
Size uint32
Members []Member
}
func (u *Union) Format(fs fmt.State, verb rune)
func (u *Union) TypeName() string
Var is a global variable.
type Var struct {
Name string
Type Type
Linkage VarLinkage
}
func (v *Var) Format(fs fmt.State, verb rune)
func (v *Var) TypeName() string
VarLinkage describes BTF variable linkage metadata.
type VarLinkage int
const (
StaticVar VarLinkage = iota // static
GlobalVar // global
ExternVar // extern
)
func (i VarLinkage) String() string
VarSecinfo describes variable in a Datasec.
It is not a valid Type.
type VarSecinfo struct {
Type Type
Offset uint32
Size uint32
}
Void is the unit type of BTF.
type Void struct{}
func (v *Void) Format(fs fmt.State, verb rune)
func (v *Void) TypeName() string
Volatile is a qualifier.
type Volatile struct {
Type Type
}
func (v *Volatile) Format(fs fmt.State, verb rune)
func (v *Volatile) TypeName() string