riot_sys

Type Alias netdev_driver_t

Source 
pub type netdev_driver_t = netdev_driver;
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).

Aliased Type§

struct netdev_driver_t {
    pub send: Option<unsafe extern "C" fn(_: *mut netdev, _: *const iolist) -> i32>,
    pub confirm_send: Option<unsafe extern "C" fn(_: *mut netdev, _: *mut c_void) -> i32>,
    pub recv: Option<unsafe extern "C" fn(_: *mut netdev, _: *mut c_void, _: u32, _: *mut c_void) -> i32>,
    pub init: Option<unsafe extern "C" fn(_: *mut netdev) -> i32>,
    pub isr: Option<unsafe extern "C" fn(_: *mut netdev)>,
    pub get: Option<unsafe extern "C" fn(_: *mut netdev, _: u8, _: *mut c_void, _: u32) -> i32>,
    pub set: Option<unsafe extern "C" fn(_: *mut netdev, _: u8, _: *const c_void, _: u32) -> i32>,
}

Fields§

§send: Option<unsafe extern "C" fn(_: *mut netdev, _: *const iolist) -> i32>

@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 (transmission already complete)

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.

If the driver implements blocking send (e.g. because it writes out the frame byte-by-byte over a serial line) it can also return the number of bytes transmitted here directly. In this case it MUST NOT emit a NETDEV_EVENT_TX_COMPLETE event, netdev_driver_t::confirm_send will never be called but should still be implemented to signal conformance to the new API.

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(_: *mut netdev, _: *mut c_void) -> i32>

@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 -EHOSTUNREACH Layer 2 ACK timeout @retval -EBUSY Medium is busy. (E.g. Auto-CCA failed / timed out, collision detected) @retval -ENETDOWN Interface is not connected / powered down @retval -EIO Any kind of transmission error Use @p info for more details @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(_: *mut netdev, _: *mut c_void, _: u32, _: *mut c_void) -> i32>

@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(_: *mut netdev) -> i32>

@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(_: *mut netdev)>

@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(_: *mut netdev, _: u8, _: *mut c_void, _: u32) -> i32>

@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(_: *mut netdev, _: u8, _: *const c_void, _: u32) -> i32>

@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

Layout§

Note: Most layout information is completely unstable and may even differ between compilations. The only exception is types with certain repr(...) attributes. Please see the Rust Reference's “Type Layout” chapter for details on type layout guarantees.

Size: 28 bytes