Struct riot_sys::netdev_driver

source ·
#[repr(C)]
pub struct netdev_driver { pub send: Option<unsafe extern "C" fn(dev: *mut netdev_t, iolist: *const iolist_t) -> c_int>, pub confirm_send: Option<unsafe extern "C" fn(dev: *mut netdev_t, info: *mut c_void) -> c_int>, pub recv: Option<unsafe extern "C" fn(dev: *mut netdev_t, buf: *mut c_void, len: size_t, info: *mut c_void) -> c_int>, pub init: Option<unsafe extern "C" fn(dev: *mut netdev_t) -> c_int>, pub isr: Option<unsafe extern "C" fn(dev: *mut netdev_t)>, pub get: Option<unsafe extern "C" fn(dev: *mut netdev_t, opt: netopt_t, value: *mut c_void, max_len: size_t) -> c_int>, pub set: Option<unsafe extern "C" fn(dev: *mut netdev_t, opt: netopt_t, value: *const c_void, value_len: size_t) -> c_int>, }
Expand description

@brief Structure to hold driver interface -> function mapping

The send/receive functions expect/return a full ethernet frame (dst mac, src mac, ethertype, payload, no checksum).

Fields§

§send: Option<unsafe extern "C" fn(dev: *mut netdev_t, iolist: *const iolist_t) -> c_int>

@brief Start transmission of the given frame and return directly

@pre (dev != NULL) && (iolist != NULL)

@param[in] dev Network device descriptor. Must not be NULL. @param[in] iolist IO vector list to send. Elements of this list may have iolist_t::iol_size == 0 and (in this case only) iolist_t::iol_data == 0.

@retval -EBUSY Driver is temporarily unable to send, e.g. because an incoming frame on a half-duplex medium is received @retval -ENETDOWN Device is powered down @retval <0 Other error @retval 0 Transmission successfully started @retval >0 Number of bytes transmitted (deprecated!)

This function will cause the driver to start the transmission in an async fashion. The driver will “own” the iolist until a subsequent call to @ref netdev_driver_t::confirm_send returns something different than -EAGAIN. The driver must signal completion using the NETDEV_EVENT_TX_COMPLETE event, regardless of success or failure.

Old drivers might not be ported to the new API and have netdev_driver_t::confirm_send set to NULL. In that case the driver will return the number of bytes transmitted on success (instead of 0) and will likely block until completion.

§confirm_send: Option<unsafe extern "C" fn(dev: *mut netdev_t, info: *mut c_void) -> c_int>

@brief Fetch the status of a transmission and perform any potential cleanup

@param[in] dev Network device descriptor. Must not be NULL. @param[out] info Device class specific type to fetch transmission info. May be NULL if not needed by upper layer. May be ignored by driver.

@return Number of bytes transmitted. (The size of the transmitted frame including all overhead, such as frame check sequence, bit stuffing, escaping, headers, trailers, preambles, start of frame delimiters, etc. May be an estimate for performance reasons.) @retval -EAGAIN Transmission still ongoing. (Call later again!) @retval -ECOMM Any kind of transmission error, such as collision detected, layer 2 ACK timeout, etc. Use @p info for more details @retval -EBUSY Medium is busy. (E.g. Auto-CCA failed / timed out) @retval <0 Other error. (Please use a negative errno code.)

@warning After netdev_driver_t::send was called and returned zero, this function must be called until it returns anything other than -EAGAIN. @note The driver will signal completion using the NETDEV_EVENT_TX_COMPLETE event. This function must not return -EAGAIN after that event was received.

§recv: Option<unsafe extern "C" fn(dev: *mut netdev_t, buf: *mut c_void, len: size_t, info: *mut c_void) -> c_int>

@brief Drop a received frame, OR get the length of a received frame, OR get a received frame.

@pre (dev != NULL)

Supposed to be called from @ref netdev_t::event_callback “netdev->event_callback()”

