README
¶
BTF: BPF Type Format in Go
This is a fork of github.com/cilium/ebpf/internal/btf to make it accessible to thirdparty applications.
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 ¶
- Variables
- func Sizeof(typ Type) (int, error)
- type Array
- type COREFixup
- type COREFixups
- type COREKind
- type Const
- type CoreRelo
- type CoreRelos
- type Datasec
- type Enum
- type EnumValue
- type Float
- type Func
- type FuncInfo
- type FuncInfos
- type FuncLinkage
- type FuncParam
- type FuncProto
- type Fwd
- type FwdKind
- type GoFormatter
- type Handle
- type ID
- type Int
- type IntEncoding
- type LineInfo
- type LineInfos
- type Map
- type Member
- type Pointer
- type Program
- 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) Program(name string) (*Program, error)
- func (s *Spec) TypeByID(id TypeID) (Type, error)
- func (s *Spec) TypeByName(name string, typ interface{}) error
- type Struct
- type Type
- type TypeID
- type Typedef
- 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.
Functions ¶
Types ¶
type COREFixups ¶
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 Datasec ¶
type Datasec struct {
TypeID
Name string
Size uint32
Vars []VarSecinfo
}
Datasec is a global program section containing data.
type Func ¶
type Func struct {
TypeID
Name string
Type Type
Linkage FuncLinkage
}
Func is a function definition.
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.
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.
Returns ErrNotExist, if there is no BTF with the given id.
Requires CAP_SYS_ADMIN.
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.
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.
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 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.
type Spec ¶
type Spec struct {
// contains filtered or unexported fields
}
Spec represents decoded BTF.
func LoadKernelSpec ¶
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 ¶
LoadSpecFromReader reads from an ELF or a raw BTF blob.
Returns ErrNotFound if reading from an ELF which contains no BTF.
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) Program ¶
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 ¶
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 {
TypeID
Name string
// The size of the struct including padding, in bytes
Size uint32
Members []Member
}
Struct is a compound type of consecutive members.
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.
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 UnderlyingType ¶
UnderlyingType skips qualifiers and Typedefs.
May return typ verbatim if too many types have to be skipped to protect against circular Types.
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.
type Var ¶
type Var struct {
TypeID
Name string
Type Type
Linkage VarLinkage
}
Var is a global variable.
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
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd/gentypes
Program gentypes reads a compressed vmlinux .BTF section and generates syscall bindings from it.
|
Program gentypes reads a compressed vmlinux .BTF section and generates syscall bindings from it. |
|
sys
Package sys contains bindings for the BPF syscall.
|
Package sys contains bindings for the BPF syscall. |