Crate btf_rs

Expand description

Library for the BPF Type Format (BTF). The BPF Type Format is a metadata format encoding debugging information such as types, function prototypes, structure layouts, etc. and is often used, but not limited, to deal with eBPF programs.

The integration tests give good examples on how to use this library. We recommend reading the official BTF documentation as this library is offering a low-level API.

§Parsing BTF

The main object this library offers is Btf, which represents a parsed BTF object. It offers helpers to resolve ids (u32), names (String) and types / chained types (Type).

Btf can be constructed using a BTF file or a split BTF one. BTF files hold self-contained information, while split BTF files are built upon a base BTF file and extend it. For example, in a standard Linux environment BTF files and split files can be found under /sys/kernel/btf, /sys/kernel/btf/vmlinux being the BTF file for the kernel and other files matching /sys/kernel/btf/<module-name> being BTF split files for its modules.

use btf_rs::Btf;

let base = Btf::from_file("/sys/kernel/btf/vmlinux").unwrap();

let ovs = Btf::from_split_file("/sys/kernel/btf/openvswitch", &base).unwrap();
let bbr = Btf::from_split_file("/sys/kernel/btf/tcp_bbr", &base).unwrap();

Btf-rs also supports constructing Btf using byte slices.

use std::fs;
use btf_rs::Btf;

let base = Btf::from_bytes(&fs::read("/sys/kernel/btf/vmlinux").unwrap()).unwrap();

let ovs = Btf::from_split_bytes(&fs::read("/sys/kernel/btf/openvswitch").unwrap(), &base)
          .unwrap();
let bbr = Btf::from_split_bytes(&fs::read("/sys/kernel/btf/bbr").unwrap(), &base).unwrap();

§Resolving types

Types can be resolved using a Btf object. The following is an example of how a function can be inspected to retrieve information about its first parameter. Here the function kfree_skb_reason is taking a struct sk_buff * as its first argument.

use btf_rs::*;

let btf = Btf::from_file("/sys/kernel/btf/vmlinux").unwrap();

let func = match btf
    .resolve_types_by_name("kfree_skb_reason")
    .unwrap()
    .pop()
    .unwrap()
{
    Type::Func(func) => func,
    _ => panic!("Resolved type is not a function"),
};

let proto = match btf.resolve_chained_type(&func).unwrap() {
    Type::FuncProto(proto) => proto,
    _ => panic!("Resolved type is not a function proto"),
};

assert!(proto.parameters.len() > 1);

// The following prints "skb".
println!("{}", btf.resolve_name(&proto.parameters[0]).unwrap());

let ptr = match btf.resolve_chained_type(&proto.parameters[0]).unwrap() {
    Type::Ptr(ptr) => ptr,
    _ => panic!("Resolved type is not a pointer"),
};

let r#struct = match btf.resolve_chained_type(&ptr).unwrap() {
    Type::Struct(r#struct) => r#struct,
    _ => panic!("Resolved type is not a struct"),
};

// The following prints "sk_buff".
println!("{}", btf.resolve_name(&r#struct).unwrap());

Other information such as function scope and return value, structure size and members, etc. can be retrieved. For all those see the Type and its associated structures documentation.

§Additional objects

Additional objects and helpers built on top of the ones described here can be found in the utils sub-module. Those are aimed at easing BTF consumption in common cases, such as parsing all BTF files of a running Linux kernel and its modules or dealing with .BTF ELF sections.

§Feature flags

elf: Enable helpers parsing the .BTF section of ELF files in [utils::elf].
elf-compression: Enable handling of compressed ELF files (e.g. compressed kernel modules) in [utils::elf]. The Bzip2, Gzip, Xz and Zstd compression algorithms are currently supported.
regex: Enable name resolutions by regex ([regex::Regex]).

§`Btf` backends

The Btf object supports different internal backends (Backend), optimized for different uses: Backend::Cache and Backend::Mmap. The former provides a faster API at the cost of slower initialization and increase in memory footprint. The latter provides a fast initialization time and lower memory footprint at the cast of slower API performances.

Backend::Cache is used by default. The backend can also be explicitly selected using dedicated constructors (see from_*_with_backend helpers). All BTF data read from bytes use Backend::Cache (this includes all elf feature helpers) and Backend::Mmap is only supported for base BTF files.

A benchmark utility is provided to gather actual numbers. It should be run on the target machine, to investigate how btf-rs would perform. E.g.

$ cargo build --release -F regex --example benchmark
$ ./target/release/examples/benchmark --help
[...]
$ ./target/release/examples/benchmark -i 100 \
    --id 77378 --name __kfree_skb --regex "^[[:alnum:]]+_drop_reason$" \
    --backend cache
[...]

A few parameters are required to configure the type id and name to use for querying the BTF data. Those can be selected by first inspecting the BTF data using bpftool (bpftool btf dump file /sys/kernel/btf/vmlinux).

Re-exports§

pub use error::*;

Modules§

btf: Main object of the btf-rs crate, providing a way to parse BTF data and helpers to query the information it describes.
error: Errors returned from btf-rs.
utils: Utilities built on top of the btf_rs library to ease the development for common use cases.

Structs§

Array: Rust representation for BTF type BTF_KIND_ARRAY.
Btf: Main representation of parsed BTF data. Provides helpers to resolve types and their associated names.
BtfSection
ChainedTypeIter: Iterator over chained types (types referencing other types in a chain).
Datasec: Rust representation for BTF type BTF_KIND_DATASEC.
DeclTag: Rust representation for BTF type BTF_KIND_DECL_TAG.
Enum: Rust representation for BTF type BTF_KIND_ENUM.
Enum64: Rust representation for BTF type BTF_KIND_ENUM64.
Enum64Member: Represents an Enum64 member.
EnumMember: Represents an Enum member.
Float: Rust representation for BTF type BTF_KIND_FLOAT.
Func: Rust representation for BTF type BTF_KIND_FUNC.
FuncProto: Rust representation for BTF type BTF_KIND_FUNC_PROTO.
Fwd: Rust representation for BTF type BTF_KIND_FWD.
Int: Rust representation for BTF type BTF_KIND_INT.
Member: Represents a Struct member.
Parameter: Represents a FuncProto parameter.
Ptr: Rust representation for BTF type BTF_KIND_PTR.
Struct: Rust representation for BTF type BTF_KIND_STRUCT.
TypeIter: Iterator over BTF types.
TypeTag: Rust representation for BTF type BTF_KIND_TYPE_TAG.
Typedef: Rust representation for BTF type BTF_KIND_TYPEDEF.
Var: Rust representation for BTF type BTF_KIND_VAR.
VarSecinfo: Represents a Datasec variable.
Volatile: Rust representation for BTF type BTF_KIND_VOLATILE.

Enums§

Backend: Backend used by the Btf object to store and access the underlying BTF information.
Type: Rust representation of BTF types. Each type then contains its own specific data and provides helpers to access it.

Traits§

BtfType: Helpers common to all BTF types. Ease the use of types.

Type Aliases§

Const: Rust representation for BTF type BTF_KIND_CONST.
Restrict: Rust representation for BTF type BTF_KIND_RESTRICT.
Union: Rust representation for BTF type BTF_KIND_UNION.

Crate btf_rs

Crate btf_rs Copy item path

§Parsing BTF

§Resolving types

§Additional objects

§Feature flags

§Btf backends

Re-exports§

Modules§

Structs§

Enums§

Traits§

Type Aliases§

Crate btf_rs

§`Btf` backends