Added doc comments for the entire public API.

Author: Frostie314159

examples/Cargo.lock

@@ -1,26 +1,23 @@
 [package]
 name = "foa"
-version = "0.1.0-alpha.0"
+version = "0.1.0"
 edition = "2021"
 
 [dependencies]
 embassy-sync = "0.7.0"
 embassy-futures = "0.1.1"
 
 esp-hal = "1.0.0-beta.1"
-# esp-wifi-hal = "0.1.2"
-# esp-wifi-hal = { git = "https://github.com/esp32-open-mac/esp-wifi-hal.git" }
-esp-wifi-hal = { path = "../../esp-wifi-hal/esp-wifi-hal" }
+esp-wifi-hal = "0.1.3"
 static_cell = "2.1.0"
 critical-section = "1.2.0"
 portable-atomic = "1.11.1"
 esp-config = "0.4.0"
 defmt-or-log = { version = "0.2.1", default-features = false }
 defmt = { version = "1.0.1", optional = true }
 embassy-time = "0.4.0"
-ieee80211 = { path = "../../../rust/ieee80211/" }
-# ieee80211 = { git = "https://github.com/Frostie314159/ieee80211-rs.git", branch = "crypto" }
 heapless = "0.8.0"
+ieee80211 = "0.5.7"
 
 [build-dependencies]
 esp-config = { version = "0.4.0", features = ["build"] }

foa/Cargo.lock

@@ -1,4 +1,5 @@
 #![no_std]
+#![deny(missing_docs)]
 //! # Ferris-on-Air (FoA)
 //! Ferris-on-Air is an asynchronous IEEE 802.11 MAC stack for the ESP32 series of chips. It is
 //! build on top of [esp_wifi_hal], which is the driver for the Wi-Fi peripheral, and is based on
@@ -64,13 +65,16 @@ pub mod util;
 const RX_BUFFER_COUNT: usize = esp_config_int!(usize, "FOA_CONFIG_RX_BUFFER_COUNT");
 const RX_QUEUE_LEN: usize = esp_config_int!(usize, "FOA_CONFIG_RX_QUEUE_LEN");
 const TX_BUFFER_COUNT: usize = esp_config_int!(usize, "FOA_CONFIG_TX_BUFFER_COUNT");
-// This is fixed, so that interfaces can rely on the size of a TX buffer.
+/// The size of a [TxBuffer].
+///
+/// This is fixed, so that interfaces can rely on the size of a TX buffer.
 pub const TX_BUFFER_SIZE: usize = 1600;
 
 /// A frame received from the driver.
 #[cfg(feature = "arc_buffers")]
 pub type ReceivedFrame<'res> = RxArcBuffer<'res>;
 #[cfg(not(feature = "arc_buffers"))]
+/// A frame received from the driver.
 pub type ReceivedFrame<'res> = BorrowedBuffer<'res>;
 /// A receiver to the RX queue of an interface.
 pub type RxQueueReceiver<'res> = DynamicReceiver<'res, ReceivedFrame<'res>>;
