Structure to hold driver interface -> function mapping. More...

Detailed Description

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).

Definition at line 383 of file netdev.h.

#include <netdev.h>

Data Fields

int(* send )(netdev_t *dev, const iolist_t *iolist)
 Start transmission of the given frame and return directly. More...
 
int(* confirm_send )(netdev_t *dev, void *info)
 Fetch the status of a transmission and perform any potential cleanup. More...
 
int(* recv )(netdev_t *dev, void *buf, size_t len, void *info)
 Drop a received frame, OR get the length of a received frame, OR get a received frame. More...
 
int(* init )(netdev_t *dev)
 the driver's initialization function More...
 
void(* isr )(netdev_t *dev)
 a driver's user-space ISR handler More...
 
int(* get )(netdev_t *dev, netopt_t opt, void *value, size_t max_len)
 Get an option value from a given network device. More...
 
int(* set )(netdev_t *dev, netopt_t opt, const void *value, size_t value_len)
 Set an option value for a given network device. More...
 

Field Documentation

◆ confirm_send

int(* netdev_driver::confirm_send) (netdev_t *dev, void *info)

Fetch the status of a transmission and perform any potential cleanup.

Parameters
[in]devNetwork device descriptor. Must not be NULL.
[out]infoDevice class specific type to fetch transmission info. May be NULL if not needed by upper layer. May be ignored by driver.
Returns
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.)
Return values
-EAGAINTransmission still ongoing. (Call later again!)
-ECOMMAny kind of transmission error, such as collision detected, layer 2 ACK timeout, etc. Use info for more details
-EBUSYMedium is busy. (E.g. Auto-CCA failed / timed out)
<0Other 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.

Definition at line 443 of file netdev.h.

◆ get

int(* netdev_driver::get) (netdev_t *dev, netopt_t opt, void *value, size_t max_len)

Get an option value from a given network device.

Precondition
(dev != NULL)
for scalar types of netopt_t max_len must be of exactly that length (see netopt documentation for type)
for array types of netopt_t max_len must greater or equal the required length (see netopt documentation for type)
value must have the natural alignment of its type (see netopt documentation for type)
Parameters
[in]devnetwork device descriptor
[in]optoption type
[out]valuepointer to store the option's value in
[in]max_lenmaximal amount of byte that fit into value
Returns
number of bytes written to value
Return values
-ENOTSUPif opt is not provided by the device

Definition at line 533 of file netdev.h.

◆ init

int(* netdev_driver::init) (netdev_t *dev)

the driver's initialization function

Precondition
(dev != NULL)
Parameters
[in]devnetwork device descriptor. Must not be NULL.
Return values
<0on error
0on success

Definition at line 492 of file netdev.h.

◆ isr

void(* netdev_driver::isr) (netdev_t *dev)

a driver's user-space ISR handler

Precondition
(dev != NULL)

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

It is supposed to call netdev->event_callback() for each occurring event.

See receive frame flow description for details.

Parameters
[in]devnetwork device descriptor. Must not be NULL.

Definition at line 510 of file netdev.h.

◆ recv

int(* netdev_driver::recv) (netdev_t *dev, void *buf, size_t len, void *info)

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

Precondition
(dev != NULL)

Supposed to be called from netdev->event_callback()

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

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

  • The received frame is dropped
  • The content in buf becomes invalid. (The driver may use the memory to implement the dropping - or may not change it.)
  • -ENOBUFS is returned
Parameters
[in]devnetwork device descriptor. Must not be NULL.
[out]bufbuffer to write into or NULL to return the frame size.
[in]lenmaximum number of bytes to read. If buf is NULL the currently buffered frame is dropped when len > 0. Must not be 0 when buf != NULL.
[out]infostatus information for the received frame. Might be of different type for different netdev devices. May be NULL if not needed or applicable.
Return values
-ENOBUFSif supplied buffer is too small
Returns
number of bytes read if buf != NULL
frame size (or upper bound estimation) if buf == NULL

Definition at line 480 of file netdev.h.

◆ send

int(* netdev_driver::send) (netdev_t *dev, const iolist_t *iolist)

Start transmission of the given frame and return directly.

Precondition
(dev != NULL) && (iolist != NULL)
Parameters
[in]devNetwork device descriptor. Must not be NULL.
[in]iolistIO 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.
Return values
-EBUSYDriver is temporarily unable to send, e.g. because an incoming frame on a half-duplex medium is received
-ENETDOWNDevice is powered down
<0Other error
0Transmission successfully started
>0Number 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 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.

Definition at line 413 of file netdev.h.

◆ set

int(* netdev_driver::set) (netdev_t *dev, netopt_t opt, const void *value, size_t value_len)

Set an option value for a given network device.

Precondition
(dev != NULL)
for scalar types of netopt_t value_len must be of exactly that length (see netopt documentation for type)
for array types of netopt_t value_len must lesser or equal the required length (see netopt documentation for type)
value must have the natural alignment of its type (see netopt documentation for type)
Parameters
[in]devnetwork device descriptor
[in]optoption type
[in]valuevalue to set
[in]value_lenthe length of value
Returns
number of bytes written to value
Return values
-ENOTSUPif opt is not configurable for the device
-EINVALif value is an invalid value with regards to opt

Definition at line 559 of file netdev.h.


The documentation for this struct was generated from the following file: