aya-bpf: Add docs to map types and methods

Signed-off-by: Michal Rostecki <vadorovsky@gmail.com>

bpf/aya-bpf/src/maps/array.rs

@@ -8,6 +8,20 @@ use crate::{
     maps::PinningType,
 };
 
+/// A fixed-size array 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::Array};
+///
+/// #[map]
+/// static MY_ARRAY: Array<u32> = Array::with_max_entries(1024, 0);
+/// ```
 #[repr(transparent)]
 pub struct Array<T> {
     def: UnsafeCell<bpf_map_def>,

bpf/aya-bpf/src/maps/hash_map.rs

@@ -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 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: UnsafeCell<bpf_map_def>,
@@ -21,6 +43,16 @@ pub struct HashMap<K, V> {
 unsafe impl<K: Sync, V: Sync> Sync for HashMap<K, V> {}
 
 impl<K, V> HashMap<K, V> {
+    /// Creates a `HashMap` with the maximum number of elements.
+    ///
+    /// # Examples
+    ///
+    /// ```no_run
+    /// use aya_bpf::{macros::map, maps::HashMap};
+    ///
+    /// #[map]
+    /// static mut MY_MAP: HashMap<u32, u32> = HashMap::with_max_entries(1024, 0);
+    /// ```
     pub const fn with_max_entries(max_entries: u32, flags: u32) -> HashMap<K, V> {
         HashMap {
             def: UnsafeCell::new(build_def::<K, V>(
@@ -34,6 +66,17 @@ impl<K, V> HashMap<K, V> {
         }
     }
 
+    /// Creates an empty `HashMap<K, V>` with the specified maximum number of
+    /// elements, and pins it to the BPF file system (BPFFS).
+    ///
+    /// # Examples
+    ///
+    /// ```no_run
+    /// use aya_bpf::{macros::map, maps::HashMap};
+    ///
+    /// #[map]
+    /// static mut MY_MAP: HashMap<u32, u32> = HashMap::pinned(1024, 0);
+    /// ```
     pub const fn pinned(max_entries: u32, flags: u32) -> HashMap<K, V> {
         HashMap {
             def: UnsafeCell::new(build_def::<K, V>(
@@ -52,12 +95,33 @@ impl<K, V> HashMap<K, V> {
     /// make guarantee on the atomicity of `insert` or `remove`, and any element removed from the
     /// map might get aliased by another element in the map, causing garbage to be read, or
     /// corruption in case of writes.
+    ///
+    /// # Examples
+    ///
+    /// ```no_run
+    /// use aya_bpf::{macros::map, maps::HashMap};
+    /// # use aya_bpf::programs::XdpContext;
+    ///
+    /// #[map]
+    /// static REDIRECT_PORTS: HashMap<u16, u16> = HashMap::with_max_entries(1024, 0);
+    ///
+    /// # fn parse_source(ctx: &XdpContext) -> u16 { 0 }
+    /// # fn try_test(ctx: &XdpContext) -> Result<i32, i32> {
+    /// // Source port of the packet.
+    /// let source: u16 = parse_source(&ctx);
+    /// // Port to which we want redirect the packet to.
+    /// let redirect = MY_MAP.get(&source);
+    ///
+    /// // Redirect the packet.
+    /// # Ok(0)
+    /// # }
+    /// ```
     #[inline]
     pub unsafe fn get(&self, key: &K) -> Option<&V> {
         get(self.def.get(), key)
     }
 
-    /// Retrieve the value associate with `key` from the map.
+    /// Retrieves the value associate with `key` from the map.
     /// The same caveat as `get` applies, but this returns a raw pointer and it's up to the caller
     /// to decide whether it's safe to dereference the pointer or not.
     #[inline]
@@ -65,7 +129,7 @@ impl<K, V> HashMap<K, V> {
         get_ptr(self.def.get(), key)
     }
 
-    /// Retrieve the value associate with `key` from the map.
+    /// Retrieves the value associate with `key` from the map.
     /// The same caveat as `get` applies, and additionally cares should be taken to avoid
     /// concurrent writes, but it's up to the caller to decide whether it's safe to dereference the
     /// pointer or not.
@@ -74,11 +138,47 @@ impl<K, V> HashMap<K, V> {
         get_ptr_mut(self.def.get(), key)
     }
 
+    /// Inserts a key-value pair into the map.
+    ///
+    /// # Examples
+    ///
+    /// ```no_run
+    /// use aya_bpf::{macros::map, maps::HashMap};
+    /// # use aya_bpf::programs::TracePointContext;
+    ///
+    /// #[map]
+    /// static PID_TO_TGID: HashMap<u32, u32> = HashMap::with_max_entries(1024, 0);
+    ///
+    /// # unsafe fn try_test(ctx: &LsmContext) -> Result<i32, i32> {
+    /// let pid: u32 = 13;
+    /// let tgid: u32 = 42;
+    /// PID_TO_TGID.insert(&pid, &tgid, 0).map_err(|e| e as i32)?;
+    /// # Ok(0)
+    /// # }
+    /// ```
     #[inline]
     pub fn insert(&self, key: &K, value: &V, flags: u64) -> Result<(), c_long> {
         insert(self.def.get(), key, value, flags)
     }
 
+    /// Removes a key-value pair from the map.
+    ///
+    /// # Examples
+    ///
+    /// ```no_run
+    /// use aya_bpf::{macros::map, maps::HashMap};
+    /// # use aya_bpf::programs::TracePointContext;
+    ///
+    /// #[map]
+    /// PROCESSES: HashMap<u32, u32> = HashMap::with_max_entries(1024, 0);
+    ///
+    /// # fn try_test(ctx: &TracePointContext) -> Result<i32, i32> {
+    /// let pid: u32 = ctx.pid();
+    /// // Remove the currently exiting process from the map.
+    /// PROCESSES.remove(&pid).map_err(|e| e as i32)?;
+    /// # Ok(0)
+    /// # }
+    /// ```
     #[inline]
     pub fn remove(&self, key: &K) -> Result<(), c_long> {
         remove(self.def.get(), key)
@@ -95,6 +195,7 @@ pub struct LruHashMap<K, V> {
 unsafe impl<K: Sync, V: Sync> Sync for 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: UnsafeCell::new(build_def::<K, V>(
@@ -108,6 +209,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: UnsafeCell::new(build_def::<K, V>(
@@ -148,17 +251,45 @@ impl<K, V> LruHashMap<K, V> {
         get_ptr_mut(self.def.get(), key)
     }
 
+    /// Returns a mutable copy of the value associated with the key.
     #[inline]
     pub fn insert(&self, key: &K, value: &V, flags: u64) -> Result<(), c_long> {
         insert(self.def.get(), key, value, flags)
     }
 
+    /// Inserts a key-value pair into the map.
     #[inline]
     pub fn remove(&self, key: &K) -> Result<(), c_long> {
         remove(self.def.get(), 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 PID_COUNTER: PerCpuHashMap<u32, u32> = PerCpuHashMap::with_max_entries(1024, 0);
+///
+/// # unsafe fn try_test(ctx: &LsmContext) -> Result<i32, i32> {
+/// let pid = ctx.pid();
+/// PID_COUNTER.insert(&key, &value, 0).map_err(|e| e as i32)?;
+/// # Ok(0)
+/// # }
+/// ```
 #[repr(transparent)]
 pub struct PerCpuHashMap<K, V> {
     def: UnsafeCell<bpf_map_def>,
@@ -169,6 +300,7 @@ pub struct PerCpuHashMap<K, V> {
 unsafe impl<K, V> Sync for 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: UnsafeCell::new(build_def::<K, V>(
@@ -182,6 +314,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: UnsafeCell::new(build_def::<K, V>(
@@ -222,11 +356,13 @@ impl<K, V> PerCpuHashMap<K, V> {
         get_ptr_mut(self.def.get(), key)
     }
 
+    /// Returns a mutable copy of the value associated with the key.
     #[inline]
     pub fn insert(&self, key: &K, value: &V, flags: u64) -> Result<(), c_long> {
         insert(self.def.get(), key, value, flags)
     }
 
+    /// Inserts a key-value pair into the map.
     #[inline]
     pub fn remove(&self, key: &K) -> Result<(), c_long> {
         remove(self.def.get(), key)
@@ -243,6 +379,7 @@ pub struct LruPerCpuHashMap<K, V> {
 unsafe impl<K, V> Sync for 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: UnsafeCell::new(build_def::<K, V>(
@@ -256,6 +393,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: UnsafeCell::new(build_def::<K, V>(
@@ -296,11 +435,13 @@ impl<K, V> LruPerCpuHashMap<K, V> {
         get_ptr_mut(self.def.get(), key)
     }
 
+    /// Returns a mutable copy of the value associated with the key.
     #[inline]
     pub fn insert(&self, key: &K, value: &V, flags: u64) -> Result<(), c_long> {
         insert(self.def.get(), key, value, flags)
     }
 
+    /// Inserts a key-value pair into the map.
     #[inline]
     pub fn remove(&self, key: &K) -> Result<(), c_long> {
         remove(self.def.get(), key)

bpf/aya-bpf/src/maps/lpm_trie.rs

@@ -33,6 +33,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> {
         let flags = flags | BPF_F_NO_PREALLOC;
         LpmTrie {
@@ -47,6 +48,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> {
         let flags = flags | BPF_F_NO_PREALLOC;
         LpmTrie {
@@ -61,6 +64,7 @@ impl<K, V> LpmTrie<K, V> {
         }
     }
 
+    /// Returns a copy of the value associated with the key.
     #[inline]
     pub fn get(&self, key: &Key<K>) -> Option<&V> {
         unsafe {
@@ -71,6 +75,7 @@ impl<K, V> LpmTrie<K, V> {
         }
     }
 
+    /// Inserts a key-value pair into the map.
     #[inline]
     pub fn insert(&self, key: &Key<K>, value: &V, flags: u64) -> Result<(), c_long> {
         let ret = unsafe {
@@ -84,6 +89,7 @@ impl<K, V> LpmTrie<K, V> {
         (ret == 0).then_some(()).ok_or(ret)
     }
 
+    /// Removes a key from the map.
     #[inline]
     pub fn remove(&self, key: &Key<K>) -> Result<(), c_long> {
         let ret = unsafe {

bpf/aya-bpf/src/maps/mod.rs

@@ -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_ptr_mut`](crate::maps::HashMap::get_ptr_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::TracePointContext;
+//!
+//! #[map]
+//! static PID_TO_TGID: HashMap<u32, u32> = HashMap::with_max_entries(1024, 0);
+//!
+//! # fn try_test(ctx: &TracePointContext) -> Result<i32, i32> {
+//! let pid: u32 = ctx.pid();
+//! let tgid: u32 = ctx.tgid();
+//! PID_TO_TGID.insert(&pid, &tgid, 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, Eq)]
 pub(crate) enum PinningType {

bpf/aya-bpf/src/maps/perf/perf_event_array.rs

@@ -7,6 +7,40 @@ use crate::{
     BpfContext,
 };
 
+/// An array for pushing out custom event data (as a struct defined by
+/// developer) to user space.
+///
+/// # Minimum kernel version
+///
+/// The minimum kernel version for this feature is 4.3.
+///
+/// # Examples
+///
+/// ```no_run
+/// use aya_bpf::{macros::map, maps::PerfEventArray};
+/// use aya_bpf::programs::XdpContext};
+///
+/// #[repr(C)]
+/// #[derive(Clone, Copy)]
+/// pub struct PacketLog {
+///     pub ipv4_address: u32,
+///     pub port: u32,
+/// }
+///
+/// #[map]
+/// static EVENTS: PerfEventArray<PacketLog> = PerfEventArray::with_max_entries(1024, 0);
+///
+/// # unsafe fn try_test(ctx: &XdpContext) -> Result<i32, i32> {
+/// let ipv4_address = parse_source_ipv4_address(&ctx.data);
+/// let port = parse_source_port(&ctx.data);
+/// let packet_log = Entry {
+///    ipv4_address,
+///    port,
+/// };
+/// EVENTS.output(ctx, &packet_log, 0);
+/// # Ok(0)
+/// # }
+/// ```
 #[repr(transparent)]
 pub struct PerfEventArray<T> {
     def: UnsafeCell<bpf_map_def>,
@@ -20,6 +54,7 @@ impl<T> PerfEventArray<T> {
         PerfEventArray::with_max_entries(0, flags)
     }
 
+    /// Creates an `PerfEventArray` with the maximum number of elements.
     pub const fn with_max_entries(max_entries: u32, flags: u32) -> PerfEventArray<T> {
         PerfEventArray {
             def: UnsafeCell::new(bpf_map_def {
@@ -35,6 +70,8 @@ impl<T> PerfEventArray<T> {
         }
     }
 
+    /// Creates an `PerfEventArray` pinned in the BPPFS filesystem, with the
+    /// maximum number of elements.
     pub const fn pinned(max_entries: u32, flags: u32) -> PerfEventArray<T> {
         PerfEventArray {
             def: UnsafeCell::new(bpf_map_def {
@@ -50,10 +87,31 @@ impl<T> PerfEventArray<T> {
         }
     }
 
+    /// Outputs the given event to the array.
+    ///
+    /// ```no_run
+    /// use aya_bpf::{macros::map, maps::PerfEventArray};
+    /// # use aya_bpf::programs::LsmContext;
+    ///
+    /// #[repr(C)]
+    /// pub struct Entry {
+    ///     pub some_field: u32,
+    /// }
+    ///
+    /// #[map]
+    /// static mut EVENTS: PerfEventArray<Entry> = PerfEventArray::<Entry>::with_max_entries(1024, 0);
+    ///
+    /// # unsafe fn try_test(ctx: &LsmContext) -> Result<i32, i32> {
+    /// let entry = Entry { some_field: 42 };
+    /// EVENTS.output(ctx, &entry, 0);
+    /// # Ok(0)
+    /// # }
+    /// ```
     pub fn output<C: BpfContext>(&self, ctx: &C, data: &T, flags: u32) {
         self.output_at_index(ctx, BPF_F_CURRENT_CPU as u32, data, flags)
     }
 
+    /// Outputs the given event to the array at the given index.
     pub fn output_at_index<C: BpfContext>(&self, ctx: &C, index: u32, data: &T, flags: u32) {
         let flags = (flags as u64) << 32 | index as u64;
         unsafe {

bpf/aya-bpf/src/maps/sock_hash.rs

@@ -21,7 +21,10 @@ pub struct SockHash<K> {
 
 unsafe impl<K: Sync> Sync for SockHash<K> {}
 
+/// A hash map that stores sockets to which messages or socket buffers can be
+/// redirected.
 impl<K> SockHash<K> {
+    /// Creates a `SockHash` map with the maximum number of elements.
     pub const fn with_max_entries(max_entries: u32, flags: u32) -> SockHash<K> {
         SockHash {
             def: UnsafeCell::new(bpf_map_def {
@@ -37,6 +40,8 @@ impl<K> SockHash<K> {
         }
     }
 
+    /// Creates a `SockHash` map pinned in the BPPFS filesystem, with the
+    /// maximum number of elements.
     pub const fn pinned(max_entries: u32, flags: u32) -> SockHash<K> {
         SockHash {
             def: UnsafeCell::new(bpf_map_def {
@@ -52,7 +57,14 @@ impl<K> SockHash<K> {
         }
     }
 
-    pub fn update(&self, key: &mut K, sk_ops: &mut bpf_sock_ops, flags: u64) -> Result<(), i64> {
+    /// Adds an entry or updates an existing one in the map referencing
+    /// sockets.
+    pub fn update(
+        &self,
+        key: &mut K,
+        sk_ops: &mut bpf_sock_ops,
+        flags: u64,
+    ) -> Result<(), i64> {
         let ret = unsafe {
             bpf_sock_hash_update(
                 sk_ops as *mut _,
@@ -64,6 +76,7 @@ impl<K> SockHash<K> {
         (ret == 0).then_some(()).ok_or(ret)
     }
 
+    /// Redirects a message to the socket associated with the given key.
     pub fn redirect_msg(&self, ctx: &SkMsgContext, key: &mut K, flags: u64) -> i64 {
         unsafe {
             bpf_msg_redirect_hash(
@@ -75,6 +88,7 @@ impl<K> SockHash<K> {
         }
     }
 
+    /// Redirects a socket buffer to the socket associated with the given key.
     pub fn redirect_skb(&self, ctx: &SkBuffContext, key: &mut K, flags: u64) -> i64 {
         unsafe {
             bpf_sk_redirect_hash(