@@ -86,6 +90,10 @@ pub struct FoAResources {
     rx_queues: [Channel<NoopRawMutex, ReceivedFrame<'static>, RX_QUEUE_LEN>; WiFi::INTERFACE_COUNT],
 }
 impl FoAResources {
+    /// Create new stack resources.
+    ///
+    /// This has to be in internal RAM, since the DMA descriptors and buffers for the Wi-Fi driver
+    /// have to be in internal RAM.
     pub fn new() -> Self {
         Self {
             wifi_resources: WiFiResources::new(),
@@ -124,6 +132,9 @@ impl<'res> VirtualInterface<'res> {
     ) {
         (&mut self.interface_control, &mut self.rx_queue_receiver)
     }
+    /// Reset the virtual interface.
+    ///
+    /// This is releases any prior channel lock, resets all filters and clears the RX queue.
     pub fn reset(&mut self) {
         // We can't call clear on a DynamicReceiver, so this is the best we can do for now.
         // This isn't too bad, since this will only be called rarely and the RX queues shouldn't be

foa/Cargo.toml

@@ -8,12 +8,18 @@ use crate::{
 };
 
 #[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Hash, PartialOrd, Ord)]
+/// This specifies the order in which channels should be scanned.
 pub enum ScanStrategy<'a> {
+    /// Only a single channel should be scanned.
     Single(u8),
+    /// Only the current channel should be scanned.
     CurrentChannel,
+    /// Scan the channels in ascending order (i.e. 1-13).
     Linear,
     #[default]
+    /// Scan the channels in groups of three non overlapping channels (i.e. 1, 6, 11, 2, 7, 12 etc.).
     NonOverlappingFirst,
+    /// Use a custom channel sequence.
     Custom(&'a [u8]),
 }
 

foa/src/lib.rs

@@ -78,6 +78,10 @@ impl RxRouterQueue {
 ///
 /// It is expected, that frames like beacons and probe responses will be matched for this operation.
 pub trait HasScanOperation: RxRouterOperation {
+    /// Does a scan like router operation exist.
+    ///
+    /// At the moment, the requirement for this is, that all beacon frames will be matched by
+    /// that operation.
     const SCAN_OPERATION: Self;
 }
 
@@ -100,12 +104,15 @@ pub trait RxRouterOperation: Clone + Copy {
 
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
 #[derive(Clone, Copy, Debug, PartialEq, Eq, PartialOrd, Ord, Hash)]
-/// Errors returned by the RX router.
-pub enum RxRouterError {
+/// Errors related to router operations.
+pub enum RxRouterOperationError {
+    /// Another router operation is already in progress for this queue.
+    ///
+    /// This does not mean, that the request operation is incompatible with that of the other
+    /// queue. [Self::IncompatibleOperations] indicates this instead.
     OperationAlreadyInProgress,
+    /// The requested operation is incompatible with the one on the other queue.
     IncompatibleOperations,
-    QueueFull,
-    InvalidFrame,
 }
 
 /// Used for dynamic dispatch.
@@ -114,7 +121,7 @@ trait Router<'foa, Operation: RxRouterOperation> {
     fn receive(&self, router_queue: RxRouterQueue)
         -> DynamicReceiveFuture<'_, ReceivedFrame<'foa>>;
     //// Route a frame to a specific queue.
-    fn route_frame(&self, frame: ReceivedFrame<'foa>) -> Result<(), RxRouterError>;
+    fn route_frame(&self, frame: ReceivedFrame<'foa>) -> Result<(), RxRouterRoutingError>;
     /// Get the operation state for the specified [RxRouterQueue].
     fn operation_state(&self, router_queue: RxRouterQueue) -> &Cell<Option<Operation>>;
     /// Get the operation completion signal.
@@ -148,6 +155,15 @@ impl<const QUEUE_DEPTH: usize, O: RxRouterOperation> QueueState<'_, QUEUE_DEPTH,
         self.operation_state.get().is_some()
     }
 }
+#[cfg_attr(feature = "defmt", derive(defmt::Format))]
+#[derive(Clone, Copy, Debug, PartialEq, Eq, PartialOrd, Ord, Hash)]
+/// An error related to the routing of a received frame.
+pub enum RxRouterRoutingError {
+    /// The queue, that the frame was supposed to be routed to, is full.
+    QueueFull,
+    /// The frame could not parsed.
+    InvalidFrame,
+}
 
 /// The core of the RX router.
 ///
@@ -215,11 +231,11 @@ impl<'foa, const QUEUE_DEPTH: usize, Operation: RxRouterOperation> Router<'foa,
     ) -> DynamicReceiveFuture<'_, ReceivedFrame<'foa>> {
         self.queue_state(router_queue).queue.receive().into()
     }
-    fn route_frame(&self, frame: ReceivedFrame<'foa>) -> Result<(), RxRouterError> {
+    fn route_frame(&self, frame: ReceivedFrame<'foa>) -> Result<(), RxRouterRoutingError> {
         // Usually the RX handler will have already created a GenericFrame, however we can't
         // reasonably assume that, so we recreate it here and hope the compiler opimizes away.
         let Ok(generic_frame) = GenericFrame::new(frame.mpdu_buffer(), false) else {
-            return Err(RxRouterError::InvalidFrame);
+            return Err(RxRouterRoutingError::InvalidFrame);
         };
         let router_queue = if self
             .foreground_queue_state
@@ -239,7 +255,7 @@ impl<'foa, const QUEUE_DEPTH: usize, Operation: RxRouterOperation> Router<'foa,
         if self.queue_state(router_queue).queue.try_send(frame).is_ok() {
             Ok(())
         } else {
-            Err(RxRouterError::QueueFull)
+            Err(RxRouterRoutingError::QueueFull)
         }
     }
     fn operation_state(&self, router_queue: RxRouterQueue) -> &Cell<Option<Operation>> {
@@ -264,14 +280,17 @@ pub struct RxRouterInput<'foa, 'router, Operation: RxRouterOperation> {
 
 impl<'foa, Operation: RxRouterOperation> RxRouterInput<'foa, '_, Operation> {
     /// Route the provided frame to the correct queue.
-    pub fn route_frame(&self, frame: ReceivedFrame<'foa>) -> Result<(), RxRouterError> {
+    pub fn route_frame(&self, frame: ReceivedFrame<'foa>) -> Result<(), RxRouterRoutingError> {
         self.rx_router.route_frame(frame)
     }
+    /// Get the currently active operation for the specified [RxRouterQueue].
     pub fn operation(&self, router_queue: RxRouterQueue) -> Option<Operation> {
         self.rx_router.operation_state(router_queue).get()
     }
 }
 #[derive(Clone, Copy, Debug, Default, PartialEq, Eq, PartialOrd, Ord, Hash)]
+/// The requested operation transition is not possible, due to it being incompatible with another
+/// currently active operation.
 pub struct TransitionNotPossibleError;
 /// A scoped router operation.
 ///
@@ -329,16 +348,16 @@ impl<'foa, 'router, Operation: RxRouterOperation> RxRouterEndpoint<'foa, 'router
         self.rx_router.receive(self.router_queue)
     }
     /// Check if the operation can be started.
-    fn can_start_operation(&self, operation: Operation) -> Result<(), RxRouterError> {
+    fn can_start_operation(&self, operation: Operation) -> Result<(), RxRouterOperationError> {
         if let Some(opposing_operation) = self
             .rx_router
             .operation_state(self.router_queue.opposite())
             .get()
         {
             if !Operation::CONCORRUENT_OPERATIONS_SUPPORTED {
-                Err(RxRouterError::OperationAlreadyInProgress)
+                Err(RxRouterOperationError::OperationAlreadyInProgress)
             } else if !opposing_operation.compatible_with(&operation) {
-                Err(RxRouterError::IncompatibleOperations)
+                Err(RxRouterOperationError::IncompatibleOperations)
             } else {
                 Ok(())
             }
@@ -370,7 +389,7 @@ impl<'foa, 'router, Operation: RxRouterOperation> RxRouterEndpoint<'foa, 'router
     pub fn try_start_operation<'endpoint>(
         &'endpoint mut self,
         operation: Operation,
-    ) -> Result<RxRouterScopedOperation<'foa, 'router, 'endpoint, Operation>, RxRouterError> {
+    ) -> Result<RxRouterScopedOperation<'foa, 'router, 'endpoint, Operation>, RxRouterOperationError> {
         self.can_start_operation(operation)?;
         self.start_operation_internal(operation);
         Ok(RxRouterScopedOperation { endpoint: self })