Improve docs, hide async features behind single async feature flag

Signed-off-by: jonas loeffelholz <jonas.loeffelholz@9elements.com>
Signed-off-by: Marvin Gudel <marvin.gudel@9elements.com>

Author: embediver

mctp-estack/Cargo.toml

@@ -34,5 +34,4 @@ default = ["log"]
 std = ["mctp/std"]
 log = ["dep:log"]
 defmt = ["mctp/defmt", "dep:defmt" ]
-embassy = ["dep:embassy-sync", "async"]
-async = ["dep:embedded-io-async"]
+async = ["dep:embedded-io-async", "dep:embassy-sync"]

mctp-estack/src/control.rs

@@ -7,9 +7,9 @@
 //! MCTP Control Protocol implementation
 
 use crate::fmt::*;
-#[cfg(feature = "embassy")]
+#[cfg(feature = "async")]
 use crate::Router;
-#[cfg(feature = "embassy")]
+#[cfg(feature = "async")]
 use mctp::{AsyncRespChannel, MsgIC};
 use mctp::{Eid, Error, Listener, MsgType};
 use uuid::Uuid;
@@ -194,9 +194,9 @@ pub struct MctpControlMsg<'a> {
     work: [u8; 2],
 }
 
-#[cfg(feature = "embassy")]
+#[cfg(feature = "async")]
 const MAX_MSG_SIZE: usize = 20; /* largest is Get Endpoint UUID */
-#[cfg(feature = "embassy")]
+#[cfg(feature = "async")]
 const MAX_MSG_TYPES: usize = 8;
 
 impl<'a> MctpControlMsg<'a> {
@@ -429,15 +429,15 @@ where
 }
 
 /// A Control Message handler.
-#[cfg(feature = "embassy")]
+#[cfg(feature = "async")]
 pub struct MctpControl<'g, 'r> {
     rsp_buf: [u8; MAX_MSG_SIZE],
     types: heapless::Vec<MsgType, MAX_MSG_TYPES>,
     uuid: Option<Uuid>,
     router: &'g Router<'r>,
 }
 
