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

netdev2: make doc for driver more precise

Browse Source 
When working on #6121 I noticed that the documentation of the `netdev2`
driver part is not really precise. This fixes that.
This commit is contained in:
Martine Lenders 2016-11-22 14:57:21 +01:00
parent 13ab672759
commit 32c19d63e3
1 changed files with 22 additions and 7 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

29
drivers/include/net/netdev2.h
View File

@ -131,17 +131,24 @@ typedef struct netdev2_driver {
/**
* @brief Send frame
*
* @pre `(dev != NULL)`
* @pre `(count == 0) || (vector != NULL)`
* (`(count != 0) => (vector != NULL)`)
*
* @param[in] dev network device descriptor
* @param[in] vector io vector array to send
* @param[in] count nr of entries in vector
*
* @return nr of bytes sent, or <=0 on error
* @return number of bytes sent, or `< 0` on error
*/
int (*send)(netdev2_t *dev, const struct iovec *vector, unsigned count);
/**
* @brief Get a received frame
*
* @pre `(dev != NULL)`
* @pre `(buf != NULL) && (len > 0)`
*
* Supposed to be called from @ref netdev2_t::event_callback().
*
* If buf == NULL and len == 0, returns the packet size without dropping it.
@ -149,13 +156,13 @@ typedef struct netdev2_driver {
*
* @param[in] dev network device descriptor
* @param[out] buf buffer to write into or NULL
* @param[in] len maximum nr. of bytes to read
* @param[in] len maximum number of bytes to read
* @param[out] info status information for the received packet. Might
* be of different type for different netdev2 devices.
* May be NULL if not needed or applicable.
*
* @return <=0 on error
* @return nr of bytes read if buf != NULL
* @return `< 0` on error
* @return number of bytes read if buf != NULL
* @return packet size if buf == NULL
*/
int (*recv)(netdev2_t *dev, void *buf, size_t len, void *info);
@ -163,13 +170,17 @@ typedef struct netdev2_driver {
/**
* @brief the driver's initialization function
*
* @return <=0 on error, >0 on success
* @pre `(dev != NULL)`
*
* @return `< 0` on error, 0 on success
*/
int (*init)(netdev2_t *dev);
/**
* @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 netdev2_isr.
*
@ -184,13 +195,15 @@ typedef struct netdev2_driver {
/**
* @brief Get an option value from a given network device
*
* @pre `(dev != NULL)`
*
* @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
* @return <0 on error
* @return `< 0` on error, 0 on success
*/
int (*get)(netdev2_t *dev, netopt_t opt,
void *value, size_t max_len);
@ -198,13 +211,15 @@ typedef struct netdev2_driver {
/**
* @brief Set an option value for a given network device
*
* @pre `(dev != NULL)`
*
* @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 used from @p value
* @return <0 on error
* @return `< 0` on error, 0 on success
*/
int (*set)(netdev2_t *dev, netopt_t opt,
void *value, size_t value_len);