11 files changed, 238 insertions, 27 deletions

diff --git a/embassy-net-driver-channel/Cargo.toml b/embassy-net-driver-channel/Cargo.toml
index e475551e1..bee2e3021 100644
--- a/embassy-net-driver-channel/Cargo.toml
+++ b/embassy-net-driver-channel/Cargo.toml
@@ -2,6 +2,14 @@
 name = "embassy-net-driver-channel"
 version = "0.1.0"
 edition = "2021"
+license = "MIT OR Apache-2.0"
+description = "High-level channel-based driver for the `embassy-net` async TCP/IP network stack."
+repository = "https://github.com/embassy-rs/embassy"
+categories = [
+    "embedded",
+    "no-std",
+    "asynchronous",
+]
 
 [package.metadata.embassy_docs]
 src_base = "https://github.com/embassy-rs/embassy/blob/embassy-net-driver-channel-v$VERSION/embassy-net-driver-channel/src/"
@@ -9,6 +17,9 @@ src_base_git = "https://github.com/embassy-rs/embassy/blob/$COMMIT/embassy-net-d
 features = ["defmt"]
 target = "thumbv7em-none-eabi"
 
+[package.metadata.docs.rs]
+features = ["defmt"]
+
 [dependencies]
 defmt = { version = "0.3", optional = true }
 log = { version = "0.4.14", optional = true }
