Optionally depend on esp-alloc (by default)

esp-rs · Sep 6, 2024 · fe3a9b6 · fe3a9b6
1 parent e54aa45
commit fe3a9b6
Show file tree

Hide file tree

Showing 6 changed files with 104 additions and 61 deletions.
diff --git a/esp-alloc/src/lib.rs b/esp-alloc/src/lib.rs
@@ -114,25 +114,6 @@ impl HeapRegion {
     }
 }
 
-/// For esp-wifi
-#[doc(hidden)]
-#[no_mangle]
-pub extern "C" fn free_internal_heap() -> usize {
-    INSTANCE.free_caps(MemoryCapability::Internal.into())
-}
-
-/// For esp-wifi
-#[doc(hidden)]
-#[no_mangle]
-pub extern "C" fn allocate_from_internal_ram(size: usize) -> *mut u8 {
-    unsafe {
-        INSTANCE.alloc_caps(
-            MemoryCapability::Internal.into(),
-            Layout::from_size_align_unchecked(size, 4),
-        )
-    }
-}
-
 /// A memory allocator
 ///
 /// In addition to what Rust's memory allocator can do it allows to allocate

diff --git a/esp-wifi/Cargo.toml b/esp-wifi/Cargo.toml
@@ -13,6 +13,8 @@ categories = ["embedded", "hardware-support", "no-std"]
 
 [dependencies]
 defmt = { version = "0.3.8", optional = true }
