Updated doxygen descriptions, particularly the @return/@retval descriptions.
No change of implementation necessary.
Signed-off-by: Ola Liljedahl <ola.liljed...@linaro.org>
---
(This document/code contribution attached is provided under the terms of
agreement LES-LTM-21309)
include/odp/api/packet_io.h | 89 ++++++++++++++++++++++++++-------------------
Updated doxygen descriptions, particularly the @return/@retval descriptions.
No change of implementation necessary.
1 file changed, 51 insertions(+), 38 deletions(-)
diff --git a/include/odp/api/packet_io.h b/include/odp/api/packet_io.h
index 0c8af0c..3fa4063 100644
--- a/include/odp/api/packet_io.h
+++ b/include/odp/api/packet_io.h
@@ -56,7 +56,8 @@ extern "C" {
* @param pool Pool from which to allocate buffers for storing packets
* received over this packet IO
*
- * @return ODP packet IO handle or ODP_PKTIO_INVALID on error
+ * @return ODP packet IO handle
+ * @retval ODP_PKTIO_INVALID on failure
*
* @note dev name loop is specially pktio reserved name for
* device used for testing. Usually it's loop back
@@ -67,110 +68,118 @@ odp_pktio_t odp_pktio_open(const char *dev, odp_pool_t
pool);
/**
* Close an ODP packet IO instance
*
- * @param id ODP packet IO handle
+ * @param hdl ODP packet IO handle
*
- * @return 0 on success or -1 on error
+ * @retval 0 on success
+ * @retval <0 on failure
*/
-int odp_pktio_close(odp_pktio_t id);
+int odp_pktio_close(odp_pktio_t hdl);
/**
* Return a packet IO handle for an already open device
*
* @param dev Packet IO device name
*
- * @return ODP packet IO handle or ODP_PKTIO_INVALID
+ * @return ODP packet IO handle
+ * @retval ODP_PKTIO_INVALID on failure
*/
odp_pktio_t odp_pktio_lookup(const char *dev);
/**
* Receive packets
*
- * @param id ODP packet IO handle
+ * @param hdl ODP packet IO handle
* @param pkt_table[] Storage for received packets (filled by function)
* @param len Length of pkt_table[], i.e. max number of pkts to receive
*
- * @return Number of packets received or -1 on error
+ * @return Number of packets received
+ * @retval <0 on failure
*/
-int odp_pktio_recv(odp_pktio_t id, odp_packet_t pkt_table[], unsigned len);
+int odp_pktio_recv(odp_pktio_t hdl, odp_packet_t pkt_table[], unsigned len);
/**
* Send packets
*
- * @param id ODP packet IO handle
+ * @param hdl ODP packet IO handle
* @param pkt_table[] Array of packets to send
* @param len length of pkt_table[]
*
- * @return Number of packets sent or -1 on error
+ * @return Number of packets sent
+ * @retval <0 on failure
*/
-int odp_pktio_send(odp_pktio_t id, odp_packet_t pkt_table[], unsigned len);
+int odp_pktio_send(odp_pktio_t hdl, odp_packet_t pkt_table[], unsigned len);
/**
* Set the default input queue to be associated with a pktio handle
*
- * @param id ODP packet IO handle
+ * @param hdl ODP packet IO handle
* @param queue default input queue set
- * @return 0 on success or -1 on error
+ * @retval 0 on success
+ * @retval <0 on failure
*/
-int odp_pktio_inq_setdef(odp_pktio_t id, odp_queue_t queue);
+int odp_pktio_inq_setdef(odp_pktio_t hdl, odp_queue_t queue);
/**
* Get default input queue associated with a pktio handle
*
- * @param id ODP packet IO handle
+ * @param hdl ODP packet IO handle
*
- * @return Default input queue set or ODP_QUEUE_INVALID on error
+ * @return Default input queue set
+ * @retval ODP_QUEUE_INVALID on failure
*/
-odp_queue_t odp_pktio_inq_getdef(odp_pktio_t id);
+odp_queue_t odp_pktio_inq_getdef(odp_pktio_t hdl);
/**
* Remove default input queue (if set)
*
- * @param id ODP packet IO handle
+ * @param hdl ODP packet IO handle
*
- * @return 0 on success or -1 on error
+ * @retval 0 on success
+ * @retval <0 on failure
*/
-int odp_pktio_inq_remdef(odp_pktio_t id);
+int odp_pktio_inq_remdef(odp_pktio_t hdl);
/**
* Query default output queue
*
- * @param id ODP packet IO handle
+ * @param hdl ODP packet IO handle
*
- * @return Default out queue or ODP_QUEUE_INVALID on error
+ * @return Default out queue
+ * @retval ODP_QUEUE_INVALID on failure
*/
-odp_queue_t odp_pktio_outq_getdef(odp_pktio_t id);
+odp_queue_t odp_pktio_outq_getdef(odp_pktio_t hdl);
/**
* Return the currently configured MTU value of a packet IO interface.
*
- * @param[in] id ODP packet IO handle.
+ * @param[in] hdl ODP packet IO handle.
*
- * @retval MTU value >0 on success.
- * @retval -1 on any error or not existance pktio id.
+ * @return MTU value on success
+ * @retval <0 on failure
*/
-int odp_pktio_mtu(odp_pktio_t id);
+int odp_pktio_mtu(odp_pktio_t hdl);
/**
* Enable/Disable promiscuous mode on a packet IO interface.
*
- * @param[in] id ODP packet IO handle.
+ * @param[in] hdl ODP packet IO handle.
* @param[in] enable 1 to enable, 0 to disable.
*
- * @retval 0 on success.
- * @retval non-zero on any error.
+ * @retval 0 on success
+ * @retval <0 on failure
*/
-int odp_pktio_promisc_mode_set(odp_pktio_t id, odp_bool_t enable);
+int odp_pktio_promisc_mode_set(odp_pktio_t hdl, odp_bool_t enable);
/**
* Determine if promiscuous mode is enabled for a packet IO interface.
*
- * @param[in] id ODP packet IO handle.
+ * @param[in] hdl ODP packet IO handle.
*
* @retval 1 if promiscuous mode is enabled.
* @retval 0 if promiscuous mode is disabled.
- * @retval -1 on any error.
+ * @retval <0 on failure
*/
-int odp_pktio_promisc_mode(odp_pktio_t id);
+int odp_pktio_promisc_mode(odp_pktio_t hdl);
/**
* Get the native MAC address of a packet IO interface.
@@ -193,7 +202,8 @@ ssize_t odp_pktio_mac_addr(odp_pktio_t hdl, void *mac_addr,
ssize_t size);
* unless overridden by subsequent
* header-based filters.
*
- * @return 0 on success, non-zero on error.
+ * @retval 0 on success
+ * @retval <0 on failure
*/
int odp_pktio_default_cos_set(odp_pktio_t pktio_in, odp_cos_t default_cos);
@@ -205,7 +215,8 @@ int odp_pktio_default_cos_set(odp_pktio_t pktio_in,
odp_cos_t default_cos);
* at the pktio_in ingress port
* that contain an error.
*
- * @return 0 on success, non-zero on error.
+ * @retval 0 on success
+ * @retval <0 on failure
*
* @note Optional.
*/
@@ -217,7 +228,8 @@ int odp_pktio_error_cos_set(odp_pktio_t pktio_in, odp_cos_t
error_cos);
* @param[in] pktio_in Ingress port identifier.
* @param[in] offset Number of bytes the classifier must skip.
*
- * @return 0 on success, non-zero on error.
+ * @retval 0 on success
+ * @retval <0 on failure
* @note Optional.
*
*/
@@ -232,7 +244,8 @@ int odp_pktio_skip_set(odp_pktio_t pktio_in, uint32_t
offset);
* Must not exceed the implementation
* defined ODP_PACKET_MAX_HEADROOM.
*
- * @return 0 on success, non-zero on error.
+ * @retval 0 on success
+ * @retval <0 on failure
*
* @note Optional.
*/
--
1.9.1
_______________________________________________
lng-odp mailing list
lng-odp@lists.linaro.org
http://lists.linaro.org/mailman/listinfo/lng-odp
