riot-ci/RIOT
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

Merge pull request #14657 from maribu/netdev_doc

Browse Source 
drivers/net: Fix netdev_driver_t doc
This commit is contained in:
José Alamos 2020-08-04 10:49:24 +02:00 committed by GitHub
commit 7967066f51
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 61 additions and 60 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

121
drivers/include/net/netdev.h
View File

@ -164,8 +164,8 @@
* The following example illustrates a receive sequence triggered by an * The following example illustrates a receive sequence triggered by an
* external interrupt: * external interrupt:
* *
* 1. packet arrives for device * 1. frame arrives for device
* 2. The driver previously registered an ISR for handling received packets. * 2. The driver previously registered an ISR for handling received frames.
* This ISR then calls @ref netdev_t::event_callback "netdev->event_callback()" * This ISR then calls @ref netdev_t::event_callback "netdev->event_callback()"
* with `event:= `@ref NETDEV_EVENT_ISR (from Interrupt Service Routine) * with `event:= `@ref NETDEV_EVENT_ISR (from Interrupt Service Routine)
* which wakes up event handler * which wakes up event handler
@ -175,7 +175,7 @@
* @ref netdev_t::event_callback "netdev->event_callback()" with * @ref netdev_t::event_callback "netdev->event_callback()" with
* `event:= `@ref NETDEV_EVENT_RX_COMPLETE * `event:= `@ref NETDEV_EVENT_RX_COMPLETE
* 5. @ref netdev_t::event_callback "netdev->event_callback()" uses * 5. @ref netdev_t::event_callback "netdev->event_callback()" uses
* @ref netdev_driver_t::recv "netdev->driver->recv()" to fetch packet * @ref netdev_driver_t::recv "netdev->driver->recv()" to fetch frame
* *
* ![RX event example](riot-netdev-rx.svg) * ![RX event example](riot-netdev-rx.svg)
* *
@ -232,13 +232,13 @@ enum {
*/ */
typedef enum { typedef enum {
NETDEV_EVENT_ISR, /**< driver needs it's ISR handled */ NETDEV_EVENT_ISR, /**< driver needs it's ISR handled */
NETDEV_EVENT_RX_STARTED, /**< started to receive a packet */ NETDEV_EVENT_RX_STARTED, /**< started to receive a frame */
NETDEV_EVENT_RX_COMPLETE, /**< finished receiving a packet */ NETDEV_EVENT_RX_COMPLETE, /**< finished receiving a frame */
NETDEV_EVENT_TX_STARTED, /**< started to transfer a packet */ NETDEV_EVENT_TX_STARTED, /**< started to transfer a frame */
NETDEV_EVENT_TX_COMPLETE, /**< transfer packet complete */ NETDEV_EVENT_TX_COMPLETE, /**< transfer frame complete */
NETDEV_EVENT_TX_COMPLETE_DATA_PENDING, /**< transfer packet complete and data pending flag */ NETDEV_EVENT_TX_COMPLETE_DATA_PENDING, /**< transfer frame complete and data pending flag */
NETDEV_EVENT_TX_NOACK, /**< ACK requested but not received */ NETDEV_EVENT_TX_NOACK, /**< ACK requested but not received */
NETDEV_EVENT_TX_MEDIUM_BUSY, /**< couldn't transfer packet */ NETDEV_EVENT_TX_MEDIUM_BUSY, /**< couldn't transfer frame */
NETDEV_EVENT_LINK_UP, /**< link established */ NETDEV_EVENT_LINK_UP, /**< link established */
NETDEV_EVENT_LINK_DOWN, /**< link gone */ NETDEV_EVENT_LINK_DOWN, /**< link gone */
NETDEV_EVENT_TX_TIMEOUT, /**< timeout when sending */ NETDEV_EVENT_TX_TIMEOUT, /**< timeout when sending */
@ -250,13 +250,13 @@ typedef enum {
} netdev_event_t; } netdev_event_t;
/** /**
* @brief Received packet status information for most radios * @brief Received frame status information for most radios
* *
* May be different for certain radios. * May be different for certain radios.
*/ */
struct netdev_radio_rx_info { struct netdev_radio_rx_info {
int16_t rssi; /**< RSSI of a received packet in dBm */ int16_t rssi; /**< RSSI of a received frame in dBm */
uint8_t lqi; /**< LQI of a received packet */ uint8_t lqi; /**< LQI of a received frame */
}; };
/** /**
@ -300,12 +300,12 @@ struct netdev {
*/ */
typedef struct netdev_driver { typedef struct netdev_driver {
/** /**
* @brief Send frame * @brief Send frame
* *
* @pre `(dev != NULL) && (iolist != NULL` * @pre `(dev != NULL) && (iolist != NULL)`
* *
* @param[in] dev Network device descriptor. Must not be NULL. * @param[in] dev Network device descriptor. Must not be NULL.
* @param[in] iolist IO vector list to send. Elements of this list may * @param[in] iolist IO vector list to send. Elements of this list may
* have iolist_t::iol_data == NULL or * have iolist_t::iol_data == NULL or
* iolist_t::iol_size == 0. However, unless otherwise * iolist_t::iol_size == 0. However, unless otherwise
* specified by the device, the *first* element * specified by the device, the *first* element
@ -317,58 +317,58 @@ typedef struct netdev_driver {
int (*send)(netdev_t *dev, const iolist_t *iolist); int (*send)(netdev_t *dev, const iolist_t *iolist);
/** /**
* @brief Drop a received frame, **OR** get the length of a received frame, * @brief Drop a received frame, **OR** get the length of a received
* **OR** get a received frame. * frame, **OR** get a received frame.
* *
* @pre `(dev != NULL)` * @pre `(dev != NULL)`
* *
* Supposed to be called from * Supposed to be called from
* @ref netdev_t::event_callback "netdev->event_callback()" * @ref netdev_t::event_callback "netdev->event_callback()"
* *
* If @p buf == NULL and @p len == 0, returns the packet size -- or an upper * If @p buf == NULL and @p len == 0, returns the frame size -- or an upper
* bound estimation of the size -- without dropping the packet. * bound estimation of the size -- without dropping the frame.
* If @p buf == NULL and @p len > 0, drops the packet and returns the packet * If @p buf == NULL and @p len > 0, drops the frame and returns the frame
* size. * size.
* *
* If called with @p buf != NULL and @p len is smaller than the received * If called with @p buf != NULL and @p len is smaller than the received
* packet: * frame:
* - The received packet is dropped * - The received frame is dropped
* - The content in @p buf becomes invalid. (The driver may use the memory * - The content in @p buf becomes invalid. (The driver may use the memory
* to implement the dropping - or may not change it.) * to implement the dropping - or may not change it.)
* - `-ENOBUFS` is returned * - `-ENOBUFS` is returned
* *
* @param[in] dev network device descriptor. Must not be NULL. * @param[in] dev network device descriptor. Must not be NULL.
* @param[out] buf buffer to write into or NULL to return the packet * @param[out] buf buffer to write into or NULL to return the frame
* size. * size.
* @param[in] len maximum number of bytes to read. If @p buf is NULL * @param[in] len maximum number of bytes to read. If @p buf is NULL
* the currently buffered packet is dropped when * the currently buffered frame is dropped when
* @p len > 0. Must not be 0 when @p buf != NULL. * @p len > 0. Must not be 0 when @p buf != NULL.
* @param[out] info status information for the received packet. Might * @param[out] info status information for the received frame. Might
* be of different type for different netdev devices. * be of different type for different netdev devices.
* May be NULL if not needed or applicable. * May be NULL if not needed or applicable.
* *
* @return `-ENOBUFS` if supplied buffer is too small * @retval -ENOBUFS if supplied buffer is too small
* @return number of bytes read if buf != NULL * @return number of bytes read if buf != NULL
* @return packet size (or upper bound estimation) if buf == NULL * @return frame size (or upper bound estimation) if buf == NULL
*/ */
int (*recv)(netdev_t *dev, void *buf, size_t len, void *info); int (*recv)(netdev_t *dev, void *buf, size_t len, void *info);
/** /**
* @brief the driver's initialization function * @brief the driver's initialization function
* *
* @pre `(dev != NULL)` * @pre `(dev != NULL)`
* *
* @param[in] dev network device descriptor. Must not be NULL. * @param[in] dev network device descriptor. Must not be NULL.
* *
* @return `< 0` on error * @retval <0 on error
* @return 0 on success * @retval 0 on success
*/ */
int (*init)(netdev_t *dev); int (*init)(netdev_t *dev);
/** /**
* @brief a driver's user-space ISR handler * @brief a driver's user-space ISR handler
* *
* @pre `(dev != NULL)` * @pre `(dev != NULL)`
* *
* This function will be called from a network stack's loop when being * This function will be called from a network stack's loop when being
* notified by netdev_isr. * notified by netdev_isr.
@ -377,7 +377,7 @@ typedef struct netdev_driver {
* @ref netdev_t::event_callback "netdev->event_callback()" for each * @ref netdev_t::event_callback "netdev->event_callback()" for each
* occurring event. * occurring event.
* *
* See receive packet flow description for details. * See receive frame flow description for details.
* *
* @param[in] dev network device descriptor. Must not be NULL. * @param[in] dev network device descriptor. Must not be NULL.
*/ */
@ -386,20 +386,21 @@ typedef struct netdev_driver {
/** /**
* @brief Get an option value from a given network device * @brief Get an option value from a given network device
* *
* @pre `(dev != NULL)` * @pre `(dev != NULL)`
* @pre for scalar types of @ref netopt_t @p max_len must be of exactly that * @pre for scalar types of @ref netopt_t @p max_len must be of exactly
* length (see [netopt documentation](@ref net_netopt) for type) * that length (see [netopt documentation](@ref net_netopt) for
* @pre for array types of @ref netopt_t @p max_len must greater or equal the * type)
* required length (see [netopt documentation](@ref net_netopt) for * @pre for array types of @ref netopt_t @p max_len must greater or
* type) * equal the required length (see
* [netopt documentation](@ref net_netopt) for type)
* *
* @param[in] dev network device descriptor * @param[in] dev network device descriptor
* @param[in] opt option type * @param[in] opt option type
* @param[out] value pointer to store the option's value in * @param[out] value pointer to store the option's value in
* @param[in] max_len maximal amount of byte that fit into @p value * @param[in] max_len maximal amount of byte that fit into @p value
* *
* @return number of bytes written to @p value * @return number of bytes written to @p value
* @return `-ENOTSUP` if @p opt is not provided by the device * @retval -ENOTSUP if @p opt is not provided by the device
*/ */
int (*get)(netdev_t *dev, netopt_t opt, int (*get)(netdev_t *dev, netopt_t opt,
void *value, size_t max_len); void *value, size_t max_len);
@ -407,23 +408,23 @@ typedef struct netdev_driver {
/** /**
* @brief Set an option value for a given network device * @brief Set an option value for a given network device
* *
* @pre `(dev != NULL)` * @pre `(dev != NULL)`
* @pre for scalar types of @ref netopt_t @p value_len must be of exactly * @pre for scalar types of @ref netopt_t @p value_len must be of
* that length (see [netopt documentation](@ref net_netopt) for type) * exactly that length (see [netopt documentation](@ref net_netopt)
* @pre for array types of @ref netopt_t @p value_len must lesser or equal * for type)
* the required length (see [netopt documentation](@ref net_netopt) for * @pre for array types of @ref netopt_t @p value_len must lesser or
* type) * equal the required length (see
* [netopt documentation](@ref net_netopt) for type)
* *
* @param[in] dev network device descriptor * @param[in] dev network device descriptor
* @param[in] opt option type * @param[in] opt option type
* @param[in] value value to set * @param[in] value value to set
* @param[in] value_len the length of @p value * @param[in] value_len the length of @p value
* *
* @return number of bytes written to @p value * @return number of bytes written to @p value
* @return `-ENOTSUP` if @p opt is not configurable for the * @retval -ENOTSUP if @p opt is not configurable for the device
* device * @retval -EINVAL if @p value is an invalid value with regards to
* @return `-EINVAL` if @p value is an invalid value with * @p opt
* regards to @p opt
*/ */
int (*set)(netdev_t *dev, netopt_t opt, int (*set)(netdev_t *dev, netopt_t opt,
const void *value, size_t value_len); const void *value, size_t value_len);