Merge pull request #157 from dave-tucker/doc-aya

aya: document the public api

aya/src/bpf.rs

@@ -192,6 +192,7 @@ impl<'a> BpfLoader<'a> {
     /// Sets the base directory path for pinned maps.
     ///
     /// Pinned maps will be loaded from `path/MAP_NAME`.
+    /// The caller is responsible for ensuring the directory exists.
     ///
     /// # Example
     ///
@@ -705,38 +706,57 @@ impl Bpf {
 /// The error type returned by [`Bpf::load_file`] and [`Bpf::load`].
 #[derive(Debug, Error)]
 pub enum BpfError {
+    /// Error loading file
     #[error("error loading {path}")]
     FileError {
+        /// The file path
         path: PathBuf,
         #[source]
+        /// The original io::Error
         error: io::Error,
     },
 
+    /// Pinning requested but no path provided
     #[error("pinning requested but no path provided")]
     NoPinPath,
 
+    /// Unexpected pinning type
     #[error("unexpected pinning type {name}")]
-    UnexpectedPinningType { name: u32 },
+    UnexpectedPinningType {
+        /// The value encountered
+        name: u32,
+    },
 
+    /// Invalid path
     #[error("invalid path `{error}`")]
-    InvalidPath { error: String },
+    InvalidPath {
+        /// The error message
+        error: String,
+    },
 
+    /// Error parsing BPF object
     #[error("error parsing BPF object")]
     ParseError(#[from] ParseError),
 
+    /// Error parsing BTF object
     #[error("BTF error")]
     BtfError(#[from] BtfError),
 
+    /// Error performing relocations
     #[error("error relocating `{function}`")]
     RelocationError {
+        /// The function name
         function: String,
         #[source]
+        /// The original error
         error: Box<dyn Error + Send + Sync>,
     },
 
     #[error("map error")]
+    /// A map error
     MapError(#[from] MapError),
 
     #[error("program error")]
+    /// A program error
     ProgramError(#[from] ProgramError),
 }

aya/src/generated/mod.rs

@@ -1,4 +1,10 @@
-#![allow(dead_code, non_camel_case_types, non_snake_case, clippy::all)]
+#![allow(
+    dead_code,
+    non_camel_case_types,
+    non_snake_case,
+    clippy::all,
+    missing_docs
+)]
 
 mod btf_internal_bindings;
 #[cfg(target_arch = "aarch64")]

aya/src/lib.rs

@@ -29,7 +29,7 @@
 //!
 //! [tokio]: https://docs.rs/tokio
 //! [async-std]: https://docs.rs/async-std
-#![deny(clippy::all)]
+#![deny(clippy::all, missing_docs)]
 #![allow(clippy::missing_safety_doc, clippy::len_without_is_empty)]
 
 #[macro_use]

aya/src/maps/mod.rs

@@ -66,75 +66,142 @@ pub use stack::Stack;
 pub use stack_trace::StackTraceMap;
 
 #[derive(Error, Debug)]
+/// Errors occuring from working with Maps
 pub enum MapError {
+    /// Unable to find the map
     #[error("map `{name}` not found ")]
-    MapNotFound { name: String },
+    MapNotFound {
+        /// Map name
+        name: String,
+    },
 
+    /// Invalid map type encontered
     #[error("invalid map type {map_type}")]
-    InvalidMapType { map_type: u32 },
+    InvalidMapType {
+        /// The map type
+        map_type: u32,
+    },
 
+    /// Invalid map name encountered
     #[error("invalid map name `{name}`")]
-    InvalidName { name: String },
+    InvalidName {
+        /// The map name
+        name: String,
+    },
 
+    /// Pin path is invalid
     #[error("invalid map path `{error}`")]
-    InvalidPinPath { error: String },
+    InvalidPinPath {
+        /// The error message
+        error: String,
+    },
 
+    /// The map has not been created
     #[error("the map has not been created")]
     NotCreated,
 
+    /// The map has already been created
     #[error("the map `{name}` has already been created")]
-    AlreadyCreated { name: String },
+    AlreadyCreated {
+        /// Map name
+        name: String,
+    },
 
+    /// The map has already been pinned
     #[error("the map `{name}` has already been pinned")]
-    AlreadyPinned { name: String },
+    AlreadyPinned {
+        /// Map name
+        name: String,
+    },
 
+    /// Failed to create map
     #[error("failed to create map `{name}` with code {code}")]
     CreateError {
+        /// Map name
         name: String,
+        /// Error code
         code: libc::c_long,
         #[source]
+        /// Original io::Error
         io_error: io::Error,
     },
 
+    /// Failed to pin map
     #[error("failed to pin map `{name}` with code {code}")]
     PinError {
+        /// Map Name
         name: String,
+        /// Error code
         code: libc::c_long,
         #[source]
+        /// Original io::Error
         io_error: io::Error,
     },
 
+    /// Invalid key size
     #[error("invalid key size {size}, expected {expected}")]
-    InvalidKeySize { size: usize, expected: usize },
+    InvalidKeySize {
+        /// Size encountered
+        size: usize,
+        /// Size expected
+        expected: usize,
+    },
 
+    /// Invalid value size
     #[error("invalid value size {size}, expected {expected}")]
-    InvalidValueSize { size: usize, expected: usize },
+    InvalidValueSize {
+        /// Size encountered
+        size: usize,
+        /// Size expected
+        expected: usize,
+    },
 
+    /// Index is out of bounds
     #[error("the index is {index} but `max_entries` is {max_entries}")]
-    OutOfBounds { index: u32, max_entries: u32 },
+    OutOfBounds {
+        /// Index accessed
+        index: u32,
+        /// Map size
+        max_entries: u32,
+    },
 
+    /// Key not found
     #[error("key not found")]
     KeyNotFound,
 
+    /// Element not found
     #[error("element not found")]
     ElementNotFound,
 
+    /// Progam Not Loaded
     #[error("the program is not loaded")]
     ProgramNotLoaded,
 
+    /// Syscall failed
     #[error("the `{call}` syscall failed with code {code}")]
     SyscallError {
+        /// Syscall Name
         call: String,
+        /// Error code
         code: libc::c_long,
         #[source]
+        /// Original io::Error
         io_error: io::Error,
     },
 
+    /// Map is borrowed mutably
     #[error("map `{name}` is borrowed mutably")]
-    BorrowError { name: String },
+    BorrowError {
+        /// Map name
+        name: String,
+    },
 
+    /// Map is already borrowed
     #[error("map `{name}` is already borrowed")]
-    BorrowMutError { name: String },
+    BorrowMutError {
+        /// Map name
+        name: String,
+    },
 }
 
 /// A generic handle to a BPF map.
@@ -144,10 +211,12 @@ pub enum MapError {
 pub struct Map {
     pub(crate) obj: obj::Map,
     pub(crate) fd: Option<RawFd>,
+    /// Indicates if this map has been pinned to bpffs
     pub pinned: bool,
 }
 
 impl Map {
+    /// Creates a new map with the provided `name`
     pub fn create(&mut self, name: &str) -> Result<RawFd, MapError> {
         if self.fd.is_some() {
             return Err(MapError::AlreadyCreated { name: name.into() });
@@ -196,6 +265,7 @@ impl Map {
         Ok(fd)
     }
 
+    /// Returns the [`bpf_map_type`] of this map
     pub fn map_type(&self) -> Result<bpf_map_type, MapError> {
         bpf_map_type::try_from(self.obj.def.map_type)
     }
@@ -234,9 +304,12 @@ impl Drop for Map {
     }
 }
 
+/// An iterable map
 pub trait IterableMap<K: Pod, V> {
+    /// Get a generic map handle
     fn map(&self) -> &Map;
 
+    /// Get the value for the provided `key`
     fn get(&self, key: &K) -> Result<V, MapError>;
 }
 

aya/src/maps/perf/perf_buffer.rs

@@ -24,11 +24,15 @@ use crate::{
 pub enum PerfBufferError {
     /// the page count value passed to [`PerfEventArray::open`](crate::maps::PerfEventArray::open) is invalid.
     #[error("invalid page count {page_count}, the value must be a power of two")]
-    InvalidPageCount { page_count: usize },
+    InvalidPageCount {
+        /// the page count
+        page_count: usize,
+    },
 
     /// `perf_event_open` failed.
     #[error("perf_event_open failed: {io_error}")]
     OpenError {
+        /// the source of this error
         #[source]
         io_error: io::Error,
     },
@@ -36,6 +40,7 @@ pub enum PerfBufferError {
     /// `mmap`-ping the buffer failed.
     #[error("mmap failed: {io_error}")]
     MMapError {
+        /// the source of this error
         #[source]
         io_error: io::Error,
     },
@@ -44,6 +49,7 @@ pub enum PerfBufferError {
     #[error("PERF_EVENT_IOC_ENABLE failed: {io_error}")]
     PerfEventEnableError {
         #[source]
+        /// the source of this error
         io_error: io::Error,
     },
 
@@ -54,7 +60,10 @@ pub enum PerfBufferError {
     /// `read_events()` was called with a buffer that is not large enough to
     /// contain the next event in the perf buffer.
     #[error("the buffer needs to be of at least {size} bytes")]
-    MoreSpaceNeeded { size: usize },
+    MoreSpaceNeeded {
+        /// expected size
+        size: usize,
+    },
 
     /// An IO error occurred.
     #[error(transparent)]

aya/src/maps/sock/mod.rs

@@ -8,6 +8,9 @@ use crate::maps::MapError;
 
 pub use sock_hash::SockHash;
 pub use sock_map::SockMap;
+
+/// Shared behaviour between [`SockHash`] and [`SockMap`]
 pub trait SocketMap {
+    /// Returns a [`Result`] containg the map fd or an error if there is none
     fn fd_or_err(&self) -> Result<RawFd, MapError>;
 }

aya/src/obj/btf/btf.rs

@@ -34,56 +34,98 @@ pub(crate) const MAX_SPEC_LEN: usize = 64;
 /// The error type returned when `BTF` operations fail.
 #[derive(Error, Debug)]
 pub enum BtfError {
+    /// Error parsing file
     #[error("error parsing {path}")]
     FileError {
+        /// file path
         path: PathBuf,
+        /// source of the error
         #[source]
         error: io::Error,
     },
 
+    /// Error parsing BTF header
     #[error("error parsing BTF header")]
     InvalidHeader,
 
+    /// invalid BTF type info segment
     #[error("invalid BTF type info segment")]
     InvalidTypeInfo,
 
+    /// invalid BTF relocation info segment
     #[error("invalid BTF relocation info segment")]
     InvalidRelocationInfo,
 
+    /// invalid BTF type kind
     #[error("invalid BTF type kind `{kind}`")]
-    InvalidTypeKind { kind: u32 },
+    InvalidTypeKind {
+        /// type kind
+        kind: u32,
+    },
 
+    /// invalid BTF relocation kind
     #[error("invalid BTF relocation kind `{kind}`")]
-    InvalidRelocationKind { kind: u32 },
+    InvalidRelocationKind {
+        /// type kind
+        kind: u32,
+    },
 
+    /// invalid BTF string offset
     #[error("invalid BTF string offset: {offset}")]
-    InvalidStringOffset { offset: usize },
+    InvalidStringOffset {
+        /// offset
+        offset: usize,
+    },
 
+    /// invalid BTF info
     #[error("invalid BTF info, offset: {offset} len: {len} section_len: {section_len}")]
     InvalidInfo {
+        /// offset
         offset: usize,
+        /// length
         len: usize,
+        /// section length
         section_len: usize,
     },
 
+    /// invalid BTF line infos
     #[error("invalid BTF line info, offset: {offset} len: {len} section_len: {section_len}")]
     InvalidLineInfo {
+        /// offset
         offset: usize,
+        /// length
         len: usize,
+        /// section length
         section_len: usize,
     },
 
+    /// unknown BTF type id
     #[error("Unknown BTF type id `{type_id}`")]
-    UnknownBtfType { type_id: u32 },
+    UnknownBtfType {
+        /// type id
+        type_id: u32,
+    },
 
+    /// unexpected btf type id
     #[error("Unexpected BTF type id `{type_id}`")]
-    UnexpectedBtfType { type_id: u32 },
+    UnexpectedBtfType {
+        /// type id
+        type_id: u32,
+    },
 
+    /// unknown BTF type
     #[error("Unknown BTF type `{type_name}`")]
-    UnknownBtfTypeName { type_name: String },
+    UnknownBtfTypeName {
+        /// type name
+        type_name: String,
+    },
 
+    /// maximum depth reached resolving BTF type
     #[error("maximum depth reached resolving BTF type")]
-    MaximumTypeDepthReached { type_id: u32 },
+    MaximumTypeDepthReached {
+        /// type id
+        type_id: u32,
+    },
 
     /// Loading the btf failed
     #[error("the BPF_BTF_LOAD syscall failed. Verifier output: {verifier_log}")]
@@ -95,15 +137,25 @@ pub enum BtfError {
         verifier_log: String,
     },
 
+    /// offset not found for symbol
     #[error("Offset not found for symbol `{symbol_name}`")]
-    SymbolOffsetNotFound { symbol_name: String },
+    SymbolOffsetNotFound {
+        /// name of the symbol
+        symbol_name: String,
+    },
 
+    /// btf type that is not VAR found in DATASEC
     #[error("BTF type that is not VAR was found in DATASEC")]
     InvalidDatasec,
 
+    /// unable to determine the size of section
     #[error("Unable to determine the size of section `{section_name}`")]
-    UnknownSectionSize { section_name: String },
+    UnknownSectionSize {
+        /// name of the section
+        section_name: String,
+    },
 
+    /// unable to get symbol name
     #[error("Unable to get symbol name")]
     InvalidSymbolName,
 }

aya/src/programs/extension.rs

@@ -14,6 +14,7 @@ use crate::{
 /// The type returned when loading or attaching an [`Extension`] fails
 #[derive(Debug, Error)]
 pub enum ExtensionError {
+    /// target BPF program does not have BTF loaded to the kernel
     #[error("target BPF program does not have BTF loaded to the kernel")]
     NoBTF,
 }

aya/src/programs/kprobe.rs

@@ -73,9 +73,12 @@ impl KProbe {
 /// The type returned when attaching a [`KProbe`] fails.
 #[derive(Debug, Error)]
 pub enum KProbeError {
+    /// Error detaching from debugfs
     #[error("`{filename}`")]
     FileError {
+        /// The file name
         filename: String,
+        /// The [`io::Error`] returned from the file operation
         #[source]
         io_error: io::Error,
     },

aya/src/programs/mod.rs

@@ -143,14 +143,21 @@ pub enum ProgramError {
 
     /// The network interface does not exist.
     #[error("unknown network interface {name}")]
-    UnknownInterface { name: String },
+    UnknownInterface {
+        /// interface name
+        name: String,
+    },
 
     /// The program is not of the expected type.
     #[error("unexpected program type")]
     UnexpectedProgramType,
 
+    /// Invalid pin path
     #[error("invalid pin path `{error}`")]
-    InvalidPinPath { error: String },
+    InvalidPinPath {
+        /// the error message
+        error: String,
+    },
 
     /// A map error occurred while loading or attaching a program.
     #[error(transparent)]
@@ -190,37 +197,63 @@ pub enum ProgramError {
 
     /// The program is not attached.
     #[error("the program name `{name}` is invalid")]
-    InvalidName { name: String },
+    InvalidName {
+        /// program name
+        name: String,
+    },
 
     /// The program is too long.
-    #[error("the program name `{name}` it longer than 16 characters")]
-    NameTooLong { name: String },
+    #[error("the program name `{name}` iss longer than 16 characters")]
+    NameTooLong {
+        /// program name
+        name: String,
+    },
 }
 
+/// Allows the Fd of a loaded [`Program`] to be retrieved
 pub trait ProgramFd {
+    /// Returns the [`RawFd`] of the program if it has been loaded, or `None`
     fn fd(&self) -> Option<RawFd>;
 }
 
 /// eBPF program type.
 #[derive(Debug)]
 pub enum Program {
+    /// A [`KProbe`] program
     KProbe(KProbe),
+    /// A [`UProbe`] program
     UProbe(UProbe),
+    /// A [`TracePoint`] program
     TracePoint(TracePoint),
+    /// A [`SocketFilter`] program
     SocketFilter(SocketFilter),
+    /// A [`Xdp`] program
     Xdp(Xdp),
+    /// A [`SkMsg`] program
     SkMsg(SkMsg),
+    /// A [`SkSkb`] program
     SkSkb(SkSkb),
+    /// A [`SockOps`] program
     SockOps(SockOps),
+    /// A [`SchedClassifier`] program
     SchedClassifier(SchedClassifier),
+    /// A [`CgroupSkb`] program
     CgroupSkb(CgroupSkb),
+    /// A [`LircMode2`] program
     LircMode2(LircMode2),
+    /// A [`PerfEvent`] program
     PerfEvent(PerfEvent),
+    /// A [`RawTracePoint`] program
     RawTracePoint(RawTracePoint),
+    /// A [`Lsm`] program
     Lsm(Lsm),
+    /// A [`BtfTracePoint`] program
     BtfTracePoint(BtfTracePoint),
+    /// A [`FEntry`] program
     FEntry(FEntry),
+    /// A [`FExit`] program
     FExit(FExit),
+    /// A [`Extension`] program
     Extension(Extension),
 }
 
@@ -492,6 +525,7 @@ pub(crate) fn query<T: AsRawFd>(
 
 /// Detach an attached program
 pub trait Link: std::fmt::Debug {
+    /// detaches an attached program
     fn detach(&mut self) -> Result<(), ProgramError>;
 }
 

aya/src/programs/perf_event.rs

@@ -12,31 +12,61 @@ pub use crate::generated::{
 
 use super::{load_program, perf_attach, LinkRef, ProgramData, ProgramError};
 
+/// The type of perf event
 #[repr(u32)]
 #[derive(Debug, Clone)]
 pub enum PerfTypeId {
+    /// PERF_TYPE_HARDWARE
     Hardware = PERF_TYPE_HARDWARE as u32,
+    /// PERF_TYPE_SOFTWARE
     Software = PERF_TYPE_SOFTWARE as u32,
+    /// PERF_TYPE_TRACEPOINT
     TracePoint = PERF_TYPE_TRACEPOINT as u32,
+    /// PERF_TYPE_HW_CACHE
     HwCache = PERF_TYPE_HW_CACHE as u32,
+    /// PERF_TYPE_RAW
     Raw = PERF_TYPE_RAW as u32,
+    /// PERF_TYPE_BREAKPOINT
     Breakpoint = PERF_TYPE_BREAKPOINT as u32,
 }
 
+/// Sample Policy
 #[derive(Debug, Clone)]
 pub enum SamplePolicy {
+    /// Period
     Period(u64),
+    /// Frequency
     Frequency(u64),
 }
 
+/// The scope of a PerfEvent
 #[derive(Debug, Clone)]
 #[allow(clippy::enum_variant_names)]
 pub enum PerfEventScope {
+    /// Calling process, any cpu
     CallingProcessAnyCpu,
-    CallingProcessOneCpu { cpu: u32 },
-    OneProcessAnyCpu { pid: u32 },
-    OneProcessOneCpu { cpu: u32, pid: u32 },
-    AllProcessesOneCpu { cpu: u32 },
+    /// calling process, one cpu
+    CallingProcessOneCpu {
+        /// cpu id
+        cpu: u32,
+    },
+    /// one process, any cpu
+    OneProcessAnyCpu {
+        /// process id
+        pid: u32,
+    },
+    /// one process, one cpu
+    OneProcessOneCpu {
+        /// cpu id
+        cpu: u32,
+        /// process id
+        pid: u32,
+    },
+    /// all processes, one cpu
+    AllProcessesOneCpu {
+        /// cpu id
+        cpu: u32,
+    },
 }
 
 /// A program that can be attached at a perf event.

aya/src/programs/probe.rs

@@ -14,6 +14,7 @@ use crate::{
     sys::{kernel_version, perf_event_open_probe, perf_event_open_trace_point},
 };
 
+/// Kind of probe program
 #[derive(Debug, Copy, Clone)]
 pub enum ProbeKind {
     /// Kernel probe

aya/src/programs/sk_skb.rs

@@ -11,7 +11,9 @@ use crate::{
 /// The kind of [`SkSkb`] program.
 #[derive(Copy, Clone, Debug)]
 pub enum SkSkbKind {
+    /// A Stream Parser
     StreamParser,
+    /// A Stream Verdict
     StreamVerdict,
 }
 

aya/src/programs/socket_filter.rs

@@ -16,6 +16,7 @@ pub enum SocketFilterError {
     /// Setting the `SO_ATTACH_BPF` socket option failed.
     #[error("setsockopt SO_ATTACH_BPF failed")]
     SoAttachBpfError {
+        /// original [`io::Error`]
         #[source]
         io_error: io::Error,
     },

aya/src/programs/tc.rs

@@ -76,13 +76,17 @@ pub struct SchedClassifier {
     pub(crate) name: Box<CStr>,
 }
 
+/// Errors from TC programs
 #[derive(Debug, Error)]
 pub enum TcError {
+    /// netlink error while attaching ebpf program
     #[error("netlink error while attaching ebpf program to tc")]
     NetlinkError {
+        /// the [`io::Error`] from the netlink call
         #[source]
         io_error: io::Error,
     },
+    /// the clsact qdisc is already attached
     #[error("the clsact qdisc is already attached")]
     AlreadyAttached,
 }

aya/src/programs/trace_point.rs

@@ -8,9 +8,12 @@ use super::{load_program, perf_attach, LinkRef, ProgramData, ProgramError};
 /// The type returned when attaching a [`TracePoint`] fails.
 #[derive(Debug, Error)]
 pub enum TracePointError {
+    /// Error detaching from debugfs
     #[error("`{filename}`")]
     FileError {
+        /// The file name
         filename: String,
+        /// The [`io::Error`] returned from the file operation
         #[source]
         io_error: io::Error,
     },

aya/src/programs/uprobe.rs

@@ -129,18 +129,24 @@ pub enum UProbeError {
     /// There was an error parsing `/etc/ld.so.cache`.
     #[error("error reading `{}` file", LD_SO_CACHE_FILE)]
     InvalidLdSoCache {
+        /// the original [`io::Error`]
         #[source]
         io_error: Arc<io::Error>,
     },
 
     /// The target program could not be found.
     #[error("could not resolve uprobe target `{path}`")]
-    InvalidTarget { path: PathBuf },
+    InvalidTarget {
+        /// path to target
+        path: PathBuf,
+    },
 
     /// There was an error resolving the target symbol.
     #[error("error resolving symbol")]
     SymbolError {
+        /// symbol name
         symbol: String,
+        /// the original error
         #[source]
         error: Box<dyn Error + Send + Sync>,
     },
@@ -148,7 +154,9 @@ pub enum UProbeError {
     /// There was an error accessing `filename`.
     #[error("`{filename}`")]
     FileError {
+        /// The file name
         filename: String,
+        /// The [`io::Error`] returned from the file operation
         #[source]
         io_error: io::Error,
     },

aya/src/programs/xdp.rs

@@ -17,8 +17,10 @@ use crate::{
 /// The type returned when attaching an [`Xdp`] program fails on kernels `< 5.9`.
 #[derive(Debug, Error)]
 pub enum XdpError {
+    /// netlink error while attaching XDP program
     #[error("netlink error while attaching XDP program")]
     NetlinkError {
+        /// the [`io::Error`] from the netlink call
         #[source]
         io_error: io::Error,
     },