Crate btf_rs

source ·
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_type_by_name("kfree_skb_reason").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.

Feature flags:

  • test_runtime: Use the system’s runtime BTF files to perform extra integration tests.

Modules

Structs

  • Array
    Rust representation for BTF type BTF_KIND_ARRAY.
  • Btf
    Main representation of a parsed BTF object. Provides helpers to resolve types and their associated names.
  • 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.
  • 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

  • Type
    Rust representation of BTF types. Each type then contains its own specific data and provides helpers to access it.

Traits

Type Definitions

  • Const
    Rust representation for BTF type BTF_KIND_CONST.
  • Restrict
    Rust representation for BTF type BTF_KIND_RESTRICT.
  • TypeTag
    Rust representation for BTF type BTF_KIND_TYPE_TAG.
  • Union
    Rust representation for BTF type BTF_KIND_UNION.