diff --git a/embassy-net-driver-channel/README.md b/embassy-net-driver-channel/README.md
new file mode 100644
index 000000000..dd90e7ad2
--- /dev/null
+++ b/embassy-net-driver-channel/README.md
@@ -0,0 +1,96 @@
+# embassy-net-driver-channel
+
+This crate provides a toolkit for implementing [`embassy-net`](https://crates.io/crates/embassy-net) drivers in a
+higher level way than implementing the [`embassy-net-driver`](https://crates.io/crates/embassy-net-driver) trait directly.
+
+The `embassy-net-driver` trait is polling-based. To implement it, you must write the packet receive/transmit state machines by
+hand, and hook up the `Waker`s provided by `embassy-net` to the right interrupt handlers so that `embassy-net`
+knows when to poll your driver again to make more progress.
+
+With `embassy-net-driver-channel`
+
+## A note about deadlocks
+
+When implementing a driver using this crate, it might be tempting to write it in the most straightforward way:
+
+```rust,ignore
+loop {
+    // Wait for either..
+    match select(
+        // ... the chip signaling an interrupt, indicating a packet is available to receive, or
+        irq_pin.wait_for_low(), 
+        // ... a TX buffer becoming available, i.e. embassy-net wants to send a packet
+        tx_chan.tx_buf(),
+    ).await {
+        Either::First(_) => {
+            // a packet is ready to be received!
+            let buf = rx_chan.rx_buf().await; // allocate a rx buf from the packet queue
+            let n = receive_packet_over_spi(buf).await; 
+            rx_chan.rx_done(n);
+        }
+        Either::Second(buf) => {
+            // a packet is ready to be sent!
+            send_packet_over_spi(buf).await; 
+            tx_chan.tx_done();
+        }
+    }
+}
+```
+
+However, this code has a latent deadlock bug. The symptom is it can hang at `rx_chan.rx_buf().await` under load.
+
+The reason is that, under load, both the TX and RX queues can get full at the same time. When this happens, the `embassy-net` task stalls trying to send because the TX queue is full, therefore it stops processing packets in the RX queue. Your driver task also stalls because the RX queue is full, therefore it stops processing packets in the TX queue.
+
+The fix is to make sure to always service the TX queue while you're waiting for space to become available in the TX queue. For example, select on either "tx_chan.tx_buf() available" or "INT is low AND rx_chan.rx_buf() available":
+
+```rust,ignore
+loop {
+    // Wait for either..
+    match select(
+        async {
+            // ... the chip signaling an interrupt, indicating a packet is available to receive
+            irq_pin.wait_for_low().await;
+            // *AND* the buffer is ready...
+            rx_chan.rx_buf().await
+        },
+        // ... or a TX buffer becoming available, i.e. embassy-net wants to send a packet
+        tx_chan.tx_buf(),
+    ).await {
+        Either::First(buf) => {
+            // a packet is ready to be received!
+            let n = receive_packet_over_spi(buf).await; 
+            rx_chan.rx_done(n);
+        }
+        Either::Second(buf) => {
+            // a packet is ready to be sent!
+            send_packet_over_spi(buf).await; 
+            tx_chan.tx_done();
+        }
+    }
+}
+```
+
+## Examples
+
+These `embassy-net` drivers are implemented using this crate. You can look at them for inspiration.
+
+- [`cyw43`](https://github.com/embassy-rs/embassy/tree/main/cyw43) for WiFi on CYW43xx chips, used in the Raspberry Pi Pico W
+- [`embassy-usb`](https://github.com/embassy-rs/embassy/tree/main/embassy-usb) for Ethernet-over-USB (CDC NCM) support.
+- [`embassy-net-w5500`](https://github.com/embassy-rs/embassy/tree/main/embassy-net-w5500) for Wiznet W5500 SPI Ethernet MAC+PHY chip.
+- [`embassy-net-esp-hosted`](https://github.com/embassy-rs/embassy/tree/main/embassy-net-esp-hosted) for using ESP32 chips with the [`esp-hosted`](https://github.com/espressif/esp-hosted) firmware as WiFi adapters for another non-ESP32 MCU.
+
+
+## Interoperability
+
+This crate can run on any executor.
+
+
+## License
+
+This work is licensed under either of
+
+- Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE) or
+  http://www.apache.org/licenses/LICENSE-2.0)
+- MIT license ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT)
+
+at your option.
diff --git a/embassy-net-driver-channel/src/lib.rs b/embassy-net-driver-channel/src/lib.rs
index 0c8dcc22b..02a4c00d6 100644
--- a/embassy-net-driver-channel/src/lib.rs
+++ b/embassy-net-driver-channel/src/lib.rs
@@ -1,4 +1,5 @@
 #![no_std]
+#![doc = include_str!("../README.md")]
 
 // must go first!
 mod fmt;
diff --git a/embassy-net-driver/Cargo.toml b/embassy-net-driver/Cargo.toml
index ff6f29355..da6d9ad62 100644
--- a/embassy-net-driver/Cargo.toml
+++ b/embassy-net-driver/Cargo.toml
@@ -3,7 +3,13 @@ name = "embassy-net-driver"
 version = "0.1.0"
 edition = "2021"
 license = "MIT OR Apache-2.0"
-
+description = "Driver trait for the `embassy-net` async TCP/IP network stack."
+repository = "https://github.com/embassy-rs/embassy"
+categories = [
+    "embedded",
+    "no-std",
+    "asynchronous",
+]
 
 [package.metadata.embassy_docs]
 src_base = "https://github.com/embassy-rs/embassy/blob/embassy-net-driver-v$VERSION/embassy-net-driver/src/"
@@ -11,5 +17,8 @@ src_base_git = "https://github.com/embassy-rs/embassy/blob/$COMMIT/embassy-net-d
 features = ["defmt"]
 target = "thumbv7em-none-eabi"
 
+[package.metadata.docs.rs]
+features = ["defmt"]
+
 [dependencies]
 defmt = { version = "0.3", optional = true }
\ No newline at end of file
diff --git a/embassy-net-driver/README.md b/embassy-net-driver/README.md
index 84f25492d..6a757380d 100644
--- a/embassy-net-driver/README.md
+++ b/embassy-net-driver/README.md
@@ -1,5 +1,21 @@
 # embassy-net-driver
 
+This crate contains the driver trait necessary for adding [`embassy-net`](https://crates.io/crates/embassy-net) support
+for a new hardware platform.
+
+If you want to *use* `embassy-net` with already made drivers, you should depend on the main `embassy-net` crate, not on this crate.
+
+If you are writing a driver, you  should depend only on this crate, not on the main `embassy-net` crate.
+This will allow your driver to continue working for newer `embassy-net` major versions, without needing an update,
+if the driver trait has not had breaking changes.
+
+See also [`embassy-net-driver-channel`](https://crates.io/crates/embassy-net-driver-channel), which provides a higer-level API
+to construct a driver that processes packets in its own background task and communicates with the `embassy-net` task via
+packet queues for RX and TX.
+
+## Interoperability
+
+This crate can run on any executor.
 
 ## License
 
diff --git a/embassy-net-w5500/src/lib.rs b/embassy-net-w5500/src/lib.rs
index 6821373e3..efd9bed66 100644
--- a/embassy-net-w5500/src/lib.rs
+++ b/embassy-net-w5500/src/lib.rs
@@ -1,5 +1,6 @@
+//! [`embassy-net`](https://crates.io/crates/embassy-net) driver for the WIZnet W5500 ethernet chip.
 #![no_std]
-/// [`embassy-net`](crates.io/crates/embassy-net) driver for the WIZnet W5500 ethernet chip.
+
 mod device;
 mod socket;
 mod spi;
@@ -77,7 +78,7 @@ impl<'d, SPI: SpiDevice, INT: Wait, RST: OutputPin> Runner<'d, SPI, INT, RST> {
     }
 }
 
-/// Obtain a driver for using the W5500 with [`embassy-net`](crates.io/crates/embassy-net).
+/// Obtain a driver for using the W5500 with [`embassy-net`](https://crates.io/crates/embassy-net).
 pub async fn new<'a, const N_RX: usize, const N_TX: usize, SPI: SpiDevice, INT: Wait, RST: OutputPin>(
     mac_addr: [u8; 6],
     state: &'a mut State<N_RX, N_TX>,
diff --git a/embassy-net/Cargo.toml b/embassy-net/Cargo.toml
index cef8247eb..e89039daa 100644
--- a/embassy-net/Cargo.toml
+++ b/embassy-net/Cargo.toml
@@ -3,7 +3,13 @@ name = "embassy-net"
 version = "0.1.0"
 edition = "2021"
 license = "MIT OR Apache-2.0"
-
+description = "Async TCP/IP network stack for embedded systems"
+repository = "https://github.com/embassy-rs/embassy"
+categories = [
+    "embedded",
+    "no-std",
+    "asynchronous",
+]
 
 [package.metadata.embassy_docs]
 src_base = "https://github.com/embassy-rs/embassy/blob/embassy-net-v$VERSION/embassy-net/src/"
@@ -44,7 +50,6 @@ smoltcp = { version = "0.10.0", default-features = false, features = [
 ] }
 
 embassy-net-driver = { version = "0.1.0", path = "../embassy-net-driver" }
-embassy-hal-common = { version = "0.1.0", path = "../embassy-hal-common" }
 embassy-time = { version = "0.1.0", path = "../embassy-time" }
 embassy-sync = { version = "0.2.0", path = "../embassy-sync" }
 embedded-io = { version = "0.4.0", optional = true }
diff --git a/embassy-net/README.md b/embassy-net/README.md
index 470926c58..48f9fd832 100644
--- a/embassy-net/README.md
+++ b/embassy-net/README.md
@@ -1,30 +1,56 @@
 # embassy-net
 
-embassy-net contains an async network API based on smoltcp and embassy, designed
-for embedded systems.
+`embassy-net` is a no-std no-alloc async network stack, designed for embedded systems.
 
-## Running the example
+It builds on [`smoltcp`](https://github.com/smoltcp-rs/smoltcp). It provides a higher-level and more opinionated
+API. It glues together the components provided by `smoltcp`, handling the low-level details with defaults and
+memory management designed to work well for embedded systems, aiiming for a more "Just Works" experience.
 
-First, create the tap0 interface. You only need to do this once.
+## Features
 
-```sh
-sudo ip tuntap add name tap0 mode tap user $USER
-sudo ip link set tap0 up
-sudo ip addr add 192.168.69.100/24 dev tap0
-sudo ip -6 addr add fe80::100/64 dev tap0
-sudo ip -6 addr add fdaa::100/64 dev tap0
-sudo ip -6 route add fe80::/64 dev tap0
-sudo ip -6 route add fdaa::/64 dev tap0
-```
+- IPv4, IPv6
+- Ethernet and bare-IP mediums.
+- TCP, UDP, DNS, DHCPv4, IGMPv4
+- TCP sockets implement the `embedded-io` async traits.
 
-Second, have something listening there. For example `nc -l 8000`
+See the [`smoltcp`](https://github.com/smoltcp-rs/smoltcp) README for a detailed list of implemented and 
+unimplemented features of the network protocols. 
 
-Then run the example located in the `examples` folder:
+## Hardware support
 
-```sh
-cd $EMBASSY_ROOT/examples/std/
-cargo run --bin net -- --static-ip
-```
+- [`esp-wifi`](https://github.com/esp-rs/esp-wifi) for WiFi support on bare-metal ESP32 chips. Maintained by Espressif.
+- [`cyw43`](https://github.com/embassy-rs/embassy/tree/main/cyw43) for WiFi on CYW43xx chips, used in the Raspberry Pi Pico W
+- [`embassy-usb`](https://github.com/embassy-rs/embassy/tree/main/embassy-usb) for Ethernet-over-USB (CDC NCM) support.
+- [`embassy-stm32`](https://github.com/embassy-rs/embassy/tree/main/embassy-stm32) for the builtin Ethernet MAC in all STM32 chips (STM32F1, STM32F2, STM32F4, STM32F7, STM32H7, STM32H5).
+- [`embassy-net-w5500`](https://github.com/embassy-rs/embassy/tree/main/embassy-net-w5500) for Wiznet W5500 SPI Ethernet MAC+PHY chip.
+- [`embassy-net-esp-hosted`](https://github.com/embassy-rs/embassy/tree/main/embassy-net-esp-hosted) for using ESP32 chips with the [`esp-hosted`](https://github.com/espressif/esp-hosted) firmware as WiFi adapters for another non-ESP32 MCU.
+
+## Examples
+
+- For usage with Embassy HALs and network chip drivers, search [here](https://github.com/embassy-rs/embassy/tree/main/examples) for `eth` or `wifi`.
+- The [`esp-wifi` repo](https://github.com/esp-rs/esp-wifi) has examples for use on bare-metal ESP32 chips.
+- For usage on `std` platforms, see [the `std` examples](https://github.com/embassy-rs/embassy/tree/main/examples/std/src/bin)
+
+## Adding support for new hardware
+
+To add `embassy-net` support for new hardware (i.e. a new Ethernet or WiFi chip, or
+an Ethernet/WiFi MCU peripheral), you have to implement the [`embassy-net-driver`](https://crates.io/crates/embassy-net-driver)
+traits.
+
+Alternatively, [`embassy-net-driver-channel`](https://crates.io/crates/embassy-net-driver-channel) provides a higer-level API
+to construct a driver that processes packets in its own background task and communicates with the `embassy-net` task via
+packet queues for RX and TX.
+
+Drivers should depend only on `embassy-net-driver` or `embassy-net-driver-channel`. Never on the main `embassy-net` crate.
+This allows existing drivers to continue working for newer `embassy-net` major versions, without needing an update, if the driver
+trait has not had breaking changes.
+
+## Interoperability
+
+This crate can run on any executor.
+
+[`embassy-time`](https://crates.io/crates/embassy-net-driver) is used for timekeeping and timeouts. You must
+link an `embassy-time` driver in your project to use this crate.
 
 ## License
 
diff --git a/embassy-net/src/lib.rs b/embassy-net/src/lib.rs
index 17a7a22a2..840d7a09a 100644
--- a/embassy-net/src/lib.rs
+++ b/embassy-net/src/lib.rs
@@ -419,7 +419,29 @@ impl<D: Driver + 'static> Stack<D> {
         })
         .await?;
 
-        use embassy_hal_common::drop::OnDrop;
+        #[must_use = "to delay the drop handler invocation to the end of the scope"]
+        struct OnDrop<F: FnOnce()> {
+            f: core::mem::MaybeUninit<F>,
+        }
+
+        impl<F: FnOnce()> OnDrop<F> {
+            fn new(f: F) -> Self {
+                Self {
+                    f: core::mem::MaybeUninit::new(f),
+                }
+            }
+
+            fn defuse(self) {
+                core::mem::forget(self)
+            }
+        }
+
+        impl<F: FnOnce()> Drop for OnDrop<F> {
+            fn drop(&mut self) {
+                unsafe { self.f.as_ptr().read()() }
+            }
+        }
+
         let drop = OnDrop::new(|| {
             self.with_mut(|s, i| {
                 let socket = s.sockets.get_mut::<dns::Socket>(i.dns_socket);
diff --git a/embassy-usb/src/class/cdc_ncm/embassy_net.rs b/embassy-usb/src/class/cdc_ncm/embassy_net.rs
index bc79b3671..670709021 100644
--- a/embassy-usb/src/class/cdc_ncm/embassy_net.rs
+++ b/embassy-usb/src/class/cdc_ncm/embassy_net.rs
@@ -1,4 +1,5 @@
-//! [`embassy-net`](crates.io/crates/embassy-net) driver for the CDC-NCM class.
+//! [`embassy-net`](https://crates.io/crates/embassy-net) driver for the CDC-NCM class.
+
 use embassy_futures::select::{select, Either};
 use embassy_net_driver_channel as ch;
 use embassy_net_driver_channel::driver::LinkState;
@@ -79,7 +80,7 @@ impl<'d, D: Driver<'d>, const MTU: usize> Runner<'d, D, MTU> {
 pub type Device<'d, const MTU: usize> = embassy_net_driver_channel::Device<'d, MTU>;
 
 impl<'d, D: Driver<'d>> CdcNcmClass<'d, D> {
-    /// Obtain a driver for using the CDC-NCM class with [`embassy-net`](crates.io/crates/embassy-net).
+    /// Obtain a driver for using the CDC-NCM class with [`embassy-net`](https://crates.io/crates/embassy-net).
     pub fn into_embassy_net_device<const MTU: usize, const N_RX: usize, const N_TX: usize>(
         self,
         state: &'d mut State<MTU, N_RX, N_TX>,
diff --git a/examples/std/README.md b/examples/std/README.md
new file mode 100644
index 000000000..adc795928
--- /dev/null
+++ b/examples/std/README.md
@@ -0,0 +1,23 @@
+
+## Running the `embassy-net` examples
+
+First, create the tap0 interface. You only need to do this once.
+
+```sh
+sudo ip tuntap add name tap0 mode tap user $USER
+sudo ip link set tap0 up
+sudo ip addr add 192.168.69.100/24 dev tap0
+sudo ip -6 addr add fe80::100/64 dev tap0
+sudo ip -6 addr add fdaa::100/64 dev tap0
+sudo ip -6 route add fe80::/64 dev tap0
+sudo ip -6 route add fdaa::/64 dev tap0
+```
+
+Second, have something listening there. For example `nc -l 8000`
+
+Then run the example located in the `examples` folder:
+
+```sh
+cd $EMBASSY_ROOT/examples/std/
+cargo run --bin net -- --static-ip
+```
\ No newline at end of file