[PATCHv5,11/18] api: odp_packet_io.h: updated return descriptions

Message ID 1422982108-13813-12-git-send-email-ola.liljedahl@linaro.org
State New
Headers show

Commit Message

Ola Liljedahl Feb. 3, 2015, 4:48 p.m.
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(-)

Comments

Ola Liljedahl Feb. 4, 2015, 1:40 p.m. | #1
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

Patch

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.
  */