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
Index ¶
- Variables
- func CheckTypeCompatibility(localType Type, targetType Type) error
- func LoadSpecAndExtInfosFromReader(rd io.ReaderAt) (*Spec, *ExtInfos, error)
- func MarshalMapKV(key, value Type) (_ *Handle, keyID, valueID TypeID, err error)
- func Sizeof(typ Type) (int, error)
- func WithFuncMetadata(ins asm.Instruction, fn *Func) asm.Instruction
- type Array
- type Bits
- type Builder
- type COREFixup
- type CORERelocation
- type Const
- type Datasec
- type Enum
- type EnumValue
- type ExtInfos
- type Float
- type Func
- type FuncLinkage
- type FuncParam
- type FuncProto
- type Fwd
- type FwdKind
- type GoFormatter
- type Handle
- func FindHandle(predicate func(info *HandleInfo) bool) (*Handle, error)
- func MarshalExtInfos(insns asm.Instructions) (_ *Handle, funcInfos, lineInfos []byte, _ error)
- func NewHandle(b *Builder) (*Handle, error)
- func NewHandleFromID(id ID) (*Handle, error)
- func NewHandleFromRawBTF(btf []byte) (*Handle, error)
- type HandleInfo
- type HandleIterator
- type ID
- type Int
- type IntEncoding
- type Line
- type MarshalOptions
- type Member
- type Pointer
- type Restrict
- type Spec
- func (s *Spec) AnyTypeByName(name string) (Type, error)
- func (s *Spec) AnyTypesByName(name string) ([]Type, error)
- func (s *Spec) Copy() *Spec
- func (s *Spec) Iterate() *TypesIterator
- func (s *Spec) TypeByID(id TypeID) (Type, error)
- func (s *Spec) TypeByName(name string, typ interface{}) error
- func (s *Spec) TypeID(typ Type) (TypeID, error)
- type Struct
- type Transformer
- type Type
- type TypeID
- type Typedef
- type TypesIterator
- type Union
- type Var
- type VarLinkage
- type VarSecinfo
- type Void
- type Volatile
Examples ¶
Constants ¶
This section is empty.
Variables ¶
var ( ErrNotSupported = internal.ErrNotSupported ErrNotFound = errors.New("not found") ErrNoExtendedInfo = errors.New("no extended info") ErrMultipleMatches = errors.New("multiple matching types") )
Errors returned by BTF functions.
var FuncInfoSize = uint32(binary.Size(bpfFuncInfo{}))
The size of a FuncInfo in BTF wire format.
var LineInfoSize = uint32(binary.Size(bpfLineInfo{}))
Functions ¶
func CheckTypeCompatibility ¶
CheckTypeCompatibility checks local and target types for Compatibility according to CO-RE rules.
Only layout compatibility is checked, ignoring names of the root type.
func LoadSpecAndExtInfosFromReader ¶
LoadSpecAndExtInfosFromReader reads from an ELF.
ExtInfos may be nil if the ELF doesn't contain section metadata. Returns ErrNotFound if the ELF contains no BTF.
func MarshalMapKV ¶
MarshalMapKV creates a BTF object containing a map key and value.
The function is intended for the use of the ebpf package and may be removed at any point in time.
func Sizeof ¶
Sizeof returns the size of a type in bytes.
Returns an error if the size can't be computed.
func WithFuncMetadata ¶
func WithFuncMetadata(ins asm.Instruction, fn *Func) asm.Instruction
WithFuncMetadata adds a btf.Func to the Metadata of asm.Instruction.
Types ¶
type Builder ¶
type Builder struct {
// contains filtered or unexported fields
}
Builder turns Types into raw BTF.
The default value may be used and represents an empty BTF blob. Void is added implicitly if necessary.
func NewBuilder ¶
NewBuilder creates a Builder from a list of types.
It is more efficient than calling [Add] individually.
Returns an error if adding any of the types fails.
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 ¶
CORERelocate calculates changes needed to adjust eBPF instructions for differences in types.
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].
type CORERelocation ¶
type CORERelocation struct {
// contains filtered or unexported fields
}
func CORERelocationMetadata ¶
func CORERelocationMetadata(ins *asm.Instruction) *CORERelocation
type Datasec ¶
type Datasec struct {
Name string
Size uint32
Vars []VarSecinfo
}
Datasec is a global program section containing data.
type Enum ¶
type Enum struct {
Name string
// Size of the enum value in bytes.
Size uint32
// True if the values should be interpreted as signed integers.
Signed bool
Values []EnumValue
}
Enum lists possible values.
type ExtInfos ¶
type ExtInfos struct {
// contains filtered or unexported fields
}
ExtInfos contains ELF section metadata.
type Func ¶
type Func struct {
Name string
Type Type
Linkage FuncLinkage
}
Func is a function definition.
func FuncMetadata ¶
func FuncMetadata(ins *asm.Instruction) *Func
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 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 FindHandle ¶
func FindHandle(predicate func(info *HandleInfo) bool) (*Handle, error)
FindHandle returns the first handle for which predicate returns true.
Requires CAP_SYS_ADMIN.
Returns an error wrapping ErrNotFound if predicate never returns true or if there is no BTF loaded into the kernel.
func MarshalExtInfos ¶
func MarshalExtInfos(insns asm.Instructions) (_ *Handle, funcInfos, lineInfos []byte, _ error)
MarshalExtInfos encodes function and line info embedded in insns into kernel wire format.
Returns ErrNotSupported if the kernel doesn't support BTF-associated programs.
func NewHandle ¶
NewHandle loads the contents of a Builder into the kernel.
Returns an error wrapping ErrNotSupported if the kernel doesn't support BTF.
func NewHandleFromID ¶
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 NewHandleFromRawBTF ¶
NewHandleFromRawBTF loads raw BTF into the kernel.
Returns an error wrapping ErrNotSupported if the kernel doesn't support BTF.
func (*Handle) Close ¶
Close destroys the handle.
Subsequent calls to FD will return an invalid value.
func (*Handle) Info ¶
func (h *Handle) Info() (*HandleInfo, error)
Info returns metadata about the handle.
type HandleInfo ¶
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
}
HandleInfo describes a Handle.
func (*HandleInfo) IsModule ¶
func (i *HandleInfo) IsModule() bool
IsModule returns true if the BTF is for a kernel module.
func (*HandleInfo) IsVmlinux ¶
func (i *HandleInfo) IsVmlinux() bool
IsVmlinux returns true if the BTF is for the kernel itself.
type HandleIterator ¶
type HandleIterator struct {
// The ID of the current handle. Only valid after a call to Next.
ID ID
// The current Handle. Only valid until a call to Next.
// See Take if you want to retain the handle.
Handle *Handle
// contains filtered or unexported fields
}
HandleIterator allows enumerating BTF blobs loaded into the kernel.
Example ¶
package main
import (
"fmt"
"github.com/cilium/ebpf/btf"
)
func main() {
it := new(btf.HandleIterator)
defer it.Handle.Close()
for it.Next() {
info, err := it.Handle.Info()
if err != nil {
panic(err)
}
fmt.Printf("Found handle with ID %d and name %s\n", it.ID, info.Name)
}
if err := it.Err(); err != nil {
panic(err)
}
}
Output:
func (*HandleIterator) Err ¶
func (it *HandleIterator) Err() error
Err returns an error if iteration failed for some reason.
func (*HandleIterator) Next ¶
func (it *HandleIterator) Next() bool
Next retrieves a handle for the next BTF object.
Returns true if another BTF object was found. Call HandleIterator.Err after the function returns false.
func (*HandleIterator) Take ¶
func (it *HandleIterator) Take() *Handle
Take the ownership of the current handle.
It's the callers responsibility to close the handle.
type Int ¶
type Int struct {
Name string
// The size of the integer in bytes.
Size uint32
Encoding IntEncoding
}
Int is an integer of a given length.
See https://www.kernel.org/doc/html/latest/bpf/btf.html#btf-kind-int
type IntEncoding ¶
type IntEncoding byte
const ( Unsigned IntEncoding = 0 Signed IntEncoding = 1 Char IntEncoding = 2 Bool IntEncoding = 4 )
Valid IntEncodings.
These may look like they are flags, but they aren't.
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) LineColumn ¶
func (*Line) LineNumber ¶
type MarshalOptions ¶
type MarshalOptions struct {
// Target byte order. Defaults to the system's native endianness.
Order binary.ByteOrder
// Remove function linkage information for compatibility with <5.6 kernels.
StripFuncLinkage bool
}
func KernelMarshalOptions ¶
func KernelMarshalOptions() *MarshalOptions
KernelMarshalOptions will generate BTF suitable for the current kernel.
type Spec ¶
type Spec struct {
// contains filtered or unexported fields
}
Spec allows querying a set of Types and loading the set into the kernel.
func LoadSpecFromReader ¶
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 ¶
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 (*Spec) AnyTypeByName ¶
AnyTypeByName returns a Type with the given name.
Returns an error if multiple types of that name exist.
func (*Spec) AnyTypesByName ¶
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) TypeByID ¶
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 ¶
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. Returns an error wrapping ErrMultipleTypes if multiple candidates are found.
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.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)
Output:
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.
type Transformer ¶
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.
Identity of Type follows the Go specification: two Types are considered equal if they have the same concrete type and the same dynamic value, aka they point at the same location in memory. This means that the following Types are considered distinct even though they have the same "shape".
a := &Int{Size: 1}
b := &Int{Size: 1}
a != b
Example (ValidTypes) ¶
The following are valid Types.
There currently is no better way to document which types implement an interface.
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{}
var _ Type = &Float{}
Output:
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.
Example (StripQualifiers) ¶
Copy can be used with UnderlyingType to strip qualifiers from a type graph.
a := &Volatile{Type: &Pointer{Target: &Typedef{Name: "foo", Type: &Int{Size: 2}}}}
b := Copy(a, UnderlyingType)
// b has Volatile and Typedef removed.
fmt.Printf("%3v\n", b)
Output: Pointer[target=Int[unsigned size=16]]
func UnderlyingType ¶
UnderlyingType skips qualifiers and Typedefs.
type TypesIterator ¶
type TypesIterator struct {
// The last visited type in the spec.
Type Type
// contains filtered or unexported fields
}
TypesIterator iterates over types of a given spec.
func (*TypesIterator) Next ¶
func (iter *TypesIterator) Next() bool
Next returns true as long as there are any remaining types.
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.
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
Source Files