Trait Driver 

pub trait Driver {
    // Required methods
    fn capabilities(&self) -> Capabilities;
    fn hardware_address(&self) -> HardwareAddress;
    fn receive(&mut self) -> Option<PacketBuf>;
    fn can_transmit(&mut self) -> bool;
    fn transmit(&mut self, buf: PacketBuf) -> Result<(), PacketBuf>;

    // Provided methods
    fn link_state(&mut self) -> LinkState { ... }
    fn register_waker(&mut self, waker: &Waker) -> Result<(), NotSupported> { ... }
    fn poll_tx_timestamp(&mut self) -> Option<TxTimestamp> { ... }
    fn set_multicast_filter(&mut self, addrs: &[[u8; 6]]) { ... }
}

A network device driver, sending and receiving raw network frames.

Required Methods

fn capabilities(&self) -> Capabilities

Get a description of the device’s capabilities.

fn hardware_address(&self) -> HardwareAddress

Get the device’s hardware address.

The address kind must match the medium in capabilities: an Ethernet address for Medium::Ethernet, HardwareAddress::Ip for Medium::Ip, an IEEE 802.15.4 extended address for Medium::Ieee802154.

The stack reads it once, when the driver is added to it. The stack has its own way to override the address after that.

fn receive(&mut self) -> Option<PacketBuf>

Poll for a received frame.

Returns a buffer holding the received frame if one is available, transferring ownership of it to the caller.

A driver that has per-packet metadata to report, such as an identifier or a receive timestamp, sets it on the buffer’s PacketMeta here. It travels with the packet up to the socket that receives it.

fn can_transmit(&mut self) -> bool

Whether the device can transmit one frame right now.

Devices typically have a transmit packet queue. This returns whether this queue has space to take one more frame.

If this returns true, the next transmit() call must not fail.

In devices where there’s no queue so transmit always succeeds, this should always return true.

fn transmit(&mut self, buf: PacketBuf) -> Result<(), PacketBuf>

Queue a frame for transmission, transferring ownership of the buffer to the driver.

The driver holds the buffer until the hardware is done with it, then drops it. If the frame cannot be queued right now (device busy or queue full), the buffer is handed back in the Err variant.

The buffer’s PacketMeta is whatever the sending socket attached to the packet (default for packets the stack generates itself). A driver that supports transmit timestamping timestamps the frame if request_timestamp is set, and reports the result from poll_tx_timestamp tagged with the packet’s id.

Provided Methods

fn link_state(&mut self) -> LinkState

Get the link state.

Devices that cannot tell, or whose link is always up, return LinkState::Up, which is the default implementation.

fn register_waker(&mut self, waker: &Waker) -> Result<(), NotSupported>

Register a waker.

The driver must wake it when:

• a frame has been received, so receive may return Some,
• there is room to transmit again, after can_transmit returned false,
• the link state changed, so link_state may return something new.

Only one waker is kept. Registering another replaces it. Wakes are allowed to be spurious.

A registered waker is woken just one. The main loop must re-register it if it wants to be woken again.

Drivers that cannot wake anything return Err(NotSupported), which is the default implementation. Such a driver can only be polled, so a caller that needs to sleep until the driver has something new cannot use it.

fn poll_tx_timestamp(&mut self) -> Option<TxTimestamp>

Poll for the timestamp of an already-transmitted packet.

Returns the transmit timestamp of a packet previously sent with PacketMeta::request_timestamp set, tagged with that packet’s PacketMeta::id, or None if no timestamp is available right now.

Transmit timestamps are reported out of band, rather than on the packet like receive timestamps are, because a packet’s transmit timestamp does not exist yet when transmit returns: it has not gone out on the wire yet.

Callers must be robust against all of the following:

• Timestamps become available an arbitrary time after transmit returned, so this should be polled repeatedly, not just once after sending.
• Timestamps may be reported out of order with respect to transmission.
• Timestamps may never arrive at all, e.g. because the hardware ran out of timestamp slots. Never block waiting for a particular id to show up without a timeout.

Devices that do not support transmit timestamping always return None, which is the default implementation.

fn set_multicast_filter(&mut self, addrs: &[[u8; 6]])

Set the device’s multicast hardware address filter.

addrs is the full list of multicast MAC addresses to listen on. It replaces the previous one.

A device with no multicast filter can ignore the calls, which is the default implementation.

Only called for Medium::Ethernet devices. The list has no duplicates.

It may be the same list as last time: the stack does not compare. If applying the filter is expensive, the driver should should keep the last list and skip if there were no changes.

If the list does not fit the filter, receive the addresses anyway if possible, for example by turning the filter off or switching it to receive all multicast. Losing filter efficiency is fine, filtering out traffic the network stack wants is not.

Dyn Compatibility

This trait is dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementations on Foreign Types

impl<T: Driver + ?Sized> Driver for &mut T

fn capabilities(&self) -> Capabilities

fn hardware_address(&self) -> HardwareAddress

fn link_state(&mut self) -> LinkState

fn register_waker(&mut self, waker: &Waker) -> Result<(), NotSupported>

fn receive(&mut self) -> Option<PacketBuf>

fn can_transmit(&mut self) -> bool

fn transmit(&mut self, buf: PacketBuf) -> Result<(), PacketBuf>

fn poll_tx_timestamp(&mut self) -> Option<TxTimestamp>

fn set_multicast_filter(&mut self, addrs: &[[u8; 6]])

Implementors