mirror of https://github.com/aya-rs/aya
feat(aya): Add iterator program type
BPF iterators[0] are a way to dump kernel data into user-space and an alternative to `/proc` filesystem. This change adds support for BPF iterators on the user-space side. It provides a possibility to retrieve the outputs of BPF iterator programs both from sync and async Rust code. [0] https://docs.kernel.org/bpf/bpf_iterators.htmlreviewable/pr1088/r1
Michal Rostecki
6 months ago
parent
e423fce58f
commit
88d20a0c99
@ -0,0 +1,225 @@
|
||||
//! Iterators.
|
||||
use std::{
|
||||
mem::ManuallyDrop,
|
||||
os::fd::{AsFd, AsRawFd, BorrowedFd, FromRawFd},
|
||||
};
|
||||
|
||||
use crate::{
|
||||
generated::{bpf_attach_type::BPF_TRACE_ITER, bpf_prog_type},
|
||||
obj::{
|
||||
btf::{Btf, BtfKind},
|
||||
generated::bpf_link_type,
|
||||
},
|
||||
programs::{
|
||||
define_link_wrapper, load_program, FdLink, LinkError, PerfLinkIdInner, PerfLinkInner,
|
||||
ProgramData, ProgramError,
|
||||
},
|
||||
sys::{bpf_create_iter, bpf_link_create, bpf_link_get_info_by_fd, LinkTarget, SyscallError},
|
||||
};
|
||||
|
||||
/// An eBPF iterator which allows to dump into user space.
|
||||
///
|
||||
/// It can be seen as an alternative to `/proc` filesystem, which offers more
|
||||
/// flexibility about what information should be retrieved and how it should be
|
||||
/// formatted.
|
||||
///
|
||||
/// # Minimum kernel version
|
||||
///
|
||||
/// The minimum kernel version required to use this feature is 5.8.
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
/// ## Non-async Rust
|
||||
///
|
||||
/// ```no_run
|
||||
/// use std::io::{BufRead, BufReader};
|
||||
/// use aya::{programs::{Iter, ProgramError}, BtfError, Btf, Ebpf};
|
||||
/// # let mut ebpf = Ebpf::load_file("ebpf_programs.o")?;
|
||||
///
|
||||
/// let btf = Btf::from_sys_fs()?;
|
||||
/// let program: &mut Iter = ebpf.program_mut("iter_prog").unwrap().try_into()?;
|
||||
/// program.load("task", &btf)?;
|
||||
///
|
||||
/// let link_id = program.attach()?;
|
||||
/// let link = program.take_link(link_id)?;
|
||||
/// let file = link.into_file()?;
|
||||
/// let reader = BufReader::new(file);
|
||||
///
|
||||
/// let mut lines = reader.lines();
|
||||
/// for line in lines {
|
||||
/// let line = line?;
|
||||
/// println!("{line}");
|
||||
/// }
|
||||
/// # Ok::<(), Box<dyn std::error::Error>>(())
|
||||
/// ```
|
||||
#[derive(Debug)]
|
||||
pub struct Iter {
|
||||
pub(crate) data: ProgramData<IterLink>,
|
||||
}
|
||||
|
||||
impl Iter {
|
||||
/// Loads the program inside the kernel.
|
||||
pub fn load(&mut self, iter_type: &str, btf: &Btf) -> Result<(), ProgramError> {
|
||||
self.data.expected_attach_type = Some(BPF_TRACE_ITER);
|
||||
let type_name = format!("bpf_iter_{iter_type}");
|
||||
self.data.attach_btf_id =
|
||||
Some(btf.id_by_type_name_kind(type_name.as_str(), BtfKind::Func)?);
|
||||
load_program(bpf_prog_type::BPF_PROG_TYPE_TRACING, &mut self.data)
|
||||
}
|
||||
|
||||
/// Attaches the program.
|
||||
///
|
||||
/// The returned value can be used to detach, see [Iter::detach].
|
||||
pub fn attach(&mut self) -> Result<IterLinkId, ProgramError> {
|
||||
let prog_fd = self.fd()?;
|
||||
let prog_fd = prog_fd.as_fd();
|
||||
let link_fd = bpf_link_create(prog_fd, LinkTarget::Iter, BPF_TRACE_ITER, None, 0, None)
|
||||
.map_err(|(_, io_error)| SyscallError {
|
||||
call: "bpf_link_create",
|
||||
io_error,
|
||||
})?;
|
||||
|
||||
self.data
|
||||
.links
|
||||
.insert(IterLink::new(PerfLinkInner::FdLink(FdLink::new(link_fd))))
|
||||
}
|
||||
|
||||
/// Detaches the program.
|
||||
///
|
||||
/// See [Iter::attach].
|
||||
pub fn detach(&mut self, link_id: IterLinkId) -> Result<(), ProgramError> {
|
||||
self.data.links.remove(link_id)
|
||||
}
|
||||
|
||||
/// Takes ownership of the link referenced by the provided link_id.
|
||||
///
|
||||
/// The link will be detached on `Drop` and the caller is now responsible
|
||||
/// for managing its lifetime.
|
||||
pub fn take_link(&mut self, link_id: IterLinkId) -> Result<IterLink, ProgramError> {
|
||||
self.data.take_link(link_id)
|
||||
}
|
||||
}
|
||||
|
||||
/// An iterator descriptor.
|
||||
#[derive(Debug)]
|
||||
pub struct IterFd {
|
||||
fd: crate::MockableFd,
|
||||
}
|
||||
|
||||
impl AsFd for IterFd {
|
||||
fn as_fd(&self) -> BorrowedFd<'_> {
|
||||
let Self { fd } = self;
|
||||
fd.as_fd()
|
||||
}
|
||||
}
|
||||
|
||||
impl TryFrom<IterLink> for FdLink {
|
||||
type Error = LinkError;
|
||||
|
||||
fn try_from(value: IterLink) -> Result<Self, Self::Error> {
|
||||
if let PerfLinkInner::FdLink(fd) = value.into_inner() {
|
||||
Ok(fd)
|
||||
} else {
|
||||
Err(LinkError::InvalidLink)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
impl TryFrom<FdLink> for IterLink {
|
||||
type Error = LinkError;
|
||||
|
||||
fn try_from(fd_link: FdLink) -> Result<Self, Self::Error> {
|
||||
let info = bpf_link_get_info_by_fd(fd_link.fd.as_fd())?;
|
||||
if info.type_ == (bpf_link_type::BPF_LINK_TYPE_ITER as u32) {
|
||||
return Ok(Self::new(PerfLinkInner::FdLink(fd_link)));
|
||||
}
|
||||
Err(LinkError::InvalidLink)
|
||||
}
|
||||
}
|
||||
|
||||
define_link_wrapper!(
|
||||
/// The link used by [Iter] programs.
|
||||
IterLink,
|
||||
/// The type returned by [Iter::attach]. Can be passed to [Iter::detach].
|
||||
IterLinkId,
|
||||
PerfLinkInner,
|
||||
PerfLinkIdInner
|
||||
);
|
||||
|
||||
impl IterLink {
|
||||
/// Converts [IterLink] into a [std::fs::File]. That file can be used to
|
||||
/// retrieve the outputs of the iterator program.
|
||||
pub fn into_file(self) -> Result<std::fs::File, LinkError> {
|
||||
if let PerfLinkInner::FdLink(fd) = self.into_inner() {
|
||||
let fd = bpf_create_iter(fd.fd.as_fd()).map_err(|(_, error)| {
|
||||
LinkError::SyscallError(SyscallError {
|
||||
call: "bpf_iter_create",
|
||||
io_error: error,
|
||||
})
|
||||
})?;
|
||||
// We don't want to drop the descriptor when going out of the scope
|
||||
// of this method. The lifecycle of the descriptor is going to be
|
||||
// managed by the `File` created below.
|
||||
let fd = ManuallyDrop::new(fd);
|
||||
// SAFETY: We are sure that the file descriptor is valid. This
|
||||
// `File` takes responsibility of closing it.
|
||||
let file = unsafe { std::fs::File::from_raw_fd(fd.as_raw_fd()) };
|
||||
Ok(file)
|
||||
} else {
|
||||
Err(LinkError::InvalidLink)
|
||||
}
|
||||
}
|
||||
|
||||
/// Converts [IterLink] into an [async_fs::File]. That file can be used to
|
||||
/// retrieve the outputs of the iterator program.
|
||||
#[cfg(feature = "async_std")]
|
||||
pub fn into_async_io_file(self) -> Result<async_fs::File, LinkError> {
|
||||
if let PerfLinkInner::FdLink(fd) = self.into_inner() {
|
||||
let fd = bpf_create_iter(fd.fd.as_fd()).map_err(|(_, error)| {
|
||||
LinkError::SyscallError(SyscallError {
|
||||
call: "bpf_iter_create",
|
||||
io_error: error,
|
||||
})
|
||||
})?;
|
||||
// We don't want to drop the descriptor when going out of the scope
|
||||
// of this method. The lifecycle of the descriptor is going to be
|
||||
// managed by the `File` created below.
|
||||
let fd = ManuallyDrop::new(fd);
|
||||
// SAFETY: We are sure that the file descriptor is valid. This
|
||||
// `File` takes responsibility of closing it.
|
||||
//
|
||||
// NOTE: Unfortunately, there is no `async_fs::File::from_raw_fd`
|
||||
// method, so we have to work around that with creating
|
||||
// `std::fs::File` and then converting it into `async_fs::File`.
|
||||
let file = unsafe { std::fs::File::from_raw_fd(fd.as_raw_fd()) };
|
||||
let file: async_fs::File = file.into();
|
||||
Ok(file)
|
||||
} else {
|
||||
Err(LinkError::InvalidLink)
|
||||
}
|
||||
}
|
||||
|
||||
/// Converts [IterLink] into a [tokio::fs::File]. That file can be used to
|
||||
/// retrieve the outputs of the iterator program.
|
||||
#[cfg(feature = "async_tokio")]
|
||||
pub fn into_tokio_file(self) -> Result<tokio::fs::File, LinkError> {
|
||||
if let PerfLinkInner::FdLink(fd) = self.into_inner() {
|
||||
let fd = bpf_create_iter(fd.fd.as_fd()).map_err(|(_, error)| {
|
||||
LinkError::SyscallError(SyscallError {
|
||||
call: "bpf_iter_create",
|
||||
io_error: error,
|
||||
})
|
||||
})?;
|
||||
// We don't want to drop the descriptor when going out of the scope
|
||||
// of this method. The lifecycle of the descriptor is going to be
|
||||
// managed by the `File` created below.
|
||||
let fd = ManuallyDrop::new(fd);
|
||||
// SAFETY: We are sure that the file descriptor is valid. This
|
||||
// `File` takes responsibility of closing it.
|
||||
let file = unsafe { tokio::fs::File::from_raw_fd(fd.as_raw_fd()) };
|
||||
Ok(file)
|
||||
} else {
|
||||
Err(LinkError::InvalidLink)
|
||||
}
|
||||
}
|
||||
}
|
||||
@ -0,0 +1,22 @@
|
||||
// clang-format off
|
||||
#include <vmlinux.h>
|
||||
#include <bpf/bpf_helpers.h>
|
||||
// clang-format on
|
||||
|
||||
char _license[] SEC("license") = "GPL";
|
||||
|
||||
SEC("iter/task")
|
||||
int iter_task(struct bpf_iter__task *ctx) {
|
||||
struct seq_file *seq = ctx->meta->seq;
|
||||
struct task_struct *task = ctx->task;
|
||||
if (task == NULL) {
|
||||
return 0;
|
||||
}
|
||||
|
||||
if (ctx->meta->seq_num == 0) {
|
||||
BPF_SEQ_PRINTF(seq, "tgid pid name\n");
|
||||
}
|
||||
BPF_SEQ_PRINTF(seq, "%-8d %-8d %s\n", task->tgid, task->pid, task->comm);
|
||||
|
||||
return 0;
|
||||
}
|
||||
@ -0,0 +1,45 @@
|
||||
use std::io::BufRead;
|
||||
|
||||
use aya::{programs::Iter, Btf, Ebpf};
|
||||
use test_log::test;
|
||||
use tokio::io::AsyncBufReadExt;
|
||||
|
||||
#[test]
|
||||
fn iter_task() {
|
||||
let mut ebpf = Ebpf::load(crate::ITER_TASK).unwrap();
|
||||
let btf = Btf::from_sys_fs().unwrap();
|
||||
let prog: &mut Iter = ebpf.program_mut("iter_task").unwrap().try_into().unwrap();
|
||||
prog.load("task", &btf).unwrap();
|
||||
|
||||
let link_id = prog.attach().unwrap();
|
||||
let link = prog.take_link(link_id).unwrap();
|
||||
let file = link.into_file().unwrap();
|
||||
let reader = std::io::BufReader::new(file);
|
||||
|
||||
let mut lines = reader.lines();
|
||||
let line_title = lines.next().unwrap().unwrap();
|
||||
let line_init = lines.next().unwrap().unwrap();
|
||||
|
||||
assert_eq!(line_title, "tgid pid name");
|
||||
assert!(line_init == "1 1 init" || line_init == "1 1 systemd");
|
||||
}
|
||||
|
||||
#[test(tokio::test)]
|
||||
async fn iter_async_task() {
|
||||
let mut ebpf = Ebpf::load(crate::ITER_TASK).unwrap();
|
||||
let btf = Btf::from_sys_fs().unwrap();
|
||||
let prog: &mut Iter = ebpf.program_mut("iter_task").unwrap().try_into().unwrap();
|
||||
prog.load("task", &btf).unwrap();
|
||||
|
||||
let link_id = prog.attach().unwrap();
|
||||
let link = prog.take_link(link_id).unwrap();
|
||||
let file = link.into_tokio_file().unwrap();
|
||||
let reader = tokio::io::BufReader::new(file);
|
||||
|
||||
let mut lines = reader.lines();
|
||||
let line_title = lines.next_line().await.unwrap().unwrap();
|
||||
let line_init = lines.next_line().await.unwrap().unwrap();
|
||||
|
||||
assert_eq!(line_title, "tgid pid name");
|
||||
assert!(line_init == "1 1 init" || line_init == "1 1 systemd");
|
||||
}
|
||||
Loading…
Reference in New Issue