> -----Original Message----- > From: lng-odp-boun...@lists.linaro.org [mailto:lng-odp- > boun...@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.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);
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 _______________________________________________ lng-odp mailing list lng-odp@lists.linaro.org http://lists.linaro.org/mailman/listinfo/lng-odp
