Struct EspNetifDriver

Source

pub struct EspNetifDriver<'d, T>where
    T: BorrowMut<EspNetif>,
{ /* private fields */ }

Implementations§

Source §

impl<T> EspNetifDriver<'static, T>
where T: BorrowMut<EspNetif>,

Source

pub fn new<P, F>(netif: T, post_attach_cfg: P, tx: F) -> Result<Self, EspError>
where P: FnMut(&mut EspNetif) -> Result<(), EspError> + Send + 'static, F: FnMut(&[u8]) -> Result<(), EspError> + Send + 'static,

Create a new netif driver around the provided EspNetif instance.

The driver transport is represented by:

The tx callback that the driver would call when it wants to ingest a packet into the underlying transport
EsNetifDriver::rx, which should be called by the transport when a new packet has arrived that has to be ingested in the driver

The transport can be anything, but with - say - PPP netif - it would typically be UART, and the tx callback implementation is simply expected to write the PPP packet into UART.

Arguments:

netif is the EspNetif instance that the driver will manage
got_ip_event_id and lost_ip_event_id are the event IDs that the driver will listen to so that it can connect/disconnect the netif upon receival / loss of IP
post_attach_cfg is a netif-specific configuration that will be executed after the netif is attached. For example, for a PPP netif, the post attach configuration might want to invoke EspNetif::set_ppp_conf.
tx is the callback that the driver will call when it wants to ingest a packet into the underlying transport

Example:

let (uart_rx, uart_tx) = uart.into_split();

let mut driver = EspNetifDriver::new(
    EspNetif::new(NetifStack::Ppp)?,
    |netif| netif.set_ppp_conf(&PppConfiguration {
        phase_events_enabled: false,
        ..Default::default()
    }),
    move |data| uart_tx.write_all(data),
)?;

loop {
    let mut buffer = [0; 128];
    let len = uart_rx.read(&mut buffer)?;
    driver.rx(&buffer[..len])?;
}

Source §

impl<'d, T> EspNetifDriver<'d, T>
where T: BorrowMut<EspNetif>,

Source

pub fn new_nonstatic<P, F>( netif: T, post_attach_cfg: P, tx: F, ) -> Result<Self, EspError>
where P: FnMut(&mut EspNetif) -> Result<(), EspError> + Send + 'd, F: FnMut(&[u8]) -> Result<(), EspError> + Send + 'd,

Create a new netif driver around the provided EspNetif instance.

The driver transport is represented by:

The tx callback that the driver would call when it wants to ingest a packet into the underlying transport
EsNetifDriver::rx, which should be called by the transport when a new packet has arrived that has to be ingested in the driver

The transport can be anything, but with - say - PPP netif - it would typically be UART, and the tx callback implementation is simply expected to write the PPP packet into UART.

Arguments:

netif is the EspNetif instance that the driver will manage
got_ip_event_id and lost_ip_event_id are the event IDs that the driver will listen to so that it can connect/disconnect the netif upon receival / loss of IP
post_attach_cfg is a netif-specific configuration that will be executed after the netif is attached. For example, for a PPP netif, the post attach configuration might want to invoke EspNetif::set_ppp_conf.
tx is the callback that the driver will call when it wants to ingest a packet into the underlying transport

Example:

let (uart_rx, uart_tx) = uart.into_split();

let mut driver = EspNetifDriver::new(
    EspNetif::new(NetifStack::Ppp)?,
    |netif| netif.set_ppp_conf(&PppConfiguration {
        phase_events_enabled: false,
        ..Default::default()
    }),
    move |data| uart_tx.write_all(data),
)?;

loop {
    let mut buffer = [0; 128];
    let len = uart_rx.read(&mut buffer)?;
    driver.rx(&buffer[..len])?;
}

§Safety

This method - in contrast to method new - allows the user to pass non-static callbacks/closures. 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