If @p buf == NULL and @p len == 0, returns the frame size – or an upper bound estimation of the size – without dropping the frame. If @p buf == NULL and @p len > 0, drops the frame and returns the frame size.

If called with @p buf != NULL and @p len is smaller than the received frame:

  • The received frame is dropped
  • The content in @p buf becomes invalid. (The driver may use the memory to implement the dropping - or may not change it.)
  • -ENOBUFS is returned

@param[in] dev network device descriptor. Must not be NULL. @param[out] buf buffer to write into or NULL to return the frame size. @param[in] len maximum number of bytes to read. If @p buf is NULL the currently buffered frame is dropped when @p len > 0. Must not be 0 when @p buf != NULL. @param[out] info status information for the received frame. Might be of different type for different netdev devices. May be NULL if not needed or applicable.

@retval -ENOBUFS if supplied buffer is too small @return number of bytes read if buf != NULL @return frame size (or upper bound estimation) if buf == NULL

§init: Option<unsafe extern "C" fn(dev: *mut netdev_t) -> c_int>

@brief the driver’s initialization function

@pre (dev != NULL)

@param[in] dev network device descriptor. Must not be NULL.

@retval <0 on error @retval 0 on success

§isr: Option<unsafe extern "C" fn(dev: *mut netdev_t)>

@brief a driver’s user-space ISR handler

@pre (dev != NULL)

This function will be called from a network stack’s loop when being notified by netdev_isr.

It is supposed to call @ref netdev_t::event_callback “netdev->event_callback()” for each occurring event.

See receive frame flow description for details.

@param[in] dev network device descriptor. Must not be NULL.

§get: Option<unsafe extern "C" fn(dev: *mut netdev_t, opt: netopt_t, value: *mut c_void, max_len: size_t) -> c_int>

@brief Get an option value from a given network device

@pre (dev != NULL) @pre for scalar types of @ref netopt_t @p max_len must be of exactly that length (see [netopt documentation](@ref net_netopt) for type) @pre for array types of @ref netopt_t @p max_len must greater or equal the required length (see [netopt documentation](@ref net_netopt) for type) @pre @p value must have the natural alignment of its type (see [netopt documentation](@ref net_netopt) for type)

@param[in] dev network device descriptor @param[in] opt option type @param[out] value pointer to store the option’s value in @param[in] max_len maximal amount of byte that fit into @p value

@return number of bytes written to @p value @retval -ENOTSUP if @p opt is not provided by the device

§set: Option<unsafe extern "C" fn(dev: *mut netdev_t, opt: netopt_t, value: *const c_void, value_len: size_t) -> c_int>

@brief Set an option value for a given network device

@pre (dev != NULL) @pre for scalar types of @ref netopt_t @p value_len must be of exactly that length (see [netopt documentation](@ref net_netopt) for type) @pre for array types of @ref netopt_t @p value_len must lesser or equal the required length (see [netopt documentation](@ref net_netopt) for type) @pre @p value must have the natural alignment of its type (see [netopt documentation](@ref net_netopt) for type)

@param[in] dev network device descriptor @param[in] opt option type @param[in] value value to set @param[in] value_len the length of @p value

@return number of bytes written to @p value @retval -ENOTSUP if @p opt is not configurable for the device @retval -EINVAL if @p value is an invalid value with regards to @p opt

Trait Implementations§

source§

impl Clone for netdev_driver

source§

fn clone(&self) -> netdev_driver

Returns a copy of the value. Read more
1.0.0 · source§

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source. Read more
source§

impl Debug for netdev_driver

source§

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter. Read more
source§

impl Default for netdev_driver

source§

fn default() -> netdev_driver

Returns the “default value” for a type. Read more
source§

impl Copy for netdev_driver

Auto Trait Implementations§

Blanket Implementations§

source§

impl<T> Any for T
where T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
source§

impl<T> Borrow<T> for T
where T: ?Sized,

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
source§

impl<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

source§

impl<T, U> Into<U> for T
where U: From<T>,

source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

§

type Error = Infallible

The type returned in the event of a conversion error.
source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.