Struct EthDriver

Help

pub struct EthDriver<'d, T> { /* private fields */ }

Expand description

This struct provides a safe wrapper over the ESP IDF Ethernet C driver.

The driver works on Layer 2 (Data Link) in the OSI model, in that it provides facilities for sending and receiving ethernet packets over the built-in RMII interface of esp32 and/or via a dedicated SPI ethernet peripheral for all other MCUs.

For most use cases, utilizing EspEth - which provides a networking (IP) layer as well - should be preferred. Using EthDriver directly is beneficial only when one would like to utilize a custom, non-STD network stack like smoltcp.

Implementations§

Source §

impl<'d, T> EthDriver<'d, SpiEth<T>>
where T: Borrow<SpiDriver<'d>>,

Source

pub fn new( driver: T, int: impl Peripheral + 'd, cs: Option<impl Peripheral + 'd>, rst: Option<impl Peripheral + 'd>, chipset: SpiEthChipset, baudrate: Hertz, mac_addr: Option<&[u8; 6]>, phy_addr: Option<u32>, sysloop: EspSystemEventLoop, ) -> Result<Self, EspError>

Source

pub fn new_spi( driver: T, int: impl Peripheral + 'd, cs: Option<impl Peripheral + 'd>, rst: Option<impl Peripheral + 'd>, chipset: SpiEthChipset, baudrate: Hertz, mac_addr: Option<&[u8; 6]>, phy_addr: Option<u32>, sysloop: EspSystemEventLoop, ) -> Result<Self, EspError>

Source

pub fn new_spi_with_event_source( driver: T, event_source: SpiEventSource<'d>, cs: Option<impl Peripheral + 'd>, rst: Option<impl Peripheral + 'd>, chipset: SpiEthChipset, baudrate: Hertz, mac_addr: Option<&[u8; 6]>, phy_addr: Option<u32>, sysloop: EspSystemEventLoop, ) -> Result<Self, EspError>

Source §

pub fn set_rx_callback<F>(&mut self, callback: F) -> Result<(), EspError>
where F: FnMut(EthFrame) + Send + 'static,

Source

pub unsafe fn set_nonstatic_rx_callback<F>( &mut self, callback: F, ) -> Result<(), EspError>
where F: FnMut(EthFrame) + Send + 'd,

§Safety

This method - in contrast to method set_rx_callback - allows the user to pass a non-static callback/closure. This enables users to borrow

in the closure - variables that live on the stack - or more generally - in the same scope where the service is created.

HOWEVER: care should be taken NOT to call core::mem::forget() on the service, as that would immediately lead to an UB (crash). Also note that forgetting the service might happen with Rc and Arc when circular references are introduced: https://github.com/rust-lang/rust/issues/24456

The reason is that the closure is actually sent to a hidden ESP IDF thread. This means that if the service is forgotten, Rust is free to e.g. unwind the stack and the closure now owned by this other thread will end up with references to variables that no longer exist.

The destructor of the service takes care - prior to the service being dropped and e.g. the stack being unwind - to remove the closure from the hidden thread and destroy it. Unfortunately, when the service is forgotten, the un-subscription does not happen and invalid references are left dangling.

This “local borrowing” will only be possible to express in a safe way once/if !Leak types are introduced to Rust (i.e. the impossibility to “forget” a type and thus not call its destructor).

Source

pub fn send(&mut self, frame: &[u8]) -> Result<(), EspError>

Source

pub fn set_promiscuous(&mut self, state: bool) -> Result<(), EspError>

Enables or disables promiscuous mode for the EthDriver.

When promiscuous mode is enabled, the driver captures all Ethernet frames on the network, regardless of their destination MAC address. This is useful for debugging or monitoring purposes.