2016-12-11 00:25:43 +08:00
|
|
|
//! Access to networking hardware.
|
|
|
|
//!
|
2016-12-12 10:39:46 +08:00
|
|
|
//! The `phy` module deals with the *network devices*. It provides an interface
|
|
|
|
//! for transmitting and receiving frames, [Device](trait.Device.html),
|
2016-12-11 07:15:26 +08:00
|
|
|
//! as well as an implementations of that trait that uses the host OS,
|
2016-12-12 10:39:46 +08:00
|
|
|
//! [RawSocket](struct.RawSocket.html) and [TapInterface](struct.TapInterface.html).
|
2016-12-12 20:30:35 +08:00
|
|
|
use Error;
|
2016-12-11 07:15:26 +08:00
|
|
|
|
|
|
|
#[cfg(feature = "std")]
|
|
|
|
mod sys;
|
2016-12-11 00:25:43 +08:00
|
|
|
|
2016-12-12 20:30:35 +08:00
|
|
|
#[cfg(feature = "std")]
|
|
|
|
mod tracer;
|
2016-12-11 07:15:26 +08:00
|
|
|
#[cfg(feature = "std")]
|
2016-12-11 00:25:43 +08:00
|
|
|
mod raw_socket;
|
2016-12-11 07:15:26 +08:00
|
|
|
#[cfg(all(feature = "std", target_os = "linux"))]
|
|
|
|
mod tap_interface;
|
|
|
|
|
2016-12-12 20:30:35 +08:00
|
|
|
#[cfg(feature = "std")]
|
|
|
|
pub use self::tracer::Tracer;
|
2016-12-11 07:15:26 +08:00
|
|
|
#[cfg(feature = "std")]
|
|
|
|
pub use self::raw_socket::RawSocket;
|
|
|
|
#[cfg(all(feature = "std", target_os = "linux"))]
|
|
|
|
pub use self::tap_interface::TapInterface;
|
2016-12-11 00:25:43 +08:00
|
|
|
|
2016-12-11 03:27:07 +08:00
|
|
|
/// An interface for sending and receiving raw network frames.
|
|
|
|
///
|
|
|
|
/// It is expected that a `Device` implementation would allocate memory for both sending
|
|
|
|
/// and receiving packets from memory pools; hence, the stack borrows the buffer for a packet
|
|
|
|
/// that it is about to receive, as well for a packet that it is about to send, from the device.
|
|
|
|
pub trait Device {
|
2016-12-12 20:30:35 +08:00
|
|
|
type RxBuffer: AsRef<[u8]>;
|
|
|
|
type TxBuffer: AsRef<[u8]> + AsMut<[u8]>;
|
|
|
|
|
|
|
|
/// Get maximum transmission unit.
|
2016-12-11 03:27:07 +08:00
|
|
|
///
|
|
|
|
/// The network device is unable to send or receive frames larger than the MTU.
|
2016-12-12 15:19:53 +08:00
|
|
|
/// In practice, MTU will fall between 576 (for IPv4) or 1280 (for IPv6) and 9216 octets.
|
|
|
|
fn mtu(&self) -> usize;
|
2016-12-11 03:27:07 +08:00
|
|
|
|
2016-12-12 20:30:35 +08:00
|
|
|
/// Receive a frame.
|
2016-12-11 03:27:07 +08:00
|
|
|
///
|
2016-12-12 20:30:35 +08:00
|
|
|
/// It is expected that a `receive` implementation, once a packet is written to memory
|
2016-12-11 03:27:07 +08:00
|
|
|
/// through DMA, would gain ownership of the underlying buffer, provide it for parsing,
|
2016-12-12 20:30:35 +08:00
|
|
|
/// and return it to the network device once it is dropped.
|
|
|
|
fn receive(&mut self) -> Result<Self::RxBuffer, Error>;
|
2016-12-11 03:27:07 +08:00
|
|
|
|
2016-12-12 20:30:35 +08:00
|
|
|
/// Transmit a frame.
|
2016-12-11 03:27:07 +08:00
|
|
|
///
|
2016-12-12 20:30:35 +08:00
|
|
|
/// It is expected that a `transmit` implementation would gain ownership of a buffer with
|
|
|
|
/// the requested length, provide it for emission, and schedule it to be read from
|
|
|
|
/// memory by the network device once it is dropped.
|
|
|
|
fn transmit(&mut self, len: usize) -> Result<Self::TxBuffer, Error>;
|
2016-12-11 03:27:07 +08:00
|
|
|
}
|