Design

February 12, 2026 ยท View on GitHub

This document captures design decisions, constraints, and invariants for the ph-esp32-mac driver. It focuses on why the system is shaped the way it is.

Table of Contents

Scope and Non-Goals

Scope:

  • ESP32 only (xtensa-esp32-none-elf)
  • no_std, no_alloc, statically allocated DMA buffers
  • LAN8720A as the canonical PHY

Non-goals:

  • WiFi support (out of scope)
  • Dynamic allocation or runtime buffer growth
  • Stable support for non-ESP32 targets (ESP32-P4 is a placeholder only)

Design Principles

  • Predictable memory usage: const generics and static allocation.
  • Explicit lifecycle: Emac::new -> init -> start.
  • Minimal unsafe surface: unsafe is isolated to internal modules.
  • HAL-friendly: ergonomic facades for esp-hal without hiding core control.
  • Runtime-agnostic: optional integrations for smoltcp/embassy-net.

Driver Model

The driver centers on Emac<RX, TX, BUF> plus EmacConfig:

  • EmacConfig::rmii_esp32_default() captures sensible ESP32 defaults.
  • Configuration is explicit and builder-style for clarity.
  • Errors are typed and recoverable where possible.

DMA and Memory Invariants

  • DMA descriptors and buffers are static and DMA-capable.
  • RX/TX rings are fixed-size and circular.
  • CPU and DMA ownership of descriptors is exclusive at any moment.
  • Buffer sizes must be large enough for expected frames (typically 1600 bytes).

Safety Boundaries

Unsafe access is concentrated in internal/:

  • Register reads/writes are isolated in internal/register/*.
  • DMA descriptor manipulation is isolated in internal/dma/*.
  • Public APIs provide safe abstractions and validate input where possible.

Macro helpers (emac_static_*) place critical buffers in DMA-capable memory when targeting Xtensa.

PHY Strategy

The PHY layer is trait-based:

  • PhyDriver defines the contract.
  • Lan8720a is the reference implementation.
  • A generic PHY fallback supports basic link operations.

This keeps the driver compatible with other PHYs without hardcoding one.

Integration Strategy

Integrations are optional and additive:

  • esp-hal: opinionated helpers for the WT32-ETH01 happy path.
  • smoltcp: implements smoltcp::phy::Device.
  • embassy-net: implements embassy-net-driver.

The core driver remains usable without any stack or runtime.

Board Support

boards::wt32_eth01 defines the canonical board configuration:

  • Known PHY address and clock requirements
  • Convenience helpers for MAC/PHY bring-up

Board helpers are public but remain experimental until more boards are added.

Feature Flags

  • esp32 (default): ESP32 target
  • esp32p4: placeholder only (not supported)
  • critical-section: ISR-safe shared access wrappers
  • async: async wakers and async TX/RX
  • esp-hal: esp-hal facades
  • smoltcp: smoltcp integration
  • embassy-net: embassy-net-driver integration
  • defmt / log: optional logging backends