Release embassy-net v0.1

3 files changed, 75 insertions, 22 deletions

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);