-#[cfg(feature = "embassy")]
+#[cfg(feature = "async")]
 impl<'g, 'r> MctpControl<'g, 'r> {
     /// Create a new instance.
     pub fn new(router: &'g Router<'r>) -> Self {

mctp-estack/src/lib.rs

@@ -5,26 +5,22 @@
 
 //! # MCTP Stack
 //!
-//! This crate provides a MCTP stack that can be embedded in other programs
-//! or devices.
-//! A `async` Router for embassy based applications is available
-//! through the `embassy` feature.
-//!
-//! A [`Router`] object lets programs use a [`Stack`] with
-//! MCTP transport binding links. Each *Port* handles transmitting and receiving
-//! packets independently. Messages destined for the stack's own EID will
-//! be passed to applications.
-//!
-//! Applications can create [`router::RouterAsyncListener`] and [`router::RouterAsyncReqChannel`]
-//! instances to communicate over MCTP. Those implement the standard [`mctp` crate](mctp)
-//! async traits.
+//! This crate provides a MCTP stack and transport bindings,
+//! that can be embedded in other programs or devices.
 //!
 //! The IO-less [`Stack`] handles MCTP message formatting and parsing, independent
 //! of any particular MCTP transport binding.
 //!
+//! A Router for *async* applications is available
+//! through the `async` feature.
+//! The async `Router` lets programs use a `Stack`
+//! by providing implementations for the standard [`mctp` crate](mctp) async traits.
+//! Transport bindings are provided by *Ports* which handle transmitting and receiving
+//! packets independently. Messages destined for the stack's own EID will
+//! be passed to applications.
+//!
 //! ## Features
-//! - `embassy`: async `Router` for [Embassy](https://embassy.dev/)
-//! - `async`: [embedded-io-async](https://docs.rs/embedded-io-async/0.6.1/embedded_io_async/) serial transport binding (enabled by `embassy` feature)
+//! - `async`: [embedded-io-async](https://docs.rs/embedded-io-async/0.6.1/embedded_io_async/) serial transport binding and async Router
 //!
 //! ## Configuration
 //!
@@ -40,6 +36,7 @@
 // defmt does not currently allow inline format arguments, so we don't want
 // those reworked when using the log crate either.
 #![allow(clippy::uninlined_format_args)]
+#![cfg_attr(docsrs, feature(doc_auto_cfg))]
 
 #[cfg(test)]
 #[macro_use]
@@ -66,22 +63,22 @@ pub mod control;
 pub mod fragment;
 pub mod i2c;
 mod reassemble;
-#[cfg(feature = "embassy")]
+#[cfg(feature = "async")]
 pub mod router;
 pub mod serial;
 pub mod usb;
 #[macro_use]
 mod util;
 mod proto;
 
-#[cfg(feature = "embassy")]
+#[cfg(feature = "async")]
 #[rustfmt::skip]
 #[allow(clippy::needless_lifetimes)]
 mod zerocopy_channel;
 
 use fragment::{Fragmenter, SendOutput};
 use reassemble::Reassembler;
-#[cfg(feature = "embassy")]
+#[cfg(feature = "async")]
 pub use router::Router;
 
 use crate::fmt::*;

mctp-estack/src/serial.rs

@@ -12,10 +12,10 @@ use mctp::{Error, Result};
 use crc::Crc;
 use heapless::Vec;
 
-#[cfg(feature = "embassy")]
+#[cfg(feature = "async")]
 use embedded_io_async::{Read, Write};
 
-#[cfg(not(feature = "embassy"))]
+#[cfg(not(feature = "async"))]
 use embedded_io::{Read, Write};
 
 const MCTP_SERIAL_REVISION: u8 = 0x01;
@@ -72,7 +72,7 @@ impl MctpSerialHandler {
     /// Read a frame.
     ///
     /// This is async cancel-safe.
-    #[cfg(feature = "embassy")]
+    #[cfg(feature = "async")]
     pub async fn recv_async(&mut self, input: &mut impl Read) -> Result<&[u8]> {
         // TODO: This reads one byte a time, might need a buffering wrapper
         // for performance. Will require more thought about cancel-safety
@@ -103,7 +103,7 @@ impl MctpSerialHandler {
 
     /// Read a frame synchronously.
     /// This function blocks until at least one byte is available
-    #[cfg(not(feature = "embassy"))]
+    #[cfg(not(feature = "async"))]
     pub fn recv(&mut self, input: &mut impl Read) -> Result<&[u8]> {
         // TODO: This reads one byte a time, might need a buffering wrapper
         // for performance. Will require more thought about cancel-safety
@@ -220,7 +220,7 @@ impl MctpSerialHandler {
     }
 
     /// Asynchronously send a MCTP packet over serial provided by `output`.
-    #[cfg(feature = "embassy")]
+    #[cfg(feature = "async")]
     pub async fn send_async(
         &mut self,
         pkt: &[u8],
@@ -232,7 +232,7 @@ impl MctpSerialHandler {
     }
 
     /// Synchronously send a MCTP packet over serial provided by `output`.
-    #[cfg(not(feature = "embassy"))]
+    #[cfg(not(feature = "async"))]
     pub fn send_sync(
         &mut self,
         pkt: &[u8],
@@ -242,7 +242,7 @@ impl MctpSerialHandler {
     }
 
     /// Frame a MCTP packet into a serial frame, writing to `output`.
-    #[cfg(feature = "embassy")]
+    #[cfg(feature = "async")]
     async fn frame_to_serial<W>(
         p: &[u8],
         output: &mut W,
@@ -267,7 +267,7 @@ impl MctpSerialHandler {
     }
 
     /// Frame a MCTP packet into a serial frame, writing to `output`.
-    #[cfg(not(feature = "embassy"))]
+    #[cfg(not(feature = "async"))]
     fn frame_to_serial<W>(
         p: &[u8],
         output: &mut W,
@@ -292,7 +292,7 @@ impl MctpSerialHandler {
     }
 
     /// Asynchronously write a byte slice to `output`, escaping 0x7e and 0x7d bytes.
-    #[cfg(feature = "embassy")]
+    #[cfg(feature = "async")]
     async fn write_escaped<W>(
         p: &[u8],
         output: &mut W,
@@ -320,7 +320,7 @@ impl MctpSerialHandler {
     }
 
     /// Synchronously write a byte slice to `output`, escaping 0x7e and 0x7d bytes.
-    #[cfg(not(feature = "embassy"))]
+    #[cfg(not(feature = "async"))]
     fn write_escaped<W>(
         p: &[u8],
         output: &mut W,
@@ -360,7 +360,7 @@ mod tests {
     use crate::*;
     use proptest::prelude::*;
 
-    #[cfg(feature = "embassy")]
+    #[cfg(feature = "async")]
     use embedded_io_adapters::futures_03::FromFutures;
 
     static TEST_DATA_ROUNTRIP: [&[u8]; 1] =
@@ -373,7 +373,7 @@ mod tests {
             .try_init();
     }
 
-    #[cfg(feature = "embassy")]
+    #[cfg(feature = "async")]
     async fn do_roundtrip_async(payload: &[u8]) {
         let mut esc = vec![];
         let mut s = FromFutures::new(&mut esc);
@@ -391,7 +391,7 @@ mod tests {
         debug_assert_eq!(payload, packet);
     }
 
-    #[cfg(not(feature = "embassy"))]
+    #[cfg(not(feature = "async"))]
     fn do_roundtrip_sync(payload: &[u8]) {
         start_log();
         let mut esc = vec![];
@@ -406,7 +406,7 @@ mod tests {
         debug_assert_eq!(payload, packet);
     }
 
-    #[cfg(feature = "embassy")]
+    #[cfg(feature = "async")]
     #[test]
     fn roundtrip_cases_async() {
         // Fixed testcases
@@ -418,7 +418,7 @@ mod tests {
         })
     }
 
-    #[cfg(not(feature = "embassy"))]
+    #[cfg(not(feature = "async"))]
     #[test]
     fn roundtrip_cases_sync() {
         start_log();
@@ -428,14 +428,14 @@ mod tests {
     }
 
     proptest! {
-        #[cfg(feature = "embassy")]
+        #[cfg(feature = "async")]
         #[test]
         fn roundtrip_escape_async(payload in proptest::collection::vec(0..255u8, 5..20)) {
             start_log();
             smol::block_on(do_roundtrip_async(&payload))
         }
 
-        #[cfg(not(feature = "embassy"))]
+        #[cfg(not(feature = "async"))]
         #[test]
         fn roundtrip_escape_sync(payload in proptest::collection::vec(0..255u8, 5..20)) {
             start_log();

mctp-estack/tests/roundtrip.rs

@@ -6,7 +6,7 @@
 // Roundtrip heavily relies on the router implementation that we currently have
 // to remove for a working synchronous implementaion.
 // For now, exclude the entire roundtrip test.
-#![cfg(feature = "embassy")]
+#![cfg(feature = "async")]
 
 #[allow(unused)]
 use log::{debug, error, info, trace, warn};

standalone/Cargo.toml

@@ -10,7 +10,7 @@ categories = ["network-programming"]
 [dependencies]
 embedded-io-async = { workspace = true }
 log = { workspace = true }
-mctp-estack = { workspace = true, default-features = true }
+mctp-estack = { workspace = true, default-features = true, features = ["async"] }
 mctp = { workspace = true }
 smol = { workspace = true }