Skip to content

Commit

Permalink
aya-bpf: Add docs for the main lib annd few map types
Browse files Browse the repository at this point in the history 
This change adds a summary of the aya-bpf lib and docs for:

* hash map
* lpm trie
* perf event arrays

Signed-off-by: Michal Rostecki <[email protected]>
  • Loading branch information
@vadorovsky
vadorovsky committed Apr 12, 2022
1 parent a1d4499 commit be662d2
Show file tree
Hide file tree
Showing 5 changed files with 198 additions and 0 deletions.
25 changes: 25 additions & 0 deletions bpf/aya-bpf/src/lib.rs
View file
Original file line number Diff line number Diff line change
@@ -1,3 +1,28 @@
//! A library to write eBPF programs.
//!
//! eBPF is a technology that allows running user-supplied programs inside the
//!
//! Linux kernel. For more info see
//! [https://ebpf.io/what-is-ebpf](https://ebpf.io/what-is-ebpf).
//!
//! Aya is an eBPF library built with a focus on operability and developer experience. It does not
//! rely on [libbpf](https://github.com/libbpf/libbpf) nor [bcc](https://github.com/iovisor/bcc) -
//! it's built from the ground up purely in Rust, using only the [libc](https://crates.io/libc)
//! crate to execute syscalls. With BTF support and when linked with musl, it offers a true
//! [compile once, run everywhere
//! solution](https://facebookmicrosites.github.io/bpf/blog/2020/02/19/bpf-portability-and-co-re.html),
//! where a single self-contained binary can be deployed on many linux distributions
//! and kernel versions.
//!
//! Some of the major features provided include:
//!
//! * Support for the **BPF Type Format** (BTF), which is transparently enabled when
//! supported by the target kernel. This allows eBPF programs compiled against
//! one kernel version to run on different kernel versions without the need to
//! recompile.
//! * Support for function call relocation and global data maps, which
//! allows eBPF programs to make **function calls** and use **global variables
//! and initializers**.
#![feature(never_type)]
#![allow(clippy::missing_safety_doc)]
#![no_std]
Expand Down
77 changes: 77 additions & 0 deletions bpf/aya-bpf/src/maps/hash_map.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,28 @@ use crate::{
maps::PinningType,
};

