| Message ID | 1422982108-13813-12-git-send-email-ola.liljedahl@linaro.org |
|---|---|
| State | New |
| Headers | show |
Another couple of patches I assume? On 4 February 2015 at 14:30, Savolainen, Petri (NSN - FI/Espoo) <petri.savolainen@nsn.com> wrote: > > >> -----Original Message----- >> From: lng-odp-bounces@lists.linaro.org [mailto:lng-odp- >> bounces@lists.linaro.org] On Behalf Of ext Ola Liljedahl >> Sent: Tuesday, February 03, 2015 6:48 PM >> To: lng-odp@lists.linaro.org >> Subject: [lng-odp] [PATCHv5 11/18] api: odp_packet_io.h: updated return >> descriptions >> >> Updated doxygen descriptions, particularly the @return/@retval >> descriptions. >> No change of implementation necessary. >> >> Signed-off-by: Ola Liljedahl <ola.liljedahl@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); > > > As agreed, it's better to rename "id" to "pktio". And do that (preferably) on a separate patch. That can rename those couple of "pktio_in" in the bottom of the file. > > > About "unsigned len": if I remember correctly we agreed that functions that handle number of objects (not bytes or offset or chars) would have int both on input and output. > > > int odp_pktio_recv(odp_pktio_t hdl, odp_packet_t pkt_table[], int len); > > > int num = 10; > int ret; > > ret = odp_pktio_recv(pktio, pkts[], num); > > if (ret < num) > ... > > >> >> /** >> * 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); > > Same here: int vs. unsigned ? > > > -Petri > > > >> >> /** >> * 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
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. */
Updated doxygen descriptions, particularly the @return/@retval descriptions. No change of implementation necessary. Signed-off-by: Ola Liljedahl <ola.liljedahl@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(-)