+document-features  = "0.2.10"
+esp-alloc = { version = "0.4.0", path = "../esp-alloc", optional = true }
 esp-hal = { version = "0.20.0", path = "../esp-hal", default-features = false }
 esp-hal-embassy = { version = "0.3.0", path = "../esp-hal-embassy", default-features = false, optional = true }
 smoltcp = { version = "0.11.0", default-features = false, features = [
@@ -57,46 +59,59 @@ esp-build    = { version = "0.1.0", path = "../esp-build" }
 esp-metadata = { version = "0.3.0", path = "../esp-metadata" }
 
 [features]
-default = ["log"]
+default = ["log", "esp-alloc"]
 
-# chip features
+## Use `esp-alloc` for dynamic allocations.
+##
+## If you opt-out you need to provide implementations for `pub extern "C" fn esp_wifi_free_internal_heap() -> usize` 
+## and `pub extern "C" fn esp_wifi_allocate_from_internal_ram(size: usize) -> *mut u8`
+esp-alloc = ["dep:esp-alloc"]
+
+# Chip Support Feature Flags
+# Target the ESP32-C2.
 esp32c2 = [
   "esp-hal/esp32c2",
   "esp-hal-embassy?/esp32c2",
   "esp-wifi-sys/esp32c2",
 ]
+# Target the ESP32-C3.
 esp32c3 = [
   "esp-hal/esp32c3",
   "esp-hal-embassy?/esp32c3",
   "esp-wifi-sys/esp32c3",
 ]
+# Target the ESP32-C6.
 esp32c6 = [
   "esp-hal/esp32c6",
   "esp-hal-embassy?/esp32c6",
   "esp-wifi-sys/esp32c6",
 ]
+# Target the ESP32-H2.
 esp32h2 = [
   "esp-hal/esp32h2",
   "esp-hal-embassy?/esp32h2",
   "esp-wifi-sys/esp32h2",
 ]
+# Target the ESP32.
 esp32 = [
   "esp-hal/esp32",
   "esp-hal-embassy?/esp32",
   "esp-wifi-sys/esp32",
 ]
+# Target the ESP32-S2.
 esp32s2 = [
   "esp-hal/esp32s2",
   "esp-hal-embassy?/esp32s2",
   "esp-wifi-sys/esp32s2",
 ]
+# Target the ESP32-S3.
 esp32s3 = [
   "esp-hal/esp32s3",
   "esp-hal-embassy?/esp32s3",
   "esp-wifi-sys/esp32s3",
 ]
 
-# async features
+## Enable Async support
 async = [
   "dep:embassy-sync",
   "dep:embassy-futures",
@@ -105,34 +120,84 @@ async = [
   "dep:bt-hci",
 ]
 
+## Enable `embassy-net` support
 embassy-net = ["dep:embassy-net-driver", "async"]
 
-# misc features
+## Enable WiFi-BLE coexistence support
 coex = []
+
+## Logs the WiFi logs from the driver at log level info (needs a nightly-compiler)
 wifi-logs = []
+
+## Dumps packet info at log level info
 dump-packets = []
+
+## Provide implementations of smoltcp traits
 smoltcp = ["dep:smoltcp"]
+
+## Provide utilities for smoltcp initialization. Adds smoltcp dependency
 utils = ["smoltcp"]
+
 enumset = []
+
+## Enable WiFi support
 wifi = ["dep:enumset", "dep:no-std-net"]
+
+## Implement the embedded-svc Wifi trait
 embedded-svc = ["dep:embedded-svc"]
+
+## Enable BLE support
 ble = ["esp-hal/bluetooth"]
+
+## See USB-SERIAL-JTAG below
 phy-enable-usb = []
+
+## Enable minimum modem sleep. Only affects STA mode
 ps-min-modem = []
+
+## Enable maximum modem sleep. Only affects STA mode
 ps-max-modem = []
+
+## Enable esp-now support
 esp-now = ["wifi"]
+
+## IPv6 support. Includes utils feature
 ipv6 = ["wifi", "utils", "smoltcp?/proto-ipv6"]
+
+## IPv4 support. Includes utils feature
 ipv4 = ["wifi", "utils", "smoltcp?/proto-ipv4"]
+
+## TCP socket support. Includes ipv4 feature
 tcp = ["ipv4", "smoltcp?/socket-tcp"]
+
+## UDP socket support. Includes ipv4 feature
 udp = ["ipv4", "smoltcp?/socket-udp"]
+
+## ICMP socket support. Includes ipv4 feature
 icmp = ["ipv4", "smoltcp?/socket-icmp"]
+
+## IGMP (multicast) support. Includes ipv4 featu
 igmp = ["ipv4", "smoltcp?/proto-igmp"]
+
+## DNS support. Includes udp feature
 dns = ["udp", "smoltcp?/proto-dns", "smoltcp?/socket-dns"]
+
+## DHCPv4 support, both creating sockets and autoconfiguring network settings. Includes utils feature
 dhcpv4 = ["wifi", "utils", "smoltcp?/proto-dhcpv4", "smoltcp?/socket-dhcpv4"]
+
+## Convenience to enable "ipv4", "tcp", "udp", "icmp", "igmp", "dns", "dhcpv4"
 wifi-default = ["ipv4", "tcp", "udp", "icmp", "igmp", "dns", "dhcpv4"]
+
+## Enable support for `defmt`
 defmt = ["dep:defmt", "smoltcp?/defmt", "esp-hal/defmt"]
+
+## Enable support for the `log` crate
 log = ["dep:log", "esp-hal/log"]
+
+## Enable sniffer mode support
 sniffer = ["wifi"]
+
+# Don't include `strchr` - not shown in docs
 have-strchr = []
 
 [package.metadata.docs.rs]

diff --git a/esp-wifi/README.md b/esp-wifi/README.md
@@ -71,38 +71,6 @@ When using USB-SERIAL-JTAG (for example by selecting `jtag-serial` in [`esp-prin
 
 Don't use this feature if you are _not_ using USB-SERIAL-JTAG as it might reduce WiFi performance.
 
-## Features
-
-| Feature        | Meaning                                                                                              |
-| -------------- | ---------------------------------------------------------------------------------------------------- |
-| wifi-logs      | logs the WiFi logs from the driver at log level `info` (needs a nightly-compiler)                    |
-| wifi-default   | A convenience feature to enable some reasonable defaults for wifi use.                               |
-| dump-packets   | dumps packet info at log level `info`                                                                |
-| smoltcp        | Provide implementations of `smoltcp` traits                                                          |
-| utils          | Provide utilities for smoltcp initialization. Adds `smoltcp` dependency                              |
-| ble            | Enable BLE support                                                                                   |
-| wifi           | Enable WiFi support                                                                                  |
-| esp-now        | Enable [esp-now](https://www.espressif.com/en/solutions/low-power-solutions/esp-now) support         |
-| coex           | Enable WiFi-BLE coexistence support                                                                  |
-| ipv4           | IPv4 support. Includes `utils` feature                                                               |
-| ipv6           | IPv6 support. Includes `utils` feature                                                               |
-| tcp            | TCP socket support. Includes `ipv4` feature                                                          |
-| udp            | UDP socket support. Includes `ipv4` feature                                                          |
-| igmp           | IGMP (multicast) support. Includes `ipv4` feature                                                    |
-| dns            | DNS support. Includes `udp` feature                                                                  |
-| dhcpv4         | DHCPv4 support, both creating sockets and autoconfiguring network settings. Includes `utils` feature |
-| phy-enable-usb | See [USB-SERIAL-JTAG](#usb-serial-jtag) above                                                        |
-| ps-min-modem   | Enable minimum modem sleep. Only affects STA mode                                                    |
-| ps-max-modem   | Enable maximum modem sleep. Only affects STA mode                                                    |
-| log            | Route log output to the `log` crate                                                                  |
-| defmt          | Add `defmt::Format` implementation and output logs via `defmt`                                       |
-| embedded-svc   | Implement the embedded-svc Wifi trait                                                                |
-
-Note that not all features are available on every MCU. For example, `ble` (and thus, `coex`) is not available on ESP32-S2.
-
-When using the `dump-packets` feature you can use the extcap in `extras/esp-wifishark` to analyze the frames in Wireshark.
-For more information see [extras/esp-wifishark/README.md](../extras/esp-wifishark/README.md)
-
 ## Tuning
 
 The defaults used by `esp-wifi` and the examples are rather conservative. It is possible to change a few of the important settings.

diff --git a/esp-wifi/src/compat/malloc.rs b/esp-wifi/src/compat/malloc.rs
@@ -7,10 +7,10 @@ pub unsafe extern "C" fn malloc(size: usize) -> *mut u8 {
     let total_size = size + 4;
 
     extern "C" {
-        fn allocate_from_internal_ram(size: usize) -> *mut u8;
+        fn esp_wifi_allocate_from_internal_ram(size: usize) -> *mut u8;
     }
 
-    let ptr = unsafe { allocate_from_internal_ram(total_size) };
+    let ptr = unsafe { esp_wifi_allocate_from_internal_ram(total_size) };
 
     if ptr.is_null() {
         warn!("Unable to allocate {} bytes", size);
@@ -73,3 +73,22 @@ unsafe extern "C" fn realloc(ptr: *mut u8, new_size: usize) -> *mut u8 {
         p
     }
 }
+
+#[cfg(feature = "esp-alloc")]
+#[doc(hidden)]
+#[no_mangle]
+pub extern "C" fn esp_wifi_free_internal_heap() -> usize {
+    esp_alloc::INSTANCE.free_caps(esp_alloc::MemoryCapability::Internal.into())
+}
+
+#[cfg(feature = "esp-alloc")]
+#[doc(hidden)]
+#[no_mangle]
+pub extern "C" fn esp_wifi_allocate_from_internal_ram(size: usize) -> *mut u8 {
+    unsafe {
+        esp_alloc::INSTANCE.alloc_caps(
+            esp_alloc::MemoryCapability::Internal.into(),
+            core::alloc::Layout::from_size_align_unchecked(size, 4),
+        )
+    }
+}
diff --git a/esp-wifi/src/lib.rs b/esp-wifi/src/lib.rs
@@ -1,8 +1,18 @@
+//! # Features flags
+//!
+//! Note that not all features are available on every MCU. For example, `ble`
+//! (and thus, `coex`) is not available on ESP32-S2.
+//!
+//! When using the `dump-packets` feature you can use the extcap in
+//! `extras/esp-wifishark` to analyze the frames in Wireshark.
+//! For more information see
+//! [extras/esp-wifishark/README.md](../extras/esp-wifishark/README.md)
+#![doc = document_features::document_features!(feature_label = r#"<span class="stab portability"><code>{feature}</code></span>"#)]
+#![doc = include_str!("../README.md")]
+#![doc(html_logo_url = "https://avatars.githubusercontent.com/u/46717278")]
 #![no_std]
 #![cfg_attr(target_arch = "xtensa", feature(asm_experimental_arch))]
 #![cfg_attr(any(feature = "wifi-logs", nightly), feature(c_variadic))]
-#![doc = include_str!("../README.md")]
-#![doc(html_logo_url = "https://avatars.githubusercontent.com/u/46717278")]
 #![allow(rustdoc::bare_urls)]
 // allow until num-derive doesn't generate this warning anymore (unknown_lints because Xtensa
 // toolchain doesn't know about that lint, yet)

diff --git a/esp-wifi/src/wifi/os_adapter.rs b/esp-wifi/src/wifi/os_adapter.rs
@@ -906,10 +906,10 @@ pub unsafe extern "C" fn event_post(
 /// *************************************************************************
 pub unsafe extern "C" fn get_free_heap_size() -> u32 {
     extern "C" {
-        fn free_internal_heap() -> usize;
+        fn esp_wifi_free_internal_heap() -> usize;
     }
 
-    free_internal_heap() as u32
+    esp_wifi_free_internal_heap() as u32
 }
 
 /// **************************************************************************