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 LoadSpecAndExtInfosFromReader(rd io.ReaderAt) (*Spec, *ExtInfos, error)
- func MarshalExtInfos(insns asm.Instructions, typeID func(Type) (TypeID, error)) (funcInfos, lineInfos []byte, _ error)
- func Sizeof(typ Type) (int, error)
- type Array
- type Bits
- 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
- type HandleInfo
- type HandleIterator
- type ID
- type Int
- type IntEncoding
- type Line
- 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") )
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 LoadSpecAndExtInfosFromReader ¶
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.
Types ¶
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].
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 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 NewHandle ¶
NewHandle loads BTF into the kernel.
Returns ErrNotSupported if BTF is not supported.
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 (*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
IsModule returns true if the BTF is for the kernel itself.
type HandleIterator ¶
type HandleIterator struct {
// The ID of the last retrieved handle. Only valid after a call to Next.
ID ID
// contains filtered or unexported fields
}
HandleIterator allows enumerating BTF blobs loaded into the kernel.
Example ¶
package main
import (
"fmt"
"github.com/kubeshark/ebpf/btf"
)
func main() {
var handle *btf.Handle
// Ensure that handle is cleaned up. This is valid for nil handles as well.
defer handle.Close()
it := new(btf.HandleIterator)
for it.Next(&handle) {
fmt.Printf("Found handle with ID %d\n", it.ID)
}
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(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.
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 ( 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) LineColumn ¶
func (*Line) LineNumber ¶
type Spec ¶
type Spec struct {
// contains filtered or unexported fields
}
Spec represents decoded BTF.
func LoadKernelSpec ¶
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 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. If multiple candidates are found, an error is returned.
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.
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{}
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