/// A hash map that can be shared between eBPF programs and user space.
///
/// # Minimum kernel version
///
/// The minimum kernel version required to use this feature is 3.19.
///
/// # Examples
///
/// ```no_run
/// use aya_bpf::{macros::map, maps::HashMap};
/// # use aya_bpf::programs::LsmContext;
///
/// #[map]
/// static mut MY_MAP: HashMap<u32, u32> = HashMap::with_max_entries(1024, 0);
///
/// # unsafe fn try_test(ctx: &LsmContext) -> Result<i32, i32> {
/// let key: u32 = 13;
/// let value: u32 = 42;
/// MY_MAP.insert(&key, &value, 0).map_err(|e| e as i32)?;
/// # Ok(0)
/// # }
/// ```
#[repr(transparent)]
pub struct HashMap<K, V> {
def: bpf_map_def,
Expand All @@ -19,6 +41,7 @@ pub struct HashMap<K, V> {
}

impl<K, V> HashMap<K, V> {
/// Creates a `HashMap` with the maximum number of elements.
pub const fn with_max_entries(max_entries: u32, flags: u32) -> HashMap<K, V> {
HashMap {
def: build_def::<K, V>(BPF_MAP_TYPE_HASH, max_entries, flags, PinningType::None),
Expand All @@ -27,6 +50,8 @@ impl<K, V> HashMap<K, V> {
}
}

/// Creates a `HashMap` pinned in the BPFFS filesystem, with the maximum
/// number of elements.
pub const fn pinned(max_entries: u32, flags: u32) -> HashMap<K, V> {
HashMap {
def: build_def::<K, V>(BPF_MAP_TYPE_HASH, max_entries, flags, PinningType::ByName),
Expand All @@ -35,21 +60,25 @@ impl<K, V> HashMap<K, V> {
}
}

/// Returns a copy of the value associated with the key.
#[inline]
pub fn get(&mut self, key: &K) -> Option<&V> {
get(&mut self.def, key)
}

/// Returns a mutable copy of the value associated with the key.
#[inline]
pub fn get_mut(&mut self, key: &K) -> Option<&mut V> {
get_mut(&mut self.def, key)
}

/// Inserts a key-value pair into the map.
#[inline]
pub fn insert(&mut self, key: &K, value: &V, flags: u64) -> Result<(), c_long> {
insert(&mut self.def, key, value, flags)
}

/// Removes a key from the map.
#[inline]
pub fn remove(&mut self, key: &K) -> Result<(), c_long> {
remove(&mut self.def, key)
Expand All @@ -64,6 +93,7 @@ pub struct LruHashMap<K, V> {
}

impl<K, V> LruHashMap<K, V> {
/// Creates an `LruHashMap` with the maximum number of elements.
pub const fn with_max_entries(max_entries: u32, flags: u32) -> LruHashMap<K, V> {
LruHashMap {
def: build_def::<K, V>(BPF_MAP_TYPE_LRU_HASH, max_entries, flags, PinningType::None),
Expand All @@ -72,6 +102,8 @@ impl<K, V> LruHashMap<K, V> {
}
}

/// Creates an `LruHashMap` pinned in the BPFFS filesystem, with the maximum
/// number of elements.
pub const fn pinned(max_entries: u32, flags: u32) -> LruHashMap<K, V> {
LruHashMap {
def: build_def::<K, V>(
Expand All @@ -85,27 +117,58 @@ impl<K, V> LruHashMap<K, V> {
}
}

/// Returns a copy of the value associated with the key.
#[inline]
pub fn get(&mut self, key: &K) -> Option<&V> {
get(&mut self.def, key)
}

/// Returns a mutable copy of the value associated with the key.
#[inline]
pub fn get_mut(&mut self, key: &K) -> Option<&mut V> {
get_mut(&mut self.def, key)
}

/// Inserts a key-value pair into the map.
#[inline]
pub fn insert(&mut self, key: &K, value: &V, flags: u64) -> Result<(), c_long> {
insert(&mut self.def, key, value, flags)
}

/// Removes a key from the map.
#[inline]
pub fn remove(&mut self, key: &K) -> Result<(), c_long> {
remove(&mut self.def, key)
}
}

/// A hash map that can be shared between eBPF programs and user space. Each
/// CPU has its own separate copy of the map. The copies are not synchronized
/// in any way.
///
/// Due to limits defined in the kernel, the `K` and `V` types cannot be larger
/// than 32KB in size.
///
/// # Minimum kernel version
///
/// The minimum kernel version required to use this feature is 4.6.
///
/// # Examples
///
/// ```no_run
/// use aya_bpf::{macros::map, maps::PerCpuHashMap};
/// # use aya_bpf::programs::LsmContext;
///
/// #[map]
/// static mut MY_MAP: PerCpuHashMap<u32, u32> = PerCpuHashMap::with_max_entries(1024, 0);
///
/// # unsafe fn try_test(ctx: &LsmContext) -> Result<i32, i32> {
/// let key: u32 = 13;
/// let value: u32 = 42;
/// MY_MAP.insert(&key, &value, 0).map_err(|e| e as i32)?;
/// # Ok(0)
/// # }
/// ```
#[repr(transparent)]
pub struct PerCpuHashMap<K, V> {
def: bpf_map_def,
Expand All @@ -114,6 +177,7 @@ pub struct PerCpuHashMap<K, V> {
}

impl<K, V> PerCpuHashMap<K, V> {
/// Creates a `PerCpuHashMap` with the maximum number of elements.
pub const fn with_max_entries(max_entries: u32, flags: u32) -> PerCpuHashMap<K, V> {
PerCpuHashMap {
def: build_def::<K, V>(
Expand All @@ -127,6 +191,8 @@ impl<K, V> PerCpuHashMap<K, V> {
}
}

/// Creates a `PerCpuHashMap` pinned in the BPFFS filesystem, with the maximum
/// number of elements.
pub const fn pinned(max_entries: u32, flags: u32) -> PerCpuHashMap<K, V> {
PerCpuHashMap {
def: build_def::<K, V>(
Expand All @@ -140,21 +206,25 @@ impl<K, V> PerCpuHashMap<K, V> {
}
}

/// Returns a copy of the value associated with the key.
#[inline]
pub fn get(&mut self, key: &K) -> Option<&V> {
get(&mut self.def, key)
}

/// Returns a mutable copy of the value associated with the key.
#[inline]
pub fn get_mut(&mut self, key: &K) -> Option<&mut V> {
get_mut(&mut self.def, key)
}

/// Inserts a key-value pair into the map.
#[inline]
pub fn insert(&mut self, key: &K, value: &V, flags: u64) -> Result<(), c_long> {
insert(&mut self.def, key, value, flags)
}

/// Removes a key from the map.
#[inline]
pub fn remove(&mut self, key: &K) -> Result<(), c_long> {
remove(&mut self.def, key)
Expand All @@ -169,6 +239,7 @@ pub struct LruPerCpuHashMap<K, V> {
}

impl<K, V> LruPerCpuHashMap<K, V> {
/// Creates an `LruPerCpuHashMap` with the maximum number of elements.
pub const fn with_max_entries(max_entries: u32, flags: u32) -> LruPerCpuHashMap<K, V> {
LruPerCpuHashMap {
def: build_def::<K, V>(
Expand All @@ -182,6 +253,8 @@ impl<K, V> LruPerCpuHashMap<K, V> {
}
}

/// Creates an `LruPerCpuHashMap` pinned in the BPFFS filesystem, with the maximum
/// number of elements.
pub const fn pinned(max_entries: u32, flags: u32) -> LruPerCpuHashMap<K, V> {
LruPerCpuHashMap {
def: build_def::<K, V>(
Expand All @@ -195,21 +268,25 @@ impl<K, V> LruPerCpuHashMap<K, V> {
}
}

/// Returns a copy of the value associated with the key.
#[inline]
pub fn get(&mut self, key: &K) -> Option<&V> {
get(&mut self.def, key)
}

/// Returns a mutable copy of the value associated with the key.
#[inline]
pub fn get_mut(&mut self, key: &K) -> Option<&mut V> {
get_mut(&mut self.def, key)
}

/// Inserts a key-value pair into the map.
#[inline]
pub fn insert(&mut self, key: &K, value: &V, flags: u64) -> Result<(), c_long> {
insert(&mut self.def, key, value, flags)
}

/// Removes a key from the map.
#[inline]
pub fn remove(&mut self, key: &K) -> Result<(), c_long> {
remove(&mut self.def, key)
Expand Down
6 changes: 6 additions & 0 deletions bpf/aya-bpf/src/maps/lpm_trie.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -30,6 +30,7 @@ impl<K> Key<K> {
}

impl<K, V> LpmTrie<K, V> {
/// Creates an `LpmTrie` map with the maximum number of elements.
pub const fn with_max_entries(max_entries: u32, flags: u32) -> LpmTrie<K, V> {
LpmTrie {
def: build_def::<K, V>(BPF_MAP_TYPE_LPM_TRIE, max_entries, flags, PinningType::None),
Expand All @@ -38,6 +39,8 @@ impl<K, V> LpmTrie<K, V> {
}
}

/// Creates an `LpmTrie` map pinned in the BPPFS filesystem, with the
/// maximum number of elements.
pub const fn pinned(max_entries: u32, flags: u32) -> LpmTrie<K, V> {
LpmTrie {
def: build_def::<K, V>(
Expand All @@ -51,6 +54,7 @@ impl<K, V> LpmTrie<K, V> {
}
}

/// Returns a copy of the value associated with the key.
#[inline]
pub fn get(&mut self, key: &Key<K>) -> Option<&V> {
unsafe {
Expand All @@ -63,6 +67,7 @@ impl<K, V> LpmTrie<K, V> {
}
}

/// Inserts a key-value pair into the map.
#[inline]
pub fn insert(&mut self, key: &Key<K>, value: &V, flags: u64) -> Result<(), c_long> {
let ret = unsafe {
Expand All @@ -76,6 +81,7 @@ impl<K, V> LpmTrie<K, V> {
(ret >= 0).then(|| ()).ok_or(ret)
}

/// Removes a key from the map.
#[inline]
pub fn remove(&mut self, key: &Key<K>) -> Result<(), c_long> {
let ret = unsafe {
Expand Down
39 changes: 39 additions & 0 deletions bpf/aya-bpf/src/maps/mod.rs
View file
Original file line number Diff line number Diff line change
@@ -1,3 +1,42 @@
//! Data structures used to store eBPF programs data and share them with the
//! user space.
//!
//! The eBPF platform provides data structures - maps in eBPF speak - that are
//! used store data and share it with the user space. When you define a static
//! variable of a map type (i.e. [`HashMap`](crate::maps::HashMap), that map gets
//! initialized during the eBPF object load into the kernel and is ready to
//! use by programs.
//!
//!
//! # Typed maps
//!
//! The eBPF API includes many map types each supporting different operations.
//!
//! Each type of map provides methods to access and modify the data in the map
//! (i.e. [`get`](crate::maps::HashMap::get), [`get_mut`](crate::maps::HashMap::get_mut),
//! [`insert`](crate::maps::HashMap::insert) and, [`remove`](crate::maps::HashMap::remove)).
//!
//! For example:
//!
//! ```no_run
//! # #![allow(dead_code)]
//! use aya_bpf::{macros::map, maps::HashMap};
//! # use aya_bpf::programs::LsmContext;
//!
//! #[map]
//! static mut MY_MAP: HashMap<u32, u32> = HashMap::with_max_entries(1024, 0);
//!
//! # unsafe fn try_test(ctx: &LsmContext) -> Result<i32, i32> {
//! let key: u32 = 13;
//! let value: u32 = 42;
//! MY_MAP.insert(&key, &value, 0).map_err(|e| e as i32)?;
//! # Ok(0)
//! # }
//! ```
//!
//! Please refer to documentation for each map type for more details.
#[repr(u32)]
#[derive(Copy, Clone, Debug, PartialEq)]
pub(crate) enum PinningType {
Expand Down
Loading

0 comments on commit be662d2

Please sign in to comment.