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