| Message ID | 1422318015-729-1-git-send-email-ola.liljedahl@linaro.org |
|---|---|
| State | New |
| Headers | show |
This looks good. It will need to be rebased following the event patch merge (all merges currently blocked until that happens). See additional comments inline: On Mon, Jan 26, 2015 at 6:20 PM, Ola Liljedahl <ola.liljedahl@linaro.org> wrote: > Unify @return and @retval descriptions. > @return used for values that cannot (meaningfully) be enumerated (e.g > pointers, > ODP handles) or simply tested for correctness. > @retval used for values that can be enumerated and should be tested by > validation programs. > Changed from bool to odp_bool_t in odp_crypto.h and dependent source files. > Changed return type and value of odp_pktio_mac_addr() to match other > similar > functions. Use int as return type, <0 to indicate failure. > > Signed-off-by: Ola Liljedahl <ola.liljedahl@linaro.org> > --- > (This document/code contribution attached is provided under the terms of > agreement LES-LTM-21309) > > example/ipsec/odp_ipsec.c | 4 +- > platform/linux-generic/include/api/odp_buffer.h | 9 ++- > .../linux-generic/include/api/odp_buffer_pool.h | 21 ++++--- > platform/linux-generic/include/api/odp_byteorder.h | 2 +- > .../linux-generic/include/api/odp_classification.h | 48 +++++++++------- > platform/linux-generic/include/api/odp_cpumask.h | 12 ++-- > platform/linux-generic/include/api/odp_crypto.h | 15 +++-- > platform/linux-generic/include/api/odp_init.h | 10 ++-- > platform/linux-generic/include/api/odp_packet.h | 66 > ++++++++++++---------- > .../linux-generic/include/api/odp_packet_flags.h | 57 > ++++++++++++------- > platform/linux-generic/include/api/odp_packet_io.h | 54 +++++++++++------- > platform/linux-generic/include/api/odp_queue.h | 25 +++++--- > platform/linux-generic/include/api/odp_schedule.h | 3 +- > .../linux-generic/include/api/odp_shared_memory.h | 15 +++-- > platform/linux-generic/include/api/odp_timer.h | 19 ++++--- > platform/linux-generic/odp_crypto.c | 4 +- > platform/linux-generic/odp_packet_io.c | 6 +- > test/validation/crypto/odp_crypto_test_async_inp.c | 2 +- > test/validation/crypto/odp_crypto_test_sync_inp.c | 2 +- > 19 files changed, 226 insertions(+), 148 deletions(-) > > diff --git a/example/ipsec/odp_ipsec.c b/example/ipsec/odp_ipsec.c > index f2fac8a..066dc40 100644 > --- a/example/ipsec/odp_ipsec.c > +++ b/example/ipsec/odp_ipsec.c > @@ -683,7 +683,7 @@ pkt_disposition_e do_ipsec_in_classify(odp_packet_t > pkt, > odph_esphdr_t *esp = NULL; > ipsec_cache_entry_t *entry; > odp_crypto_op_params_t params; > - bool posted = 0; > + odp_bool_t posted = 0; > > /* Default to skip IPsec */ > *skip = TRUE; > @@ -955,7 +955,7 @@ pkt_disposition_e do_ipsec_out_seq(odp_packet_t pkt, > pkt_ctx_t *ctx) > { > uint8_t *buf = odp_packet_data(pkt); > - bool posted = 0; > + odp_bool_t posted = 0; > > /* We were dispatched from atomic queue, assign sequence numbers */ > if (ctx->ipsec.ah_offset) { > diff --git a/platform/linux-generic/include/api/odp_buffer.h > b/platform/linux-generic/include/api/odp_buffer.h > index 0670464..fd0871b 100644 > --- a/platform/linux-generic/include/api/odp_buffer.h > +++ b/platform/linux-generic/include/api/odp_buffer.h > @@ -32,6 +32,7 @@ extern "C" { > * Buffer start address > * > * @param buf Buffer handle > + * Note: Buffer handle must be valid or the behavior will be undefined. > Should these be @note ? Same comment for similar Note: adds. Phrasing in present tense (...or behavior is undefined) seems more natural, but that's a stylistic point that's I won't argue. > * > * @return Buffer start address > */ > @@ -41,6 +42,7 @@ void *odp_buffer_addr(odp_buffer_t buf); > * Buffer maximum data size > * > * @param buf Buffer handle > + * Note: Buffer handle must be valid or the behavior will be undefined. > * > * @return Buffer maximum data size > */ > @@ -50,12 +52,12 @@ uint32_t odp_buffer_size(odp_buffer_t buf); > * Buffer type > * > * @param buf Buffer handle > + * Note: Buffer handle must be valid or the behavior will be undefined. > * > * @return Buffer type > */ > int odp_buffer_type(odp_buffer_t buf); > > -#define ODP_BUFFER_TYPE_INVALID (-1) /**< Buffer type invalid */ > #define ODP_BUFFER_TYPE_ANY 0 /**< Buffer that can hold any other > buffer type */ > #define ODP_BUFFER_TYPE_RAW 1 /**< Raw buffer, no additional > metadata */ > @@ -65,7 +67,9 @@ int odp_buffer_type(odp_buffer_t buf); > /** > * Tests if buffer is valid > * > - * @param buf Buffer handle > + * @param buf Buffer handle (possibly invalid) > + * Note: This is the only call which accepts invalid buffer handles (any > bit > + * value) without causing undefined behavior. > Definitely should be @note for this one. Would it be clearer to say "API" rather than "call"? Grammar nit: that rather than which is correct here. > * > * @retval 1 Buffer handle represents a valid buffer. > * @retval 0 Buffer handle does not represent a valid buffer. > @@ -76,6 +80,7 @@ int odp_buffer_is_valid(odp_buffer_t buf); > * Buffer pool of the buffer > * > * @param buf Buffer handle > + * Note: Buffer handle must be valid or the behavior will be undefined. > * > * @return Handle of buffer pool buffer belongs to > */ > diff --git a/platform/linux-generic/include/api/odp_buffer_pool.h > b/platform/linux-generic/include/api/odp_buffer_pool.h > index 8380ac1..fe917a4 100644 > --- a/platform/linux-generic/include/api/odp_buffer_pool.h > +++ b/platform/linux-generic/include/api/odp_buffer_pool.h > @@ -81,8 +81,8 @@ odp_buffer_pool_t odp_buffer_pool_create(const char > *name, > * > * @param pool Handle of the buffer pool to be destroyed > * > - * @retval 0 Success > - * @retval -1 Failure > + * @retval 0 if successful > + * @retval <0 on failure > * > * @note This routine destroys a previously created buffer pool. This call > * does not destroy any shared memory object passed to > @@ -117,7 +117,7 @@ typedef struct odp_buffer_pool_info_t { > odp_shm_t shm; /**< handle of shared memory area > supplied by application to > contain buffer pool, or > - ODP_SHM_INVALID if this pool > is > + ODP_SHM_NULL if this pool is > managed by ODP */ > odp_buffer_pool_param_t params; /**< pool parameters */ > } odp_buffer_pool_info_t; > @@ -125,13 +125,13 @@ typedef struct odp_buffer_pool_info_t { > /** > * Retrieve information about a buffer pool > * > - * @param pool Buffer pool handle > + * @param pool Buffer pool handle (possibly invalid) > * > * @param[out] info Receives an odp_buffer_pool_info_t object > * that describes the pool. > * > - * @retval 0 Success > - * @retval -1 Failure. Info could not be retrieved. > + * @retval 0 if successful > + * @retval <0 on failure. Info could not be retrieved (invalid pool > handle) > */ > > int odp_buffer_pool_info(odp_buffer_pool_t pool, > @@ -149,17 +149,22 @@ void odp_buffer_pool_print(odp_buffer_pool_t pool); > > /** > * Buffer alloc > + * Note: the pool handle must be valid or the behavior is undefined. > + * > + * The validity of a buffer handle can be checked at any time using > + * odp_buffer_is_valid() > * > - * The validity of a buffer can be cheked at any time with > odp_buffer_is_valid() > * @param pool Pool handle > * > * @return Handle of allocated buffer > - * @retval ODP_BUFFER_INVALID Buffer could not be allocated > + * @retval ODP_BUFFER_INVALID Buffer could not be allocated (e.g. pool > + * exhausted) > */ > odp_buffer_t odp_buffer_alloc(odp_buffer_pool_t pool); > > /** > * Buffer free > + * Note: the buffer handle must be valid or the behavior is undefined. > * > * @param buf Buffer handle > * > diff --git a/platform/linux-generic/include/api/odp_byteorder.h > b/platform/linux-generic/include/api/odp_byteorder.h > index 5890011..8e38937 100644 > --- a/platform/linux-generic/include/api/odp_byteorder.h > +++ b/platform/linux-generic/include/api/odp_byteorder.h > @@ -24,7 +24,7 @@ extern "C" { > #include <odp_compiler.h> > > /** @defgroup odp_compiler_optim ODP COMPILER / OPTIMIZATION > - * Macros that check byte order and byte converting operations. > + * Macros that check and convert byte order. > * @{ > */ > > diff --git a/platform/linux-generic/include/api/odp_classification.h > b/platform/linux-generic/include/api/odp_classification.h > index 46189bc..6bca8fc 100644 > --- a/platform/linux-generic/include/api/odp_classification.h > +++ b/platform/linux-generic/include/api/odp_classification.h > @@ -79,8 +79,8 @@ typedef enum odp_cos_hdr_flow_fields { > * > * @param[in] name String intended for debugging purposes. > * > - * @return Class of service instance identifier, > - * or ODP_COS_INVALID on error. > + * @return Class of service instance identifier > + * @retval ODP_COS_INVALID on failure. > */ > odp_cos_t odp_cos_create(const char *name); > > @@ -89,7 +89,8 @@ odp_cos_t odp_cos_create(const char *name); > * > * @param[in] cos_id class-of-service instance. > * > - * @return 0 on success, non-zero on error. > + * @retval 0 if successful > + * @retval <0 on failure > */ > int odp_cos_destroy(odp_cos_t cos_id); > > @@ -102,7 +103,8 @@ int odp_cos_destroy(odp_cos_t cos_id); > * of this specific class of service > * will be enqueued. > * > - * @return 0 on success, non-zero on error. > + * @retval 0 if successful > + * @retval <0 on failure > */ > int odp_cos_set_queue(odp_cos_t cos_id, odp_queue_t queue_id); > > @@ -112,7 +114,8 @@ int odp_cos_set_queue(odp_cos_t cos_id, odp_queue_t > queue_id); > * @param[in] cos_id class-of-service instance. > * @param[in] drop_policy Desired packet drop policy for this class. > * > - * @return 0 on success, non-zero on error. > + * @retval 0 if successful > + * @retval <0 on failure > * > * @note Optional. > */ > @@ -127,7 +130,8 @@ int odp_cos_set_drop(odp_cos_t cos_id, odp_drop_e > drop_policy); > * @param[in] qos_table Values of the Layer-2 QoS header field. > * @param[in] cos_table Class-of-service assigned to each of the > * allowed Layer-2 QOS levels. > - * @return 0 on success, non-zero on error. > + * @retval 0 if successful > + * @retval <0 on failure > */ > int odp_cos_with_l2_priority(odp_pktio_t pktio_in, > uint8_t num_qos, > @@ -146,7 +150,8 @@ int odp_cos_with_l2_priority(odp_pktio_t pktio_in, > * @param[in] l3_preference when true, Layer-3 QoS overrides > * L2 QoS when present. > * > - * @return 0 on success, non-zero on error. > + * @retval 0 if successful > + * @retval <0 on failure > * > * @note Optional. > */ > @@ -219,7 +224,8 @@ typedef enum odp_pmr_term { > * that must match the value size requirement of the > * specific term. > * > - * @return Handle of the matching rule or ODP_PMR_INVAL on > error > + * @return Handle of the matching rule > + * @retval ODP_PMR_INVAL on failure > */ > odp_pmr_t odp_pmr_create_match(odp_pmr_term_e term, > const void *val, > @@ -236,7 +242,8 @@ odp_pmr_t odp_pmr_create_match(odp_pmr_term_e term, > * that must match the value size requirement of the > * specific term. > * > - * @return Handle of the matching rule or ODP_PMR_INVAL on > error > + * @return Handle of the matching rule > + * @retval ODP_PMR_INVAL on failure > * @note: Range is inclusive [val1..val2]. > */ > odp_pmr_t odp_pmr_create_range(odp_pmr_term_e term, > @@ -248,7 +255,8 @@ odp_pmr_t odp_pmr_create_range(odp_pmr_term_e term, > * > * @param[in] pmr_id Identifier of the PMR to be destroyed > * > - * @return 0 on success, non-zero or error. > + * @retval 0 if successful > + * @retval <0 on failure > */ > int odp_pmr_destroy(odp_pmr_t pmr_id); > > @@ -259,7 +267,8 @@ int odp_pmr_destroy(odp_pmr_t pmr_id); > * @param[in] src_pktio pktio to which this PMR is to be applied > * @param[in] dst_cos CoS to be assigned by this PMR > * > - * @return 0 on success, non-zero or error. > + * @retval 0 if successful > + * @retval <0 on failure > */ > int odp_pktio_pmr_cos(odp_pmr_t pmr_id, > odp_pktio_t src_pktio, odp_cos_t dst_cos); > @@ -272,7 +281,8 @@ int odp_pktio_pmr_cos(odp_pmr_t pmr_id, > * @param[in] dst_cos CoS to be assigned to packets filtered > * from src_cos that match pmr_id. > * > - * @return 0 on success, non-zero on error. > + * @retval 0 if successful > + * @retval <0 on failure > */ > int odp_cos_pmr_cos(odp_pmr_t pmr_id, odp_cos_t src_cos, odp_cos_t > dst_cos); > > @@ -346,12 +356,10 @@ typedef uint32_t odp_pmr_set_t; > * term desired. > * @param[out] pmr_set_id Returned handle to the composite rule set. > * > - * @return Return value may be a positive number > - * indicating the number of terms elements > + * @return the number of terms elements > * that have been successfully mapped to the > - * underlying platform classification engine > and > - * may be in the range from 1 to num_terms, > - * or non-zero for error. > + * underlying platform classification engine > + * @retval <0 on failure > */ > int odp_pmr_match_set_create(int num_terms, odp_pmr_match_t *terms, > odp_pmr_set_t *pmr_set_id); > @@ -369,7 +377,8 @@ int odp_pmr_match_set_create(int num_terms, > odp_pmr_match_t *terms, > * @param[in] pmr_set_id A composite rule-set handle > * returned when created. > * > - * @return 0 on success, non-zero on error. > + * @retval 0 if successful > + * @retval <0 on failure > */ > int odp_pmr_match_set_destroy(odp_pmr_set_t pmr_set_id); > > @@ -381,7 +390,8 @@ int odp_pmr_match_set_destroy(odp_pmr_set_t > pmr_set_id); > * set is to be applied > * @param[in] dst_cos CoS to be assigned by this PMR match set > * > - * @return 0 on success, non-zero or error. > + * @retval 0 if successful > + * @retval <0 on failure > */ > int odp_pktio_pmr_match_set_cos(odp_pmr_set_t pmr_set_id, odp_pktio_t > src_pktio, > odp_cos_t dst_cos); > diff --git a/platform/linux-generic/include/api/odp_cpumask.h > b/platform/linux-generic/include/api/odp_cpumask.h > index ebff9b0..5c5bcd7 100644 > --- a/platform/linux-generic/include/api/odp_cpumask.h > +++ b/platform/linux-generic/include/api/odp_cpumask.h > @@ -79,7 +79,8 @@ void odp_cpumask_clr(odp_cpumask_t *mask, int cpu); > * Test if cpu is a member of mask > * @param mask CPU mask to check if cpu num set or not > * @param cpu CPU number > - * @return non-zero if set otherwise 0 > + * @return non-zero if set > + * @retval 0 if not set > */ > int odp_cpumask_isset(const odp_cpumask_t *mask, int cpu); > > @@ -134,14 +135,16 @@ void odp_cpumask_copy(odp_cpumask_t *dest, const > odp_cpumask_t *src); > /** > * Find first bit set in mask > * > - * @return cpu else -1 if no bits set in cpumask > + * @return cpu > + * @retval -1 if no bits set in cpumask > Should this be <0 for consistency with other error RC descriptions? > */ > int odp_cpumask_first(const odp_cpumask_t *mask); > > /** > * Find last bit set in mask > * > - * @return cpu else -1 if no bits set in cpumask > + * @return cpu > + * @retval -1 if no bits set in cpumask > Same here. <0 ? > */ > int odp_cpumask_last(const odp_cpumask_t *mask); > > @@ -160,7 +163,8 @@ int odp_cpumask_last(const odp_cpumask_t *mask); > * > * @param mask CPU mask to find next cpu in > * @param cpu CPU to start from > - * @return cpu found else -1 > + * @return cpu found > + * @retval -1 if not found > And again here. > * > * @see odp_cpumask_first() > */ > diff --git a/platform/linux-generic/include/api/odp_crypto.h > b/platform/linux-generic/include/api/odp_crypto.h > index 337e7cf..2f00f95 100644 > --- a/platform/linux-generic/include/api/odp_crypto.h > +++ b/platform/linux-generic/include/api/odp_crypto.h > @@ -218,7 +218,8 @@ typedef struct odp_crypto_compl_status { > * @param session Created session else > ODP_CRYPTO_SESSION_INVALID > * @param status Failure code if unsuccessful > * > - * @return 0 if successful else -1 > + * @retval 0 if successful > + * @retval <0 on failure > */ > int > odp_crypto_session_create(odp_crypto_session_params_t *params, > @@ -242,11 +243,12 @@ > odp_crypto_session_create(odp_crypto_session_params_t *params, > * @param posted Pointer to return posted, TRUE for async > operation > * @param completion_event Event by which the operation results are > delivered. > * > - * @return 0 if successful else -1 > + * @retval 0 if successful > + * @retval <0 on failure > */ > int > odp_crypto_operation(odp_crypto_op_params_t *params, > - bool *posted, > + odp_bool_t *posted, > odp_buffer_t completion_event); > > /** > @@ -281,7 +283,7 @@ odp_crypto_get_operation_compl_status(odp_buffer_t > completion_event, > * > * @param completion_event Event containing operation results > * > - * @return Packet structure where data now resides > + * @return Handle for packet where data now resides > */ > odp_packet_t > odp_crypto_get_operation_compl_packet(odp_buffer_t completion_event); > @@ -305,10 +307,11 @@ odp_crypto_get_operation_compl_ctx(odp_buffer_t > completion_event); > * > * @todo Define the implication of the use_entropy parameter > * > - * @return 0 if succesful > + * @retval 0 if successful > + * @retval <0 on failure > */ > int > -odp_hw_random_get(uint8_t *buf, size_t *len, bool use_entropy); > +odp_hw_random_get(uint8_t *buf, size_t *len, odp_bool_t use_entropy); > > /** > * @} > diff --git a/platform/linux-generic/include/api/odp_init.h > b/platform/linux-generic/include/api/odp_init.h > index ac856df..4a98717 100644 > --- a/platform/linux-generic/include/api/odp_init.h > +++ b/platform/linux-generic/include/api/odp_init.h > @@ -66,8 +66,8 @@ typedef enum odp_log_level { > * @param[in] level Log level > * @param[in] fmt printf-style message format > * > - * @return The number of characters logged if succeeded. Otherwise returns > - * a negative number. > + * @return The number of characters logged if successful > + * @retval <0 on failure > */ > int odp_override_log(odp_log_level_e level, const char *fmt, ...); > > @@ -109,7 +109,7 @@ typedef struct odp_platform_init_t { > * interpretation by the ODP API to the implementation. > * > * @retval 0 if successful > - * @retval -1 on failure > + * @retval <0 on failure > */ > int odp_init_global(odp_init_t *params, odp_platform_init_t > *platform_params); > > @@ -134,7 +134,7 @@ int odp_init_global(odp_init_t *params, > odp_platform_init_t *platform_params); > * @sa odp_term_local() which must have been called prior to this. > * > * @retval 0 if successful > - * @retval -1 on failure > + * @retval <0 on failure > */ > int odp_term_global(void); > > @@ -148,7 +148,7 @@ int odp_term_global(void); > * @sa odp_init_global() which must have been called prior to this. > * > * @retval 0 if successful > - * @retval -1 on failure > + * @retval <0 on failure > */ > int odp_init_local(void); > > diff --git a/platform/linux-generic/include/api/odp_packet.h > b/platform/linux-generic/include/api/odp_packet.h > index 920a593..b471d07 100644 > --- a/platform/linux-generic/include/api/odp_packet.h > +++ b/platform/linux-generic/include/api/odp_packet.h > @@ -88,8 +88,8 @@ void odp_packet_free(odp_packet_t pkt); > * @param pkt Packet handle > * @param len Packet data length > * > - * @retval 0 Success > - * @retval Non-zero Failure > + * @retval 0 if successful > + * @retval <0 on failure > * > * @see odp_packet_buf_len() > */ > @@ -279,7 +279,7 @@ void *odp_packet_push_head(odp_packet_t pkt, uint32_t > len); > * @param pkt Packet handle > * @param len Number of bytes to pull the head (0 ... seg_len - 1) > * > - * @return The new data pointer, or NULL in case of an error. > + * @return The new data pointer > * @retval NULL Requested offset exceeds packet segment length * > * @see odp_packet_seg_len(), odp_packet_push_head() > @@ -391,7 +391,7 @@ odp_buffer_pool_t odp_packet_pool(odp_packet_t pkt); > * @param pkt Packet handle > * > * @return Packet interface handle > - * @retval ODP_PKTIO_INVALID Packet was not received > + * @retval ODP_PKTIO_INVALID Packet was not received on any interface > */ > odp_pktio_t odp_packet_input(odp_packet_t pkt); > > @@ -451,8 +451,8 @@ void odp_packet_user_u64_set(odp_packet_t pkt, > uint64_t ctx); > * @param[out] len Number of data bytes remaining in the segment > (output). > * Ignored when NULL. > * > - * @return Layer 2 start pointer, or NULL when packet does not contain a > valid > - * L2 header. > + * @return Layer 2 start pointer > + * @retval NULL packet does not contain a valid L2 header > * > * @see odp_packet_l2_offset(), odp_packet_l2_offset_set(), > odp_packet_has_l2() > */ > @@ -469,8 +469,8 @@ void *odp_packet_l2_ptr(odp_packet_t pkt, uint32_t > *len); > * > * @param pkt Packet handle > * > - * @return Layer 2 start offset, or ODP_PACKET_OFFSET_INVALID when > packet does > - * not contain a valid L2 header. > + * @return Layer 2 start offset > + * @retval ODP_PACKET_OFFSET_INVALID packet does not contain a valid L2 > header > * > * @see odp_packet_l2_offset_set(), odp_packet_has_l2() > */ > @@ -486,8 +486,8 @@ uint32_t odp_packet_l2_offset(odp_packet_t pkt); > * @param pkt Packet handle > * @param offset Layer 2 start offset (0 ... odp_packet_len()-1) > * > - * @retval 0 Success > - * @retval Non-zero Failure > + * @retval 0 if successful > + * @retval <0 on failure > */ > int odp_packet_l2_offset_set(odp_packet_t pkt, uint32_t offset); > > @@ -501,8 +501,8 @@ int odp_packet_l2_offset_set(odp_packet_t pkt, > uint32_t offset); > * @param[out] len Number of data bytes remaining in the segment > (output). > * Ignored when NULL. > * > - * @return Layer 3 start pointer, or NULL when packet does not contain a > valid > - * L3 header. > + * @return Layer 3 start pointer > + * @retval NULL packet does not contain a valid L3 header > * > * @see odp_packet_l3_offset(), odp_packet_l3_offset_set(), > odp_packet_has_l3() > */ > @@ -536,8 +536,8 @@ uint32_t odp_packet_l3_offset(odp_packet_t pkt); > * @param pkt Packet handle > * @param offset Layer 3 start offset (0 ... odp_packet_len()-1) > * > - * @retval 0 Success > - * @retval Non-zero Failure > + * @retval 0 if successful > + * @retval <0 on failure > */ > int odp_packet_l3_offset_set(odp_packet_t pkt, uint32_t offset); > > @@ -551,8 +551,8 @@ int odp_packet_l3_offset_set(odp_packet_t pkt, > uint32_t offset); > * @param[out] len Number of data bytes remaining in the segment > (output). > * Ignored when NULL. > * > - * @return Layer 4 start pointer, or NULL when packet does not contain a > valid > - * L4 header. > + * @return Layer 4 start pointer > + * @retval NULL packet does not contain a valid L4 header > * > * @see odp_packet_l4_offset(), odp_packet_l4_offset_set(), > odp_packet_has_l4() > */ > @@ -569,8 +569,8 @@ void *odp_packet_l4_ptr(odp_packet_t pkt, uint32_t > *len); > * > * @param pkt Packet handle > * > - * @return Layer 4 start offset, or ODP_PACKET_OFFSET_INVALID when > packet does > - * not contain a valid L4 header. > + * @return Layer 4 start offset > + * @retval ODP_PACKET_OFFSET_INVALID packet does not contain a valid L4 > header > * > * @see odp_packet_l4_offset_set(), odp_packet_has_l4() > */ > @@ -586,8 +586,8 @@ uint32_t odp_packet_l4_offset(odp_packet_t pkt); > * @param pkt Packet handle > * @param offset Layer 4 start offset (0 ... odp_packet_len()-1) > * > - * @retval 0 Success > - * @retval Non-zero Failure > + * @retval 0 on success > + * @retval <0 on failure > */ > int odp_packet_l4_offset_set(odp_packet_t pkt, uint32_t offset); > > @@ -645,7 +645,8 @@ odp_packet_seg_t odp_packet_last_seg(odp_packet_t pkt); > * @param pkt Packet handle > * @param seg Current segment handle > * > - * @return Handle to the next segment, or ODP_PACKET_SEG_INVALID > + * @return Handle to the next segment > + * @retval ODP_PACKET_SEG_INVALID if there are no more segments > */ > odp_packet_seg_t odp_packet_next_seg(odp_packet_t pkt, odp_packet_seg_t > seg); > > @@ -665,7 +666,8 @@ odp_packet_seg_t odp_packet_next_seg(odp_packet_t pkt, > odp_packet_seg_t seg); > * @param pkt Packet handle > * @param seg Segment handle > * > - * @return Start address of the segment, or NULL on an error > + * @return Start address of the segment > + * @retval NULL on failure > * > * @see odp_packet_seg_buf_len() > */ > @@ -693,7 +695,8 @@ uint32_t odp_packet_seg_buf_len(odp_packet_t pkt, > odp_packet_seg_t seg); > * @param pkt Packet handle > * @param seg Segment handle > * > - * @return Pointer to the segment data, or NULL on an error > + * @return Pointer to the segment data > + * @retval NULL on failure > * > * @see odp_packet_seg_data_len() > */ > @@ -735,7 +738,8 @@ uint32_t odp_packet_seg_data_len(odp_packet_t pkt, > odp_packet_seg_t seg); > * @param offset Byte offset into the packet > * @param len Number of bytes to add into the offset > * > - * @return New packet handle, or ODP_PACKET_INVALID in case of an error. > + * @return New packet handle > + * @retval ODP_PACKET_INVALID on failure > */ > odp_packet_t odp_packet_add_data(odp_packet_t pkt, uint32_t offset, > uint32_t len); > @@ -753,7 +757,8 @@ odp_packet_t odp_packet_add_data(odp_packet_t pkt, > uint32_t offset, > * @param offset Byte offset into the packet > * @param len Number of bytes to remove from the offset > * > - * @return New packet handle, or ODP_PACKET_INVALID in case of an error. > + * @return New packet handle > + * @retval ODP_PACKET_INVALID on failure > */ > odp_packet_t odp_packet_rem_data(odp_packet_t pkt, uint32_t offset, > uint32_t len); > @@ -776,7 +781,8 @@ odp_packet_t odp_packet_rem_data(odp_packet_t pkt, > uint32_t offset, > * @param pkt Packet handle > * @param pool Buffer pool for allocation of the new packet. > * > - * @return Handle to the copy of the packet, or ODP_PACKET_INVALID > + * @return Handle to the copy of the packet > + * @retval ODP_PACKET_INVALID on failure > */ > odp_packet_t odp_packet_copy(odp_packet_t pkt, odp_buffer_pool_t pool); > > @@ -791,8 +797,8 @@ odp_packet_t odp_packet_copy(odp_packet_t pkt, > odp_buffer_pool_t pool); > * @param len Number of bytes to copy > * @param dst Destination address > * > - * @retval 0 Success > - * @retval Non-zero Failure > + * @retval 0 on success > + * @retval <0 on failure > */ > int odp_packet_copydata_out(odp_packet_t pkt, uint32_t offset, > uint32_t len, void *dst); > @@ -809,8 +815,8 @@ int odp_packet_copydata_out(odp_packet_t pkt, uint32_t > offset, > * @param len Number of bytes to copy > * @param src Source address > * > - * @retval 0 Success > - * @retval Non-zero Failure > + * @retval 0 on success > + * @retval <0 on failure > */ > int odp_packet_copydata_in(odp_packet_t pkt, uint32_t offset, > uint32_t len, const void *src); > diff --git a/platform/linux-generic/include/api/odp_packet_flags.h > b/platform/linux-generic/include/api/odp_packet_flags.h > index 24c4065..399a0bf 100644 > --- a/platform/linux-generic/include/api/odp_packet_flags.h > +++ b/platform/linux-generic/include/api/odp_packet_flags.h > @@ -32,7 +32,8 @@ extern "C" { > * Checks all error flags at once. > * > * @param pkt Packet handle > - * @return 1 if packet has errors, 0 otherwise > + * @retval 1 if packet has errors > + * @retval 0 if packet has no errors > */ > int odp_packet_error(odp_packet_t pkt); > > @@ -40,7 +41,8 @@ int odp_packet_error(odp_packet_t pkt); > * Check if error was 'frame length' error > * > * @param pkt Packet handle > - * @return 1 if frame length error detected, 0 otherwise > + * @retval 1 if frame length error detected > + * @retval 0 if frame length error not detected > */ > int odp_packet_errflag_frame_len(odp_packet_t pkt); > > @@ -48,7 +50,8 @@ int odp_packet_errflag_frame_len(odp_packet_t pkt); > * Check for L2 header, e.g. ethernet > * > * @param pkt Packet handle > - * @return 1 if packet contains a valid & known L2 header, 0 otherwise > + * @retval 1 if packet contains a valid & known L2 header > + * @retval 0 if packet does not contain a valid & known L2 header > */ > int odp_packet_has_l2(odp_packet_t pkt); > > @@ -56,7 +59,8 @@ int odp_packet_has_l2(odp_packet_t pkt); > * Check for L3 header, e.g. IPv4, IPv6 > * > * @param pkt Packet handle > - * @return 1 if packet contains a valid & known L3 header, 0 otherwise > + * @retval 1 if packet contains a valid & known L3 header > + * @retval 0 if packet does not contain a valid & known L3 header > */ > int odp_packet_has_l3(odp_packet_t pkt); > > @@ -64,7 +68,8 @@ int odp_packet_has_l3(odp_packet_t pkt); > * Check for L4 header, e.g. UDP, TCP, SCTP (also ICMP) > * > * @param pkt Packet handle > - * @return 1 if packet contains a valid & known L4 header, 0 otherwise > + * @retval 1 if packet contains a valid & known L4 header > + * @retval 0 if packet does not contain a valid & known L4 header > */ > int odp_packet_has_l4(odp_packet_t pkt); > > @@ -72,7 +77,8 @@ int odp_packet_has_l4(odp_packet_t pkt); > * Check for Ethernet header > * > * @param pkt Packet handle > - * @return 1 if packet contains a valid eth header, 0 otherwise > + * @retval 1 if packet contains a valid eth header > + * @retval 0 if packet does not contain a valid & known eth header > */ > int odp_packet_has_eth(odp_packet_t pkt); > > @@ -80,7 +86,8 @@ int odp_packet_has_eth(odp_packet_t pkt); > * Check for jumbo frame > * > * @param pkt Packet handle > - * @return 1 if packet contains jumbo frame, 0 otherwise > + * @retval 1 if packet contains a jumbo frame > + * @retval 0 if packet does not contain a jumbo frame > */ > int odp_packet_has_jumbo(odp_packet_t pkt); > > @@ -88,7 +95,8 @@ int odp_packet_has_jumbo(odp_packet_t pkt); > * Check for VLAN > * > * @param pkt Packet handle > - * @return 1 if packet contains a VLAN header, 0 otherwise > + * @retval 1 if packet contains a VLAN header > + * @retval 0 if packet does not contain a VLAN header > */ > int odp_packet_has_vlan(odp_packet_t pkt); > > @@ -96,7 +104,8 @@ int odp_packet_has_vlan(odp_packet_t pkt); > * Check for VLAN QinQ (stacked VLAN) > * > * @param pkt Packet handle > - * @return 1 if packet contains a VLAN QinQ header, 0 otherwise > + * @retval 1 if packet contains a VLAN QinQ header > + * @retval 0 if packet does not contain a VLAN QinQ header > */ > int odp_packet_has_vlan_qinq(odp_packet_t pkt); > > @@ -104,7 +113,8 @@ int odp_packet_has_vlan_qinq(odp_packet_t pkt); > * Check for ARP > * > * @param pkt Packet handle > - * @return 1 if packet contains an ARP header, 0 otherwise > + * @retval 1 if packet contains an ARP message > + * @retval 0 if packet does not contain an ARP message > */ > int odp_packet_has_arp(odp_packet_t pkt); > > @@ -112,7 +122,8 @@ int odp_packet_has_arp(odp_packet_t pkt); > * Check for IPv4 > * > * @param pkt Packet handle > - * @return 1 if packet contains an IPv4 header, 0 otherwise > + * @retval 1 if packet contains an IPv4 header > + * @retval 0 if packet does not contain an IPv4 header > */ > int odp_packet_has_ipv4(odp_packet_t pkt); > > @@ -120,7 +131,8 @@ int odp_packet_has_ipv4(odp_packet_t pkt); > * Check for IPv6 > * > * @param pkt Packet handle > - * @return 1 if packet contains an IPv6 header, 0 otherwise > + * @retval 1 if packet contains an IPv6 header > + * @retval 0 if packet does not contain an IPv6 header > */ > int odp_packet_has_ipv6(odp_packet_t pkt); > > @@ -128,7 +140,8 @@ int odp_packet_has_ipv6(odp_packet_t pkt); > * Check for IP fragment > * > * @param pkt Packet handle > - * @return 1 if packet is an IP fragment, 0 otherwise > + * @retval 1 if packet is an IP fragment > + * @retval 0 if packet is not an IP fragment > */ > int odp_packet_has_ipfrag(odp_packet_t pkt); > > @@ -136,7 +149,8 @@ int odp_packet_has_ipfrag(odp_packet_t pkt); > * Check for IP options > * > * @param pkt Packet handle > - * @return 1 if packet contains IP options, 0 otherwise > + * @retval 1 if packet contains IP options > + * @retval 0 if packet does not contain IP options > */ > int odp_packet_has_ipopt(odp_packet_t pkt); > > @@ -144,7 +158,8 @@ int odp_packet_has_ipopt(odp_packet_t pkt); > * Check for IPSec > * > * @param pkt Packet handle > - * @return 1 if packet requires IPSec processing, 0 otherwise > + * @retval 1 if packet requires IPSec processing > + * @retval 0 if packet does not require IPSec processing > */ > int odp_packet_has_ipsec(odp_packet_t pkt); > > @@ -152,7 +167,8 @@ int odp_packet_has_ipsec(odp_packet_t pkt); > * Check for UDP > * > * @param pkt Packet handle > - * @return 1 if packet contains a UDP header, 0 otherwise > + * @retval 1 if packet contains a UDP header > + * @retval 0 if packet does not contain a UDP header > */ > int odp_packet_has_udp(odp_packet_t pkt); > > @@ -160,7 +176,8 @@ int odp_packet_has_udp(odp_packet_t pkt); > * Check for TCP > * > * @param pkt Packet handle > - * @return 1 if packet contains a TCP header, 0 otherwise > + * @retval 1 if packet contains a TCP header > + * @retval 0 if packet does not contain a TCP header > */ > int odp_packet_has_tcp(odp_packet_t pkt); > > @@ -168,7 +185,8 @@ int odp_packet_has_tcp(odp_packet_t pkt); > * Check for SCTP > * > * @param pkt Packet handle > - * @return 1 if packet contains an SCTP header, 0 otherwise > + * @retval 1 if packet contains a SCTP header > + * @retval 0 if packet does not contain a SCTP header > */ > int odp_packet_has_sctp(odp_packet_t pkt); > > @@ -176,7 +194,8 @@ int odp_packet_has_sctp(odp_packet_t pkt); > * Check for ICMP > * > * @param pkt Packet handle > - * @return 1 if packet contains an ICMP header, 0 otherwise > + * @retval 1 if packet contains an ICMP header > + * @retval 0 if packet does not contain an ICMP header > */ > int odp_packet_has_icmp(odp_packet_t pkt); > > diff --git a/platform/linux-generic/include/api/odp_packet_io.h > b/platform/linux-generic/include/api/odp_packet_io.h > index 4835f4d..1a770b6 100644 > --- a/platform/linux-generic/include/api/odp_packet_io.h > +++ b/platform/linux-generic/include/api/odp_packet_io.h > @@ -40,7 +40,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 > @@ -53,7 +54,8 @@ odp_pktio_t odp_pktio_open(const char *dev, > odp_buffer_pool_t pool); > * > * @param id 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); > > @@ -62,7 +64,8 @@ int odp_pktio_close(odp_pktio_t id); > * > * @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); > > @@ -73,7 +76,8 @@ odp_pktio_t odp_pktio_lookup(const char *dev); > * @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); > > @@ -84,7 +88,8 @@ int odp_pktio_recv(odp_pktio_t id, odp_packet_t > pkt_table[], unsigned len); > * @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); > > @@ -93,7 +98,8 @@ int odp_pktio_send(odp_pktio_t id, odp_packet_t > pkt_table[], unsigned len); > * > * @param id 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); > > @@ -102,7 +108,8 @@ int odp_pktio_inq_setdef(odp_pktio_t id, odp_queue_t > queue); > * > * @param id 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); > > @@ -111,7 +118,8 @@ odp_queue_t odp_pktio_inq_getdef(odp_pktio_t id); > * > * @param id 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); > > @@ -120,7 +128,8 @@ int odp_pktio_inq_remdef(odp_pktio_t id); > * > * @param id 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); > > @@ -129,8 +138,8 @@ odp_queue_t odp_pktio_outq_getdef(odp_pktio_t id); > * > * @param[in] id 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); > > @@ -140,8 +149,8 @@ int odp_pktio_mtu(odp_pktio_t id); > * @param[in] id 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); > > @@ -152,7 +161,7 @@ int odp_pktio_promisc_mode_set(odp_pktio_t id, > odp_bool_t enable); > * > * @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); > > @@ -163,9 +172,10 @@ int odp_pktio_promisc_mode(odp_pktio_t id); > * @param[out] mac_addr Storage for MAC address of the packet IO > interface. > * @param addr_size Storage size for the address > * > - * @retval Number of bytes written on success, 0 on failure. > + * @return Number of bytes written on success > + * @retval <0 on failure > */ > -size_t odp_pktio_mac_addr(odp_pktio_t id, void *mac_addr, > +int odp_pktio_mac_addr(odp_pktio_t id, void *mac_addr, > size_t addr_size); > > /** > @@ -177,7 +187,8 @@ size_t odp_pktio_mac_addr(odp_pktio_t id, void > *mac_addr, > * 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); > > @@ -189,7 +200,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. > */ > @@ -201,7 +213,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. > * > */ > @@ -216,7 +229,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. > */ > diff --git a/platform/linux-generic/include/api/odp_queue.h > b/platform/linux-generic/include/api/odp_queue.h > index b0f7185..25633e0 100644 > --- a/platform/linux-generic/include/api/odp_queue.h > +++ b/platform/linux-generic/include/api/odp_queue.h > @@ -118,7 +118,8 @@ typedef struct odp_queue_param_t { > * @param type Queue type > * @param param Queue parameters. Uses defaults if NULL. > * > - * @return Queue handle or ODP_QUEUE_INVALID > + * @return Queue handle > + * @retval ODP_QUEUE_INVALID on failure > */ > odp_queue_t odp_queue_create(const char *name, odp_queue_type_t type, > odp_queue_param_t *param); > @@ -133,7 +134,8 @@ odp_queue_t odp_queue_create(const char *name, > odp_queue_type_t type, > * > * @param queue Queue handle > * > - * @return 0 if successful > + * @retval 0 on success > + * @retval <0 on failure > */ > int odp_queue_destroy(odp_queue_t queue); > > @@ -142,7 +144,8 @@ int odp_queue_destroy(odp_queue_t queue); > * > * @param name Queue name > * > - * @return Queue handle or ODP_QUEUE_INVALID > + * @return Queue handle > + * @retval ODP_QUEUE_INVALID on failure > */ > odp_queue_t odp_queue_lookup(const char *name); > > @@ -156,7 +159,8 @@ odp_queue_t odp_queue_lookup(const char *name); > * @param queue Queue handle > * @param context Address to the queue context > * > - * @return 0 if successful > + * @retval 0 on success > + * @retval <0 on failure > */ > int odp_queue_set_context(odp_queue_t queue, void *context); > > @@ -165,8 +169,8 @@ int odp_queue_set_context(odp_queue_t queue, void > *context); > * > * @param queue Queue handle > * > - * @return If successful, a pointer to the queue context, > - * NULL for failure. > + * @return pointer to the queue context > + * @retval NULL on failure > */ > void *odp_queue_get_context(odp_queue_t queue); > > @@ -176,7 +180,8 @@ void *odp_queue_get_context(odp_queue_t queue); > * @param queue Queue handle > * @param buf Buffer handle > * > - * @return 0 if succesful > + * @retval 0 on success > + * @retval <0 on failure > */ > int odp_queue_enq(odp_queue_t queue, odp_buffer_t buf); > > @@ -187,7 +192,8 @@ int odp_queue_enq(odp_queue_t queue, odp_buffer_t buf); > * @param buf Buffer handles > * @param num Number of buffer handles > * > - * @return 0 if succesful > + * @retval 0 on success > + * @retval <0 on failure > */ > int odp_queue_enq_multi(odp_queue_t queue, odp_buffer_t buf[], int num); > > @@ -199,7 +205,8 @@ int odp_queue_enq_multi(odp_queue_t queue, > odp_buffer_t buf[], int num); > * > * @param queue Queue handle > * > - * @return Buffer handle, or ODP_BUFFER_INVALID > + * @return Buffer handle > + * @retval ODP_BUFFER_INVALID on failure > */ > odp_buffer_t odp_queue_deq(odp_queue_t queue); > > diff --git a/platform/linux-generic/include/api/odp_schedule.h > b/platform/linux-generic/include/api/odp_schedule.h > index cdf6705..36fbba3 100644 > --- a/platform/linux-generic/include/api/odp_schedule.h > +++ b/platform/linux-generic/include/api/odp_schedule.h > @@ -59,7 +59,8 @@ uint64_t odp_schedule_wait_time(uint64_t ns); > * Use odp_schedule_wait_time() to convert time to other > wait > * values. > * > - * @return Next highest priority buffer, or ODP_BUFFER_INVALID > + * @return Next highest priority buffer > + * @retval ODP_BUFFER_INVALID on timeout > */ > odp_buffer_t odp_schedule(odp_queue_t *from, uint64_t wait); > > diff --git a/platform/linux-generic/include/api/odp_shared_memory.h > b/platform/linux-generic/include/api/odp_shared_memory.h > index f70db5a..78d108a 100644 > --- a/platform/linux-generic/include/api/odp_shared_memory.h > +++ b/platform/linux-generic/include/api/odp_shared_memory.h > @@ -59,7 +59,8 @@ typedef struct odp_shm_info_t { > * @param[in] flags Shared memory parameter flags (ODP_SHM_*). > * Default value is 0. > * > - * @return Pointer to the reserved block, or NULL > + * @return Handle of the reserved block > + * @retval NULL on failure > */ > odp_shm_t odp_shm_reserve(const char *name, uint64_t size, uint64_t align, > uint32_t flags); > @@ -72,9 +73,9 @@ odp_shm_t odp_shm_reserve(const char *name, uint64_t > size, uint64_t align, > * > * @param[in] shm Block handle > * > - * @retval 0 if the handle is already free > + * @retval 0 if the handle is already free (FIXME how can we know this?) > The linux-generic implementation tracks block allocation status. Good point as to whether this should be part of the spec, however. > * @retval 0 if the handle free succeeds > - * @retval -1 on failure to free the handle > + * @retval <0 on failure to free the handle > */ > int odp_shm_free(odp_shm_t shm); > > @@ -84,7 +85,7 @@ int odp_shm_free(odp_shm_t shm); > * @param[in] name Name of the block > * > * @return A handle to the block if it is found by name > - * @retval #ODP_SHM_INVALID if the block is not found > + * @retval ODP_SHM_INVALID on failure > */ > odp_shm_t odp_shm_lookup(const char *name); > > @@ -94,7 +95,8 @@ odp_shm_t odp_shm_lookup(const char *name); > * > * @param[in] shm Block handle > * > - * @return Memory block address, or NULL on error > + * @return Memory block address > + * @retval NULL on failure (FIXME: when?) > Why the FIXME? NULL is returned if the operation is unable to succeed. > */ > void *odp_shm_addr(odp_shm_t shm); > > @@ -105,7 +107,8 @@ void *odp_shm_addr(odp_shm_t shm); > * @param[in] shm Block handle > * @param[out] info Block info pointer for output > * > - * @return 0 on success, otherwise non-zero > + * @retval 0 on success > + * @retval <0 on failure > */ > int odp_shm_info(odp_shm_t shm, odp_shm_info_t *info); > > diff --git a/platform/linux-generic/include/api/odp_timer.h > b/platform/linux-generic/include/api/odp_timer.h > index 69402ef..c8c3270 100644 > --- a/platform/linux-generic/include/api/odp_timer.h > +++ b/platform/linux-generic/include/api/odp_timer.h > @@ -112,8 +112,8 @@ typedef struct { > * @param name Name of the timer pool. The string will be copied. > * @param params Timer pool parameters. The content will be copied. > * > - * @return Timer pool handle if successful, otherwise > ODP_TIMER_POOL_INVALID > - * and errno set > + * @return Timer pool handle on success > + * @retval ODP_TIMER_POOL_INVALID on failure and errno set > */ > odp_timer_pool_t > odp_timer_pool_create(const char *name, > @@ -185,8 +185,8 @@ typedef struct { > * @param tpid Timer pool identifier > * @param[out] info Pointer to information buffer > * > - * @retval 0 Success > - * @retval -1 Failure. Info could not be retrieved. > + * @retval 0 on success > + * @retval <0 on failure. Info could not be retrieved. > */ > int odp_timer_pool_info(odp_timer_pool_t tpid, > odp_timer_pool_info_t *info); > @@ -202,8 +202,8 @@ int odp_timer_pool_info(odp_timer_pool_t tpid, > * @param queue Destination queue for timeout notifications > * @param user_ptr User defined pointer or NULL to be copied to timeouts > * > - * @return Timer handle if successful, otherwise ODP_TIMER_INVALID and > - * errno set. > + * @return Timer handle on success > + * @retval ODP_TIMER_INVALID on failure and errno set. > */ > odp_timer_t odp_timer_alloc(odp_timer_pool_t tpid, > odp_queue_t queue, > @@ -218,7 +218,8 @@ odp_timer_t odp_timer_alloc(odp_timer_pool_t tpid, > * responsibility of the application to handle this timeout when it is > received. > * > * @param tim Timer handle > - * @return Buffer handle of timeout buffer or ODP_BUFFER_INVALID > + * @return Buffer handle of timeout buffer > + * @retval ODP_BUFFER_INVALID on failure > */ > odp_buffer_t odp_timer_free(odp_timer_t tim); > > @@ -292,8 +293,8 @@ int odp_timer_set_rel(odp_timer_t tim, > * > * @param tim Timer > * @param[out] tmo_buf Pointer to a buffer variable > - * @retval 0 Success, active timer cancelled, timeout returned in > '*tmo_buf' > - * @retval -1 Failure, timer already expired (or inactive) > + * @retval 0 on success, active timer cancelled, timeout returned in > '*tmo_buf' > + * @retval <0 on failure, timer already expired (or inactive) > */ > int odp_timer_cancel(odp_timer_t tim, odp_buffer_t *tmo_buf); > > diff --git a/platform/linux-generic/odp_crypto.c > b/platform/linux-generic/odp_crypto.c > index 2f95cbe..ded3b62 100644 > --- a/platform/linux-generic/odp_crypto.c > +++ b/platform/linux-generic/odp_crypto.c > @@ -343,7 +343,7 @@ odp_crypto_session_create(odp_crypto_session_params_t > *params, > > int > odp_crypto_operation(odp_crypto_op_params_t *params, > - bool *posted, > + odp_bool_t *posted, > odp_buffer_t completion_event) > { > enum crypto_alg_err rc_cipher = ODP_CRYPTO_ALG_ERR_NONE; > @@ -423,7 +423,7 @@ odp_crypto_init_global(void) > } > > int > -odp_hw_random_get(uint8_t *buf, size_t *len, bool use_entropy ODP_UNUSED) > +odp_hw_random_get(uint8_t *buf, size_t *len, odp_bool_t use_entropy > ODP_UNUSED) > { > int rc; > rc = RAND_bytes(buf, *len); > diff --git a/platform/linux-generic/odp_packet_io.c > b/platform/linux-generic/odp_packet_io.c > index 0efa3d0..c51098f 100644 > --- a/platform/linux-generic/odp_packet_io.c > +++ b/platform/linux-generic/odp_packet_io.c > @@ -797,18 +797,18 @@ int odp_pktio_promisc_mode(odp_pktio_t id) > } > > > -size_t odp_pktio_mac_addr(odp_pktio_t id, void *mac_addr, > +int odp_pktio_mac_addr(odp_pktio_t id, void *mac_addr, > size_t addr_size) > { > pktio_entry_t *entry; > > if (addr_size < ETH_ALEN) > - return 0; > + return -1; > > entry = get_pktio_entry(id); > if (entry == NULL) { > ODP_DBG("pktio entry %d does not exist\n", id); > - return 0; > + return -1; > } > > lock_entry(entry); > diff --git a/test/validation/crypto/odp_crypto_test_async_inp.c > b/test/validation/crypto/odp_crypto_test_async_inp.c > index 96d4c3f..1db7844 100644 > --- a/test/validation/crypto/odp_crypto_test_async_inp.c > +++ b/test/validation/crypto/odp_crypto_test_async_inp.c > @@ -34,7 +34,7 @@ static void alg_test(enum odp_crypto_op op, > odp_crypto_session_t session; > int rc; > enum odp_crypto_ses_create_err status; > - bool posted; > + odp_bool_t posted; > odp_buffer_t compl_event; > > odp_queue_t compl_queue = odp_queue_lookup("crypto-out"); > diff --git a/test/validation/crypto/odp_crypto_test_sync_inp.c > b/test/validation/crypto/odp_crypto_test_sync_inp.c > index f37ad54..5082f13 100644 > --- a/test/validation/crypto/odp_crypto_test_sync_inp.c > +++ b/test/validation/crypto/odp_crypto_test_sync_inp.c > @@ -23,7 +23,7 @@ static void alg_test(enum odp_crypto_op op, > odp_crypto_session_t session; > int rc; > enum odp_crypto_ses_create_err status; > - bool posted; > + odp_bool_t posted; > > odp_queue_t compl_queue = odp_queue_lookup("crypto-out"); > CU_ASSERT(compl_queue != ODP_QUEUE_INVALID); > -- > 1.9.1 > > > _______________________________________________ > lng-odp mailing list > lng-odp@lists.linaro.org > http://lists.linaro.org/mailman/listinfo/lng-odp >
On 27 January 2015 at 02:14, Bill Fischofer <bill.fischofer@linaro.org> wrote: > This looks good. It will need to be rebased following the event patch merge > (all merges currently blocked until that happens). See additional comments > inline: I'll rebase as necessary and post updated patches. > > On Mon, Jan 26, 2015 at 6:20 PM, Ola Liljedahl <ola.liljedahl@linaro.org> > wrote: >> >> Unify @return and @retval descriptions. >> @return used for values that cannot (meaningfully) be enumerated (e.g >> pointers, >> ODP handles) or simply tested for correctness. >> @retval used for values that can be enumerated and should be tested by >> validation programs. >> Changed from bool to odp_bool_t in odp_crypto.h and dependent source >> files. >> Changed return type and value of odp_pktio_mac_addr() to match other >> similar >> functions. Use int as return type, <0 to indicate failure. >> >> Signed-off-by: Ola Liljedahl <ola.liljedahl@linaro.org> >> --- >> (This document/code contribution attached is provided under the terms of >> agreement LES-LTM-21309) >> >> example/ipsec/odp_ipsec.c | 4 +- >> platform/linux-generic/include/api/odp_buffer.h | 9 ++- >> .../linux-generic/include/api/odp_buffer_pool.h | 21 ++++--- >> platform/linux-generic/include/api/odp_byteorder.h | 2 +- >> .../linux-generic/include/api/odp_classification.h | 48 +++++++++------- >> platform/linux-generic/include/api/odp_cpumask.h | 12 ++-- >> platform/linux-generic/include/api/odp_crypto.h | 15 +++-- >> platform/linux-generic/include/api/odp_init.h | 10 ++-- >> platform/linux-generic/include/api/odp_packet.h | 66 >> ++++++++++++---------- >> .../linux-generic/include/api/odp_packet_flags.h | 57 >> ++++++++++++------- >> platform/linux-generic/include/api/odp_packet_io.h | 54 >> +++++++++++------- >> platform/linux-generic/include/api/odp_queue.h | 25 +++++--- >> platform/linux-generic/include/api/odp_schedule.h | 3 +- >> .../linux-generic/include/api/odp_shared_memory.h | 15 +++-- >> platform/linux-generic/include/api/odp_timer.h | 19 ++++--- >> platform/linux-generic/odp_crypto.c | 4 +- >> platform/linux-generic/odp_packet_io.c | 6 +- >> test/validation/crypto/odp_crypto_test_async_inp.c | 2 +- >> test/validation/crypto/odp_crypto_test_sync_inp.c | 2 +- >> 19 files changed, 226 insertions(+), 148 deletions(-) >> >> diff --git a/example/ipsec/odp_ipsec.c b/example/ipsec/odp_ipsec.c >> index f2fac8a..066dc40 100644 >> --- a/example/ipsec/odp_ipsec.c >> +++ b/example/ipsec/odp_ipsec.c >> @@ -683,7 +683,7 @@ pkt_disposition_e do_ipsec_in_classify(odp_packet_t >> pkt, >> odph_esphdr_t *esp = NULL; >> ipsec_cache_entry_t *entry; >> odp_crypto_op_params_t params; >> - bool posted = 0; >> + odp_bool_t posted = 0; >> >> /* Default to skip IPsec */ >> *skip = TRUE; >> @@ -955,7 +955,7 @@ pkt_disposition_e do_ipsec_out_seq(odp_packet_t pkt, >> pkt_ctx_t *ctx) >> { >> uint8_t *buf = odp_packet_data(pkt); >> - bool posted = 0; >> + odp_bool_t posted = 0; >> >> /* We were dispatched from atomic queue, assign sequence numbers >> */ >> if (ctx->ipsec.ah_offset) { >> diff --git a/platform/linux-generic/include/api/odp_buffer.h >> b/platform/linux-generic/include/api/odp_buffer.h >> index 0670464..fd0871b 100644 >> --- a/platform/linux-generic/include/api/odp_buffer.h >> +++ b/platform/linux-generic/include/api/odp_buffer.h >> @@ -32,6 +32,7 @@ extern "C" { >> * Buffer start address >> * >> * @param buf Buffer handle >> + * Note: Buffer handle must be valid or the behavior will be undefined. > > > Should these be @note ? Same comment for similar Note: adds. Yes should use @note. > Phrasing in > present tense (...or behavior is undefined) seems more natural, but that's a > stylistic point that's I won't argue. You are probably better at English than I am... I am following your suggestion without argument. The language is a bit mixed with these undefined warnings. One problem I see is that if we make a @note for undefined behavior for each function, we need to make that note for *all* relevant functions. The omission of this note for some functions could indicate that undefined behavior is not present (even in the presence of invalid parameters). But I also think a global definition and documentation of undefined behavior in the ODP documentation might not be sufficient. Most programmers will go straight at the documentation of individual functions they want to use. > >> >> * >> * @return Buffer start address >> */ >> @@ -41,6 +42,7 @@ void *odp_buffer_addr(odp_buffer_t buf); >> * Buffer maximum data size >> * >> * @param buf Buffer handle >> + * Note: Buffer handle must be valid or the behavior will be undefined. >> * >> * @return Buffer maximum data size >> */ >> @@ -50,12 +52,12 @@ uint32_t odp_buffer_size(odp_buffer_t buf); >> * Buffer type >> * >> * @param buf Buffer handle >> + * Note: Buffer handle must be valid or the behavior will be undefined. >> * >> * @return Buffer type >> */ >> int odp_buffer_type(odp_buffer_t buf); >> >> -#define ODP_BUFFER_TYPE_INVALID (-1) /**< Buffer type invalid */ >> #define ODP_BUFFER_TYPE_ANY 0 /**< Buffer that can hold any other >> buffer type */ >> #define ODP_BUFFER_TYPE_RAW 1 /**< Raw buffer, no additional >> metadata */ >> @@ -65,7 +67,9 @@ int odp_buffer_type(odp_buffer_t buf); >> /** >> * Tests if buffer is valid >> * >> - * @param buf Buffer handle >> + * @param buf Buffer handle (possibly invalid) >> + * Note: This is the only call which accepts invalid buffer handles (any >> bit >> + * value) without causing undefined behavior. > > > Definitely should be @note for this one. Would it be clearer to say "API" > rather than "call"? Grammar nit: that rather than which is correct here. Well this is just one function, the whole set of functions is an API. Or is my definition of API too narrow? Maybe "this API function"? > >> >> * >> * @retval 1 Buffer handle represents a valid buffer. >> * @retval 0 Buffer handle does not represent a valid buffer. >> @@ -76,6 +80,7 @@ int odp_buffer_is_valid(odp_buffer_t buf); >> * Buffer pool of the buffer >> * >> * @param buf Buffer handle >> + * Note: Buffer handle must be valid or the behavior will be undefined. >> * >> * @return Handle of buffer pool buffer belongs to >> */ >> diff --git a/platform/linux-generic/include/api/odp_buffer_pool.h >> b/platform/linux-generic/include/api/odp_buffer_pool.h >> index 8380ac1..fe917a4 100644 >> --- a/platform/linux-generic/include/api/odp_buffer_pool.h >> +++ b/platform/linux-generic/include/api/odp_buffer_pool.h >> @@ -81,8 +81,8 @@ odp_buffer_pool_t odp_buffer_pool_create(const char >> *name, >> * >> * @param pool Handle of the buffer pool to be destroyed >> * >> - * @retval 0 Success >> - * @retval -1 Failure >> + * @retval 0 if successful >> + * @retval <0 on failure >> * >> * @note This routine destroys a previously created buffer pool. This >> call >> * does not destroy any shared memory object passed to >> @@ -117,7 +117,7 @@ typedef struct odp_buffer_pool_info_t { >> odp_shm_t shm; /**< handle of shared memory >> area >> supplied by application to >> contain buffer pool, or >> - ODP_SHM_INVALID if this pool >> is >> + ODP_SHM_NULL if this pool is >> managed by ODP */ >> odp_buffer_pool_param_t params; /**< pool parameters */ >> } odp_buffer_pool_info_t; >> @@ -125,13 +125,13 @@ typedef struct odp_buffer_pool_info_t { >> /** >> * Retrieve information about a buffer pool >> * >> - * @param pool Buffer pool handle >> + * @param pool Buffer pool handle (possibly invalid) >> * >> * @param[out] info Receives an odp_buffer_pool_info_t object >> * that describes the pool. >> * >> - * @retval 0 Success >> - * @retval -1 Failure. Info could not be retrieved. >> + * @retval 0 if successful >> + * @retval <0 on failure. Info could not be retrieved (invalid pool >> handle) >> */ >> >> int odp_buffer_pool_info(odp_buffer_pool_t pool, >> @@ -149,17 +149,22 @@ void odp_buffer_pool_print(odp_buffer_pool_t pool); >> >> /** >> * Buffer alloc >> + * Note: the pool handle must be valid or the behavior is undefined. >> + * >> + * The validity of a buffer handle can be checked at any time using >> + * odp_buffer_is_valid() >> * >> - * The validity of a buffer can be cheked at any time with >> odp_buffer_is_valid() >> * @param pool Pool handle >> * >> * @return Handle of allocated buffer >> - * @retval ODP_BUFFER_INVALID Buffer could not be allocated >> + * @retval ODP_BUFFER_INVALID Buffer could not be allocated (e.g. pool >> + * exhausted) >> */ >> odp_buffer_t odp_buffer_alloc(odp_buffer_pool_t pool); >> >> /** >> * Buffer free >> + * Note: the buffer handle must be valid or the behavior is undefined. >> * >> * @param buf Buffer handle >> * >> diff --git a/platform/linux-generic/include/api/odp_byteorder.h >> b/platform/linux-generic/include/api/odp_byteorder.h >> index 5890011..8e38937 100644 >> --- a/platform/linux-generic/include/api/odp_byteorder.h >> +++ b/platform/linux-generic/include/api/odp_byteorder.h >> @@ -24,7 +24,7 @@ extern "C" { >> #include <odp_compiler.h> >> >> /** @defgroup odp_compiler_optim ODP COMPILER / OPTIMIZATION >> - * Macros that check byte order and byte converting operations. >> + * Macros that check and convert byte order. >> * @{ >> */ >> >> diff --git a/platform/linux-generic/include/api/odp_classification.h >> b/platform/linux-generic/include/api/odp_classification.h >> index 46189bc..6bca8fc 100644 >> --- a/platform/linux-generic/include/api/odp_classification.h >> +++ b/platform/linux-generic/include/api/odp_classification.h >> @@ -79,8 +79,8 @@ typedef enum odp_cos_hdr_flow_fields { >> * >> * @param[in] name String intended for debugging purposes. >> * >> - * @return Class of service instance identifier, >> - * or ODP_COS_INVALID on error. >> + * @return Class of service instance identifier >> + * @retval ODP_COS_INVALID on failure. >> */ >> odp_cos_t odp_cos_create(const char *name); >> >> @@ -89,7 +89,8 @@ odp_cos_t odp_cos_create(const char *name); >> * >> * @param[in] cos_id class-of-service instance. >> * >> - * @return 0 on success, non-zero on error. >> + * @retval 0 if successful >> + * @retval <0 on failure >> */ >> int odp_cos_destroy(odp_cos_t cos_id); >> >> @@ -102,7 +103,8 @@ int odp_cos_destroy(odp_cos_t cos_id); >> * of this specific class of service >> * will be enqueued. >> * >> - * @return 0 on success, non-zero on error. >> + * @retval 0 if successful >> + * @retval <0 on failure >> */ >> int odp_cos_set_queue(odp_cos_t cos_id, odp_queue_t queue_id); >> >> @@ -112,7 +114,8 @@ int odp_cos_set_queue(odp_cos_t cos_id, odp_queue_t >> queue_id); >> * @param[in] cos_id class-of-service instance. >> * @param[in] drop_policy Desired packet drop policy for this class. >> * >> - * @return 0 on success, non-zero on error. >> + * @retval 0 if successful >> + * @retval <0 on failure >> * >> * @note Optional. >> */ >> @@ -127,7 +130,8 @@ int odp_cos_set_drop(odp_cos_t cos_id, odp_drop_e >> drop_policy); >> * @param[in] qos_table Values of the Layer-2 QoS header field. >> * @param[in] cos_table Class-of-service assigned to each of the >> * allowed Layer-2 QOS levels. >> - * @return 0 on success, non-zero on error. >> + * @retval 0 if successful >> + * @retval <0 on failure >> */ >> int odp_cos_with_l2_priority(odp_pktio_t pktio_in, >> uint8_t num_qos, >> @@ -146,7 +150,8 @@ int odp_cos_with_l2_priority(odp_pktio_t pktio_in, >> * @param[in] l3_preference when true, Layer-3 QoS overrides >> * L2 QoS when present. >> * >> - * @return 0 on success, non-zero on error. >> + * @retval 0 if successful >> + * @retval <0 on failure >> * >> * @note Optional. >> */ >> @@ -219,7 +224,8 @@ typedef enum odp_pmr_term { >> * that must match the value size requirement of the >> * specific term. >> * >> - * @return Handle of the matching rule or ODP_PMR_INVAL on >> error >> + * @return Handle of the matching rule >> + * @retval ODP_PMR_INVAL on failure >> */ >> odp_pmr_t odp_pmr_create_match(odp_pmr_term_e term, >> const void *val, >> @@ -236,7 +242,8 @@ odp_pmr_t odp_pmr_create_match(odp_pmr_term_e term, >> * that must match the value size requirement of the >> * specific term. >> * >> - * @return Handle of the matching rule or ODP_PMR_INVAL on >> error >> + * @return Handle of the matching rule >> + * @retval ODP_PMR_INVAL on failure >> * @note: Range is inclusive [val1..val2]. >> */ >> odp_pmr_t odp_pmr_create_range(odp_pmr_term_e term, >> @@ -248,7 +255,8 @@ odp_pmr_t odp_pmr_create_range(odp_pmr_term_e term, >> * >> * @param[in] pmr_id Identifier of the PMR to be destroyed >> * >> - * @return 0 on success, non-zero or error. >> + * @retval 0 if successful >> + * @retval <0 on failure >> */ >> int odp_pmr_destroy(odp_pmr_t pmr_id); >> >> @@ -259,7 +267,8 @@ int odp_pmr_destroy(odp_pmr_t pmr_id); >> * @param[in] src_pktio pktio to which this PMR is to be applied >> * @param[in] dst_cos CoS to be assigned by this PMR >> * >> - * @return 0 on success, non-zero or error. >> + * @retval 0 if successful >> + * @retval <0 on failure >> */ >> int odp_pktio_pmr_cos(odp_pmr_t pmr_id, >> odp_pktio_t src_pktio, odp_cos_t dst_cos); >> @@ -272,7 +281,8 @@ int odp_pktio_pmr_cos(odp_pmr_t pmr_id, >> * @param[in] dst_cos CoS to be assigned to packets filtered >> * from src_cos that match pmr_id. >> * >> - * @return 0 on success, non-zero on error. >> + * @retval 0 if successful >> + * @retval <0 on failure >> */ >> int odp_cos_pmr_cos(odp_pmr_t pmr_id, odp_cos_t src_cos, odp_cos_t >> dst_cos); >> >> @@ -346,12 +356,10 @@ typedef uint32_t odp_pmr_set_t; >> * term desired. >> * @param[out] pmr_set_id Returned handle to the composite rule set. >> * >> - * @return Return value may be a positive number >> - * indicating the number of terms elements >> + * @return the number of terms elements >> * that have been successfully mapped to the >> - * underlying platform classification engine >> and >> - * may be in the range from 1 to num_terms, >> - * or non-zero for error. >> + * underlying platform classification engine >> + * @retval <0 on failure >> */ >> int odp_pmr_match_set_create(int num_terms, odp_pmr_match_t *terms, >> odp_pmr_set_t *pmr_set_id); >> @@ -369,7 +377,8 @@ int odp_pmr_match_set_create(int num_terms, >> odp_pmr_match_t *terms, >> * @param[in] pmr_set_id A composite rule-set handle >> * returned when created. >> * >> - * @return 0 on success, non-zero on error. >> + * @retval 0 if successful >> + * @retval <0 on failure >> */ >> int odp_pmr_match_set_destroy(odp_pmr_set_t pmr_set_id); >> >> @@ -381,7 +390,8 @@ int odp_pmr_match_set_destroy(odp_pmr_set_t >> pmr_set_id); >> * set is to be applied >> * @param[in] dst_cos CoS to be assigned by this PMR match set >> * >> - * @return 0 on success, non-zero or error. >> + * @retval 0 if successful >> + * @retval <0 on failure >> */ >> int odp_pktio_pmr_match_set_cos(odp_pmr_set_t pmr_set_id, odp_pktio_t >> src_pktio, >> odp_cos_t dst_cos); >> diff --git a/platform/linux-generic/include/api/odp_cpumask.h >> b/platform/linux-generic/include/api/odp_cpumask.h >> index ebff9b0..5c5bcd7 100644 >> --- a/platform/linux-generic/include/api/odp_cpumask.h >> +++ b/platform/linux-generic/include/api/odp_cpumask.h >> @@ -79,7 +79,8 @@ void odp_cpumask_clr(odp_cpumask_t *mask, int cpu); >> * Test if cpu is a member of mask >> * @param mask CPU mask to check if cpu num set or not >> * @param cpu CPU number >> - * @return non-zero if set otherwise 0 >> + * @return non-zero if set >> + * @retval 0 if not set >> */ >> int odp_cpumask_isset(const odp_cpumask_t *mask, int cpu); >> >> @@ -134,14 +135,16 @@ void odp_cpumask_copy(odp_cpumask_t *dest, const >> odp_cpumask_t *src); >> /** >> * Find first bit set in mask >> * >> - * @return cpu else -1 if no bits set in cpumask >> + * @return cpu >> + * @retval -1 if no bits set in cpumask > > > Should this be <0 for consistency with other error RC descriptions? Possibly. I was a little loath at changing the definitions of these basically bit set operations (where return values might be the direct results of binary/arithmetic operations) but this one could be unified with the rest without any problems. It was also getting rather late in the evening, I was probably not thinking too clearly at the end. I changed all three remaining instances in this file. > >> >> */ >> int odp_cpumask_first(const odp_cpumask_t *mask); >> >> /** >> * Find last bit set in mask >> * >> - * @return cpu else -1 if no bits set in cpumask >> + * @return cpu >> + * @retval -1 if no bits set in cpumask > > > Same here. <0 ? yes > >> >> */ >> int odp_cpumask_last(const odp_cpumask_t *mask); >> >> @@ -160,7 +163,8 @@ int odp_cpumask_last(const odp_cpumask_t *mask); >> * >> * @param mask CPU mask to find next cpu in >> * @param cpu CPU to start from >> - * @return cpu found else -1 >> + * @return cpu found >> + * @retval -1 if not found > > > And again here. yes > >> >> * >> * @see odp_cpumask_first() >> */ >> diff --git a/platform/linux-generic/include/api/odp_crypto.h >> b/platform/linux-generic/include/api/odp_crypto.h >> index 337e7cf..2f00f95 100644 >> --- a/platform/linux-generic/include/api/odp_crypto.h >> +++ b/platform/linux-generic/include/api/odp_crypto.h >> @@ -218,7 +218,8 @@ typedef struct odp_crypto_compl_status { >> * @param session Created session else >> ODP_CRYPTO_SESSION_INVALID >> * @param status Failure code if unsuccessful >> * >> - * @return 0 if successful else -1 >> + * @retval 0 if successful >> + * @retval <0 on failure >> */ >> int >> odp_crypto_session_create(odp_crypto_session_params_t *params, >> @@ -242,11 +243,12 @@ >> odp_crypto_session_create(odp_crypto_session_params_t *params, >> * @param posted Pointer to return posted, TRUE for async >> operation >> * @param completion_event Event by which the operation results are >> delivered. >> * >> - * @return 0 if successful else -1 >> + * @retval 0 if successful >> + * @retval <0 on failure >> */ >> int >> odp_crypto_operation(odp_crypto_op_params_t *params, >> - bool *posted, >> + odp_bool_t *posted, >> odp_buffer_t completion_event); >> >> /** >> @@ -281,7 +283,7 @@ odp_crypto_get_operation_compl_status(odp_buffer_t >> completion_event, >> * >> * @param completion_event Event containing operation results >> * >> - * @return Packet structure where data now resides >> + * @return Handle for packet where data now resides >> */ >> odp_packet_t >> odp_crypto_get_operation_compl_packet(odp_buffer_t completion_event); >> @@ -305,10 +307,11 @@ odp_crypto_get_operation_compl_ctx(odp_buffer_t >> completion_event); >> * >> * @todo Define the implication of the use_entropy parameter >> * >> - * @return 0 if succesful >> + * @retval 0 if successful >> + * @retval <0 on failure >> */ >> int >> -odp_hw_random_get(uint8_t *buf, size_t *len, bool use_entropy); >> +odp_hw_random_get(uint8_t *buf, size_t *len, odp_bool_t use_entropy); >> >> /** >> * @} >> diff --git a/platform/linux-generic/include/api/odp_init.h >> b/platform/linux-generic/include/api/odp_init.h >> index ac856df..4a98717 100644 >> --- a/platform/linux-generic/include/api/odp_init.h >> +++ b/platform/linux-generic/include/api/odp_init.h >> @@ -66,8 +66,8 @@ typedef enum odp_log_level { >> * @param[in] level Log level >> * @param[in] fmt printf-style message format >> * >> - * @return The number of characters logged if succeeded. Otherwise >> returns >> - * a negative number. >> + * @return The number of characters logged if successful >> + * @retval <0 on failure >> */ >> int odp_override_log(odp_log_level_e level, const char *fmt, ...); >> >> @@ -109,7 +109,7 @@ typedef struct odp_platform_init_t { >> * interpretation by the ODP API to the implementation. >> * >> * @retval 0 if successful >> - * @retval -1 on failure >> + * @retval <0 on failure >> */ >> int odp_init_global(odp_init_t *params, odp_platform_init_t >> *platform_params); >> >> @@ -134,7 +134,7 @@ int odp_init_global(odp_init_t *params, >> odp_platform_init_t *platform_params); >> * @sa odp_term_local() which must have been called prior to this. >> * >> * @retval 0 if successful >> - * @retval -1 on failure >> + * @retval <0 on failure >> */ >> int odp_term_global(void); >> >> @@ -148,7 +148,7 @@ int odp_term_global(void); >> * @sa odp_init_global() which must have been called prior to this. >> * >> * @retval 0 if successful >> - * @retval -1 on failure >> + * @retval <0 on failure >> */ >> int odp_init_local(void); >> >> diff --git a/platform/linux-generic/include/api/odp_packet.h >> b/platform/linux-generic/include/api/odp_packet.h >> index 920a593..b471d07 100644 >> --- a/platform/linux-generic/include/api/odp_packet.h >> +++ b/platform/linux-generic/include/api/odp_packet.h >> @@ -88,8 +88,8 @@ void odp_packet_free(odp_packet_t pkt); >> * @param pkt Packet handle >> * @param len Packet data length >> * >> - * @retval 0 Success >> - * @retval Non-zero Failure >> + * @retval 0 if successful >> + * @retval <0 on failure >> * >> * @see odp_packet_buf_len() >> */ >> @@ -279,7 +279,7 @@ void *odp_packet_push_head(odp_packet_t pkt, uint32_t >> len); >> * @param pkt Packet handle >> * @param len Number of bytes to pull the head (0 ... seg_len - 1) >> * >> - * @return The new data pointer, or NULL in case of an error. >> + * @return The new data pointer >> * @retval NULL Requested offset exceeds packet segment length >> >> * >> * @see odp_packet_seg_len(), odp_packet_push_head() >> @@ -391,7 +391,7 @@ odp_buffer_pool_t odp_packet_pool(odp_packet_t pkt); >> * @param pkt Packet handle >> * >> * @return Packet interface handle >> - * @retval ODP_PKTIO_INVALID Packet was not received >> + * @retval ODP_PKTIO_INVALID Packet was not received on any interface >> */ >> odp_pktio_t odp_packet_input(odp_packet_t pkt); >> >> @@ -451,8 +451,8 @@ void odp_packet_user_u64_set(odp_packet_t pkt, >> uint64_t ctx); >> * @param[out] len Number of data bytes remaining in the segment >> (output). >> * Ignored when NULL. >> * >> - * @return Layer 2 start pointer, or NULL when packet does not contain a >> valid >> - * L2 header. >> + * @return Layer 2 start pointer >> + * @retval NULL packet does not contain a valid L2 header >> * >> * @see odp_packet_l2_offset(), odp_packet_l2_offset_set(), >> odp_packet_has_l2() >> */ >> @@ -469,8 +469,8 @@ void *odp_packet_l2_ptr(odp_packet_t pkt, uint32_t >> *len); >> * >> * @param pkt Packet handle >> * >> - * @return Layer 2 start offset, or ODP_PACKET_OFFSET_INVALID when >> packet does >> - * not contain a valid L2 header. >> + * @return Layer 2 start offset >> + * @retval ODP_PACKET_OFFSET_INVALID packet does not contain a valid L2 >> header >> * >> * @see odp_packet_l2_offset_set(), odp_packet_has_l2() >> */ >> @@ -486,8 +486,8 @@ uint32_t odp_packet_l2_offset(odp_packet_t pkt); >> * @param pkt Packet handle >> * @param offset Layer 2 start offset (0 ... odp_packet_len()-1) >> * >> - * @retval 0 Success >> - * @retval Non-zero Failure >> + * @retval 0 if successful >> + * @retval <0 on failure >> */ >> int odp_packet_l2_offset_set(odp_packet_t pkt, uint32_t offset); >> >> @@ -501,8 +501,8 @@ int odp_packet_l2_offset_set(odp_packet_t pkt, >> uint32_t offset); >> * @param[out] len Number of data bytes remaining in the segment >> (output). >> * Ignored when NULL. >> * >> - * @return Layer 3 start pointer, or NULL when packet does not contain a >> valid >> - * L3 header. >> + * @return Layer 3 start pointer >> + * @retval NULL packet does not contain a valid L3 header >> * >> * @see odp_packet_l3_offset(), odp_packet_l3_offset_set(), >> odp_packet_has_l3() >> */ >> @@ -536,8 +536,8 @@ uint32_t odp_packet_l3_offset(odp_packet_t pkt); >> * @param pkt Packet handle >> * @param offset Layer 3 start offset (0 ... odp_packet_len()-1) >> * >> - * @retval 0 Success >> - * @retval Non-zero Failure >> + * @retval 0 if successful >> + * @retval <0 on failure >> */ >> int odp_packet_l3_offset_set(odp_packet_t pkt, uint32_t offset); >> >> @@ -551,8 +551,8 @@ int odp_packet_l3_offset_set(odp_packet_t pkt, >> uint32_t offset); >> * @param[out] len Number of data bytes remaining in the segment >> (output). >> * Ignored when NULL. >> * >> - * @return Layer 4 start pointer, or NULL when packet does not contain a >> valid >> - * L4 header. >> + * @return Layer 4 start pointer >> + * @retval NULL packet does not contain a valid L4 header >> * >> * @see odp_packet_l4_offset(), odp_packet_l4_offset_set(), >> odp_packet_has_l4() >> */ >> @@ -569,8 +569,8 @@ void *odp_packet_l4_ptr(odp_packet_t pkt, uint32_t >> *len); >> * >> * @param pkt Packet handle >> * >> - * @return Layer 4 start offset, or ODP_PACKET_OFFSET_INVALID when >> packet does >> - * not contain a valid L4 header. >> + * @return Layer 4 start offset >> + * @retval ODP_PACKET_OFFSET_INVALID packet does not contain a valid L4 >> header >> * >> * @see odp_packet_l4_offset_set(), odp_packet_has_l4() >> */ >> @@ -586,8 +586,8 @@ uint32_t odp_packet_l4_offset(odp_packet_t pkt); >> * @param pkt Packet handle >> * @param offset Layer 4 start offset (0 ... odp_packet_len()-1) >> * >> - * @retval 0 Success >> - * @retval Non-zero Failure >> + * @retval 0 on success >> + * @retval <0 on failure >> */ >> int odp_packet_l4_offset_set(odp_packet_t pkt, uint32_t offset); >> >> @@ -645,7 +645,8 @@ odp_packet_seg_t odp_packet_last_seg(odp_packet_t >> pkt); >> * @param pkt Packet handle >> * @param seg Current segment handle >> * >> - * @return Handle to the next segment, or ODP_PACKET_SEG_INVALID >> + * @return Handle to the next segment >> + * @retval ODP_PACKET_SEG_INVALID if there are no more segments >> */ >> odp_packet_seg_t odp_packet_next_seg(odp_packet_t pkt, odp_packet_seg_t >> seg); >> >> @@ -665,7 +666,8 @@ odp_packet_seg_t odp_packet_next_seg(odp_packet_t pkt, >> odp_packet_seg_t seg); >> * @param pkt Packet handle >> * @param seg Segment handle >> * >> - * @return Start address of the segment, or NULL on an error >> + * @return Start address of the segment >> + * @retval NULL on failure >> * >> * @see odp_packet_seg_buf_len() >> */ >> @@ -693,7 +695,8 @@ uint32_t odp_packet_seg_buf_len(odp_packet_t pkt, >> odp_packet_seg_t seg); >> * @param pkt Packet handle >> * @param seg Segment handle >> * >> - * @return Pointer to the segment data, or NULL on an error >> + * @return Pointer to the segment data >> + * @retval NULL on failure >> * >> * @see odp_packet_seg_data_len() >> */ >> @@ -735,7 +738,8 @@ uint32_t odp_packet_seg_data_len(odp_packet_t pkt, >> odp_packet_seg_t seg); >> * @param offset Byte offset into the packet >> * @param len Number of bytes to add into the offset >> * >> - * @return New packet handle, or ODP_PACKET_INVALID in case of an error. >> + * @return New packet handle >> + * @retval ODP_PACKET_INVALID on failure >> */ >> odp_packet_t odp_packet_add_data(odp_packet_t pkt, uint32_t offset, >> uint32_t len); >> @@ -753,7 +757,8 @@ odp_packet_t odp_packet_add_data(odp_packet_t pkt, >> uint32_t offset, >> * @param offset Byte offset into the packet >> * @param len Number of bytes to remove from the offset >> * >> - * @return New packet handle, or ODP_PACKET_INVALID in case of an error. >> + * @return New packet handle >> + * @retval ODP_PACKET_INVALID on failure >> */ >> odp_packet_t odp_packet_rem_data(odp_packet_t pkt, uint32_t offset, >> uint32_t len); >> @@ -776,7 +781,8 @@ odp_packet_t odp_packet_rem_data(odp_packet_t pkt, >> uint32_t offset, >> * @param pkt Packet handle >> * @param pool Buffer pool for allocation of the new packet. >> * >> - * @return Handle to the copy of the packet, or ODP_PACKET_INVALID >> + * @return Handle to the copy of the packet >> + * @retval ODP_PACKET_INVALID on failure >> */ >> odp_packet_t odp_packet_copy(odp_packet_t pkt, odp_buffer_pool_t pool); >> >> @@ -791,8 +797,8 @@ odp_packet_t odp_packet_copy(odp_packet_t pkt, >> odp_buffer_pool_t pool); >> * @param len Number of bytes to copy >> * @param dst Destination address >> * >> - * @retval 0 Success >> - * @retval Non-zero Failure >> + * @retval 0 on success >> + * @retval <0 on failure >> */ >> int odp_packet_copydata_out(odp_packet_t pkt, uint32_t offset, >> uint32_t len, void *dst); >> @@ -809,8 +815,8 @@ int odp_packet_copydata_out(odp_packet_t pkt, uint32_t >> offset, >> * @param len Number of bytes to copy >> * @param src Source address >> * >> - * @retval 0 Success >> - * @retval Non-zero Failure >> + * @retval 0 on success >> + * @retval <0 on failure >> */ >> int odp_packet_copydata_in(odp_packet_t pkt, uint32_t offset, >> uint32_t len, const void *src); >> diff --git a/platform/linux-generic/include/api/odp_packet_flags.h >> b/platform/linux-generic/include/api/odp_packet_flags.h >> index 24c4065..399a0bf 100644 >> --- a/platform/linux-generic/include/api/odp_packet_flags.h >> +++ b/platform/linux-generic/include/api/odp_packet_flags.h >> @@ -32,7 +32,8 @@ extern "C" { >> * Checks all error flags at once. >> * >> * @param pkt Packet handle >> - * @return 1 if packet has errors, 0 otherwise >> + * @retval 1 if packet has errors >> + * @retval 0 if packet has no errors >> */ >> int odp_packet_error(odp_packet_t pkt); >> >> @@ -40,7 +41,8 @@ int odp_packet_error(odp_packet_t pkt); >> * Check if error was 'frame length' error >> * >> * @param pkt Packet handle >> - * @return 1 if frame length error detected, 0 otherwise >> + * @retval 1 if frame length error detected >> + * @retval 0 if frame length error not detected >> */ >> int odp_packet_errflag_frame_len(odp_packet_t pkt); >> >> @@ -48,7 +50,8 @@ int odp_packet_errflag_frame_len(odp_packet_t pkt); >> * Check for L2 header, e.g. ethernet >> * >> * @param pkt Packet handle >> - * @return 1 if packet contains a valid & known L2 header, 0 otherwise >> + * @retval 1 if packet contains a valid & known L2 header >> + * @retval 0 if packet does not contain a valid & known L2 header >> */ >> int odp_packet_has_l2(odp_packet_t pkt); >> >> @@ -56,7 +59,8 @@ int odp_packet_has_l2(odp_packet_t pkt); >> * Check for L3 header, e.g. IPv4, IPv6 >> * >> * @param pkt Packet handle >> - * @return 1 if packet contains a valid & known L3 header, 0 otherwise >> + * @retval 1 if packet contains a valid & known L3 header >> + * @retval 0 if packet does not contain a valid & known L3 header >> */ >> int odp_packet_has_l3(odp_packet_t pkt); >> >> @@ -64,7 +68,8 @@ int odp_packet_has_l3(odp_packet_t pkt); >> * Check for L4 header, e.g. UDP, TCP, SCTP (also ICMP) >> * >> * @param pkt Packet handle >> - * @return 1 if packet contains a valid & known L4 header, 0 otherwise >> + * @retval 1 if packet contains a valid & known L4 header >> + * @retval 0 if packet does not contain a valid & known L4 header >> */ >> int odp_packet_has_l4(odp_packet_t pkt); >> >> @@ -72,7 +77,8 @@ int odp_packet_has_l4(odp_packet_t pkt); >> * Check for Ethernet header >> * >> * @param pkt Packet handle >> - * @return 1 if packet contains a valid eth header, 0 otherwise >> + * @retval 1 if packet contains a valid eth header >> + * @retval 0 if packet does not contain a valid & known eth header >> */ >> int odp_packet_has_eth(odp_packet_t pkt); >> >> @@ -80,7 +86,8 @@ int odp_packet_has_eth(odp_packet_t pkt); >> * Check for jumbo frame >> * >> * @param pkt Packet handle >> - * @return 1 if packet contains jumbo frame, 0 otherwise >> + * @retval 1 if packet contains a jumbo frame >> + * @retval 0 if packet does not contain a jumbo frame >> */ >> int odp_packet_has_jumbo(odp_packet_t pkt); >> >> @@ -88,7 +95,8 @@ int odp_packet_has_jumbo(odp_packet_t pkt); >> * Check for VLAN >> * >> * @param pkt Packet handle >> - * @return 1 if packet contains a VLAN header, 0 otherwise >> + * @retval 1 if packet contains a VLAN header >> + * @retval 0 if packet does not contain a VLAN header >> */ >> int odp_packet_has_vlan(odp_packet_t pkt); >> >> @@ -96,7 +104,8 @@ int odp_packet_has_vlan(odp_packet_t pkt); >> * Check for VLAN QinQ (stacked VLAN) >> * >> * @param pkt Packet handle >> - * @return 1 if packet contains a VLAN QinQ header, 0 otherwise >> + * @retval 1 if packet contains a VLAN QinQ header >> + * @retval 0 if packet does not contain a VLAN QinQ header >> */ >> int odp_packet_has_vlan_qinq(odp_packet_t pkt); >> >> @@ -104,7 +113,8 @@ int odp_packet_has_vlan_qinq(odp_packet_t pkt); >> * Check for ARP >> * >> * @param pkt Packet handle >> - * @return 1 if packet contains an ARP header, 0 otherwise >> + * @retval 1 if packet contains an ARP message >> + * @retval 0 if packet does not contain an ARP message >> */ >> int odp_packet_has_arp(odp_packet_t pkt); >> >> @@ -112,7 +122,8 @@ int odp_packet_has_arp(odp_packet_t pkt); >> * Check for IPv4 >> * >> * @param pkt Packet handle >> - * @return 1 if packet contains an IPv4 header, 0 otherwise >> + * @retval 1 if packet contains an IPv4 header >> + * @retval 0 if packet does not contain an IPv4 header >> */ >> int odp_packet_has_ipv4(odp_packet_t pkt); >> >> @@ -120,7 +131,8 @@ int odp_packet_has_ipv4(odp_packet_t pkt); >> * Check for IPv6 >> * >> * @param pkt Packet handle >> - * @return 1 if packet contains an IPv6 header, 0 otherwise >> + * @retval 1 if packet contains an IPv6 header >> + * @retval 0 if packet does not contain an IPv6 header >> */ >> int odp_packet_has_ipv6(odp_packet_t pkt); >> >> @@ -128,7 +140,8 @@ int odp_packet_has_ipv6(odp_packet_t pkt); >> * Check for IP fragment >> * >> * @param pkt Packet handle >> - * @return 1 if packet is an IP fragment, 0 otherwise >> + * @retval 1 if packet is an IP fragment >> + * @retval 0 if packet is not an IP fragment >> */ >> int odp_packet_has_ipfrag(odp_packet_t pkt); >> >> @@ -136,7 +149,8 @@ int odp_packet_has_ipfrag(odp_packet_t pkt); >> * Check for IP options >> * >> * @param pkt Packet handle >> - * @return 1 if packet contains IP options, 0 otherwise >> + * @retval 1 if packet contains IP options >> + * @retval 0 if packet does not contain IP options >> */ >> int odp_packet_has_ipopt(odp_packet_t pkt); >> >> @@ -144,7 +158,8 @@ int odp_packet_has_ipopt(odp_packet_t pkt); >> * Check for IPSec >> * >> * @param pkt Packet handle >> - * @return 1 if packet requires IPSec processing, 0 otherwise >> + * @retval 1 if packet requires IPSec processing >> + * @retval 0 if packet does not require IPSec processing >> */ >> int odp_packet_has_ipsec(odp_packet_t pkt); >> >> @@ -152,7 +167,8 @@ int odp_packet_has_ipsec(odp_packet_t pkt); >> * Check for UDP >> * >> * @param pkt Packet handle >> - * @return 1 if packet contains a UDP header, 0 otherwise >> + * @retval 1 if packet contains a UDP header >> + * @retval 0 if packet does not contain a UDP header >> */ >> int odp_packet_has_udp(odp_packet_t pkt); >> >> @@ -160,7 +176,8 @@ int odp_packet_has_udp(odp_packet_t pkt); >> * Check for TCP >> * >> * @param pkt Packet handle >> - * @return 1 if packet contains a TCP header, 0 otherwise >> + * @retval 1 if packet contains a TCP header >> + * @retval 0 if packet does not contain a TCP header >> */ >> int odp_packet_has_tcp(odp_packet_t pkt); >> >> @@ -168,7 +185,8 @@ int odp_packet_has_tcp(odp_packet_t pkt); >> * Check for SCTP >> * >> * @param pkt Packet handle >> - * @return 1 if packet contains an SCTP header, 0 otherwise >> + * @retval 1 if packet contains a SCTP header >> + * @retval 0 if packet does not contain a SCTP header >> */ >> int odp_packet_has_sctp(odp_packet_t pkt); >> >> @@ -176,7 +194,8 @@ int odp_packet_has_sctp(odp_packet_t pkt); >> * Check for ICMP >> * >> * @param pkt Packet handle >> - * @return 1 if packet contains an ICMP header, 0 otherwise >> + * @retval 1 if packet contains an ICMP header >> + * @retval 0 if packet does not contain an ICMP header >> */ >> int odp_packet_has_icmp(odp_packet_t pkt); >> >> diff --git a/platform/linux-generic/include/api/odp_packet_io.h >> b/platform/linux-generic/include/api/odp_packet_io.h >> index 4835f4d..1a770b6 100644 >> --- a/platform/linux-generic/include/api/odp_packet_io.h >> +++ b/platform/linux-generic/include/api/odp_packet_io.h >> @@ -40,7 +40,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 >> @@ -53,7 +54,8 @@ odp_pktio_t odp_pktio_open(const char *dev, >> odp_buffer_pool_t pool); >> * >> * @param id 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); >> >> @@ -62,7 +64,8 @@ int odp_pktio_close(odp_pktio_t id); >> * >> * @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); >> >> @@ -73,7 +76,8 @@ odp_pktio_t odp_pktio_lookup(const char *dev); >> * @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); >> >> @@ -84,7 +88,8 @@ int odp_pktio_recv(odp_pktio_t id, odp_packet_t >> pkt_table[], unsigned len); >> * @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); >> >> @@ -93,7 +98,8 @@ int odp_pktio_send(odp_pktio_t id, odp_packet_t >> pkt_table[], unsigned len); >> * >> * @param id 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); >> >> @@ -102,7 +108,8 @@ int odp_pktio_inq_setdef(odp_pktio_t id, odp_queue_t >> queue); >> * >> * @param id 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); >> >> @@ -111,7 +118,8 @@ odp_queue_t odp_pktio_inq_getdef(odp_pktio_t id); >> * >> * @param id 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); >> >> @@ -120,7 +128,8 @@ int odp_pktio_inq_remdef(odp_pktio_t id); >> * >> * @param id 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); >> >> @@ -129,8 +138,8 @@ odp_queue_t odp_pktio_outq_getdef(odp_pktio_t id); >> * >> * @param[in] id 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); >> >> @@ -140,8 +149,8 @@ int odp_pktio_mtu(odp_pktio_t id); >> * @param[in] id 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); >> >> @@ -152,7 +161,7 @@ int odp_pktio_promisc_mode_set(odp_pktio_t id, >> odp_bool_t enable); >> * >> * @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); >> >> @@ -163,9 +172,10 @@ int odp_pktio_promisc_mode(odp_pktio_t id); >> * @param[out] mac_addr Storage for MAC address of the packet IO >> interface. >> * @param addr_size Storage size for the address >> * >> - * @retval Number of bytes written on success, 0 on failure. >> + * @return Number of bytes written on success >> + * @retval <0 on failure >> */ >> -size_t odp_pktio_mac_addr(odp_pktio_t id, void *mac_addr, >> +int odp_pktio_mac_addr(odp_pktio_t id, void *mac_addr, >> size_t addr_size); >> >> /** >> @@ -177,7 +187,8 @@ size_t odp_pktio_mac_addr(odp_pktio_t id, void >> *mac_addr, >> * 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); >> >> @@ -189,7 +200,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. >> */ >> @@ -201,7 +213,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. >> * >> */ >> @@ -216,7 +229,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. >> */ >> diff --git a/platform/linux-generic/include/api/odp_queue.h >> b/platform/linux-generic/include/api/odp_queue.h >> index b0f7185..25633e0 100644 >> --- a/platform/linux-generic/include/api/odp_queue.h >> +++ b/platform/linux-generic/include/api/odp_queue.h >> @@ -118,7 +118,8 @@ typedef struct odp_queue_param_t { >> * @param type Queue type >> * @param param Queue parameters. Uses defaults if NULL. >> * >> - * @return Queue handle or ODP_QUEUE_INVALID >> + * @return Queue handle >> + * @retval ODP_QUEUE_INVALID on failure >> */ >> odp_queue_t odp_queue_create(const char *name, odp_queue_type_t type, >> odp_queue_param_t *param); >> @@ -133,7 +134,8 @@ odp_queue_t odp_queue_create(const char *name, >> odp_queue_type_t type, >> * >> * @param queue Queue handle >> * >> - * @return 0 if successful >> + * @retval 0 on success >> + * @retval <0 on failure >> */ >> int odp_queue_destroy(odp_queue_t queue); >> >> @@ -142,7 +144,8 @@ int odp_queue_destroy(odp_queue_t queue); >> * >> * @param name Queue name >> * >> - * @return Queue handle or ODP_QUEUE_INVALID >> + * @return Queue handle >> + * @retval ODP_QUEUE_INVALID on failure >> */ >> odp_queue_t odp_queue_lookup(const char *name); >> >> @@ -156,7 +159,8 @@ odp_queue_t odp_queue_lookup(const char *name); >> * @param queue Queue handle >> * @param context Address to the queue context >> * >> - * @return 0 if successful >> + * @retval 0 on success >> + * @retval <0 on failure >> */ >> int odp_queue_set_context(odp_queue_t queue, void *context); >> >> @@ -165,8 +169,8 @@ int odp_queue_set_context(odp_queue_t queue, void >> *context); >> * >> * @param queue Queue handle >> * >> - * @return If successful, a pointer to the queue context, >> - * NULL for failure. >> + * @return pointer to the queue context >> + * @retval NULL on failure >> */ >> void *odp_queue_get_context(odp_queue_t queue); >> >> @@ -176,7 +180,8 @@ void *odp_queue_get_context(odp_queue_t queue); >> * @param queue Queue handle >> * @param buf Buffer handle >> * >> - * @return 0 if succesful >> + * @retval 0 on success >> + * @retval <0 on failure >> */ >> int odp_queue_enq(odp_queue_t queue, odp_buffer_t buf); >> >> @@ -187,7 +192,8 @@ int odp_queue_enq(odp_queue_t queue, odp_buffer_t >> buf); >> * @param buf Buffer handles >> * @param num Number of buffer handles >> * >> - * @return 0 if succesful >> + * @retval 0 on success >> + * @retval <0 on failure >> */ >> int odp_queue_enq_multi(odp_queue_t queue, odp_buffer_t buf[], int num); >> >> @@ -199,7 +205,8 @@ int odp_queue_enq_multi(odp_queue_t queue, >> odp_buffer_t buf[], int num); >> * >> * @param queue Queue handle >> * >> - * @return Buffer handle, or ODP_BUFFER_INVALID >> + * @return Buffer handle >> + * @retval ODP_BUFFER_INVALID on failure >> */ >> odp_buffer_t odp_queue_deq(odp_queue_t queue); >> >> diff --git a/platform/linux-generic/include/api/odp_schedule.h >> b/platform/linux-generic/include/api/odp_schedule.h >> index cdf6705..36fbba3 100644 >> --- a/platform/linux-generic/include/api/odp_schedule.h >> +++ b/platform/linux-generic/include/api/odp_schedule.h >> @@ -59,7 +59,8 @@ uint64_t odp_schedule_wait_time(uint64_t ns); >> * Use odp_schedule_wait_time() to convert time to other >> wait >> * values. >> * >> - * @return Next highest priority buffer, or ODP_BUFFER_INVALID >> + * @return Next highest priority buffer >> + * @retval ODP_BUFFER_INVALID on timeout >> */ >> odp_buffer_t odp_schedule(odp_queue_t *from, uint64_t wait); >> >> diff --git a/platform/linux-generic/include/api/odp_shared_memory.h >> b/platform/linux-generic/include/api/odp_shared_memory.h >> index f70db5a..78d108a 100644 >> --- a/platform/linux-generic/include/api/odp_shared_memory.h >> +++ b/platform/linux-generic/include/api/odp_shared_memory.h >> @@ -59,7 +59,8 @@ typedef struct odp_shm_info_t { >> * @param[in] flags Shared memory parameter flags (ODP_SHM_*). >> * Default value is 0. >> * >> - * @return Pointer to the reserved block, or NULL >> + * @return Handle of the reserved block >> + * @retval NULL on failure >> */ >> odp_shm_t odp_shm_reserve(const char *name, uint64_t size, uint64_t >> align, >> uint32_t flags); >> @@ -72,9 +73,9 @@ odp_shm_t odp_shm_reserve(const char *name, uint64_t >> size, uint64_t align, >> * >> * @param[in] shm Block handle >> * >> - * @retval 0 if the handle is already free >> + * @retval 0 if the handle is already free (FIXME how can we know this?) > > > The linux-generic implementation tracks block allocation status. Good point > as to whether this should be part of the spec, however. The above definition puts some more restrictions on the ODP implementation. It must remember all past shm handles and their current status. How does this work if shm regions are created and destroyed repeatedly (an unlikely use case I agree). Possibly there is a fixed array of shm handles with generation counters for each handle but this will eventually wrap around and old stale handles become fresh again. Resource cleanup (e.g. for controlled program termination) has to be a highly synchronized operation anyway, you can't have worker threads continuing their execution, allocating buffers and timers, interacting with HW etc. when you are tearing down those resources. Specifying undefined behavior is better in my opinion. linux-generic only has to be changed so that it does not return 0 for an already freed shm region (because this would be a bad example and we want linux-generic to be a good example), instead it could call ODP_ABORT. > >> >> * @retval 0 if the handle free succeeds >> - * @retval -1 on failure to free the handle >> + * @retval <0 on failure to free the handle >> */ >> int odp_shm_free(odp_shm_t shm); >> >> @@ -84,7 +85,7 @@ int odp_shm_free(odp_shm_t shm); >> * @param[in] name Name of the block >> * >> * @return A handle to the block if it is found by name >> - * @retval #ODP_SHM_INVALID if the block is not found >> + * @retval ODP_SHM_INVALID on failure >> */ >> odp_shm_t odp_shm_lookup(const char *name); >> >> @@ -94,7 +95,8 @@ odp_shm_t odp_shm_lookup(const char *name); >> * >> * @param[in] shm Block handle >> * >> - * @return Memory block address, or NULL on error >> + * @return Memory block address >> + * @retval NULL on failure (FIXME: when?) > > > Why the FIXME? NULL is returned if the operation is unable to succeed. Yes but when can the translation from shm handle to virtual address fail? Are there any situations where we think this is normal behavior? Shared memory regions that are not mapped to virtual memory? Passing invalid shm handles cause undefined behavior, not well-defined failures. So I am questioning why we need a @retval NULL for this function. > >> >> */ >> void *odp_shm_addr(odp_shm_t shm); >> >> @@ -105,7 +107,8 @@ void *odp_shm_addr(odp_shm_t shm); >> * @param[in] shm Block handle >> * @param[out] info Block info pointer for output >> * >> - * @return 0 on success, otherwise non-zero >> + * @retval 0 on success >> + * @retval <0 on failure >> */ >> int odp_shm_info(odp_shm_t shm, odp_shm_info_t *info); >> >> diff --git a/platform/linux-generic/include/api/odp_timer.h >> b/platform/linux-generic/include/api/odp_timer.h >> index 69402ef..c8c3270 100644 >> --- a/platform/linux-generic/include/api/odp_timer.h >> +++ b/platform/linux-generic/include/api/odp_timer.h >> @@ -112,8 +112,8 @@ typedef struct { >> * @param name Name of the timer pool. The string will be copied. >> * @param params Timer pool parameters. The content will be copied. >> * >> - * @return Timer pool handle if successful, otherwise >> ODP_TIMER_POOL_INVALID >> - * and errno set >> + * @return Timer pool handle on success >> + * @retval ODP_TIMER_POOL_INVALID on failure and errno set >> */ >> odp_timer_pool_t >> odp_timer_pool_create(const char *name, >> @@ -185,8 +185,8 @@ typedef struct { >> * @param tpid Timer pool identifier >> * @param[out] info Pointer to information buffer >> * >> - * @retval 0 Success >> - * @retval -1 Failure. Info could not be retrieved. >> + * @retval 0 on success >> + * @retval <0 on failure. Info could not be retrieved. >> */ >> int odp_timer_pool_info(odp_timer_pool_t tpid, >> odp_timer_pool_info_t *info); >> @@ -202,8 +202,8 @@ int odp_timer_pool_info(odp_timer_pool_t tpid, >> * @param queue Destination queue for timeout notifications >> * @param user_ptr User defined pointer or NULL to be copied to timeouts >> * >> - * @return Timer handle if successful, otherwise ODP_TIMER_INVALID and >> - * errno set. >> + * @return Timer handle on success >> + * @retval ODP_TIMER_INVALID on failure and errno set. >> */ >> odp_timer_t odp_timer_alloc(odp_timer_pool_t tpid, >> odp_queue_t queue, >> @@ -218,7 +218,8 @@ odp_timer_t odp_timer_alloc(odp_timer_pool_t tpid, >> * responsibility of the application to handle this timeout when it is >> received. >> * >> * @param tim Timer handle >> - * @return Buffer handle of timeout buffer or ODP_BUFFER_INVALID >> + * @return Buffer handle of timeout buffer >> + * @retval ODP_BUFFER_INVALID on failure >> */ >> odp_buffer_t odp_timer_free(odp_timer_t tim); >> >> @@ -292,8 +293,8 @@ int odp_timer_set_rel(odp_timer_t tim, >> * >> * @param tim Timer >> * @param[out] tmo_buf Pointer to a buffer variable >> - * @retval 0 Success, active timer cancelled, timeout returned in >> '*tmo_buf' >> - * @retval -1 Failure, timer already expired (or inactive) >> + * @retval 0 on success, active timer cancelled, timeout returned in >> '*tmo_buf' >> + * @retval <0 on failure, timer already expired (or inactive) >> */ >> int odp_timer_cancel(odp_timer_t tim, odp_buffer_t *tmo_buf); >> >> diff --git a/platform/linux-generic/odp_crypto.c >> b/platform/linux-generic/odp_crypto.c >> index 2f95cbe..ded3b62 100644 >> --- a/platform/linux-generic/odp_crypto.c >> +++ b/platform/linux-generic/odp_crypto.c >> @@ -343,7 +343,7 @@ odp_crypto_session_create(odp_crypto_session_params_t >> *params, >> >> int >> odp_crypto_operation(odp_crypto_op_params_t *params, >> - bool *posted, >> + odp_bool_t *posted, >> odp_buffer_t completion_event) >> { >> enum crypto_alg_err rc_cipher = ODP_CRYPTO_ALG_ERR_NONE; >> @@ -423,7 +423,7 @@ odp_crypto_init_global(void) >> } >> >> int >> -odp_hw_random_get(uint8_t *buf, size_t *len, bool use_entropy ODP_UNUSED) >> +odp_hw_random_get(uint8_t *buf, size_t *len, odp_bool_t use_entropy >> ODP_UNUSED) >> { >> int rc; >> rc = RAND_bytes(buf, *len); >> diff --git a/platform/linux-generic/odp_packet_io.c >> b/platform/linux-generic/odp_packet_io.c >> index 0efa3d0..c51098f 100644 >> --- a/platform/linux-generic/odp_packet_io.c >> +++ b/platform/linux-generic/odp_packet_io.c >> @@ -797,18 +797,18 @@ int odp_pktio_promisc_mode(odp_pktio_t id) >> } >> >> >> -size_t odp_pktio_mac_addr(odp_pktio_t id, void *mac_addr, >> +int odp_pktio_mac_addr(odp_pktio_t id, void *mac_addr, >> size_t addr_size) >> { >> pktio_entry_t *entry; >> >> if (addr_size < ETH_ALEN) >> - return 0; >> + return -1; >> >> entry = get_pktio_entry(id); >> if (entry == NULL) { >> ODP_DBG("pktio entry %d does not exist\n", id); >> - return 0; >> + return -1; >> } >> >> lock_entry(entry); >> diff --git a/test/validation/crypto/odp_crypto_test_async_inp.c >> b/test/validation/crypto/odp_crypto_test_async_inp.c >> index 96d4c3f..1db7844 100644 >> --- a/test/validation/crypto/odp_crypto_test_async_inp.c >> +++ b/test/validation/crypto/odp_crypto_test_async_inp.c >> @@ -34,7 +34,7 @@ static void alg_test(enum odp_crypto_op op, >> odp_crypto_session_t session; >> int rc; >> enum odp_crypto_ses_create_err status; >> - bool posted; >> + odp_bool_t posted; >> odp_buffer_t compl_event; >> >> odp_queue_t compl_queue = odp_queue_lookup("crypto-out"); >> diff --git a/test/validation/crypto/odp_crypto_test_sync_inp.c >> b/test/validation/crypto/odp_crypto_test_sync_inp.c >> index f37ad54..5082f13 100644 >> --- a/test/validation/crypto/odp_crypto_test_sync_inp.c >> +++ b/test/validation/crypto/odp_crypto_test_sync_inp.c >> @@ -23,7 +23,7 @@ static void alg_test(enum odp_crypto_op op, >> odp_crypto_session_t session; >> int rc; >> enum odp_crypto_ses_create_err status; >> - bool posted; >> + odp_bool_t posted; >> >> odp_queue_t compl_queue = odp_queue_lookup("crypto-out"); >> CU_ASSERT(compl_queue != ODP_QUEUE_INVALID); >> -- >> 1.9.1 >> >> >> _______________________________________________ >> lng-odp mailing list >> lng-odp@lists.linaro.org >> http://lists.linaro.org/mailman/listinfo/lng-odp > >
As a general rule, all functions that return information about e.g. shared memory areas, buffer/event pools and timer pools should be robust in the presence of invalid parameters (handles). The reason is that you might want to implement a form of post-mortem dump which examines all ODP objects and saves the information in some dump area and you don't want this post-mortem dump function to crash. The system is already in a bad state (that's why we need a dump so we can debug it) and not all data can be trusted. Buffers/events are special, we have a special function for checking the validity of such handles so that all other (performance critical) buffer/event operations can expect the handle to be valid and avoid any checks. On 27 January 2015 at 11:43, Ola Liljedahl <ola.liljedahl@linaro.org> wrote: > On 27 January 2015 at 02:14, Bill Fischofer <bill.fischofer@linaro.org> wrote: >> This looks good. It will need to be rebased following the event patch merge >> (all merges currently blocked until that happens). See additional comments >> inline: > I'll rebase as necessary and post updated patches. > >> >> On Mon, Jan 26, 2015 at 6:20 PM, Ola Liljedahl <ola.liljedahl@linaro.org> >> wrote: >>> >>> Unify @return and @retval descriptions. >>> @return used for values that cannot (meaningfully) be enumerated (e.g >>> pointers, >>> ODP handles) or simply tested for correctness. >>> @retval used for values that can be enumerated and should be tested by >>> validation programs. >>> Changed from bool to odp_bool_t in odp_crypto.h and dependent source >>> files. >>> Changed return type and value of odp_pktio_mac_addr() to match other >>> similar >>> functions. Use int as return type, <0 to indicate failure. >>> >>> Signed-off-by: Ola Liljedahl <ola.liljedahl@linaro.org> >>> --- >>> (This document/code contribution attached is provided under the terms of >>> agreement LES-LTM-21309) >>> >>> example/ipsec/odp_ipsec.c | 4 +- >>> platform/linux-generic/include/api/odp_buffer.h | 9 ++- >>> .../linux-generic/include/api/odp_buffer_pool.h | 21 ++++--- >>> platform/linux-generic/include/api/odp_byteorder.h | 2 +- >>> .../linux-generic/include/api/odp_classification.h | 48 +++++++++------- >>> platform/linux-generic/include/api/odp_cpumask.h | 12 ++-- >>> platform/linux-generic/include/api/odp_crypto.h | 15 +++-- >>> platform/linux-generic/include/api/odp_init.h | 10 ++-- >>> platform/linux-generic/include/api/odp_packet.h | 66 >>> ++++++++++++---------- >>> .../linux-generic/include/api/odp_packet_flags.h | 57 >>> ++++++++++++------- >>> platform/linux-generic/include/api/odp_packet_io.h | 54 >>> +++++++++++------- >>> platform/linux-generic/include/api/odp_queue.h | 25 +++++--- >>> platform/linux-generic/include/api/odp_schedule.h | 3 +- >>> .../linux-generic/include/api/odp_shared_memory.h | 15 +++-- >>> platform/linux-generic/include/api/odp_timer.h | 19 ++++--- >>> platform/linux-generic/odp_crypto.c | 4 +- >>> platform/linux-generic/odp_packet_io.c | 6 +- >>> test/validation/crypto/odp_crypto_test_async_inp.c | 2 +- >>> test/validation/crypto/odp_crypto_test_sync_inp.c | 2 +- >>> 19 files changed, 226 insertions(+), 148 deletions(-) >>> >>> diff --git a/example/ipsec/odp_ipsec.c b/example/ipsec/odp_ipsec.c >>> index f2fac8a..066dc40 100644 >>> --- a/example/ipsec/odp_ipsec.c >>> +++ b/example/ipsec/odp_ipsec.c >>> @@ -683,7 +683,7 @@ pkt_disposition_e do_ipsec_in_classify(odp_packet_t >>> pkt, >>> odph_esphdr_t *esp = NULL; >>> ipsec_cache_entry_t *entry; >>> odp_crypto_op_params_t params; >>> - bool posted = 0; >>> + odp_bool_t posted = 0; >>> >>> /* Default to skip IPsec */ >>> *skip = TRUE; >>> @@ -955,7 +955,7 @@ pkt_disposition_e do_ipsec_out_seq(odp_packet_t pkt, >>> pkt_ctx_t *ctx) >>> { >>> uint8_t *buf = odp_packet_data(pkt); >>> - bool posted = 0; >>> + odp_bool_t posted = 0; >>> >>> /* We were dispatched from atomic queue, assign sequence numbers >>> */ >>> if (ctx->ipsec.ah_offset) { >>> diff --git a/platform/linux-generic/include/api/odp_buffer.h >>> b/platform/linux-generic/include/api/odp_buffer.h >>> index 0670464..fd0871b 100644 >>> --- a/platform/linux-generic/include/api/odp_buffer.h >>> +++ b/platform/linux-generic/include/api/odp_buffer.h >>> @@ -32,6 +32,7 @@ extern "C" { >>> * Buffer start address >>> * >>> * @param buf Buffer handle >>> + * Note: Buffer handle must be valid or the behavior will be undefined. >> >> >> Should these be @note ? Same comment for similar Note: adds. > Yes should use @note. > >> Phrasing in >> present tense (...or behavior is undefined) seems more natural, but that's a >> stylistic point that's I won't argue. > You are probably better at English than I am... I am following your > suggestion without argument. > > The language is a bit mixed with these undefined warnings. > > One problem I see is that if we make a @note for undefined behavior > for each function, we need to make that note for *all* relevant > functions. The omission of this note for some functions could indicate > that undefined behavior is not present (even in the presence of > invalid parameters). But I also think a global definition and > documentation of undefined behavior in the ODP documentation might not > be sufficient. Most programmers will go straight at the documentation > of individual functions they want to use. > > >> >>> >>> * >>> * @return Buffer start address >>> */ >>> @@ -41,6 +42,7 @@ void *odp_buffer_addr(odp_buffer_t buf); >>> * Buffer maximum data size >>> * >>> * @param buf Buffer handle >>> + * Note: Buffer handle must be valid or the behavior will be undefined. >>> * >>> * @return Buffer maximum data size >>> */ >>> @@ -50,12 +52,12 @@ uint32_t odp_buffer_size(odp_buffer_t buf); >>> * Buffer type >>> * >>> * @param buf Buffer handle >>> + * Note: Buffer handle must be valid or the behavior will be undefined. >>> * >>> * @return Buffer type >>> */ >>> int odp_buffer_type(odp_buffer_t buf); >>> >>> -#define ODP_BUFFER_TYPE_INVALID (-1) /**< Buffer type invalid */ >>> #define ODP_BUFFER_TYPE_ANY 0 /**< Buffer that can hold any other >>> buffer type */ >>> #define ODP_BUFFER_TYPE_RAW 1 /**< Raw buffer, no additional >>> metadata */ >>> @@ -65,7 +67,9 @@ int odp_buffer_type(odp_buffer_t buf); >>> /** >>> * Tests if buffer is valid >>> * >>> - * @param buf Buffer handle >>> + * @param buf Buffer handle (possibly invalid) >>> + * Note: This is the only call which accepts invalid buffer handles (any >>> bit >>> + * value) without causing undefined behavior. >> >> >> Definitely should be @note for this one. Would it be clearer to say "API" >> rather than "call"? Grammar nit: that rather than which is correct here. > Well this is just one function, the whole set of functions is an API. > Or is my definition of API too narrow? > Maybe "this API function"? > >> >>> >>> * >>> * @retval 1 Buffer handle represents a valid buffer. >>> * @retval 0 Buffer handle does not represent a valid buffer. >>> @@ -76,6 +80,7 @@ int odp_buffer_is_valid(odp_buffer_t buf); >>> * Buffer pool of the buffer >>> * >>> * @param buf Buffer handle >>> + * Note: Buffer handle must be valid or the behavior will be undefined. >>> * >>> * @return Handle of buffer pool buffer belongs to >>> */ >>> diff --git a/platform/linux-generic/include/api/odp_buffer_pool.h >>> b/platform/linux-generic/include/api/odp_buffer_pool.h >>> index 8380ac1..fe917a4 100644 >>> --- a/platform/linux-generic/include/api/odp_buffer_pool.h >>> +++ b/platform/linux-generic/include/api/odp_buffer_pool.h >>> @@ -81,8 +81,8 @@ odp_buffer_pool_t odp_buffer_pool_create(const char >>> *name, >>> * >>> * @param pool Handle of the buffer pool to be destroyed >>> * >>> - * @retval 0 Success >>> - * @retval -1 Failure >>> + * @retval 0 if successful >>> + * @retval <0 on failure >>> * >>> * @note This routine destroys a previously created buffer pool. This >>> call >>> * does not destroy any shared memory object passed to >>> @@ -117,7 +117,7 @@ typedef struct odp_buffer_pool_info_t { >>> odp_shm_t shm; /**< handle of shared memory >>> area >>> supplied by application to >>> contain buffer pool, or >>> - ODP_SHM_INVALID if this pool >>> is >>> + ODP_SHM_NULL if this pool is >>> managed by ODP */ >>> odp_buffer_pool_param_t params; /**< pool parameters */ >>> } odp_buffer_pool_info_t; >>> @@ -125,13 +125,13 @@ typedef struct odp_buffer_pool_info_t { >>> /** >>> * Retrieve information about a buffer pool >>> * >>> - * @param pool Buffer pool handle >>> + * @param pool Buffer pool handle (possibly invalid) >>> * >>> * @param[out] info Receives an odp_buffer_pool_info_t object >>> * that describes the pool. >>> * >>> - * @retval 0 Success >>> - * @retval -1 Failure. Info could not be retrieved. >>> + * @retval 0 if successful >>> + * @retval <0 on failure. Info could not be retrieved (invalid pool >>> handle) >>> */ >>> >>> int odp_buffer_pool_info(odp_buffer_pool_t pool, >>> @@ -149,17 +149,22 @@ void odp_buffer_pool_print(odp_buffer_pool_t pool); >>> >>> /** >>> * Buffer alloc >>> + * Note: the pool handle must be valid or the behavior is undefined. >>> + * >>> + * The validity of a buffer handle can be checked at any time using >>> + * odp_buffer_is_valid() >>> * >>> - * The validity of a buffer can be cheked at any time with >>> odp_buffer_is_valid() >>> * @param pool Pool handle >>> * >>> * @return Handle of allocated buffer >>> - * @retval ODP_BUFFER_INVALID Buffer could not be allocated >>> + * @retval ODP_BUFFER_INVALID Buffer could not be allocated (e.g. pool >>> + * exhausted) >>> */ >>> odp_buffer_t odp_buffer_alloc(odp_buffer_pool_t pool); >>> >>> /** >>> * Buffer free >>> + * Note: the buffer handle must be valid or the behavior is undefined. >>> * >>> * @param buf Buffer handle >>> * >>> diff --git a/platform/linux-generic/include/api/odp_byteorder.h >>> b/platform/linux-generic/include/api/odp_byteorder.h >>> index 5890011..8e38937 100644 >>> --- a/platform/linux-generic/include/api/odp_byteorder.h >>> +++ b/platform/linux-generic/include/api/odp_byteorder.h >>> @@ -24,7 +24,7 @@ extern "C" { >>> #include <odp_compiler.h> >>> >>> /** @defgroup odp_compiler_optim ODP COMPILER / OPTIMIZATION >>> - * Macros that check byte order and byte converting operations. >>> + * Macros that check and convert byte order. >>> * @{ >>> */ >>> >>> diff --git a/platform/linux-generic/include/api/odp_classification.h >>> b/platform/linux-generic/include/api/odp_classification.h >>> index 46189bc..6bca8fc 100644 >>> --- a/platform/linux-generic/include/api/odp_classification.h >>> +++ b/platform/linux-generic/include/api/odp_classification.h >>> @@ -79,8 +79,8 @@ typedef enum odp_cos_hdr_flow_fields { >>> * >>> * @param[in] name String intended for debugging purposes. >>> * >>> - * @return Class of service instance identifier, >>> - * or ODP_COS_INVALID on error. >>> + * @return Class of service instance identifier >>> + * @retval ODP_COS_INVALID on failure. >>> */ >>> odp_cos_t odp_cos_create(const char *name); >>> >>> @@ -89,7 +89,8 @@ odp_cos_t odp_cos_create(const char *name); >>> * >>> * @param[in] cos_id class-of-service instance. >>> * >>> - * @return 0 on success, non-zero on error. >>> + * @retval 0 if successful >>> + * @retval <0 on failure >>> */ >>> int odp_cos_destroy(odp_cos_t cos_id); >>> >>> @@ -102,7 +103,8 @@ int odp_cos_destroy(odp_cos_t cos_id); >>> * of this specific class of service >>> * will be enqueued. >>> * >>> - * @return 0 on success, non-zero on error. >>> + * @retval 0 if successful >>> + * @retval <0 on failure >>> */ >>> int odp_cos_set_queue(odp_cos_t cos_id, odp_queue_t queue_id); >>> >>> @@ -112,7 +114,8 @@ int odp_cos_set_queue(odp_cos_t cos_id, odp_queue_t >>> queue_id); >>> * @param[in] cos_id class-of-service instance. >>> * @param[in] drop_policy Desired packet drop policy for this class. >>> * >>> - * @return 0 on success, non-zero on error. >>> + * @retval 0 if successful >>> + * @retval <0 on failure >>> * >>> * @note Optional. >>> */ >>> @@ -127,7 +130,8 @@ int odp_cos_set_drop(odp_cos_t cos_id, odp_drop_e >>> drop_policy); >>> * @param[in] qos_table Values of the Layer-2 QoS header field. >>> * @param[in] cos_table Class-of-service assigned to each of the >>> * allowed Layer-2 QOS levels. >>> - * @return 0 on success, non-zero on error. >>> + * @retval 0 if successful >>> + * @retval <0 on failure >>> */ >>> int odp_cos_with_l2_priority(odp_pktio_t pktio_in, >>> uint8_t num_qos, >>> @@ -146,7 +150,8 @@ int odp_cos_with_l2_priority(odp_pktio_t pktio_in, >>> * @param[in] l3_preference when true, Layer-3 QoS overrides >>> * L2 QoS when present. >>> * >>> - * @return 0 on success, non-zero on error. >>> + * @retval 0 if successful >>> + * @retval <0 on failure >>> * >>> * @note Optional. >>> */ >>> @@ -219,7 +224,8 @@ typedef enum odp_pmr_term { >>> * that must match the value size requirement of the >>> * specific term. >>> * >>> - * @return Handle of the matching rule or ODP_PMR_INVAL on >>> error >>> + * @return Handle of the matching rule >>> + * @retval ODP_PMR_INVAL on failure >>> */ >>> odp_pmr_t odp_pmr_create_match(odp_pmr_term_e term, >>> const void *val, >>> @@ -236,7 +242,8 @@ odp_pmr_t odp_pmr_create_match(odp_pmr_term_e term, >>> * that must match the value size requirement of the >>> * specific term. >>> * >>> - * @return Handle of the matching rule or ODP_PMR_INVAL on >>> error >>> + * @return Handle of the matching rule >>> + * @retval ODP_PMR_INVAL on failure >>> * @note: Range is inclusive [val1..val2]. >>> */ >>> odp_pmr_t odp_pmr_create_range(odp_pmr_term_e term, >>> @@ -248,7 +255,8 @@ odp_pmr_t odp_pmr_create_range(odp_pmr_term_e term, >>> * >>> * @param[in] pmr_id Identifier of the PMR to be destroyed >>> * >>> - * @return 0 on success, non-zero or error. >>> + * @retval 0 if successful >>> + * @retval <0 on failure >>> */ >>> int odp_pmr_destroy(odp_pmr_t pmr_id); >>> >>> @@ -259,7 +267,8 @@ int odp_pmr_destroy(odp_pmr_t pmr_id); >>> * @param[in] src_pktio pktio to which this PMR is to be applied >>> * @param[in] dst_cos CoS to be assigned by this PMR >>> * >>> - * @return 0 on success, non-zero or error. >>> + * @retval 0 if successful >>> + * @retval <0 on failure >>> */ >>> int odp_pktio_pmr_cos(odp_pmr_t pmr_id, >>> odp_pktio_t src_pktio, odp_cos_t dst_cos); >>> @@ -272,7 +281,8 @@ int odp_pktio_pmr_cos(odp_pmr_t pmr_id, >>> * @param[in] dst_cos CoS to be assigned to packets filtered >>> * from src_cos that match pmr_id. >>> * >>> - * @return 0 on success, non-zero on error. >>> + * @retval 0 if successful >>> + * @retval <0 on failure >>> */ >>> int odp_cos_pmr_cos(odp_pmr_t pmr_id, odp_cos_t src_cos, odp_cos_t >>> dst_cos); >>> >>> @@ -346,12 +356,10 @@ typedef uint32_t odp_pmr_set_t; >>> * term desired. >>> * @param[out] pmr_set_id Returned handle to the composite rule set. >>> * >>> - * @return Return value may be a positive number >>> - * indicating the number of terms elements >>> + * @return the number of terms elements >>> * that have been successfully mapped to the >>> - * underlying platform classification engine >>> and >>> - * may be in the range from 1 to num_terms, >>> - * or non-zero for error. >>> + * underlying platform classification engine >>> + * @retval <0 on failure >>> */ >>> int odp_pmr_match_set_create(int num_terms, odp_pmr_match_t *terms, >>> odp_pmr_set_t *pmr_set_id); >>> @@ -369,7 +377,8 @@ int odp_pmr_match_set_create(int num_terms, >>> odp_pmr_match_t *terms, >>> * @param[in] pmr_set_id A composite rule-set handle >>> * returned when created. >>> * >>> - * @return 0 on success, non-zero on error. >>> + * @retval 0 if successful >>> + * @retval <0 on failure >>> */ >>> int odp_pmr_match_set_destroy(odp_pmr_set_t pmr_set_id); >>> >>> @@ -381,7 +390,8 @@ int odp_pmr_match_set_destroy(odp_pmr_set_t >>> pmr_set_id); >>> * set is to be applied >>> * @param[in] dst_cos CoS to be assigned by this PMR match set >>> * >>> - * @return 0 on success, non-zero or error. >>> + * @retval 0 if successful >>> + * @retval <0 on failure >>> */ >>> int odp_pktio_pmr_match_set_cos(odp_pmr_set_t pmr_set_id, odp_pktio_t >>> src_pktio, >>> odp_cos_t dst_cos); >>> diff --git a/platform/linux-generic/include/api/odp_cpumask.h >>> b/platform/linux-generic/include/api/odp_cpumask.h >>> index ebff9b0..5c5bcd7 100644 >>> --- a/platform/linux-generic/include/api/odp_cpumask.h >>> +++ b/platform/linux-generic/include/api/odp_cpumask.h >>> @@ -79,7 +79,8 @@ void odp_cpumask_clr(odp_cpumask_t *mask, int cpu); >>> * Test if cpu is a member of mask >>> * @param mask CPU mask to check if cpu num set or not >>> * @param cpu CPU number >>> - * @return non-zero if set otherwise 0 >>> + * @return non-zero if set >>> + * @retval 0 if not set >>> */ >>> int odp_cpumask_isset(const odp_cpumask_t *mask, int cpu); >>> >>> @@ -134,14 +135,16 @@ void odp_cpumask_copy(odp_cpumask_t *dest, const >>> odp_cpumask_t *src); >>> /** >>> * Find first bit set in mask >>> * >>> - * @return cpu else -1 if no bits set in cpumask >>> + * @return cpu >>> + * @retval -1 if no bits set in cpumask >> >> >> Should this be <0 for consistency with other error RC descriptions? > Possibly. I was a little loath at changing the definitions of these > basically bit set operations (where return values might be the direct > results of binary/arithmetic operations) but this one could be unified > with the rest without any problems. It was also getting rather late in > the evening, I was probably not thinking too clearly at the end. > I changed all three remaining instances in this file. > >> >>> >>> */ >>> int odp_cpumask_first(const odp_cpumask_t *mask); >>> >>> /** >>> * Find last bit set in mask >>> * >>> - * @return cpu else -1 if no bits set in cpumask >>> + * @return cpu >>> + * @retval -1 if no bits set in cpumask >> >> >> Same here. <0 ? > yes > >> >>> >>> */ >>> int odp_cpumask_last(const odp_cpumask_t *mask); >>> >>> @@ -160,7 +163,8 @@ int odp_cpumask_last(const odp_cpumask_t *mask); >>> * >>> * @param mask CPU mask to find next cpu in >>> * @param cpu CPU to start from >>> - * @return cpu found else -1 >>> + * @return cpu found >>> + * @retval -1 if not found >> >> >> And again here. > yes > >> >>> >>> * >>> * @see odp_cpumask_first() >>> */ >>> diff --git a/platform/linux-generic/include/api/odp_crypto.h >>> b/platform/linux-generic/include/api/odp_crypto.h >>> index 337e7cf..2f00f95 100644 >>> --- a/platform/linux-generic/include/api/odp_crypto.h >>> +++ b/platform/linux-generic/include/api/odp_crypto.h >>> @@ -218,7 +218,8 @@ typedef struct odp_crypto_compl_status { >>> * @param session Created session else >>> ODP_CRYPTO_SESSION_INVALID >>> * @param status Failure code if unsuccessful >>> * >>> - * @return 0 if successful else -1 >>> + * @retval 0 if successful >>> + * @retval <0 on failure >>> */ >>> int >>> odp_crypto_session_create(odp_crypto_session_params_t *params, >>> @@ -242,11 +243,12 @@ >>> odp_crypto_session_create(odp_crypto_session_params_t *params, >>> * @param posted Pointer to return posted, TRUE for async >>> operation >>> * @param completion_event Event by which the operation results are >>> delivered. >>> * >>> - * @return 0 if successful else -1 >>> + * @retval 0 if successful >>> + * @retval <0 on failure >>> */ >>> int >>> odp_crypto_operation(odp_crypto_op_params_t *params, >>> - bool *posted, >>> + odp_bool_t *posted, >>> odp_buffer_t completion_event); >>> >>> /** >>> @@ -281,7 +283,7 @@ odp_crypto_get_operation_compl_status(odp_buffer_t >>> completion_event, >>> * >>> * @param completion_event Event containing operation results >>> * >>> - * @return Packet structure where data now resides >>> + * @return Handle for packet where data now resides >>> */ >>> odp_packet_t >>> odp_crypto_get_operation_compl_packet(odp_buffer_t completion_event); >>> @@ -305,10 +307,11 @@ odp_crypto_get_operation_compl_ctx(odp_buffer_t >>> completion_event); >>> * >>> * @todo Define the implication of the use_entropy parameter >>> * >>> - * @return 0 if succesful >>> + * @retval 0 if successful >>> + * @retval <0 on failure >>> */ >>> int >>> -odp_hw_random_get(uint8_t *buf, size_t *len, bool use_entropy); >>> +odp_hw_random_get(uint8_t *buf, size_t *len, odp_bool_t use_entropy); >>> >>> /** >>> * @} >>> diff --git a/platform/linux-generic/include/api/odp_init.h >>> b/platform/linux-generic/include/api/odp_init.h >>> index ac856df..4a98717 100644 >>> --- a/platform/linux-generic/include/api/odp_init.h >>> +++ b/platform/linux-generic/include/api/odp_init.h >>> @@ -66,8 +66,8 @@ typedef enum odp_log_level { >>> * @param[in] level Log level >>> * @param[in] fmt printf-style message format >>> * >>> - * @return The number of characters logged if succeeded. Otherwise >>> returns >>> - * a negative number. >>> + * @return The number of characters logged if successful >>> + * @retval <0 on failure >>> */ >>> int odp_override_log(odp_log_level_e level, const char *fmt, ...); >>> >>> @@ -109,7 +109,7 @@ typedef struct odp_platform_init_t { >>> * interpretation by the ODP API to the implementation. >>> * >>> * @retval 0 if successful >>> - * @retval -1 on failure >>> + * @retval <0 on failure >>> */ >>> int odp_init_global(odp_init_t *params, odp_platform_init_t >>> *platform_params); >>> >>> @@ -134,7 +134,7 @@ int odp_init_global(odp_init_t *params, >>> odp_platform_init_t *platform_params); >>> * @sa odp_term_local() which must have been called prior to this. >>> * >>> * @retval 0 if successful >>> - * @retval -1 on failure >>> + * @retval <0 on failure >>> */ >>> int odp_term_global(void); >>> >>> @@ -148,7 +148,7 @@ int odp_term_global(void); >>> * @sa odp_init_global() which must have been called prior to this. >>> * >>> * @retval 0 if successful >>> - * @retval -1 on failure >>> + * @retval <0 on failure >>> */ >>> int odp_init_local(void); >>> >>> diff --git a/platform/linux-generic/include/api/odp_packet.h >>> b/platform/linux-generic/include/api/odp_packet.h >>> index 920a593..b471d07 100644 >>> --- a/platform/linux-generic/include/api/odp_packet.h >>> +++ b/platform/linux-generic/include/api/odp_packet.h >>> @@ -88,8 +88,8 @@ void odp_packet_free(odp_packet_t pkt); >>> * @param pkt Packet handle >>> * @param len Packet data length >>> * >>> - * @retval 0 Success >>> - * @retval Non-zero Failure >>> + * @retval 0 if successful >>> + * @retval <0 on failure >>> * >>> * @see odp_packet_buf_len() >>> */ >>> @@ -279,7 +279,7 @@ void *odp_packet_push_head(odp_packet_t pkt, uint32_t >>> len); >>> * @param pkt Packet handle >>> * @param len Number of bytes to pull the head (0 ... seg_len - 1) >>> * >>> - * @return The new data pointer, or NULL in case of an error. >>> + * @return The new data pointer >>> * @retval NULL Requested offset exceeds packet segment length >>> >>> * >>> * @see odp_packet_seg_len(), odp_packet_push_head() >>> @@ -391,7 +391,7 @@ odp_buffer_pool_t odp_packet_pool(odp_packet_t pkt); >>> * @param pkt Packet handle >>> * >>> * @return Packet interface handle >>> - * @retval ODP_PKTIO_INVALID Packet was not received >>> + * @retval ODP_PKTIO_INVALID Packet was not received on any interface >>> */ >>> odp_pktio_t odp_packet_input(odp_packet_t pkt); >>> >>> @@ -451,8 +451,8 @@ void odp_packet_user_u64_set(odp_packet_t pkt, >>> uint64_t ctx); >>> * @param[out] len Number of data bytes remaining in the segment >>> (output). >>> * Ignored when NULL. >>> * >>> - * @return Layer 2 start pointer, or NULL when packet does not contain a >>> valid >>> - * L2 header. >>> + * @return Layer 2 start pointer >>> + * @retval NULL packet does not contain a valid L2 header >>> * >>> * @see odp_packet_l2_offset(), odp_packet_l2_offset_set(), >>> odp_packet_has_l2() >>> */ >>> @@ -469,8 +469,8 @@ void *odp_packet_l2_ptr(odp_packet_t pkt, uint32_t >>> *len); >>> * >>> * @param pkt Packet handle >>> * >>> - * @return Layer 2 start offset, or ODP_PACKET_OFFSET_INVALID when >>> packet does >>> - * not contain a valid L2 header. >>> + * @return Layer 2 start offset >>> + * @retval ODP_PACKET_OFFSET_INVALID packet does not contain a valid L2 >>> header >>> * >>> * @see odp_packet_l2_offset_set(), odp_packet_has_l2() >>> */ >>> @@ -486,8 +486,8 @@ uint32_t odp_packet_l2_offset(odp_packet_t pkt); >>> * @param pkt Packet handle >>> * @param offset Layer 2 start offset (0 ... odp_packet_len()-1) >>> * >>> - * @retval 0 Success >>> - * @retval Non-zero Failure >>> + * @retval 0 if successful >>> + * @retval <0 on failure >>> */ >>> int odp_packet_l2_offset_set(odp_packet_t pkt, uint32_t offset); >>> >>> @@ -501,8 +501,8 @@ int odp_packet_l2_offset_set(odp_packet_t pkt, >>> uint32_t offset); >>> * @param[out] len Number of data bytes remaining in the segment >>> (output). >>> * Ignored when NULL. >>> * >>> - * @return Layer 3 start pointer, or NULL when packet does not contain a >>> valid >>> - * L3 header. >>> + * @return Layer 3 start pointer >>> + * @retval NULL packet does not contain a valid L3 header >>> * >>> * @see odp_packet_l3_offset(), odp_packet_l3_offset_set(), >>> odp_packet_has_l3() >>> */ >>> @@ -536,8 +536,8 @@ uint32_t odp_packet_l3_offset(odp_packet_t pkt); >>> * @param pkt Packet handle >>> * @param offset Layer 3 start offset (0 ... odp_packet_len()-1) >>> * >>> - * @retval 0 Success >>> - * @retval Non-zero Failure >>> + * @retval 0 if successful >>> + * @retval <0 on failure >>> */ >>> int odp_packet_l3_offset_set(odp_packet_t pkt, uint32_t offset); >>> >>> @@ -551,8 +551,8 @@ int odp_packet_l3_offset_set(odp_packet_t pkt, >>> uint32_t offset); >>> * @param[out] len Number of data bytes remaining in the segment >>> (output). >>> * Ignored when NULL. >>> * >>> - * @return Layer 4 start pointer, or NULL when packet does not contain a >>> valid >>> - * L4 header. >>> + * @return Layer 4 start pointer >>> + * @retval NULL packet does not contain a valid L4 header >>> * >>> * @see odp_packet_l4_offset(), odp_packet_l4_offset_set(), >>> odp_packet_has_l4() >>> */ >>> @@ -569,8 +569,8 @@ void *odp_packet_l4_ptr(odp_packet_t pkt, uint32_t >>> *len); >>> * >>> * @param pkt Packet handle >>> * >>> - * @return Layer 4 start offset, or ODP_PACKET_OFFSET_INVALID when >>> packet does >>> - * not contain a valid L4 header. >>> + * @return Layer 4 start offset >>> + * @retval ODP_PACKET_OFFSET_INVALID packet does not contain a valid L4 >>> header >>> * >>> * @see odp_packet_l4_offset_set(), odp_packet_has_l4() >>> */ >>> @@ -586,8 +586,8 @@ uint32_t odp_packet_l4_offset(odp_packet_t pkt); >>> * @param pkt Packet handle >>> * @param offset Layer 4 start offset (0 ... odp_packet_len()-1) >>> * >>> - * @retval 0 Success >>> - * @retval Non-zero Failure >>> + * @retval 0 on success >>> + * @retval <0 on failure >>> */ >>> int odp_packet_l4_offset_set(odp_packet_t pkt, uint32_t offset); >>> >>> @@ -645,7 +645,8 @@ odp_packet_seg_t odp_packet_last_seg(odp_packet_t >>> pkt); >>> * @param pkt Packet handle >>> * @param seg Current segment handle >>> * >>> - * @return Handle to the next segment, or ODP_PACKET_SEG_INVALID >>> + * @return Handle to the next segment >>> + * @retval ODP_PACKET_SEG_INVALID if there are no more segments >>> */ >>> odp_packet_seg_t odp_packet_next_seg(odp_packet_t pkt, odp_packet_seg_t >>> seg); >>> >>> @@ -665,7 +666,8 @@ odp_packet_seg_t odp_packet_next_seg(odp_packet_t pkt, >>> odp_packet_seg_t seg); >>> * @param pkt Packet handle >>> * @param seg Segment handle >>> * >>> - * @return Start address of the segment, or NULL on an error >>> + * @return Start address of the segment >>> + * @retval NULL on failure >>> * >>> * @see odp_packet_seg_buf_len() >>> */ >>> @@ -693,7 +695,8 @@ uint32_t odp_packet_seg_buf_len(odp_packet_t pkt, >>> odp_packet_seg_t seg); >>> * @param pkt Packet handle >>> * @param seg Segment handle >>> * >>> - * @return Pointer to the segment data, or NULL on an error >>> + * @return Pointer to the segment data >>> + * @retval NULL on failure >>> * >>> * @see odp_packet_seg_data_len() >>> */ >>> @@ -735,7 +738,8 @@ uint32_t odp_packet_seg_data_len(odp_packet_t pkt, >>> odp_packet_seg_t seg); >>> * @param offset Byte offset into the packet >>> * @param len Number of bytes to add into the offset >>> * >>> - * @return New packet handle, or ODP_PACKET_INVALID in case of an error. >>> + * @return New packet handle >>> + * @retval ODP_PACKET_INVALID on failure >>> */ >>> odp_packet_t odp_packet_add_data(odp_packet_t pkt, uint32_t offset, >>> uint32_t len); >>> @@ -753,7 +757,8 @@ odp_packet_t odp_packet_add_data(odp_packet_t pkt, >>> uint32_t offset, >>> * @param offset Byte offset into the packet >>> * @param len Number of bytes to remove from the offset >>> * >>> - * @return New packet handle, or ODP_PACKET_INVALID in case of an error. >>> + * @return New packet handle >>> + * @retval ODP_PACKET_INVALID on failure >>> */ >>> odp_packet_t odp_packet_rem_data(odp_packet_t pkt, uint32_t offset, >>> uint32_t len); >>> @@ -776,7 +781,8 @@ odp_packet_t odp_packet_rem_data(odp_packet_t pkt, >>> uint32_t offset, >>> * @param pkt Packet handle >>> * @param pool Buffer pool for allocation of the new packet. >>> * >>> - * @return Handle to the copy of the packet, or ODP_PACKET_INVALID >>> + * @return Handle to the copy of the packet >>> + * @retval ODP_PACKET_INVALID on failure >>> */ >>> odp_packet_t odp_packet_copy(odp_packet_t pkt, odp_buffer_pool_t pool); >>> >>> @@ -791,8 +797,8 @@ odp_packet_t odp_packet_copy(odp_packet_t pkt, >>> odp_buffer_pool_t pool); >>> * @param len Number of bytes to copy >>> * @param dst Destination address >>> * >>> - * @retval 0 Success >>> - * @retval Non-zero Failure >>> + * @retval 0 on success >>> + * @retval <0 on failure >>> */ >>> int odp_packet_copydata_out(odp_packet_t pkt, uint32_t offset, >>> uint32_t len, void *dst); >>> @@ -809,8 +815,8 @@ int odp_packet_copydata_out(odp_packet_t pkt, uint32_t >>> offset, >>> * @param len Number of bytes to copy >>> * @param src Source address >>> * >>> - * @retval 0 Success >>> - * @retval Non-zero Failure >>> + * @retval 0 on success >>> + * @retval <0 on failure >>> */ >>> int odp_packet_copydata_in(odp_packet_t pkt, uint32_t offset, >>> uint32_t len, const void *src); >>> diff --git a/platform/linux-generic/include/api/odp_packet_flags.h >>> b/platform/linux-generic/include/api/odp_packet_flags.h >>> index 24c4065..399a0bf 100644 >>> --- a/platform/linux-generic/include/api/odp_packet_flags.h >>> +++ b/platform/linux-generic/include/api/odp_packet_flags.h >>> @@ -32,7 +32,8 @@ extern "C" { >>> * Checks all error flags at once. >>> * >>> * @param pkt Packet handle >>> - * @return 1 if packet has errors, 0 otherwise >>> + * @retval 1 if packet has errors >>> + * @retval 0 if packet has no errors >>> */ >>> int odp_packet_error(odp_packet_t pkt); >>> >>> @@ -40,7 +41,8 @@ int odp_packet_error(odp_packet_t pkt); >>> * Check if error was 'frame length' error >>> * >>> * @param pkt Packet handle >>> - * @return 1 if frame length error detected, 0 otherwise >>> + * @retval 1 if frame length error detected >>> + * @retval 0 if frame length error not detected >>> */ >>> int odp_packet_errflag_frame_len(odp_packet_t pkt); >>> >>> @@ -48,7 +50,8 @@ int odp_packet_errflag_frame_len(odp_packet_t pkt); >>> * Check for L2 header, e.g. ethernet >>> * >>> * @param pkt Packet handle >>> - * @return 1 if packet contains a valid & known L2 header, 0 otherwise >>> + * @retval 1 if packet contains a valid & known L2 header >>> + * @retval 0 if packet does not contain a valid & known L2 header >>> */ >>> int odp_packet_has_l2(odp_packet_t pkt); >>> >>> @@ -56,7 +59,8 @@ int odp_packet_has_l2(odp_packet_t pkt); >>> * Check for L3 header, e.g. IPv4, IPv6 >>> * >>> * @param pkt Packet handle >>> - * @return 1 if packet contains a valid & known L3 header, 0 otherwise >>> + * @retval 1 if packet contains a valid & known L3 header >>> + * @retval 0 if packet does not contain a valid & known L3 header >>> */ >>> int odp_packet_has_l3(odp_packet_t pkt); >>> >>> @@ -64,7 +68,8 @@ int odp_packet_has_l3(odp_packet_t pkt); >>> * Check for L4 header, e.g. UDP, TCP, SCTP (also ICMP) >>> * >>> * @param pkt Packet handle >>> - * @return 1 if packet contains a valid & known L4 header, 0 otherwise >>> + * @retval 1 if packet contains a valid & known L4 header >>> + * @retval 0 if packet does not contain a valid & known L4 header >>> */ >>> int odp_packet_has_l4(odp_packet_t pkt); >>> >>> @@ -72,7 +77,8 @@ int odp_packet_has_l4(odp_packet_t pkt); >>> * Check for Ethernet header >>> * >>> * @param pkt Packet handle >>> - * @return 1 if packet contains a valid eth header, 0 otherwise >>> + * @retval 1 if packet contains a valid eth header >>> + * @retval 0 if packet does not contain a valid & known eth header >>> */ >>> int odp_packet_has_eth(odp_packet_t pkt); >>> >>> @@ -80,7 +86,8 @@ int odp_packet_has_eth(odp_packet_t pkt); >>> * Check for jumbo frame >>> * >>> * @param pkt Packet handle >>> - * @return 1 if packet contains jumbo frame, 0 otherwise >>> + * @retval 1 if packet contains a jumbo frame >>> + * @retval 0 if packet does not contain a jumbo frame >>> */ >>> int odp_packet_has_jumbo(odp_packet_t pkt); >>> >>> @@ -88,7 +95,8 @@ int odp_packet_has_jumbo(odp_packet_t pkt); >>> * Check for VLAN >>> * >>> * @param pkt Packet handle >>> - * @return 1 if packet contains a VLAN header, 0 otherwise >>> + * @retval 1 if packet contains a VLAN header >>> + * @retval 0 if packet does not contain a VLAN header >>> */ >>> int odp_packet_has_vlan(odp_packet_t pkt); >>> >>> @@ -96,7 +104,8 @@ int odp_packet_has_vlan(odp_packet_t pkt); >>> * Check for VLAN QinQ (stacked VLAN) >>> * >>> * @param pkt Packet handle >>> - * @return 1 if packet contains a VLAN QinQ header, 0 otherwise >>> + * @retval 1 if packet contains a VLAN QinQ header >>> + * @retval 0 if packet does not contain a VLAN QinQ header >>> */ >>> int odp_packet_has_vlan_qinq(odp_packet_t pkt); >>> >>> @@ -104,7 +113,8 @@ int odp_packet_has_vlan_qinq(odp_packet_t pkt); >>> * Check for ARP >>> * >>> * @param pkt Packet handle >>> - * @return 1 if packet contains an ARP header, 0 otherwise >>> + * @retval 1 if packet contains an ARP message >>> + * @retval 0 if packet does not contain an ARP message >>> */ >>> int odp_packet_has_arp(odp_packet_t pkt); >>> >>> @@ -112,7 +122,8 @@ int odp_packet_has_arp(odp_packet_t pkt); >>> * Check for IPv4 >>> * >>> * @param pkt Packet handle >>> - * @return 1 if packet contains an IPv4 header, 0 otherwise >>> + * @retval 1 if packet contains an IPv4 header >>> + * @retval 0 if packet does not contain an IPv4 header >>> */ >>> int odp_packet_has_ipv4(odp_packet_t pkt); >>> >>> @@ -120,7 +131,8 @@ int odp_packet_has_ipv4(odp_packet_t pkt); >>> * Check for IPv6 >>> * >>> * @param pkt Packet handle >>> - * @return 1 if packet contains an IPv6 header, 0 otherwise >>> + * @retval 1 if packet contains an IPv6 header >>> + * @retval 0 if packet does not contain an IPv6 header >>> */ >>> int odp_packet_has_ipv6(odp_packet_t pkt); >>> >>> @@ -128,7 +140,8 @@ int odp_packet_has_ipv6(odp_packet_t pkt); >>> * Check for IP fragment >>> * >>> * @param pkt Packet handle >>> - * @return 1 if packet is an IP fragment, 0 otherwise >>> + * @retval 1 if packet is an IP fragment >>> + * @retval 0 if packet is not an IP fragment >>> */ >>> int odp_packet_has_ipfrag(odp_packet_t pkt); >>> >>> @@ -136,7 +149,8 @@ int odp_packet_has_ipfrag(odp_packet_t pkt); >>> * Check for IP options >>> * >>> * @param pkt Packet handle >>> - * @return 1 if packet contains IP options, 0 otherwise >>> + * @retval 1 if packet contains IP options >>> + * @retval 0 if packet does not contain IP options >>> */ >>> int odp_packet_has_ipopt(odp_packet_t pkt); >>> >>> @@ -144,7 +158,8 @@ int odp_packet_has_ipopt(odp_packet_t pkt); >>> * Check for IPSec >>> * >>> * @param pkt Packet handle >>> - * @return 1 if packet requires IPSec processing, 0 otherwise >>> + * @retval 1 if packet requires IPSec processing >>> + * @retval 0 if packet does not require IPSec processing >>> */ >>> int odp_packet_has_ipsec(odp_packet_t pkt); >>> >>> @@ -152,7 +167,8 @@ int odp_packet_has_ipsec(odp_packet_t pkt); >>> * Check for UDP >>> * >>> * @param pkt Packet handle >>> - * @return 1 if packet contains a UDP header, 0 otherwise >>> + * @retval 1 if packet contains a UDP header >>> + * @retval 0 if packet does not contain a UDP header >>> */ >>> int odp_packet_has_udp(odp_packet_t pkt); >>> >>> @@ -160,7 +176,8 @@ int odp_packet_has_udp(odp_packet_t pkt); >>> * Check for TCP >>> * >>> * @param pkt Packet handle >>> - * @return 1 if packet contains a TCP header, 0 otherwise >>> + * @retval 1 if packet contains a TCP header >>> + * @retval 0 if packet does not contain a TCP header >>> */ >>> int odp_packet_has_tcp(odp_packet_t pkt); >>> >>> @@ -168,7 +185,8 @@ int odp_packet_has_tcp(odp_packet_t pkt); >>> * Check for SCTP >>> * >>> * @param pkt Packet handle >>> - * @return 1 if packet contains an SCTP header, 0 otherwise >>> + * @retval 1 if packet contains a SCTP header >>> + * @retval 0 if packet does not contain a SCTP header >>> */ >>> int odp_packet_has_sctp(odp_packet_t pkt); >>> >>> @@ -176,7 +194,8 @@ int odp_packet_has_sctp(odp_packet_t pkt); >>> * Check for ICMP >>> * >>> * @param pkt Packet handle >>> - * @return 1 if packet contains an ICMP header, 0 otherwise >>> + * @retval 1 if packet contains an ICMP header >>> + * @retval 0 if packet does not contain an ICMP header >>> */ >>> int odp_packet_has_icmp(odp_packet_t pkt); >>> >>> diff --git a/platform/linux-generic/include/api/odp_packet_io.h >>> b/platform/linux-generic/include/api/odp_packet_io.h >>> index 4835f4d..1a770b6 100644 >>> --- a/platform/linux-generic/include/api/odp_packet_io.h >>> +++ b/platform/linux-generic/include/api/odp_packet_io.h >>> @@ -40,7 +40,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 >>> @@ -53,7 +54,8 @@ odp_pktio_t odp_pktio_open(const char *dev, >>> odp_buffer_pool_t pool); >>> * >>> * @param id 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); >>> >>> @@ -62,7 +64,8 @@ int odp_pktio_close(odp_pktio_t id); >>> * >>> * @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); >>> >>> @@ -73,7 +76,8 @@ odp_pktio_t odp_pktio_lookup(const char *dev); >>> * @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); >>> >>> @@ -84,7 +88,8 @@ int odp_pktio_recv(odp_pktio_t id, odp_packet_t >>> pkt_table[], unsigned len); >>> * @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); >>> >>> @@ -93,7 +98,8 @@ int odp_pktio_send(odp_pktio_t id, odp_packet_t >>> pkt_table[], unsigned len); >>> * >>> * @param id 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); >>> >>> @@ -102,7 +108,8 @@ int odp_pktio_inq_setdef(odp_pktio_t id, odp_queue_t >>> queue); >>> * >>> * @param id 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); >>> >>> @@ -111,7 +118,8 @@ odp_queue_t odp_pktio_inq_getdef(odp_pktio_t id); >>> * >>> * @param id 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); >>> >>> @@ -120,7 +128,8 @@ int odp_pktio_inq_remdef(odp_pktio_t id); >>> * >>> * @param id 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); >>> >>> @@ -129,8 +138,8 @@ odp_queue_t odp_pktio_outq_getdef(odp_pktio_t id); >>> * >>> * @param[in] id 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); >>> >>> @@ -140,8 +149,8 @@ int odp_pktio_mtu(odp_pktio_t id); >>> * @param[in] id 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); >>> >>> @@ -152,7 +161,7 @@ int odp_pktio_promisc_mode_set(odp_pktio_t id, >>> odp_bool_t enable); >>> * >>> * @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); >>> >>> @@ -163,9 +172,10 @@ int odp_pktio_promisc_mode(odp_pktio_t id); >>> * @param[out] mac_addr Storage for MAC address of the packet IO >>> interface. >>> * @param addr_size Storage size for the address >>> * >>> - * @retval Number of bytes written on success, 0 on failure. >>> + * @return Number of bytes written on success >>> + * @retval <0 on failure >>> */ >>> -size_t odp_pktio_mac_addr(odp_pktio_t id, void *mac_addr, >>> +int odp_pktio_mac_addr(odp_pktio_t id, void *mac_addr, >>> size_t addr_size); >>> >>> /** >>> @@ -177,7 +187,8 @@ size_t odp_pktio_mac_addr(odp_pktio_t id, void >>> *mac_addr, >>> * 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); >>> >>> @@ -189,7 +200,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. >>> */ >>> @@ -201,7 +213,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. >>> * >>> */ >>> @@ -216,7 +229,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. >>> */ >>> diff --git a/platform/linux-generic/include/api/odp_queue.h >>> b/platform/linux-generic/include/api/odp_queue.h >>> index b0f7185..25633e0 100644 >>> --- a/platform/linux-generic/include/api/odp_queue.h >>> +++ b/platform/linux-generic/include/api/odp_queue.h >>> @@ -118,7 +118,8 @@ typedef struct odp_queue_param_t { >>> * @param type Queue type >>> * @param param Queue parameters. Uses defaults if NULL. >>> * >>> - * @return Queue handle or ODP_QUEUE_INVALID >>> + * @return Queue handle >>> + * @retval ODP_QUEUE_INVALID on failure >>> */ >>> odp_queue_t odp_queue_create(const char *name, odp_queue_type_t type, >>> odp_queue_param_t *param); >>> @@ -133,7 +134,8 @@ odp_queue_t odp_queue_create(const char *name, >>> odp_queue_type_t type, >>> * >>> * @param queue Queue handle >>> * >>> - * @return 0 if successful >>> + * @retval 0 on success >>> + * @retval <0 on failure >>> */ >>> int odp_queue_destroy(odp_queue_t queue); >>> >>> @@ -142,7 +144,8 @@ int odp_queue_destroy(odp_queue_t queue); >>> * >>> * @param name Queue name >>> * >>> - * @return Queue handle or ODP_QUEUE_INVALID >>> + * @return Queue handle >>> + * @retval ODP_QUEUE_INVALID on failure >>> */ >>> odp_queue_t odp_queue_lookup(const char *name); >>> >>> @@ -156,7 +159,8 @@ odp_queue_t odp_queue_lookup(const char *name); >>> * @param queue Queue handle >>> * @param context Address to the queue context >>> * >>> - * @return 0 if successful >>> + * @retval 0 on success >>> + * @retval <0 on failure >>> */ >>> int odp_queue_set_context(odp_queue_t queue, void *context); >>> >>> @@ -165,8 +169,8 @@ int odp_queue_set_context(odp_queue_t queue, void >>> *context); >>> * >>> * @param queue Queue handle >>> * >>> - * @return If successful, a pointer to the queue context, >>> - * NULL for failure. >>> + * @return pointer to the queue context >>> + * @retval NULL on failure >>> */ >>> void *odp_queue_get_context(odp_queue_t queue); >>> >>> @@ -176,7 +180,8 @@ void *odp_queue_get_context(odp_queue_t queue); >>> * @param queue Queue handle >>> * @param buf Buffer handle >>> * >>> - * @return 0 if succesful >>> + * @retval 0 on success >>> + * @retval <0 on failure >>> */ >>> int odp_queue_enq(odp_queue_t queue, odp_buffer_t buf); >>> >>> @@ -187,7 +192,8 @@ int odp_queue_enq(odp_queue_t queue, odp_buffer_t >>> buf); >>> * @param buf Buffer handles >>> * @param num Number of buffer handles >>> * >>> - * @return 0 if succesful >>> + * @retval 0 on success >>> + * @retval <0 on failure >>> */ >>> int odp_queue_enq_multi(odp_queue_t queue, odp_buffer_t buf[], int num); >>> >>> @@ -199,7 +205,8 @@ int odp_queue_enq_multi(odp_queue_t queue, >>> odp_buffer_t buf[], int num); >>> * >>> * @param queue Queue handle >>> * >>> - * @return Buffer handle, or ODP_BUFFER_INVALID >>> + * @return Buffer handle >>> + * @retval ODP_BUFFER_INVALID on failure >>> */ >>> odp_buffer_t odp_queue_deq(odp_queue_t queue); >>> >>> diff --git a/platform/linux-generic/include/api/odp_schedule.h >>> b/platform/linux-generic/include/api/odp_schedule.h >>> index cdf6705..36fbba3 100644 >>> --- a/platform/linux-generic/include/api/odp_schedule.h >>> +++ b/platform/linux-generic/include/api/odp_schedule.h >>> @@ -59,7 +59,8 @@ uint64_t odp_schedule_wait_time(uint64_t ns); >>> * Use odp_schedule_wait_time() to convert time to other >>> wait >>> * values. >>> * >>> - * @return Next highest priority buffer, or ODP_BUFFER_INVALID >>> + * @return Next highest priority buffer >>> + * @retval ODP_BUFFER_INVALID on timeout >>> */ >>> odp_buffer_t odp_schedule(odp_queue_t *from, uint64_t wait); >>> >>> diff --git a/platform/linux-generic/include/api/odp_shared_memory.h >>> b/platform/linux-generic/include/api/odp_shared_memory.h >>> index f70db5a..78d108a 100644 >>> --- a/platform/linux-generic/include/api/odp_shared_memory.h >>> +++ b/platform/linux-generic/include/api/odp_shared_memory.h >>> @@ -59,7 +59,8 @@ typedef struct odp_shm_info_t { >>> * @param[in] flags Shared memory parameter flags (ODP_SHM_*). >>> * Default value is 0. >>> * >>> - * @return Pointer to the reserved block, or NULL >>> + * @return Handle of the reserved block >>> + * @retval NULL on failure >>> */ >>> odp_shm_t odp_shm_reserve(const char *name, uint64_t size, uint64_t >>> align, >>> uint32_t flags); >>> @@ -72,9 +73,9 @@ odp_shm_t odp_shm_reserve(const char *name, uint64_t >>> size, uint64_t align, >>> * >>> * @param[in] shm Block handle >>> * >>> - * @retval 0 if the handle is already free >>> + * @retval 0 if the handle is already free (FIXME how can we know this?) >> >> >> The linux-generic implementation tracks block allocation status. Good point >> as to whether this should be part of the spec, however. > The above definition puts some more restrictions on the ODP > implementation. It must remember all past shm handles and their > current status. How does this work if shm regions are created and > destroyed repeatedly (an unlikely use case I agree). Possibly there is > a fixed array of shm handles with generation counters for each handle > but this will eventually wrap around and old stale handles become > fresh again. > > Resource cleanup (e.g. for controlled program termination) has to be a > highly synchronized operation anyway, you can't have worker threads > continuing their execution, allocating buffers and timers, interacting > with HW etc. when you are tearing down those resources. > > Specifying undefined behavior is better in my opinion. linux-generic > only has to be changed so that it does not return 0 for an already > freed shm region (because this would be a bad example and we want > linux-generic to be a good example), instead it could call ODP_ABORT. > >> >>> >>> * @retval 0 if the handle free succeeds >>> - * @retval -1 on failure to free the handle >>> + * @retval <0 on failure to free the handle >>> */ >>> int odp_shm_free(odp_shm_t shm); >>> >>> @@ -84,7 +85,7 @@ int odp_shm_free(odp_shm_t shm); >>> * @param[in] name Name of the block >>> * >>> * @return A handle to the block if it is found by name >>> - * @retval #ODP_SHM_INVALID if the block is not found >>> + * @retval ODP_SHM_INVALID on failure >>> */ >>> odp_shm_t odp_shm_lookup(const char *name); >>> >>> @@ -94,7 +95,8 @@ odp_shm_t odp_shm_lookup(const char *name); >>> * >>> * @param[in] shm Block handle >>> * >>> - * @return Memory block address, or NULL on error >>> + * @return Memory block address >>> + * @retval NULL on failure (FIXME: when?) >> >> >> Why the FIXME? NULL is returned if the operation is unable to succeed. > Yes but when can the translation from shm handle to virtual address > fail? Are there any situations where we think this is normal behavior? > Shared memory regions that are not mapped to virtual memory? > > Passing invalid shm handles cause undefined behavior, not well-defined failures. > So I am questioning why we need a @retval NULL for this function. > > >> >>> >>> */ >>> void *odp_shm_addr(odp_shm_t shm); >>> >>> @@ -105,7 +107,8 @@ void *odp_shm_addr(odp_shm_t shm); >>> * @param[in] shm Block handle >>> * @param[out] info Block info pointer for output >>> * >>> - * @return 0 on success, otherwise non-zero >>> + * @retval 0 on success >>> + * @retval <0 on failure >>> */ >>> int odp_shm_info(odp_shm_t shm, odp_shm_info_t *info); >>> >>> diff --git a/platform/linux-generic/include/api/odp_timer.h >>> b/platform/linux-generic/include/api/odp_timer.h >>> index 69402ef..c8c3270 100644 >>> --- a/platform/linux-generic/include/api/odp_timer.h >>> +++ b/platform/linux-generic/include/api/odp_timer.h >>> @@ -112,8 +112,8 @@ typedef struct { >>> * @param name Name of the timer pool. The string will be copied. >>> * @param params Timer pool parameters. The content will be copied. >>> * >>> - * @return Timer pool handle if successful, otherwise >>> ODP_TIMER_POOL_INVALID >>> - * and errno set >>> + * @return Timer pool handle on success >>> + * @retval ODP_TIMER_POOL_INVALID on failure and errno set >>> */ >>> odp_timer_pool_t >>> odp_timer_pool_create(const char *name, >>> @@ -185,8 +185,8 @@ typedef struct { >>> * @param tpid Timer pool identifier >>> * @param[out] info Pointer to information buffer >>> * >>> - * @retval 0 Success >>> - * @retval -1 Failure. Info could not be retrieved. >>> + * @retval 0 on success >>> + * @retval <0 on failure. Info could not be retrieved. >>> */ >>> int odp_timer_pool_info(odp_timer_pool_t tpid, >>> odp_timer_pool_info_t *info); >>> @@ -202,8 +202,8 @@ int odp_timer_pool_info(odp_timer_pool_t tpid, >>> * @param queue Destination queue for timeout notifications >>> * @param user_ptr User defined pointer or NULL to be copied to timeouts >>> * >>> - * @return Timer handle if successful, otherwise ODP_TIMER_INVALID and >>> - * errno set. >>> + * @return Timer handle on success >>> + * @retval ODP_TIMER_INVALID on failure and errno set. >>> */ >>> odp_timer_t odp_timer_alloc(odp_timer_pool_t tpid, >>> odp_queue_t queue, >>> @@ -218,7 +218,8 @@ odp_timer_t odp_timer_alloc(odp_timer_pool_t tpid, >>> * responsibility of the application to handle this timeout when it is >>> received. >>> * >>> * @param tim Timer handle >>> - * @return Buffer handle of timeout buffer or ODP_BUFFER_INVALID >>> + * @return Buffer handle of timeout buffer >>> + * @retval ODP_BUFFER_INVALID on failure >>> */ >>> odp_buffer_t odp_timer_free(odp_timer_t tim); >>> >>> @@ -292,8 +293,8 @@ int odp_timer_set_rel(odp_timer_t tim, >>> * >>> * @param tim Timer >>> * @param[out] tmo_buf Pointer to a buffer variable >>> - * @retval 0 Success, active timer cancelled, timeout returned in >>> '*tmo_buf' >>> - * @retval -1 Failure, timer already expired (or inactive) >>> + * @retval 0 on success, active timer cancelled, timeout returned in >>> '*tmo_buf' >>> + * @retval <0 on failure, timer already expired (or inactive) >>> */ >>> int odp_timer_cancel(odp_timer_t tim, odp_buffer_t *tmo_buf); >>> >>> diff --git a/platform/linux-generic/odp_crypto.c >>> b/platform/linux-generic/odp_crypto.c >>> index 2f95cbe..ded3b62 100644 >>> --- a/platform/linux-generic/odp_crypto.c >>> +++ b/platform/linux-generic/odp_crypto.c >>> @@ -343,7 +343,7 @@ odp_crypto_session_create(odp_crypto_session_params_t >>> *params, >>> >>> int >>> odp_crypto_operation(odp_crypto_op_params_t *params, >>> - bool *posted, >>> + odp_bool_t *posted, >>> odp_buffer_t completion_event) >>> { >>> enum crypto_alg_err rc_cipher = ODP_CRYPTO_ALG_ERR_NONE; >>> @@ -423,7 +423,7 @@ odp_crypto_init_global(void) >>> } >>> >>> int >>> -odp_hw_random_get(uint8_t *buf, size_t *len, bool use_entropy ODP_UNUSED) >>> +odp_hw_random_get(uint8_t *buf, size_t *len, odp_bool_t use_entropy >>> ODP_UNUSED) >>> { >>> int rc; >>> rc = RAND_bytes(buf, *len); >>> diff --git a/platform/linux-generic/odp_packet_io.c >>> b/platform/linux-generic/odp_packet_io.c >>> index 0efa3d0..c51098f 100644 >>> --- a/platform/linux-generic/odp_packet_io.c >>> +++ b/platform/linux-generic/odp_packet_io.c >>> @@ -797,18 +797,18 @@ int odp_pktio_promisc_mode(odp_pktio_t id) >>> } >>> >>> >>> -size_t odp_pktio_mac_addr(odp_pktio_t id, void *mac_addr, >>> +int odp_pktio_mac_addr(odp_pktio_t id, void *mac_addr, >>> size_t addr_size) >>> { >>> pktio_entry_t *entry; >>> >>> if (addr_size < ETH_ALEN) >>> - return 0; >>> + return -1; >>> >>> entry = get_pktio_entry(id); >>> if (entry == NULL) { >>> ODP_DBG("pktio entry %d does not exist\n", id); >>> - return 0; >>> + return -1; >>> } >>> >>> lock_entry(entry); >>> diff --git a/test/validation/crypto/odp_crypto_test_async_inp.c >>> b/test/validation/crypto/odp_crypto_test_async_inp.c >>> index 96d4c3f..1db7844 100644 >>> --- a/test/validation/crypto/odp_crypto_test_async_inp.c >>> +++ b/test/validation/crypto/odp_crypto_test_async_inp.c >>> @@ -34,7 +34,7 @@ static void alg_test(enum odp_crypto_op op, >>> odp_crypto_session_t session; >>> int rc; >>> enum odp_crypto_ses_create_err status; >>> - bool posted; >>> + odp_bool_t posted; >>> odp_buffer_t compl_event; >>> >>> odp_queue_t compl_queue = odp_queue_lookup("crypto-out"); >>> diff --git a/test/validation/crypto/odp_crypto_test_sync_inp.c >>> b/test/validation/crypto/odp_crypto_test_sync_inp.c >>> index f37ad54..5082f13 100644 >>> --- a/test/validation/crypto/odp_crypto_test_sync_inp.c >>> +++ b/test/validation/crypto/odp_crypto_test_sync_inp.c >>> @@ -23,7 +23,7 @@ static void alg_test(enum odp_crypto_op op, >>> odp_crypto_session_t session; >>> int rc; >>> enum odp_crypto_ses_create_err status; >>> - bool posted; >>> + odp_bool_t posted; >>> >>> odp_queue_t compl_queue = odp_queue_lookup("crypto-out"); >>> CU_ASSERT(compl_queue != ODP_QUEUE_INVALID); >>> -- >>> 1.9.1 >>> >>> >>> _______________________________________________ >>> lng-odp mailing list >>> lng-odp@lists.linaro.org >>> http://lists.linaro.org/mailman/listinfo/lng-odp >> >>
I think it's good practice for functions to be robust in parameter handling unless they are expected to be used in performance paths. That's the reason why we've said that things like odp_buffer_addr() etc. have undefined behavior if they're passed invalid handles. But shm and pools are things that will typically get set up once during init, and seldom changed (maybe as part of reconfig) so the performance argument is less compelling there. On Tue, Jan 27, 2015 at 4:54 AM, Ola Liljedahl <ola.liljedahl@linaro.org> wrote: > As a general rule, all functions that return information about e.g. > shared memory areas, buffer/event pools and timer pools should be > robust in the presence of invalid parameters (handles). The reason is > that you might want to implement a form of post-mortem dump which > examines all ODP objects and saves the information in some dump area > and you don't want this post-mortem dump function to crash. The system > is already in a bad state (that's why we need a dump so we can debug > it) and not all data can be trusted. > Buffers/events are special, we have a special function for checking > the validity of such handles so that all other (performance critical) > buffer/event operations can expect the handle to be valid and avoid > any checks. > > > > On 27 January 2015 at 11:43, Ola Liljedahl <ola.liljedahl@linaro.org> > wrote: > > On 27 January 2015 at 02:14, Bill Fischofer <bill.fischofer@linaro.org> > wrote: > >> This looks good. It will need to be rebased following the event patch > merge > >> (all merges currently blocked until that happens). See additional > comments > >> inline: > > I'll rebase as necessary and post updated patches. > > > >> > >> On Mon, Jan 26, 2015 at 6:20 PM, Ola Liljedahl < > ola.liljedahl@linaro.org> > >> wrote: > >>> > >>> Unify @return and @retval descriptions. > >>> @return used for values that cannot (meaningfully) be enumerated (e.g > >>> pointers, > >>> ODP handles) or simply tested for correctness. > >>> @retval used for values that can be enumerated and should be tested by > >>> validation programs. > >>> Changed from bool to odp_bool_t in odp_crypto.h and dependent source > >>> files. > >>> Changed return type and value of odp_pktio_mac_addr() to match other > >>> similar > >>> functions. Use int as return type, <0 to indicate failure. > >>> > >>> Signed-off-by: Ola Liljedahl <ola.liljedahl@linaro.org> > >>> --- > >>> (This document/code contribution attached is provided under the terms > of > >>> agreement LES-LTM-21309) > >>> > >>> example/ipsec/odp_ipsec.c | 4 +- > >>> platform/linux-generic/include/api/odp_buffer.h | 9 ++- > >>> .../linux-generic/include/api/odp_buffer_pool.h | 21 ++++--- > >>> platform/linux-generic/include/api/odp_byteorder.h | 2 +- > >>> .../linux-generic/include/api/odp_classification.h | 48 > +++++++++------- > >>> platform/linux-generic/include/api/odp_cpumask.h | 12 ++-- > >>> platform/linux-generic/include/api/odp_crypto.h | 15 +++-- > >>> platform/linux-generic/include/api/odp_init.h | 10 ++-- > >>> platform/linux-generic/include/api/odp_packet.h | 66 > >>> ++++++++++++---------- > >>> .../linux-generic/include/api/odp_packet_flags.h | 57 > >>> ++++++++++++------- > >>> platform/linux-generic/include/api/odp_packet_io.h | 54 > >>> +++++++++++------- > >>> platform/linux-generic/include/api/odp_queue.h | 25 +++++--- > >>> platform/linux-generic/include/api/odp_schedule.h | 3 +- > >>> .../linux-generic/include/api/odp_shared_memory.h | 15 +++-- > >>> platform/linux-generic/include/api/odp_timer.h | 19 ++++--- > >>> platform/linux-generic/odp_crypto.c | 4 +- > >>> platform/linux-generic/odp_packet_io.c | 6 +- > >>> test/validation/crypto/odp_crypto_test_async_inp.c | 2 +- > >>> test/validation/crypto/odp_crypto_test_sync_inp.c | 2 +- > >>> 19 files changed, 226 insertions(+), 148 deletions(-) > >>> > >>> diff --git a/example/ipsec/odp_ipsec.c b/example/ipsec/odp_ipsec.c > >>> index f2fac8a..066dc40 100644 > >>> --- a/example/ipsec/odp_ipsec.c > >>> +++ b/example/ipsec/odp_ipsec.c > >>> @@ -683,7 +683,7 @@ pkt_disposition_e do_ipsec_in_classify(odp_packet_t > >>> pkt, > >>> odph_esphdr_t *esp = NULL; > >>> ipsec_cache_entry_t *entry; > >>> odp_crypto_op_params_t params; > >>> - bool posted = 0; > >>> + odp_bool_t posted = 0; > >>> > >>> /* Default to skip IPsec */ > >>> *skip = TRUE; > >>> @@ -955,7 +955,7 @@ pkt_disposition_e do_ipsec_out_seq(odp_packet_t > pkt, > >>> pkt_ctx_t *ctx) > >>> { > >>> uint8_t *buf = odp_packet_data(pkt); > >>> - bool posted = 0; > >>> + odp_bool_t posted = 0; > >>> > >>> /* We were dispatched from atomic queue, assign sequence > numbers > >>> */ > >>> if (ctx->ipsec.ah_offset) { > >>> diff --git a/platform/linux-generic/include/api/odp_buffer.h > >>> b/platform/linux-generic/include/api/odp_buffer.h > >>> index 0670464..fd0871b 100644 > >>> --- a/platform/linux-generic/include/api/odp_buffer.h > >>> +++ b/platform/linux-generic/include/api/odp_buffer.h > >>> @@ -32,6 +32,7 @@ extern "C" { > >>> * Buffer start address > >>> * > >>> * @param buf Buffer handle > >>> + * Note: Buffer handle must be valid or the behavior will be > undefined. > >> > >> > >> Should these be @note ? Same comment for similar Note: adds. > > Yes should use @note. > > > >> Phrasing in > >> present tense (...or behavior is undefined) seems more natural, but > that's a > >> stylistic point that's I won't argue. > > You are probably better at English than I am... I am following your > > suggestion without argument. > > > > The language is a bit mixed with these undefined warnings. > > > > One problem I see is that if we make a @note for undefined behavior > > for each function, we need to make that note for *all* relevant > > functions. The omission of this note for some functions could indicate > > that undefined behavior is not present (even in the presence of > > invalid parameters). But I also think a global definition and > > documentation of undefined behavior in the ODP documentation might not > > be sufficient. Most programmers will go straight at the documentation > > of individual functions they want to use. > > > > > >> > >>> > >>> * > >>> * @return Buffer start address > >>> */ > >>> @@ -41,6 +42,7 @@ void *odp_buffer_addr(odp_buffer_t buf); > >>> * Buffer maximum data size > >>> * > >>> * @param buf Buffer handle > >>> + * Note: Buffer handle must be valid or the behavior will be > undefined. > >>> * > >>> * @return Buffer maximum data size > >>> */ > >>> @@ -50,12 +52,12 @@ uint32_t odp_buffer_size(odp_buffer_t buf); > >>> * Buffer type > >>> * > >>> * @param buf Buffer handle > >>> + * Note: Buffer handle must be valid or the behavior will be > undefined. > >>> * > >>> * @return Buffer type > >>> */ > >>> int odp_buffer_type(odp_buffer_t buf); > >>> > >>> -#define ODP_BUFFER_TYPE_INVALID (-1) /**< Buffer type invalid */ > >>> #define ODP_BUFFER_TYPE_ANY 0 /**< Buffer that can hold any > other > >>> buffer type */ > >>> #define ODP_BUFFER_TYPE_RAW 1 /**< Raw buffer, no additional > >>> metadata */ > >>> @@ -65,7 +67,9 @@ int odp_buffer_type(odp_buffer_t buf); > >>> /** > >>> * Tests if buffer is valid > >>> * > >>> - * @param buf Buffer handle > >>> + * @param buf Buffer handle (possibly invalid) > >>> + * Note: This is the only call which accepts invalid buffer handles > (any > >>> bit > >>> + * value) without causing undefined behavior. > >> > >> > >> Definitely should be @note for this one. Would it be clearer to say > "API" > >> rather than "call"? Grammar nit: that rather than which is correct here. > > Well this is just one function, the whole set of functions is an API. > > Or is my definition of API too narrow? > > Maybe "this API function"? > > > >> > >>> > >>> * > >>> * @retval 1 Buffer handle represents a valid buffer. > >>> * @retval 0 Buffer handle does not represent a valid buffer. > >>> @@ -76,6 +80,7 @@ int odp_buffer_is_valid(odp_buffer_t buf); > >>> * Buffer pool of the buffer > >>> * > >>> * @param buf Buffer handle > >>> + * Note: Buffer handle must be valid or the behavior will be > undefined. > >>> * > >>> * @return Handle of buffer pool buffer belongs to > >>> */ > >>> diff --git a/platform/linux-generic/include/api/odp_buffer_pool.h > >>> b/platform/linux-generic/include/api/odp_buffer_pool.h > >>> index 8380ac1..fe917a4 100644 > >>> --- a/platform/linux-generic/include/api/odp_buffer_pool.h > >>> +++ b/platform/linux-generic/include/api/odp_buffer_pool.h > >>> @@ -81,8 +81,8 @@ odp_buffer_pool_t odp_buffer_pool_create(const char > >>> *name, > >>> * > >>> * @param pool Handle of the buffer pool to be destroyed > >>> * > >>> - * @retval 0 Success > >>> - * @retval -1 Failure > >>> + * @retval 0 if successful > >>> + * @retval <0 on failure > >>> * > >>> * @note This routine destroys a previously created buffer pool. This > >>> call > >>> * does not destroy any shared memory object passed to > >>> @@ -117,7 +117,7 @@ typedef struct odp_buffer_pool_info_t { > >>> odp_shm_t shm; /**< handle of shared memory > >>> area > >>> supplied by application to > >>> contain buffer pool, or > >>> - ODP_SHM_INVALID if this > pool > >>> is > >>> + ODP_SHM_NULL if this pool > is > >>> managed by ODP */ > >>> odp_buffer_pool_param_t params; /**< pool parameters */ > >>> } odp_buffer_pool_info_t; > >>> @@ -125,13 +125,13 @@ typedef struct odp_buffer_pool_info_t { > >>> /** > >>> * Retrieve information about a buffer pool > >>> * > >>> - * @param pool Buffer pool handle > >>> + * @param pool Buffer pool handle (possibly invalid) > >>> * > >>> * @param[out] info Receives an odp_buffer_pool_info_t object > >>> * that describes the pool. > >>> * > >>> - * @retval 0 Success > >>> - * @retval -1 Failure. Info could not be retrieved. > >>> + * @retval 0 if successful > >>> + * @retval <0 on failure. Info could not be retrieved (invalid pool > >>> handle) > >>> */ > >>> > >>> int odp_buffer_pool_info(odp_buffer_pool_t pool, > >>> @@ -149,17 +149,22 @@ void odp_buffer_pool_print(odp_buffer_pool_t > pool); > >>> > >>> /** > >>> * Buffer alloc > >>> + * Note: the pool handle must be valid or the behavior is undefined. > >>> + * > >>> + * The validity of a buffer handle can be checked at any time using > >>> + * odp_buffer_is_valid() > >>> * > >>> - * The validity of a buffer can be cheked at any time with > >>> odp_buffer_is_valid() > >>> * @param pool Pool handle > >>> * > >>> * @return Handle of allocated buffer > >>> - * @retval ODP_BUFFER_INVALID Buffer could not be allocated > >>> + * @retval ODP_BUFFER_INVALID Buffer could not be allocated (e.g. > pool > >>> + * exhausted) > >>> */ > >>> odp_buffer_t odp_buffer_alloc(odp_buffer_pool_t pool); > >>> > >>> /** > >>> * Buffer free > >>> + * Note: the buffer handle must be valid or the behavior is undefined. > >>> * > >>> * @param buf Buffer handle > >>> * > >>> diff --git a/platform/linux-generic/include/api/odp_byteorder.h > >>> b/platform/linux-generic/include/api/odp_byteorder.h > >>> index 5890011..8e38937 100644 > >>> --- a/platform/linux-generic/include/api/odp_byteorder.h > >>> +++ b/platform/linux-generic/include/api/odp_byteorder.h > >>> @@ -24,7 +24,7 @@ extern "C" { > >>> #include <odp_compiler.h> > >>> > >>> /** @defgroup odp_compiler_optim ODP COMPILER / OPTIMIZATION > >>> - * Macros that check byte order and byte converting operations. > >>> + * Macros that check and convert byte order. > >>> * @{ > >>> */ > >>> > >>> diff --git a/platform/linux-generic/include/api/odp_classification.h > >>> b/platform/linux-generic/include/api/odp_classification.h > >>> index 46189bc..6bca8fc 100644 > >>> --- a/platform/linux-generic/include/api/odp_classification.h > >>> +++ b/platform/linux-generic/include/api/odp_classification.h > >>> @@ -79,8 +79,8 @@ typedef enum odp_cos_hdr_flow_fields { > >>> * > >>> * @param[in] name String intended for debugging purposes. > >>> * > >>> - * @return Class of service instance identifier, > >>> - * or ODP_COS_INVALID on error. > >>> + * @return Class of service instance identifier > >>> + * @retval ODP_COS_INVALID on failure. > >>> */ > >>> odp_cos_t odp_cos_create(const char *name); > >>> > >>> @@ -89,7 +89,8 @@ odp_cos_t odp_cos_create(const char *name); > >>> * > >>> * @param[in] cos_id class-of-service instance. > >>> * > >>> - * @return 0 on success, non-zero on error. > >>> + * @retval 0 if successful > >>> + * @retval <0 on failure > >>> */ > >>> int odp_cos_destroy(odp_cos_t cos_id); > >>> > >>> @@ -102,7 +103,8 @@ int odp_cos_destroy(odp_cos_t cos_id); > >>> * of this specific class of service > >>> * will be enqueued. > >>> * > >>> - * @return 0 on success, non-zero on error. > >>> + * @retval 0 if successful > >>> + * @retval <0 on failure > >>> */ > >>> int odp_cos_set_queue(odp_cos_t cos_id, odp_queue_t queue_id); > >>> > >>> @@ -112,7 +114,8 @@ int odp_cos_set_queue(odp_cos_t cos_id, odp_queue_t > >>> queue_id); > >>> * @param[in] cos_id class-of-service instance. > >>> * @param[in] drop_policy Desired packet drop policy for this > class. > >>> * > >>> - * @return 0 on success, non-zero on error. > >>> + * @retval 0 if successful > >>> + * @retval <0 on failure > >>> * > >>> * @note Optional. > >>> */ > >>> @@ -127,7 +130,8 @@ int odp_cos_set_drop(odp_cos_t cos_id, odp_drop_e > >>> drop_policy); > >>> * @param[in] qos_table Values of the Layer-2 QoS header field. > >>> * @param[in] cos_table Class-of-service assigned to each of > the > >>> * allowed Layer-2 QOS levels. > >>> - * @return 0 on success, non-zero on error. > >>> + * @retval 0 if successful > >>> + * @retval <0 on failure > >>> */ > >>> int odp_cos_with_l2_priority(odp_pktio_t pktio_in, > >>> uint8_t num_qos, > >>> @@ -146,7 +150,8 @@ int odp_cos_with_l2_priority(odp_pktio_t pktio_in, > >>> * @param[in] l3_preference when true, Layer-3 QoS overrides > >>> * L2 QoS when present. > >>> * > >>> - * @return 0 on success, non-zero on error. > >>> + * @retval 0 if successful > >>> + * @retval <0 on failure > >>> * > >>> * @note Optional. > >>> */ > >>> @@ -219,7 +224,8 @@ typedef enum odp_pmr_term { > >>> * that must match the value size requirement of > the > >>> * specific term. > >>> * > >>> - * @return Handle of the matching rule or ODP_PMR_INVAL on > >>> error > >>> + * @return Handle of the matching rule > >>> + * @retval ODP_PMR_INVAL on failure > >>> */ > >>> odp_pmr_t odp_pmr_create_match(odp_pmr_term_e term, > >>> const void *val, > >>> @@ -236,7 +242,8 @@ odp_pmr_t odp_pmr_create_match(odp_pmr_term_e term, > >>> * that must match the value size requirement of > the > >>> * specific term. > >>> * > >>> - * @return Handle of the matching rule or ODP_PMR_INVAL on > >>> error > >>> + * @return Handle of the matching rule > >>> + * @retval ODP_PMR_INVAL on failure > >>> * @note: Range is inclusive [val1..val2]. > >>> */ > >>> odp_pmr_t odp_pmr_create_range(odp_pmr_term_e term, > >>> @@ -248,7 +255,8 @@ odp_pmr_t odp_pmr_create_range(odp_pmr_term_e term, > >>> * > >>> * @param[in] pmr_id Identifier of the PMR to be destroyed > >>> * > >>> - * @return 0 on success, non-zero or error. > >>> + * @retval 0 if successful > >>> + * @retval <0 on failure > >>> */ > >>> int odp_pmr_destroy(odp_pmr_t pmr_id); > >>> > >>> @@ -259,7 +267,8 @@ int odp_pmr_destroy(odp_pmr_t pmr_id); > >>> * @param[in] src_pktio pktio to which this PMR is to be > applied > >>> * @param[in] dst_cos CoS to be assigned by this PMR > >>> * > >>> - * @return 0 on success, non-zero or error. > >>> + * @retval 0 if successful > >>> + * @retval <0 on failure > >>> */ > >>> int odp_pktio_pmr_cos(odp_pmr_t pmr_id, > >>> odp_pktio_t src_pktio, odp_cos_t dst_cos); > >>> @@ -272,7 +281,8 @@ int odp_pktio_pmr_cos(odp_pmr_t pmr_id, > >>> * @param[in] dst_cos CoS to be assigned to packets filtered > >>> * from src_cos that match pmr_id. > >>> * > >>> - * @return 0 on success, non-zero on error. > >>> + * @retval 0 if successful > >>> + * @retval <0 on failure > >>> */ > >>> int odp_cos_pmr_cos(odp_pmr_t pmr_id, odp_cos_t src_cos, odp_cos_t > >>> dst_cos); > >>> > >>> @@ -346,12 +356,10 @@ typedef uint32_t odp_pmr_set_t; > >>> * term desired. > >>> * @param[out] pmr_set_id Returned handle to the composite rule > set. > >>> * > >>> - * @return Return value may be a positive number > >>> - * indicating the number of terms elements > >>> + * @return the number of terms elements > >>> * that have been successfully mapped to > the > >>> - * underlying platform classification > engine > >>> and > >>> - * may be in the range from 1 to > num_terms, > >>> - * or non-zero for error. > >>> + * underlying platform classification > engine > >>> + * @retval <0 on failure > >>> */ > >>> int odp_pmr_match_set_create(int num_terms, odp_pmr_match_t *terms, > >>> odp_pmr_set_t *pmr_set_id); > >>> @@ -369,7 +377,8 @@ int odp_pmr_match_set_create(int num_terms, > >>> odp_pmr_match_t *terms, > >>> * @param[in] pmr_set_id A composite rule-set handle > >>> * returned when created. > >>> * > >>> - * @return 0 on success, non-zero on error. > >>> + * @retval 0 if successful > >>> + * @retval <0 on failure > >>> */ > >>> int odp_pmr_match_set_destroy(odp_pmr_set_t pmr_set_id); > >>> > >>> @@ -381,7 +390,8 @@ int odp_pmr_match_set_destroy(odp_pmr_set_t > >>> pmr_set_id); > >>> * set is to be applied > >>> * @param[in] dst_cos CoS to be assigned by this PMR match > set > >>> * > >>> - * @return 0 on success, non-zero or error. > >>> + * @retval 0 if successful > >>> + * @retval <0 on failure > >>> */ > >>> int odp_pktio_pmr_match_set_cos(odp_pmr_set_t pmr_set_id, odp_pktio_t > >>> src_pktio, > >>> odp_cos_t dst_cos); > >>> diff --git a/platform/linux-generic/include/api/odp_cpumask.h > >>> b/platform/linux-generic/include/api/odp_cpumask.h > >>> index ebff9b0..5c5bcd7 100644 > >>> --- a/platform/linux-generic/include/api/odp_cpumask.h > >>> +++ b/platform/linux-generic/include/api/odp_cpumask.h > >>> @@ -79,7 +79,8 @@ void odp_cpumask_clr(odp_cpumask_t *mask, int cpu); > >>> * Test if cpu is a member of mask > >>> * @param mask CPU mask to check if cpu num set or not > >>> * @param cpu CPU number > >>> - * @return non-zero if set otherwise 0 > >>> + * @return non-zero if set > >>> + * @retval 0 if not set > >>> */ > >>> int odp_cpumask_isset(const odp_cpumask_t *mask, int cpu); > >>> > >>> @@ -134,14 +135,16 @@ void odp_cpumask_copy(odp_cpumask_t *dest, const > >>> odp_cpumask_t *src); > >>> /** > >>> * Find first bit set in mask > >>> * > >>> - * @return cpu else -1 if no bits set in cpumask > >>> + * @return cpu > >>> + * @retval -1 if no bits set in cpumask > >> > >> > >> Should this be <0 for consistency with other error RC descriptions? > > Possibly. I was a little loath at changing the definitions of these > > basically bit set operations (where return values might be the direct > > results of binary/arithmetic operations) but this one could be unified > > with the rest without any problems. It was also getting rather late in > > the evening, I was probably not thinking too clearly at the end. > > I changed all three remaining instances in this file. > > > >> > >>> > >>> */ > >>> int odp_cpumask_first(const odp_cpumask_t *mask); > >>> > >>> /** > >>> * Find last bit set in mask > >>> * > >>> - * @return cpu else -1 if no bits set in cpumask > >>> + * @return cpu > >>> + * @retval -1 if no bits set in cpumask > >> > >> > >> Same here. <0 ? > > yes > > > >> > >>> > >>> */ > >>> int odp_cpumask_last(const odp_cpumask_t *mask); > >>> > >>> @@ -160,7 +163,8 @@ int odp_cpumask_last(const odp_cpumask_t *mask); > >>> * > >>> * @param mask CPU mask to find next cpu in > >>> * @param cpu CPU to start from > >>> - * @return cpu found else -1 > >>> + * @return cpu found > >>> + * @retval -1 if not found > >> > >> > >> And again here. > > yes > > > >> > >>> > >>> * > >>> * @see odp_cpumask_first() > >>> */ > >>> diff --git a/platform/linux-generic/include/api/odp_crypto.h > >>> b/platform/linux-generic/include/api/odp_crypto.h > >>> index 337e7cf..2f00f95 100644 > >>> --- a/platform/linux-generic/include/api/odp_crypto.h > >>> +++ b/platform/linux-generic/include/api/odp_crypto.h > >>> @@ -218,7 +218,8 @@ typedef struct odp_crypto_compl_status { > >>> * @param session Created session else > >>> ODP_CRYPTO_SESSION_INVALID > >>> * @param status Failure code if unsuccessful > >>> * > >>> - * @return 0 if successful else -1 > >>> + * @retval 0 if successful > >>> + * @retval <0 on failure > >>> */ > >>> int > >>> odp_crypto_session_create(odp_crypto_session_params_t *params, > >>> @@ -242,11 +243,12 @@ > >>> odp_crypto_session_create(odp_crypto_session_params_t *params, > >>> * @param posted Pointer to return posted, TRUE for async > >>> operation > >>> * @param completion_event Event by which the operation results are > >>> delivered. > >>> * > >>> - * @return 0 if successful else -1 > >>> + * @retval 0 if successful > >>> + * @retval <0 on failure > >>> */ > >>> int > >>> odp_crypto_operation(odp_crypto_op_params_t *params, > >>> - bool *posted, > >>> + odp_bool_t *posted, > >>> odp_buffer_t completion_event); > >>> > >>> /** > >>> @@ -281,7 +283,7 @@ odp_crypto_get_operation_compl_status(odp_buffer_t > >>> completion_event, > >>> * > >>> * @param completion_event Event containing operation results > >>> * > >>> - * @return Packet structure where data now resides > >>> + * @return Handle for packet where data now resides > >>> */ > >>> odp_packet_t > >>> odp_crypto_get_operation_compl_packet(odp_buffer_t completion_event); > >>> @@ -305,10 +307,11 @@ odp_crypto_get_operation_compl_ctx(odp_buffer_t > >>> completion_event); > >>> * > >>> * @todo Define the implication of the use_entropy parameter > >>> * > >>> - * @return 0 if succesful > >>> + * @retval 0 if successful > >>> + * @retval <0 on failure > >>> */ > >>> int > >>> -odp_hw_random_get(uint8_t *buf, size_t *len, bool use_entropy); > >>> +odp_hw_random_get(uint8_t *buf, size_t *len, odp_bool_t use_entropy); > >>> > >>> /** > >>> * @} > >>> diff --git a/platform/linux-generic/include/api/odp_init.h > >>> b/platform/linux-generic/include/api/odp_init.h > >>> index ac856df..4a98717 100644 > >>> --- a/platform/linux-generic/include/api/odp_init.h > >>> +++ b/platform/linux-generic/include/api/odp_init.h > >>> @@ -66,8 +66,8 @@ typedef enum odp_log_level { > >>> * @param[in] level Log level > >>> * @param[in] fmt printf-style message format > >>> * > >>> - * @return The number of characters logged if succeeded. Otherwise > >>> returns > >>> - * a negative number. > >>> + * @return The number of characters logged if successful > >>> + * @retval <0 on failure > >>> */ > >>> int odp_override_log(odp_log_level_e level, const char *fmt, ...); > >>> > >>> @@ -109,7 +109,7 @@ typedef struct odp_platform_init_t { > >>> * interpretation by the ODP API to the implementation. > >>> * > >>> * @retval 0 if successful > >>> - * @retval -1 on failure > >>> + * @retval <0 on failure > >>> */ > >>> int odp_init_global(odp_init_t *params, odp_platform_init_t > >>> *platform_params); > >>> > >>> @@ -134,7 +134,7 @@ int odp_init_global(odp_init_t *params, > >>> odp_platform_init_t *platform_params); > >>> * @sa odp_term_local() which must have been called prior to this. > >>> * > >>> * @retval 0 if successful > >>> - * @retval -1 on failure > >>> + * @retval <0 on failure > >>> */ > >>> int odp_term_global(void); > >>> > >>> @@ -148,7 +148,7 @@ int odp_term_global(void); > >>> * @sa odp_init_global() which must have been called prior to this. > >>> * > >>> * @retval 0 if successful > >>> - * @retval -1 on failure > >>> + * @retval <0 on failure > >>> */ > >>> int odp_init_local(void); > >>> > >>> diff --git a/platform/linux-generic/include/api/odp_packet.h > >>> b/platform/linux-generic/include/api/odp_packet.h > >>> index 920a593..b471d07 100644 > >>> --- a/platform/linux-generic/include/api/odp_packet.h > >>> +++ b/platform/linux-generic/include/api/odp_packet.h > >>> @@ -88,8 +88,8 @@ void odp_packet_free(odp_packet_t pkt); > >>> * @param pkt Packet handle > >>> * @param len Packet data length > >>> * > >>> - * @retval 0 Success > >>> - * @retval Non-zero Failure > >>> + * @retval 0 if successful > >>> + * @retval <0 on failure > >>> * > >>> * @see odp_packet_buf_len() > >>> */ > >>> @@ -279,7 +279,7 @@ void *odp_packet_push_head(odp_packet_t pkt, > uint32_t > >>> len); > >>> * @param pkt Packet handle > >>> * @param len Number of bytes to pull the head (0 ... seg_len - 1) > >>> * > >>> - * @return The new data pointer, or NULL in case of an error. > >>> + * @return The new data pointer > >>> * @retval NULL Requested offset exceeds packet segment length > >>> > >>> * > >>> * @see odp_packet_seg_len(), odp_packet_push_head() > >>> @@ -391,7 +391,7 @@ odp_buffer_pool_t odp_packet_pool(odp_packet_t > pkt); > >>> * @param pkt Packet handle > >>> * > >>> * @return Packet interface handle > >>> - * @retval ODP_PKTIO_INVALID Packet was not received > >>> + * @retval ODP_PKTIO_INVALID Packet was not received on any interface > >>> */ > >>> odp_pktio_t odp_packet_input(odp_packet_t pkt); > >>> > >>> @@ -451,8 +451,8 @@ void odp_packet_user_u64_set(odp_packet_t pkt, > >>> uint64_t ctx); > >>> * @param[out] len Number of data bytes remaining in the segment > >>> (output). > >>> * Ignored when NULL. > >>> * > >>> - * @return Layer 2 start pointer, or NULL when packet does not > contain a > >>> valid > >>> - * L2 header. > >>> + * @return Layer 2 start pointer > >>> + * @retval NULL packet does not contain a valid L2 header > >>> * > >>> * @see odp_packet_l2_offset(), odp_packet_l2_offset_set(), > >>> odp_packet_has_l2() > >>> */ > >>> @@ -469,8 +469,8 @@ void *odp_packet_l2_ptr(odp_packet_t pkt, uint32_t > >>> *len); > >>> * > >>> * @param pkt Packet handle > >>> * > >>> - * @return Layer 2 start offset, or ODP_PACKET_OFFSET_INVALID when > >>> packet does > >>> - * not contain a valid L2 header. > >>> + * @return Layer 2 start offset > >>> + * @retval ODP_PACKET_OFFSET_INVALID packet does not contain a valid > L2 > >>> header > >>> * > >>> * @see odp_packet_l2_offset_set(), odp_packet_has_l2() > >>> */ > >>> @@ -486,8 +486,8 @@ uint32_t odp_packet_l2_offset(odp_packet_t pkt); > >>> * @param pkt Packet handle > >>> * @param offset Layer 2 start offset (0 ... odp_packet_len()-1) > >>> * > >>> - * @retval 0 Success > >>> - * @retval Non-zero Failure > >>> + * @retval 0 if successful > >>> + * @retval <0 on failure > >>> */ > >>> int odp_packet_l2_offset_set(odp_packet_t pkt, uint32_t offset); > >>> > >>> @@ -501,8 +501,8 @@ int odp_packet_l2_offset_set(odp_packet_t pkt, > >>> uint32_t offset); > >>> * @param[out] len Number of data bytes remaining in the segment > >>> (output). > >>> * Ignored when NULL. > >>> * > >>> - * @return Layer 3 start pointer, or NULL when packet does not > contain a > >>> valid > >>> - * L3 header. > >>> + * @return Layer 3 start pointer > >>> + * @retval NULL packet does not contain a valid L3 header > >>> * > >>> * @see odp_packet_l3_offset(), odp_packet_l3_offset_set(), > >>> odp_packet_has_l3() > >>> */ > >>> @@ -536,8 +536,8 @@ uint32_t odp_packet_l3_offset(odp_packet_t pkt); > >>> * @param pkt Packet handle > >>> * @param offset Layer 3 start offset (0 ... odp_packet_len()-1) > >>> * > >>> - * @retval 0 Success > >>> - * @retval Non-zero Failure > >>> + * @retval 0 if successful > >>> + * @retval <0 on failure > >>> */ > >>> int odp_packet_l3_offset_set(odp_packet_t pkt, uint32_t offset); > >>> > >>> @@ -551,8 +551,8 @@ int odp_packet_l3_offset_set(odp_packet_t pkt, > >>> uint32_t offset); > >>> * @param[out] len Number of data bytes remaining in the segment > >>> (output). > >>> * Ignored when NULL. > >>> * > >>> - * @return Layer 4 start pointer, or NULL when packet does not > contain a > >>> valid > >>> - * L4 header. > >>> + * @return Layer 4 start pointer > >>> + * @retval NULL packet does not contain a valid L4 header > >>> * > >>> * @see odp_packet_l4_offset(), odp_packet_l4_offset_set(), > >>> odp_packet_has_l4() > >>> */ > >>> @@ -569,8 +569,8 @@ void *odp_packet_l4_ptr(odp_packet_t pkt, uint32_t > >>> *len); > >>> * > >>> * @param pkt Packet handle > >>> * > >>> - * @return Layer 4 start offset, or ODP_PACKET_OFFSET_INVALID when > >>> packet does > >>> - * not contain a valid L4 header. > >>> + * @return Layer 4 start offset > >>> + * @retval ODP_PACKET_OFFSET_INVALID packet does not contain a valid > L4 > >>> header > >>> * > >>> * @see odp_packet_l4_offset_set(), odp_packet_has_l4() > >>> */ > >>> @@ -586,8 +586,8 @@ uint32_t odp_packet_l4_offset(odp_packet_t pkt); > >>> * @param pkt Packet handle > >>> * @param offset Layer 4 start offset (0 ... odp_packet_len()-1) > >>> * > >>> - * @retval 0 Success > >>> - * @retval Non-zero Failure > >>> + * @retval 0 on success > >>> + * @retval <0 on failure > >>> */ > >>> int odp_packet_l4_offset_set(odp_packet_t pkt, uint32_t offset); > >>> > >>> @@ -645,7 +645,8 @@ odp_packet_seg_t odp_packet_last_seg(odp_packet_t > >>> pkt); > >>> * @param pkt Packet handle > >>> * @param seg Current segment handle > >>> * > >>> - * @return Handle to the next segment, or ODP_PACKET_SEG_INVALID > >>> + * @return Handle to the next segment > >>> + * @retval ODP_PACKET_SEG_INVALID if there are no more segments > >>> */ > >>> odp_packet_seg_t odp_packet_next_seg(odp_packet_t pkt, > odp_packet_seg_t > >>> seg); > >>> > >>> @@ -665,7 +666,8 @@ odp_packet_seg_t odp_packet_next_seg(odp_packet_t > pkt, > >>> odp_packet_seg_t seg); > >>> * @param pkt Packet handle > >>> * @param seg Segment handle > >>> * > >>> - * @return Start address of the segment, or NULL on an error > >>> + * @return Start address of the segment > >>> + * @retval NULL on failure > >>> * > >>> * @see odp_packet_seg_buf_len() > >>> */ > >>> @@ -693,7 +695,8 @@ uint32_t odp_packet_seg_buf_len(odp_packet_t pkt, > >>> odp_packet_seg_t seg); > >>> * @param pkt Packet handle > >>> * @param seg Segment handle > >>> * > >>> - * @return Pointer to the segment data, or NULL on an error > >>> + * @return Pointer to the segment data > >>> + * @retval NULL on failure > >>> * > >>> * @see odp_packet_seg_data_len() > >>> */ > >>> @@ -735,7 +738,8 @@ uint32_t odp_packet_seg_data_len(odp_packet_t pkt, > >>> odp_packet_seg_t seg); > >>> * @param offset Byte offset into the packet > >>> * @param len Number of bytes to add into the offset > >>> * > >>> - * @return New packet handle, or ODP_PACKET_INVALID in case of an > error. > >>> + * @return New packet handle > >>> + * @retval ODP_PACKET_INVALID on failure > >>> */ > >>> odp_packet_t odp_packet_add_data(odp_packet_t pkt, uint32_t offset, > >>> uint32_t len); > >>> @@ -753,7 +757,8 @@ odp_packet_t odp_packet_add_data(odp_packet_t pkt, > >>> uint32_t offset, > >>> * @param offset Byte offset into the packet > >>> * @param len Number of bytes to remove from the offset > >>> * > >>> - * @return New packet handle, or ODP_PACKET_INVALID in case of an > error. > >>> + * @return New packet handle > >>> + * @retval ODP_PACKET_INVALID on failure > >>> */ > >>> odp_packet_t odp_packet_rem_data(odp_packet_t pkt, uint32_t offset, > >>> uint32_t len); > >>> @@ -776,7 +781,8 @@ odp_packet_t odp_packet_rem_data(odp_packet_t pkt, > >>> uint32_t offset, > >>> * @param pkt Packet handle > >>> * @param pool Buffer pool for allocation of the new packet. > >>> * > >>> - * @return Handle to the copy of the packet, or ODP_PACKET_INVALID > >>> + * @return Handle to the copy of the packet > >>> + * @retval ODP_PACKET_INVALID on failure > >>> */ > >>> odp_packet_t odp_packet_copy(odp_packet_t pkt, odp_buffer_pool_t > pool); > >>> > >>> @@ -791,8 +797,8 @@ odp_packet_t odp_packet_copy(odp_packet_t pkt, > >>> odp_buffer_pool_t pool); > >>> * @param len Number of bytes to copy > >>> * @param dst Destination address > >>> * > >>> - * @retval 0 Success > >>> - * @retval Non-zero Failure > >>> + * @retval 0 on success > >>> + * @retval <0 on failure > >>> */ > >>> int odp_packet_copydata_out(odp_packet_t pkt, uint32_t offset, > >>> uint32_t len, void *dst); > >>> @@ -809,8 +815,8 @@ int odp_packet_copydata_out(odp_packet_t pkt, > uint32_t > >>> offset, > >>> * @param len Number of bytes to copy > >>> * @param src Source address > >>> * > >>> - * @retval 0 Success > >>> - * @retval Non-zero Failure > >>> + * @retval 0 on success > >>> + * @retval <0 on failure > >>> */ > >>> int odp_packet_copydata_in(odp_packet_t pkt, uint32_t offset, > >>> uint32_t len, const void *src); > >>> diff --git a/platform/linux-generic/include/api/odp_packet_flags.h > >>> b/platform/linux-generic/include/api/odp_packet_flags.h > >>> index 24c4065..399a0bf 100644 > >>> --- a/platform/linux-generic/include/api/odp_packet_flags.h > >>> +++ b/platform/linux-generic/include/api/odp_packet_flags.h > >>> @@ -32,7 +32,8 @@ extern "C" { > >>> * Checks all error flags at once. > >>> * > >>> * @param pkt Packet handle > >>> - * @return 1 if packet has errors, 0 otherwise > >>> + * @retval 1 if packet has errors > >>> + * @retval 0 if packet has no errors > >>> */ > >>> int odp_packet_error(odp_packet_t pkt); > >>> > >>> @@ -40,7 +41,8 @@ int odp_packet_error(odp_packet_t pkt); > >>> * Check if error was 'frame length' error > >>> * > >>> * @param pkt Packet handle > >>> - * @return 1 if frame length error detected, 0 otherwise > >>> + * @retval 1 if frame length error detected > >>> + * @retval 0 if frame length error not detected > >>> */ > >>> int odp_packet_errflag_frame_len(odp_packet_t pkt); > >>> > >>> @@ -48,7 +50,8 @@ int odp_packet_errflag_frame_len(odp_packet_t pkt); > >>> * Check for L2 header, e.g. ethernet > >>> * > >>> * @param pkt Packet handle > >>> - * @return 1 if packet contains a valid & known L2 header, 0 otherwise > >>> + * @retval 1 if packet contains a valid & known L2 header > >>> + * @retval 0 if packet does not contain a valid & known L2 header > >>> */ > >>> int odp_packet_has_l2(odp_packet_t pkt); > >>> > >>> @@ -56,7 +59,8 @@ int odp_packet_has_l2(odp_packet_t pkt); > >>> * Check for L3 header, e.g. IPv4, IPv6 > >>> * > >>> * @param pkt Packet handle > >>> - * @return 1 if packet contains a valid & known L3 header, 0 otherwise > >>> + * @retval 1 if packet contains a valid & known L3 header > >>> + * @retval 0 if packet does not contain a valid & known L3 header > >>> */ > >>> int odp_packet_has_l3(odp_packet_t pkt); > >>> > >>> @@ -64,7 +68,8 @@ int odp_packet_has_l3(odp_packet_t pkt); > >>> * Check for L4 header, e.g. UDP, TCP, SCTP (also ICMP) > >>> * > >>> * @param pkt Packet handle > >>> - * @return 1 if packet contains a valid & known L4 header, 0 otherwise > >>> + * @retval 1 if packet contains a valid & known L4 header > >>> + * @retval 0 if packet does not contain a valid & known L4 header > >>> */ > >>> int odp_packet_has_l4(odp_packet_t pkt); > >>> > >>> @@ -72,7 +77,8 @@ int odp_packet_has_l4(odp_packet_t pkt); > >>> * Check for Ethernet header > >>> * > >>> * @param pkt Packet handle > >>> - * @return 1 if packet contains a valid eth header, 0 otherwise > >>> + * @retval 1 if packet contains a valid eth header > >>> + * @retval 0 if packet does not contain a valid & known eth header > >>> */ > >>> int odp_packet_has_eth(odp_packet_t pkt); > >>> > >>> @@ -80,7 +86,8 @@ int odp_packet_has_eth(odp_packet_t pkt); > >>> * Check for jumbo frame > >>> * > >>> * @param pkt Packet handle > >>> - * @return 1 if packet contains jumbo frame, 0 otherwise > >>> + * @retval 1 if packet contains a jumbo frame > >>> + * @retval 0 if packet does not contain a jumbo frame > >>> */ > >>> int odp_packet_has_jumbo(odp_packet_t pkt); > >>> > >>> @@ -88,7 +95,8 @@ int odp_packet_has_jumbo(odp_packet_t pkt); > >>> * Check for VLAN > >>> * > >>> * @param pkt Packet handle > >>> - * @return 1 if packet contains a VLAN header, 0 otherwise > >>> + * @retval 1 if packet contains a VLAN header > >>> + * @retval 0 if packet does not contain a VLAN header > >>> */ > >>> int odp_packet_has_vlan(odp_packet_t pkt); > >>> > >>> @@ -96,7 +104,8 @@ int odp_packet_has_vlan(odp_packet_t pkt); > >>> * Check for VLAN QinQ (stacked VLAN) > >>> * > >>> * @param pkt Packet handle > >>> - * @return 1 if packet contains a VLAN QinQ header, 0 otherwise > >>> + * @retval 1 if packet contains a VLAN QinQ header > >>> + * @retval 0 if packet does not contain a VLAN QinQ header > >>> */ > >>> int odp_packet_has_vlan_qinq(odp_packet_t pkt); > >>> > >>> @@ -104,7 +113,8 @@ int odp_packet_has_vlan_qinq(odp_packet_t pkt); > >>> * Check for ARP > >>> * > >>> * @param pkt Packet handle > >>> - * @return 1 if packet contains an ARP header, 0 otherwise > >>> + * @retval 1 if packet contains an ARP message > >>> + * @retval 0 if packet does not contain an ARP message > >>> */ > >>> int odp_packet_has_arp(odp_packet_t pkt); > >>> > >>> @@ -112,7 +122,8 @@ int odp_packet_has_arp(odp_packet_t pkt); > >>> * Check for IPv4 > >>> * > >>> * @param pkt Packet handle > >>> - * @return 1 if packet contains an IPv4 header, 0 otherwise > >>> + * @retval 1 if packet contains an IPv4 header > >>> + * @retval 0 if packet does not contain an IPv4 header > >>> */ > >>> int odp_packet_has_ipv4(odp_packet_t pkt); > >>> > >>> @@ -120,7 +131,8 @@ int odp_packet_has_ipv4(odp_packet_t pkt); > >>> * Check for IPv6 > >>> * > >>> * @param pkt Packet handle > >>> - * @return 1 if packet contains an IPv6 header, 0 otherwise > >>> + * @retval 1 if packet contains an IPv6 header > >>> + * @retval 0 if packet does not contain an IPv6 header > >>> */ > >>> int odp_packet_has_ipv6(odp_packet_t pkt); > >>> > >>> @@ -128,7 +140,8 @@ int odp_packet_has_ipv6(odp_packet_t pkt); > >>> * Check for IP fragment > >>> * > >>> * @param pkt Packet handle > >>> - * @return 1 if packet is an IP fragment, 0 otherwise > >>> + * @retval 1 if packet is an IP fragment > >>> + * @retval 0 if packet is not an IP fragment > >>> */ > >>> int odp_packet_has_ipfrag(odp_packet_t pkt); > >>> > >>> @@ -136,7 +149,8 @@ int odp_packet_has_ipfrag(odp_packet_t pkt); > >>> * Check for IP options > >>> * > >>> * @param pkt Packet handle > >>> - * @return 1 if packet contains IP options, 0 otherwise > >>> + * @retval 1 if packet contains IP options > >>> + * @retval 0 if packet does not contain IP options > >>> */ > >>> int odp_packet_has_ipopt(odp_packet_t pkt); > >>> > >>> @@ -144,7 +158,8 @@ int odp_packet_has_ipopt(odp_packet_t pkt); > >>> * Check for IPSec > >>> * > >>> * @param pkt Packet handle > >>> - * @return 1 if packet requires IPSec processing, 0 otherwise > >>> + * @retval 1 if packet requires IPSec processing > >>> + * @retval 0 if packet does not require IPSec processing > >>> */ > >>> int odp_packet_has_ipsec(odp_packet_t pkt); > >>> > >>> @@ -152,7 +167,8 @@ int odp_packet_has_ipsec(odp_packet_t pkt); > >>> * Check for UDP > >>> * > >>> * @param pkt Packet handle > >>> - * @return 1 if packet contains a UDP header, 0 otherwise > >>> + * @retval 1 if packet contains a UDP header > >>> + * @retval 0 if packet does not contain a UDP header > >>> */ > >>> int odp_packet_has_udp(odp_packet_t pkt); > >>> > >>> @@ -160,7 +176,8 @@ int odp_packet_has_udp(odp_packet_t pkt); > >>> * Check for TCP > >>> * > >>> * @param pkt Packet handle > >>> - * @return 1 if packet contains a TCP header, 0 otherwise > >>> + * @retval 1 if packet contains a TCP header > >>> + * @retval 0 if packet does not contain a TCP header > >>> */ > >>> int odp_packet_has_tcp(odp_packet_t pkt); > >>> > >>> @@ -168,7 +185,8 @@ int odp_packet_has_tcp(odp_packet_t pkt); > >>> * Check for SCTP > >>> * > >>> * @param pkt Packet handle > >>> - * @return 1 if packet contains an SCTP header, 0 otherwise > >>> + * @retval 1 if packet contains a SCTP header > >>> + * @retval 0 if packet does not contain a SCTP header > >>> */ > >>> int odp_packet_has_sctp(odp_packet_t pkt); > >>> > >>> @@ -176,7 +194,8 @@ int odp_packet_has_sctp(odp_packet_t pkt); > >>> * Check for ICMP > >>> * > >>> * @param pkt Packet handle > >>> - * @return 1 if packet contains an ICMP header, 0 otherwise > >>> + * @retval 1 if packet contains an ICMP header > >>> + * @retval 0 if packet does not contain an ICMP header > >>> */ > >>> int odp_packet_has_icmp(odp_packet_t pkt); > >>> > >>> diff --git a/platform/linux-generic/include/api/odp_packet_io.h > >>> b/platform/linux-generic/include/api/odp_packet_io.h > >>> index 4835f4d..1a770b6 100644 > >>> --- a/platform/linux-generic/include/api/odp_packet_io.h > >>> +++ b/platform/linux-generic/include/api/odp_packet_io.h > >>> @@ -40,7 +40,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 > >>> @@ -53,7 +54,8 @@ odp_pktio_t odp_pktio_open(const char *dev, > >>> odp_buffer_pool_t pool); > >>> * > >>> * @param id 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); > >>> > >>> @@ -62,7 +64,8 @@ int odp_pktio_close(odp_pktio_t id); > >>> * > >>> * @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); > >>> > >>> @@ -73,7 +76,8 @@ odp_pktio_t odp_pktio_lookup(const char *dev); > >>> * @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); > >>> > >>> @@ -84,7 +88,8 @@ int odp_pktio_recv(odp_pktio_t id, odp_packet_t > >>> pkt_table[], unsigned len); > >>> * @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); > >>> > >>> @@ -93,7 +98,8 @@ int odp_pktio_send(odp_pktio_t id, odp_packet_t > >>> pkt_table[], unsigned len); > >>> * > >>> * @param id 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); > >>> > >>> @@ -102,7 +108,8 @@ int odp_pktio_inq_setdef(odp_pktio_t id, > odp_queue_t > >>> queue); > >>> * > >>> * @param id 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); > >>> > >>> @@ -111,7 +118,8 @@ odp_queue_t odp_pktio_inq_getdef(odp_pktio_t id); > >>> * > >>> * @param id 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); > >>> > >>> @@ -120,7 +128,8 @@ int odp_pktio_inq_remdef(odp_pktio_t id); > >>> * > >>> * @param id 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); > >>> > >>> @@ -129,8 +138,8 @@ odp_queue_t odp_pktio_outq_getdef(odp_pktio_t id); > >>> * > >>> * @param[in] id 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); > >>> > >>> @@ -140,8 +149,8 @@ int odp_pktio_mtu(odp_pktio_t id); > >>> * @param[in] id 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); > >>> > >>> @@ -152,7 +161,7 @@ int odp_pktio_promisc_mode_set(odp_pktio_t id, > >>> odp_bool_t enable); > >>> * > >>> * @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); > >>> > >>> @@ -163,9 +172,10 @@ int odp_pktio_promisc_mode(odp_pktio_t id); > >>> * @param[out] mac_addr Storage for MAC address of the packet IO > >>> interface. > >>> * @param addr_size Storage size for the address > >>> * > >>> - * @retval Number of bytes written on success, 0 on failure. > >>> + * @return Number of bytes written on success > >>> + * @retval <0 on failure > >>> */ > >>> -size_t odp_pktio_mac_addr(odp_pktio_t id, void *mac_addr, > >>> +int odp_pktio_mac_addr(odp_pktio_t id, void *mac_addr, > >>> size_t addr_size); > >>> > >>> /** > >>> @@ -177,7 +187,8 @@ size_t odp_pktio_mac_addr(odp_pktio_t id, void > >>> *mac_addr, > >>> * 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); > >>> > >>> @@ -189,7 +200,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. > >>> */ > >>> @@ -201,7 +213,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. > >>> * > >>> */ > >>> @@ -216,7 +229,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. > >>> */ > >>> diff --git a/platform/linux-generic/include/api/odp_queue.h > >>> b/platform/linux-generic/include/api/odp_queue.h > >>> index b0f7185..25633e0 100644 > >>> --- a/platform/linux-generic/include/api/odp_queue.h > >>> +++ b/platform/linux-generic/include/api/odp_queue.h > >>> @@ -118,7 +118,8 @@ typedef struct odp_queue_param_t { > >>> * @param type Queue type > >>> * @param param Queue parameters. Uses defaults if NULL. > >>> * > >>> - * @return Queue handle or ODP_QUEUE_INVALID > >>> + * @return Queue handle > >>> + * @retval ODP_QUEUE_INVALID on failure > >>> */ > >>> odp_queue_t odp_queue_create(const char *name, odp_queue_type_t type, > >>> odp_queue_param_t *param); > >>> @@ -133,7 +134,8 @@ odp_queue_t odp_queue_create(const char *name, > >>> odp_queue_type_t type, > >>> * > >>> * @param queue Queue handle > >>> * > >>> - * @return 0 if successful > >>> + * @retval 0 on success > >>> + * @retval <0 on failure > >>> */ > >>> int odp_queue_destroy(odp_queue_t queue); > >>> > >>> @@ -142,7 +144,8 @@ int odp_queue_destroy(odp_queue_t queue); > >>> * > >>> * @param name Queue name > >>> * > >>> - * @return Queue handle or ODP_QUEUE_INVALID > >>> + * @return Queue handle > >>> + * @retval ODP_QUEUE_INVALID on failure > >>> */ > >>> odp_queue_t odp_queue_lookup(const char *name); > >>> > >>> @@ -156,7 +159,8 @@ odp_queue_t odp_queue_lookup(const char *name); > >>> * @param queue Queue handle > >>> * @param context Address to the queue context > >>> * > >>> - * @return 0 if successful > >>> + * @retval 0 on success > >>> + * @retval <0 on failure > >>> */ > >>> int odp_queue_set_context(odp_queue_t queue, void *context); > >>> > >>> @@ -165,8 +169,8 @@ int odp_queue_set_context(odp_queue_t queue, void > >>> *context); > >>> * > >>> * @param queue Queue handle > >>> * > >>> - * @return If successful, a pointer to the queue context, > >>> - * NULL for failure. > >>> + * @return pointer to the queue context > >>> + * @retval NULL on failure > >>> */ > >>> void *odp_queue_get_context(odp_queue_t queue); > >>> > >>> @@ -176,7 +180,8 @@ void *odp_queue_get_context(odp_queue_t queue); > >>> * @param queue Queue handle > >>> * @param buf Buffer handle > >>> * > >>> - * @return 0 if succesful > >>> + * @retval 0 on success > >>> + * @retval <0 on failure > >>> */ > >>> int odp_queue_enq(odp_queue_t queue, odp_buffer_t buf); > >>> > >>> @@ -187,7 +192,8 @@ int odp_queue_enq(odp_queue_t queue, odp_buffer_t > >>> buf); > >>> * @param buf Buffer handles > >>> * @param num Number of buffer handles > >>> * > >>> - * @return 0 if succesful > >>> + * @retval 0 on success > >>> + * @retval <0 on failure > >>> */ > >>> int odp_queue_enq_multi(odp_queue_t queue, odp_buffer_t buf[], int > num); > >>> > >>> @@ -199,7 +205,8 @@ int odp_queue_enq_multi(odp_queue_t queue, > >>> odp_buffer_t buf[], int num); > >>> * > >>> * @param queue Queue handle > >>> * > >>> - * @return Buffer handle, or ODP_BUFFER_INVALID > >>> + * @return Buffer handle > >>> + * @retval ODP_BUFFER_INVALID on failure > >>> */ > >>> odp_buffer_t odp_queue_deq(odp_queue_t queue); > >>> > >>> diff --git a/platform/linux-generic/include/api/odp_schedule.h > >>> b/platform/linux-generic/include/api/odp_schedule.h > >>> index cdf6705..36fbba3 100644 > >>> --- a/platform/linux-generic/include/api/odp_schedule.h > >>> +++ b/platform/linux-generic/include/api/odp_schedule.h > >>> @@ -59,7 +59,8 @@ uint64_t odp_schedule_wait_time(uint64_t ns); > >>> * Use odp_schedule_wait_time() to convert time to > other > >>> wait > >>> * values. > >>> * > >>> - * @return Next highest priority buffer, or ODP_BUFFER_INVALID > >>> + * @return Next highest priority buffer > >>> + * @retval ODP_BUFFER_INVALID on timeout > >>> */ > >>> odp_buffer_t odp_schedule(odp_queue_t *from, uint64_t wait); > >>> > >>> diff --git a/platform/linux-generic/include/api/odp_shared_memory.h > >>> b/platform/linux-generic/include/api/odp_shared_memory.h > >>> index f70db5a..78d108a 100644 > >>> --- a/platform/linux-generic/include/api/odp_shared_memory.h > >>> +++ b/platform/linux-generic/include/api/odp_shared_memory.h > >>> @@ -59,7 +59,8 @@ typedef struct odp_shm_info_t { > >>> * @param[in] flags Shared memory parameter flags (ODP_SHM_*). > >>> * Default value is 0. > >>> * > >>> - * @return Pointer to the reserved block, or NULL > >>> + * @return Handle of the reserved block > >>> + * @retval NULL on failure > >>> */ > >>> odp_shm_t odp_shm_reserve(const char *name, uint64_t size, uint64_t > >>> align, > >>> uint32_t flags); > >>> @@ -72,9 +73,9 @@ odp_shm_t odp_shm_reserve(const char *name, uint64_t > >>> size, uint64_t align, > >>> * > >>> * @param[in] shm Block handle > >>> * > >>> - * @retval 0 if the handle is already free > >>> + * @retval 0 if the handle is already free (FIXME how can we know > this?) > >> > >> > >> The linux-generic implementation tracks block allocation status. Good > point > >> as to whether this should be part of the spec, however. > > The above definition puts some more restrictions on the ODP > > implementation. It must remember all past shm handles and their > > current status. How does this work if shm regions are created and > > destroyed repeatedly (an unlikely use case I agree). Possibly there is > > a fixed array of shm handles with generation counters for each handle > > but this will eventually wrap around and old stale handles become > > fresh again. > > > > Resource cleanup (e.g. for controlled program termination) has to be a > > highly synchronized operation anyway, you can't have worker threads > > continuing their execution, allocating buffers and timers, interacting > > with HW etc. when you are tearing down those resources. > > > > Specifying undefined behavior is better in my opinion. linux-generic > > only has to be changed so that it does not return 0 for an already > > freed shm region (because this would be a bad example and we want > > linux-generic to be a good example), instead it could call ODP_ABORT. > > > >> > >>> > >>> * @retval 0 if the handle free succeeds > >>> - * @retval -1 on failure to free the handle > >>> + * @retval <0 on failure to free the handle > >>> */ > >>> int odp_shm_free(odp_shm_t shm); > >>> > >>> @@ -84,7 +85,7 @@ int odp_shm_free(odp_shm_t shm); > >>> * @param[in] name Name of the block > >>> * > >>> * @return A handle to the block if it is found by name > >>> - * @retval #ODP_SHM_INVALID if the block is not found > >>> + * @retval ODP_SHM_INVALID on failure > >>> */ > >>> odp_shm_t odp_shm_lookup(const char *name); > >>> > >>> @@ -94,7 +95,8 @@ odp_shm_t odp_shm_lookup(const char *name); > >>> * > >>> * @param[in] shm Block handle > >>> * > >>> - * @return Memory block address, or NULL on error > >>> + * @return Memory block address > >>> + * @retval NULL on failure (FIXME: when?) > >> > >> > >> Why the FIXME? NULL is returned if the operation is unable to succeed. > > Yes but when can the translation from shm handle to virtual address > > fail? Are there any situations where we think this is normal behavior? > > Shared memory regions that are not mapped to virtual memory? > > > > Passing invalid shm handles cause undefined behavior, not well-defined > failures. > > So I am questioning why we need a @retval NULL for this function. > > > > > >> > >>> > >>> */ > >>> void *odp_shm_addr(odp_shm_t shm); > >>> > >>> @@ -105,7 +107,8 @@ void *odp_shm_addr(odp_shm_t shm); > >>> * @param[in] shm Block handle > >>> * @param[out] info Block info pointer for output > >>> * > >>> - * @return 0 on success, otherwise non-zero > >>> + * @retval 0 on success > >>> + * @retval <0 on failure > >>> */ > >>> int odp_shm_info(odp_shm_t shm, odp_shm_info_t *info); > >>> > >>> diff --git a/platform/linux-generic/include/api/odp_timer.h > >>> b/platform/linux-generic/include/api/odp_timer.h > >>> index 69402ef..c8c3270 100644 > >>> --- a/platform/linux-generic/include/api/odp_timer.h > >>> +++ b/platform/linux-generic/include/api/odp_timer.h > >>> @@ -112,8 +112,8 @@ typedef struct { > >>> * @param name Name of the timer pool. The string will be > copied. > >>> * @param params Timer pool parameters. The content will be > copied. > >>> * > >>> - * @return Timer pool handle if successful, otherwise > >>> ODP_TIMER_POOL_INVALID > >>> - * and errno set > >>> + * @return Timer pool handle on success > >>> + * @retval ODP_TIMER_POOL_INVALID on failure and errno set > >>> */ > >>> odp_timer_pool_t > >>> odp_timer_pool_create(const char *name, > >>> @@ -185,8 +185,8 @@ typedef struct { > >>> * @param tpid Timer pool identifier > >>> * @param[out] info Pointer to information buffer > >>> * > >>> - * @retval 0 Success > >>> - * @retval -1 Failure. Info could not be retrieved. > >>> + * @retval 0 on success > >>> + * @retval <0 on failure. Info could not be retrieved. > >>> */ > >>> int odp_timer_pool_info(odp_timer_pool_t tpid, > >>> odp_timer_pool_info_t *info); > >>> @@ -202,8 +202,8 @@ int odp_timer_pool_info(odp_timer_pool_t tpid, > >>> * @param queue Destination queue for timeout notifications > >>> * @param user_ptr User defined pointer or NULL to be copied to > timeouts > >>> * > >>> - * @return Timer handle if successful, otherwise ODP_TIMER_INVALID and > >>> - * errno set. > >>> + * @return Timer handle on success > >>> + * @retval ODP_TIMER_INVALID on failure and errno set. > >>> */ > >>> odp_timer_t odp_timer_alloc(odp_timer_pool_t tpid, > >>> odp_queue_t queue, > >>> @@ -218,7 +218,8 @@ odp_timer_t odp_timer_alloc(odp_timer_pool_t tpid, > >>> * responsibility of the application to handle this timeout when it is > >>> received. > >>> * > >>> * @param tim Timer handle > >>> - * @return Buffer handle of timeout buffer or ODP_BUFFER_INVALID > >>> + * @return Buffer handle of timeout buffer > >>> + * @retval ODP_BUFFER_INVALID on failure > >>> */ > >>> odp_buffer_t odp_timer_free(odp_timer_t tim); > >>> > >>> @@ -292,8 +293,8 @@ int odp_timer_set_rel(odp_timer_t tim, > >>> * > >>> * @param tim Timer > >>> * @param[out] tmo_buf Pointer to a buffer variable > >>> - * @retval 0 Success, active timer cancelled, timeout returned in > >>> '*tmo_buf' > >>> - * @retval -1 Failure, timer already expired (or inactive) > >>> + * @retval 0 on success, active timer cancelled, timeout returned in > >>> '*tmo_buf' > >>> + * @retval <0 on failure, timer already expired (or inactive) > >>> */ > >>> int odp_timer_cancel(odp_timer_t tim, odp_buffer_t *tmo_buf); > >>> > >>> diff --git a/platform/linux-generic/odp_crypto.c > >>> b/platform/linux-generic/odp_crypto.c > >>> index 2f95cbe..ded3b62 100644 > >>> --- a/platform/linux-generic/odp_crypto.c > >>> +++ b/platform/linux-generic/odp_crypto.c > >>> @@ -343,7 +343,7 @@ > odp_crypto_session_create(odp_crypto_session_params_t > >>> *params, > >>> > >>> int > >>> odp_crypto_operation(odp_crypto_op_params_t *params, > >>> - bool *posted, > >>> + odp_bool_t *posted, > >>> odp_buffer_t completion_event) > >>> { > >>> enum crypto_alg_err rc_cipher = ODP_CRYPTO_ALG_ERR_NONE; > >>> @@ -423,7 +423,7 @@ odp_crypto_init_global(void) > >>> } > >>> > >>> int > >>> -odp_hw_random_get(uint8_t *buf, size_t *len, bool use_entropy > ODP_UNUSED) > >>> +odp_hw_random_get(uint8_t *buf, size_t *len, odp_bool_t use_entropy > >>> ODP_UNUSED) > >>> { > >>> int rc; > >>> rc = RAND_bytes(buf, *len); > >>> diff --git a/platform/linux-generic/odp_packet_io.c > >>> b/platform/linux-generic/odp_packet_io.c > >>> index 0efa3d0..c51098f 100644 > >>> --- a/platform/linux-generic/odp_packet_io.c > >>> +++ b/platform/linux-generic/odp_packet_io.c > >>> @@ -797,18 +797,18 @@ int odp_pktio_promisc_mode(odp_pktio_t id) > >>> } > >>> > >>> > >>> -size_t odp_pktio_mac_addr(odp_pktio_t id, void *mac_addr, > >>> +int odp_pktio_mac_addr(odp_pktio_t id, void *mac_addr, > >>> size_t addr_size) > >>> { > >>> pktio_entry_t *entry; > >>> > >>> if (addr_size < ETH_ALEN) > >>> - return 0; > >>> + return -1; > >>> > >>> entry = get_pktio_entry(id); > >>> if (entry == NULL) { > >>> ODP_DBG("pktio entry %d does not exist\n", id); > >>> - return 0; > >>> + return -1; > >>> } > >>> > >>> lock_entry(entry); > >>> diff --git a/test/validation/crypto/odp_crypto_test_async_inp.c > >>> b/test/validation/crypto/odp_crypto_test_async_inp.c > >>> index 96d4c3f..1db7844 100644 > >>> --- a/test/validation/crypto/odp_crypto_test_async_inp.c > >>> +++ b/test/validation/crypto/odp_crypto_test_async_inp.c > >>> @@ -34,7 +34,7 @@ static void alg_test(enum odp_crypto_op op, > >>> odp_crypto_session_t session; > >>> int rc; > >>> enum odp_crypto_ses_create_err status; > >>> - bool posted; > >>> + odp_bool_t posted; > >>> odp_buffer_t compl_event; > >>> > >>> odp_queue_t compl_queue = odp_queue_lookup("crypto-out"); > >>> diff --git a/test/validation/crypto/odp_crypto_test_sync_inp.c > >>> b/test/validation/crypto/odp_crypto_test_sync_inp.c > >>> index f37ad54..5082f13 100644 > >>> --- a/test/validation/crypto/odp_crypto_test_sync_inp.c > >>> +++ b/test/validation/crypto/odp_crypto_test_sync_inp.c > >>> @@ -23,7 +23,7 @@ static void alg_test(enum odp_crypto_op op, > >>> odp_crypto_session_t session; > >>> int rc; > >>> enum odp_crypto_ses_create_err status; > >>> - bool posted; > >>> + odp_bool_t posted; > >>> > >>> odp_queue_t compl_queue = odp_queue_lookup("crypto-out"); > >>> CU_ASSERT(compl_queue != ODP_QUEUE_INVALID); > >>> -- > >>> 1.9.1 > >>> > >>> > >>> _______________________________________________ > >>> lng-odp mailing list > >>> lng-odp@lists.linaro.org > >>> http://lists.linaro.org/mailman/listinfo/lng-odp > >> > >> >
On 27 January 2015 at 12:52, Bill Fischofer <bill.fischofer@linaro.org> wrote: > I think it's good practice for functions to be robust in parameter handling > unless they are expected to be used in performance paths. That's the reason > why we've said that things like odp_buffer_addr() etc. have undefined > behavior if they're passed invalid handles. But shm and pools are things > that will typically get set up once during init, and seldom changed (maybe > as part of reconfig) so the performance argument is less compelling there. I agree but this is not only about performance. Sprinkling the API's with error codes also forces the user to check those return values which complicates the application logic and probably creates code that will be difficult to get test coverage for. I have a lot of experience with API's that cannot return errors and I really prefer this style. Applications becomes so much simpler. Why should odp_shm_addr() be allowed to return an error code? Most implementations most likely will not even utilize the possibility and applications will not expect an error to happen and so might not even check the return value. How often do you check the return value of printf or close? Just because the functions do not have to check for valid parameters so that they can return corresponding error indications does not mean that implementations cannot and should not check for (in)valid parameters. But if invalid parameters are detected, the error has to be signaled in some other way, e.g. by calling ODP_ABORT (as ODP doesn't have any error handling mechanism for users to hook into). The timer implementation always checks timer pool handles and timer handles for validity. As ODP_ABORT (which does not return control to the caller) is used to report invalid parameters, the applications cannot rely on the ODP implementation handling invalid parameters. In another implementation, the checks could be removed with no change of semantics. As you say that should only be considered for truly performance critical functions. > > On Tue, Jan 27, 2015 at 4:54 AM, Ola Liljedahl <ola.liljedahl@linaro.org> > wrote: >> >> As a general rule, all functions that return information about e.g. >> shared memory areas, buffer/event pools and timer pools should be >> robust in the presence of invalid parameters (handles). The reason is >> that you might want to implement a form of post-mortem dump which >> examines all ODP objects and saves the information in some dump area >> and you don't want this post-mortem dump function to crash. The system >> is already in a bad state (that's why we need a dump so we can debug >> it) and not all data can be trusted. >> Buffers/events are special, we have a special function for checking >> the validity of such handles so that all other (performance critical) >> buffer/event operations can expect the handle to be valid and avoid >> any checks. >> >> >> >> On 27 January 2015 at 11:43, Ola Liljedahl <ola.liljedahl@linaro.org> >> wrote: >> > On 27 January 2015 at 02:14, Bill Fischofer <bill.fischofer@linaro.org> >> > wrote: >> >> This looks good. It will need to be rebased following the event patch >> >> merge >> >> (all merges currently blocked until that happens). See additional >> >> comments >> >> inline: >> > I'll rebase as necessary and post updated patches. >> > >> >> >> >> On Mon, Jan 26, 2015 at 6:20 PM, Ola Liljedahl >> >> <ola.liljedahl@linaro.org> >> >> wrote: >> >>> >> >>> Unify @return and @retval descriptions. >> >>> @return used for values that cannot (meaningfully) be enumerated (e.g >> >>> pointers, >> >>> ODP handles) or simply tested for correctness. >> >>> @retval used for values that can be enumerated and should be tested by >> >>> validation programs. >> >>> Changed from bool to odp_bool_t in odp_crypto.h and dependent source >> >>> files. >> >>> Changed return type and value of odp_pktio_mac_addr() to match other >> >>> similar >> >>> functions. Use int as return type, <0 to indicate failure. >> >>> >> >>> Signed-off-by: Ola Liljedahl <ola.liljedahl@linaro.org> >> >>> --- >> >>> (This document/code contribution attached is provided under the terms >> >>> of >> >>> agreement LES-LTM-21309) >> >>> >> >>> example/ipsec/odp_ipsec.c | 4 +- >> >>> platform/linux-generic/include/api/odp_buffer.h | 9 ++- >> >>> .../linux-generic/include/api/odp_buffer_pool.h | 21 ++++--- >> >>> platform/linux-generic/include/api/odp_byteorder.h | 2 +- >> >>> .../linux-generic/include/api/odp_classification.h | 48 >> >>> +++++++++------- >> >>> platform/linux-generic/include/api/odp_cpumask.h | 12 ++-- >> >>> platform/linux-generic/include/api/odp_crypto.h | 15 +++-- >> >>> platform/linux-generic/include/api/odp_init.h | 10 ++-- >> >>> platform/linux-generic/include/api/odp_packet.h | 66 >> >>> ++++++++++++---------- >> >>> .../linux-generic/include/api/odp_packet_flags.h | 57 >> >>> ++++++++++++------- >> >>> platform/linux-generic/include/api/odp_packet_io.h | 54 >> >>> +++++++++++------- >> >>> platform/linux-generic/include/api/odp_queue.h | 25 +++++--- >> >>> platform/linux-generic/include/api/odp_schedule.h | 3 +- >> >>> .../linux-generic/include/api/odp_shared_memory.h | 15 +++-- >> >>> platform/linux-generic/include/api/odp_timer.h | 19 ++++--- >> >>> platform/linux-generic/odp_crypto.c | 4 +- >> >>> platform/linux-generic/odp_packet_io.c | 6 +- >> >>> test/validation/crypto/odp_crypto_test_async_inp.c | 2 +- >> >>> test/validation/crypto/odp_crypto_test_sync_inp.c | 2 +- >> >>> 19 files changed, 226 insertions(+), 148 deletions(-) >> >>> >> >>> diff --git a/example/ipsec/odp_ipsec.c b/example/ipsec/odp_ipsec.c >> >>> index f2fac8a..066dc40 100644 >> >>> --- a/example/ipsec/odp_ipsec.c >> >>> +++ b/example/ipsec/odp_ipsec.c >> >>> @@ -683,7 +683,7 @@ pkt_disposition_e >> >>> do_ipsec_in_classify(odp_packet_t >> >>> pkt, >> >>> odph_esphdr_t *esp = NULL; >> >>> ipsec_cache_entry_t *entry; >> >>> odp_crypto_op_params_t params; >> >>> - bool posted = 0; >> >>> + odp_bool_t posted = 0; >> >>> >> >>> /* Default to skip IPsec */ >> >>> *skip = TRUE; >> >>> @@ -955,7 +955,7 @@ pkt_disposition_e do_ipsec_out_seq(odp_packet_t >> >>> pkt, >> >>> pkt_ctx_t *ctx) >> >>> { >> >>> uint8_t *buf = odp_packet_data(pkt); >> >>> - bool posted = 0; >> >>> + odp_bool_t posted = 0; >> >>> >> >>> /* We were dispatched from atomic queue, assign sequence >> >>> numbers >> >>> */ >> >>> if (ctx->ipsec.ah_offset) { >> >>> diff --git a/platform/linux-generic/include/api/odp_buffer.h >> >>> b/platform/linux-generic/include/api/odp_buffer.h >> >>> index 0670464..fd0871b 100644 >> >>> --- a/platform/linux-generic/include/api/odp_buffer.h >> >>> +++ b/platform/linux-generic/include/api/odp_buffer.h >> >>> @@ -32,6 +32,7 @@ extern "C" { >> >>> * Buffer start address >> >>> * >> >>> * @param buf Buffer handle >> >>> + * Note: Buffer handle must be valid or the behavior will be >> >>> undefined. >> >> >> >> >> >> Should these be @note ? Same comment for similar Note: adds. >> > Yes should use @note. >> > >> >> Phrasing in >> >> present tense (...or behavior is undefined) seems more natural, but >> >> that's a >> >> stylistic point that's I won't argue. >> > You are probably better at English than I am... I am following your >> > suggestion without argument. >> > >> > The language is a bit mixed with these undefined warnings. >> > >> > One problem I see is that if we make a @note for undefined behavior >> > for each function, we need to make that note for *all* relevant >> > functions. The omission of this note for some functions could indicate >> > that undefined behavior is not present (even in the presence of >> > invalid parameters). But I also think a global definition and >> > documentation of undefined behavior in the ODP documentation might not >> > be sufficient. Most programmers will go straight at the documentation >> > of individual functions they want to use. >> > >> > >> >> >> >>> >> >>> * >> >>> * @return Buffer start address >> >>> */ >> >>> @@ -41,6 +42,7 @@ void *odp_buffer_addr(odp_buffer_t buf); >> >>> * Buffer maximum data size >> >>> * >> >>> * @param buf Buffer handle >> >>> + * Note: Buffer handle must be valid or the behavior will be >> >>> undefined. >> >>> * >> >>> * @return Buffer maximum data size >> >>> */ >> >>> @@ -50,12 +52,12 @@ uint32_t odp_buffer_size(odp_buffer_t buf); >> >>> * Buffer type >> >>> * >> >>> * @param buf Buffer handle >> >>> + * Note: Buffer handle must be valid or the behavior will be >> >>> undefined. >> >>> * >> >>> * @return Buffer type >> >>> */ >> >>> int odp_buffer_type(odp_buffer_t buf); >> >>> >> >>> -#define ODP_BUFFER_TYPE_INVALID (-1) /**< Buffer type invalid */ >> >>> #define ODP_BUFFER_TYPE_ANY 0 /**< Buffer that can hold any >> >>> other >> >>> buffer type */ >> >>> #define ODP_BUFFER_TYPE_RAW 1 /**< Raw buffer, no additional >> >>> metadata */ >> >>> @@ -65,7 +67,9 @@ int odp_buffer_type(odp_buffer_t buf); >> >>> /** >> >>> * Tests if buffer is valid >> >>> * >> >>> - * @param buf Buffer handle >> >>> + * @param buf Buffer handle (possibly invalid) >> >>> + * Note: This is the only call which accepts invalid buffer handles >> >>> (any >> >>> bit >> >>> + * value) without causing undefined behavior. >> >> >> >> >> >> Definitely should be @note for this one. Would it be clearer to say >> >> "API" >> >> rather than "call"? Grammar nit: that rather than which is correct >> >> here. >> > Well this is just one function, the whole set of functions is an API. >> > Or is my definition of API too narrow? >> > Maybe "this API function"? >> > >> >> >> >>> >> >>> * >> >>> * @retval 1 Buffer handle represents a valid buffer. >> >>> * @retval 0 Buffer handle does not represent a valid buffer. >> >>> @@ -76,6 +80,7 @@ int odp_buffer_is_valid(odp_buffer_t buf); >> >>> * Buffer pool of the buffer >> >>> * >> >>> * @param buf Buffer handle >> >>> + * Note: Buffer handle must be valid or the behavior will be >> >>> undefined. >> >>> * >> >>> * @return Handle of buffer pool buffer belongs to >> >>> */ >> >>> diff --git a/platform/linux-generic/include/api/odp_buffer_pool.h >> >>> b/platform/linux-generic/include/api/odp_buffer_pool.h >> >>> index 8380ac1..fe917a4 100644 >> >>> --- a/platform/linux-generic/include/api/odp_buffer_pool.h >> >>> +++ b/platform/linux-generic/include/api/odp_buffer_pool.h >> >>> @@ -81,8 +81,8 @@ odp_buffer_pool_t odp_buffer_pool_create(const char >> >>> *name, >> >>> * >> >>> * @param pool Handle of the buffer pool to be destroyed >> >>> * >> >>> - * @retval 0 Success >> >>> - * @retval -1 Failure >> >>> + * @retval 0 if successful >> >>> + * @retval <0 on failure >> >>> * >> >>> * @note This routine destroys a previously created buffer pool. This >> >>> call >> >>> * does not destroy any shared memory object passed to >> >>> @@ -117,7 +117,7 @@ typedef struct odp_buffer_pool_info_t { >> >>> odp_shm_t shm; /**< handle of shared memory >> >>> area >> >>> supplied by application >> >>> to >> >>> contain buffer pool, or >> >>> - ODP_SHM_INVALID if this >> >>> pool >> >>> is >> >>> + ODP_SHM_NULL if this pool >> >>> is >> >>> managed by ODP */ >> >>> odp_buffer_pool_param_t params; /**< pool parameters */ >> >>> } odp_buffer_pool_info_t; >> >>> @@ -125,13 +125,13 @@ typedef struct odp_buffer_pool_info_t { >> >>> /** >> >>> * Retrieve information about a buffer pool >> >>> * >> >>> - * @param pool Buffer pool handle >> >>> + * @param pool Buffer pool handle (possibly invalid) >> >>> * >> >>> * @param[out] info Receives an odp_buffer_pool_info_t object >> >>> * that describes the pool. >> >>> * >> >>> - * @retval 0 Success >> >>> - * @retval -1 Failure. Info could not be retrieved. >> >>> + * @retval 0 if successful >> >>> + * @retval <0 on failure. Info could not be retrieved (invalid pool >> >>> handle) >> >>> */ >> >>> >> >>> int odp_buffer_pool_info(odp_buffer_pool_t pool, >> >>> @@ -149,17 +149,22 @@ void odp_buffer_pool_print(odp_buffer_pool_t >> >>> pool); >> >>> >> >>> /** >> >>> * Buffer alloc >> >>> + * Note: the pool handle must be valid or the behavior is undefined. >> >>> + * >> >>> + * The validity of a buffer handle can be checked at any time using >> >>> + * odp_buffer_is_valid() >> >>> * >> >>> - * The validity of a buffer can be cheked at any time with >> >>> odp_buffer_is_valid() >> >>> * @param pool Pool handle >> >>> * >> >>> * @return Handle of allocated buffer >> >>> - * @retval ODP_BUFFER_INVALID Buffer could not be allocated >> >>> + * @retval ODP_BUFFER_INVALID Buffer could not be allocated (e.g. >> >>> pool >> >>> + * exhausted) >> >>> */ >> >>> odp_buffer_t odp_buffer_alloc(odp_buffer_pool_t pool); >> >>> >> >>> /** >> >>> * Buffer free >> >>> + * Note: the buffer handle must be valid or the behavior is >> >>> undefined. >> >>> * >> >>> * @param buf Buffer handle >> >>> * >> >>> diff --git a/platform/linux-generic/include/api/odp_byteorder.h >> >>> b/platform/linux-generic/include/api/odp_byteorder.h >> >>> index 5890011..8e38937 100644 >> >>> --- a/platform/linux-generic/include/api/odp_byteorder.h >> >>> +++ b/platform/linux-generic/include/api/odp_byteorder.h >> >>> @@ -24,7 +24,7 @@ extern "C" { >> >>> #include <odp_compiler.h> >> >>> >> >>> /** @defgroup odp_compiler_optim ODP COMPILER / OPTIMIZATION >> >>> - * Macros that check byte order and byte converting operations. >> >>> + * Macros that check and convert byte order. >> >>> * @{ >> >>> */ >> >>> >> >>> diff --git a/platform/linux-generic/include/api/odp_classification.h >> >>> b/platform/linux-generic/include/api/odp_classification.h >> >>> index 46189bc..6bca8fc 100644 >> >>> --- a/platform/linux-generic/include/api/odp_classification.h >> >>> +++ b/platform/linux-generic/include/api/odp_classification.h >> >>> @@ -79,8 +79,8 @@ typedef enum odp_cos_hdr_flow_fields { >> >>> * >> >>> * @param[in] name String intended for debugging purposes. >> >>> * >> >>> - * @return Class of service instance identifier, >> >>> - * or ODP_COS_INVALID on error. >> >>> + * @return Class of service instance identifier >> >>> + * @retval ODP_COS_INVALID on failure. >> >>> */ >> >>> odp_cos_t odp_cos_create(const char *name); >> >>> >> >>> @@ -89,7 +89,8 @@ odp_cos_t odp_cos_create(const char *name); >> >>> * >> >>> * @param[in] cos_id class-of-service instance. >> >>> * >> >>> - * @return 0 on success, non-zero on error. >> >>> + * @retval 0 if successful >> >>> + * @retval <0 on failure >> >>> */ >> >>> int odp_cos_destroy(odp_cos_t cos_id); >> >>> >> >>> @@ -102,7 +103,8 @@ int odp_cos_destroy(odp_cos_t cos_id); >> >>> * of this specific class of service >> >>> * will be enqueued. >> >>> * >> >>> - * @return 0 on success, non-zero on error. >> >>> + * @retval 0 if successful >> >>> + * @retval <0 on failure >> >>> */ >> >>> int odp_cos_set_queue(odp_cos_t cos_id, odp_queue_t queue_id); >> >>> >> >>> @@ -112,7 +114,8 @@ int odp_cos_set_queue(odp_cos_t cos_id, >> >>> odp_queue_t >> >>> queue_id); >> >>> * @param[in] cos_id class-of-service instance. >> >>> * @param[in] drop_policy Desired packet drop policy for this >> >>> class. >> >>> * >> >>> - * @return 0 on success, non-zero on error. >> >>> + * @retval 0 if successful >> >>> + * @retval <0 on failure >> >>> * >> >>> * @note Optional. >> >>> */ >> >>> @@ -127,7 +130,8 @@ int odp_cos_set_drop(odp_cos_t cos_id, odp_drop_e >> >>> drop_policy); >> >>> * @param[in] qos_table Values of the Layer-2 QoS header >> >>> field. >> >>> * @param[in] cos_table Class-of-service assigned to each of >> >>> the >> >>> * allowed Layer-2 QOS levels. >> >>> - * @return 0 on success, non-zero on error. >> >>> + * @retval 0 if successful >> >>> + * @retval <0 on failure >> >>> */ >> >>> int odp_cos_with_l2_priority(odp_pktio_t pktio_in, >> >>> uint8_t num_qos, >> >>> @@ -146,7 +150,8 @@ int odp_cos_with_l2_priority(odp_pktio_t pktio_in, >> >>> * @param[in] l3_preference when true, Layer-3 QoS overrides >> >>> * L2 QoS when present. >> >>> * >> >>> - * @return 0 on success, non-zero on error. >> >>> + * @retval 0 if successful >> >>> + * @retval <0 on failure >> >>> * >> >>> * @note Optional. >> >>> */ >> >>> @@ -219,7 +224,8 @@ typedef enum odp_pmr_term { >> >>> * that must match the value size requirement of >> >>> the >> >>> * specific term. >> >>> * >> >>> - * @return Handle of the matching rule or ODP_PMR_INVAL >> >>> on >> >>> error >> >>> + * @return Handle of the matching rule >> >>> + * @retval ODP_PMR_INVAL on failure >> >>> */ >> >>> odp_pmr_t odp_pmr_create_match(odp_pmr_term_e term, >> >>> const void *val, >> >>> @@ -236,7 +242,8 @@ odp_pmr_t odp_pmr_create_match(odp_pmr_term_e >> >>> term, >> >>> * that must match the value size requirement of >> >>> the >> >>> * specific term. >> >>> * >> >>> - * @return Handle of the matching rule or ODP_PMR_INVAL >> >>> on >> >>> error >> >>> + * @return Handle of the matching rule >> >>> + * @retval ODP_PMR_INVAL on failure >> >>> * @note: Range is inclusive [val1..val2]. >> >>> */ >> >>> odp_pmr_t odp_pmr_create_range(odp_pmr_term_e term, >> >>> @@ -248,7 +255,8 @@ odp_pmr_t odp_pmr_create_range(odp_pmr_term_e >> >>> term, >> >>> * >> >>> * @param[in] pmr_id Identifier of the PMR to be destroyed >> >>> * >> >>> - * @return 0 on success, non-zero or error. >> >>> + * @retval 0 if successful >> >>> + * @retval <0 on failure >> >>> */ >> >>> int odp_pmr_destroy(odp_pmr_t pmr_id); >> >>> >> >>> @@ -259,7 +267,8 @@ int odp_pmr_destroy(odp_pmr_t pmr_id); >> >>> * @param[in] src_pktio pktio to which this PMR is to be >> >>> applied >> >>> * @param[in] dst_cos CoS to be assigned by this PMR >> >>> * >> >>> - * @return 0 on success, non-zero or error. >> >>> + * @retval 0 if successful >> >>> + * @retval <0 on failure >> >>> */ >> >>> int odp_pktio_pmr_cos(odp_pmr_t pmr_id, >> >>> odp_pktio_t src_pktio, odp_cos_t dst_cos); >> >>> @@ -272,7 +281,8 @@ int odp_pktio_pmr_cos(odp_pmr_t pmr_id, >> >>> * @param[in] dst_cos CoS to be assigned to packets filtered >> >>> * from src_cos that match pmr_id. >> >>> * >> >>> - * @return 0 on success, non-zero on error. >> >>> + * @retval 0 if successful >> >>> + * @retval <0 on failure >> >>> */ >> >>> int odp_cos_pmr_cos(odp_pmr_t pmr_id, odp_cos_t src_cos, odp_cos_t >> >>> dst_cos); >> >>> >> >>> @@ -346,12 +356,10 @@ typedef uint32_t odp_pmr_set_t; >> >>> * term desired. >> >>> * @param[out] pmr_set_id Returned handle to the composite rule >> >>> set. >> >>> * >> >>> - * @return Return value may be a positive number >> >>> - * indicating the number of terms >> >>> elements >> >>> + * @return the number of terms elements >> >>> * that have been successfully mapped to >> >>> the >> >>> - * underlying platform classification >> >>> engine >> >>> and >> >>> - * may be in the range from 1 to >> >>> num_terms, >> >>> - * or non-zero for error. >> >>> + * underlying platform classification >> >>> engine >> >>> + * @retval <0 on failure >> >>> */ >> >>> int odp_pmr_match_set_create(int num_terms, odp_pmr_match_t *terms, >> >>> odp_pmr_set_t *pmr_set_id); >> >>> @@ -369,7 +377,8 @@ int odp_pmr_match_set_create(int num_terms, >> >>> odp_pmr_match_t *terms, >> >>> * @param[in] pmr_set_id A composite rule-set handle >> >>> * returned when created. >> >>> * >> >>> - * @return 0 on success, non-zero on error. >> >>> + * @retval 0 if successful >> >>> + * @retval <0 on failure >> >>> */ >> >>> int odp_pmr_match_set_destroy(odp_pmr_set_t pmr_set_id); >> >>> >> >>> @@ -381,7 +390,8 @@ int odp_pmr_match_set_destroy(odp_pmr_set_t >> >>> pmr_set_id); >> >>> * set is to be applied >> >>> * @param[in] dst_cos CoS to be assigned by this PMR match >> >>> set >> >>> * >> >>> - * @return 0 on success, non-zero or error. >> >>> + * @retval 0 if successful >> >>> + * @retval <0 on failure >> >>> */ >> >>> int odp_pktio_pmr_match_set_cos(odp_pmr_set_t pmr_set_id, odp_pktio_t >> >>> src_pktio, >> >>> odp_cos_t dst_cos); >> >>> diff --git a/platform/linux-generic/include/api/odp_cpumask.h >> >>> b/platform/linux-generic/include/api/odp_cpumask.h >> >>> index ebff9b0..5c5bcd7 100644 >> >>> --- a/platform/linux-generic/include/api/odp_cpumask.h >> >>> +++ b/platform/linux-generic/include/api/odp_cpumask.h >> >>> @@ -79,7 +79,8 @@ void odp_cpumask_clr(odp_cpumask_t *mask, int cpu); >> >>> * Test if cpu is a member of mask >> >>> * @param mask CPU mask to check if cpu num set or not >> >>> * @param cpu CPU number >> >>> - * @return non-zero if set otherwise 0 >> >>> + * @return non-zero if set >> >>> + * @retval 0 if not set >> >>> */ >> >>> int odp_cpumask_isset(const odp_cpumask_t *mask, int cpu); >> >>> >> >>> @@ -134,14 +135,16 @@ void odp_cpumask_copy(odp_cpumask_t *dest, const >> >>> odp_cpumask_t *src); >> >>> /** >> >>> * Find first bit set in mask >> >>> * >> >>> - * @return cpu else -1 if no bits set in cpumask >> >>> + * @return cpu >> >>> + * @retval -1 if no bits set in cpumask >> >> >> >> >> >> Should this be <0 for consistency with other error RC descriptions? >> > Possibly. I was a little loath at changing the definitions of these >> > basically bit set operations (where return values might be the direct >> > results of binary/arithmetic operations) but this one could be unified >> > with the rest without any problems. It was also getting rather late in >> > the evening, I was probably not thinking too clearly at the end. >> > I changed all three remaining instances in this file. >> > >> >> >> >>> >> >>> */ >> >>> int odp_cpumask_first(const odp_cpumask_t *mask); >> >>> >> >>> /** >> >>> * Find last bit set in mask >> >>> * >> >>> - * @return cpu else -1 if no bits set in cpumask >> >>> + * @return cpu >> >>> + * @retval -1 if no bits set in cpumask >> >> >> >> >> >> Same here. <0 ? >> > yes >> > >> >> >> >>> >> >>> */ >> >>> int odp_cpumask_last(const odp_cpumask_t *mask); >> >>> >> >>> @@ -160,7 +163,8 @@ int odp_cpumask_last(const odp_cpumask_t *mask); >> >>> * >> >>> * @param mask CPU mask to find next cpu in >> >>> * @param cpu CPU to start from >> >>> - * @return cpu found else -1 >> >>> + * @return cpu found >> >>> + * @retval -1 if not found >> >> >> >> >> >> And again here. >> > yes >> > >> >> >> >>> >> >>> * >> >>> * @see odp_cpumask_first() >> >>> */ >> >>> diff --git a/platform/linux-generic/include/api/odp_crypto.h >> >>> b/platform/linux-generic/include/api/odp_crypto.h >> >>> index 337e7cf..2f00f95 100644 >> >>> --- a/platform/linux-generic/include/api/odp_crypto.h >> >>> +++ b/platform/linux-generic/include/api/odp_crypto.h >> >>> @@ -218,7 +218,8 @@ typedef struct odp_crypto_compl_status { >> >>> * @param session Created session else >> >>> ODP_CRYPTO_SESSION_INVALID >> >>> * @param status Failure code if unsuccessful >> >>> * >> >>> - * @return 0 if successful else -1 >> >>> + * @retval 0 if successful >> >>> + * @retval <0 on failure >> >>> */ >> >>> int >> >>> odp_crypto_session_create(odp_crypto_session_params_t *params, >> >>> @@ -242,11 +243,12 @@ >> >>> odp_crypto_session_create(odp_crypto_session_params_t *params, >> >>> * @param posted Pointer to return posted, TRUE for async >> >>> operation >> >>> * @param completion_event Event by which the operation results are >> >>> delivered. >> >>> * >> >>> - * @return 0 if successful else -1 >> >>> + * @retval 0 if successful >> >>> + * @retval <0 on failure >> >>> */ >> >>> int >> >>> odp_crypto_operation(odp_crypto_op_params_t *params, >> >>> - bool *posted, >> >>> + odp_bool_t *posted, >> >>> odp_buffer_t completion_event); >> >>> >> >>> /** >> >>> @@ -281,7 +283,7 @@ odp_crypto_get_operation_compl_status(odp_buffer_t >> >>> completion_event, >> >>> * >> >>> * @param completion_event Event containing operation results >> >>> * >> >>> - * @return Packet structure where data now resides >> >>> + * @return Handle for packet where data now resides >> >>> */ >> >>> odp_packet_t >> >>> odp_crypto_get_operation_compl_packet(odp_buffer_t completion_event); >> >>> @@ -305,10 +307,11 @@ odp_crypto_get_operation_compl_ctx(odp_buffer_t >> >>> completion_event); >> >>> * >> >>> * @todo Define the implication of the use_entropy parameter >> >>> * >> >>> - * @return 0 if succesful >> >>> + * @retval 0 if successful >> >>> + * @retval <0 on failure >> >>> */ >> >>> int >> >>> -odp_hw_random_get(uint8_t *buf, size_t *len, bool use_entropy); >> >>> +odp_hw_random_get(uint8_t *buf, size_t *len, odp_bool_t use_entropy); >> >>> >> >>> /** >> >>> * @} >> >>> diff --git a/platform/linux-generic/include/api/odp_init.h >> >>> b/platform/linux-generic/include/api/odp_init.h >> >>> index ac856df..4a98717 100644 >> >>> --- a/platform/linux-generic/include/api/odp_init.h >> >>> +++ b/platform/linux-generic/include/api/odp_init.h >> >>> @@ -66,8 +66,8 @@ typedef enum odp_log_level { >> >>> * @param[in] level Log level >> >>> * @param[in] fmt printf-style message format >> >>> * >> >>> - * @return The number of characters logged if succeeded. Otherwise >> >>> returns >> >>> - * a negative number. >> >>> + * @return The number of characters logged if successful >> >>> + * @retval <0 on failure >> >>> */ >> >>> int odp_override_log(odp_log_level_e level, const char *fmt, ...); >> >>> >> >>> @@ -109,7 +109,7 @@ typedef struct odp_platform_init_t { >> >>> * interpretation by the ODP API to the implementation. >> >>> * >> >>> * @retval 0 if successful >> >>> - * @retval -1 on failure >> >>> + * @retval <0 on failure >> >>> */ >> >>> int odp_init_global(odp_init_t *params, odp_platform_init_t >> >>> *platform_params); >> >>> >> >>> @@ -134,7 +134,7 @@ int odp_init_global(odp_init_t *params, >> >>> odp_platform_init_t *platform_params); >> >>> * @sa odp_term_local() which must have been called prior to this. >> >>> * >> >>> * @retval 0 if successful >> >>> - * @retval -1 on failure >> >>> + * @retval <0 on failure >> >>> */ >> >>> int odp_term_global(void); >> >>> >> >>> @@ -148,7 +148,7 @@ int odp_term_global(void); >> >>> * @sa odp_init_global() which must have been called prior to this. >> >>> * >> >>> * @retval 0 if successful >> >>> - * @retval -1 on failure >> >>> + * @retval <0 on failure >> >>> */ >> >>> int odp_init_local(void); >> >>> >> >>> diff --git a/platform/linux-generic/include/api/odp_packet.h >> >>> b/platform/linux-generic/include/api/odp_packet.h >> >>> index 920a593..b471d07 100644 >> >>> --- a/platform/linux-generic/include/api/odp_packet.h >> >>> +++ b/platform/linux-generic/include/api/odp_packet.h >> >>> @@ -88,8 +88,8 @@ void odp_packet_free(odp_packet_t pkt); >> >>> * @param pkt Packet handle >> >>> * @param len Packet data length >> >>> * >> >>> - * @retval 0 Success >> >>> - * @retval Non-zero Failure >> >>> + * @retval 0 if successful >> >>> + * @retval <0 on failure >> >>> * >> >>> * @see odp_packet_buf_len() >> >>> */ >> >>> @@ -279,7 +279,7 @@ void *odp_packet_push_head(odp_packet_t pkt, >> >>> uint32_t >> >>> len); >> >>> * @param pkt Packet handle >> >>> * @param len Number of bytes to pull the head (0 ... seg_len - 1) >> >>> * >> >>> - * @return The new data pointer, or NULL in case of an error. >> >>> + * @return The new data pointer >> >>> * @retval NULL Requested offset exceeds packet segment length >> >>> >> >>> * >> >>> * @see odp_packet_seg_len(), odp_packet_push_head() >> >>> @@ -391,7 +391,7 @@ odp_buffer_pool_t odp_packet_pool(odp_packet_t >> >>> pkt); >> >>> * @param pkt Packet handle >> >>> * >> >>> * @return Packet interface handle >> >>> - * @retval ODP_PKTIO_INVALID Packet was not received >> >>> + * @retval ODP_PKTIO_INVALID Packet was not received on any >> >>> interface >> >>> */ >> >>> odp_pktio_t odp_packet_input(odp_packet_t pkt); >> >>> >> >>> @@ -451,8 +451,8 @@ void odp_packet_user_u64_set(odp_packet_t pkt, >> >>> uint64_t ctx); >> >>> * @param[out] len Number of data bytes remaining in the segment >> >>> (output). >> >>> * Ignored when NULL. >> >>> * >> >>> - * @return Layer 2 start pointer, or NULL when packet does not >> >>> contain a >> >>> valid >> >>> - * L2 header. >> >>> + * @return Layer 2 start pointer >> >>> + * @retval NULL packet does not contain a valid L2 header >> >>> * >> >>> * @see odp_packet_l2_offset(), odp_packet_l2_offset_set(), >> >>> odp_packet_has_l2() >> >>> */ >> >>> @@ -469,8 +469,8 @@ void *odp_packet_l2_ptr(odp_packet_t pkt, uint32_t >> >>> *len); >> >>> * >> >>> * @param pkt Packet handle >> >>> * >> >>> - * @return Layer 2 start offset, or ODP_PACKET_OFFSET_INVALID when >> >>> packet does >> >>> - * not contain a valid L2 header. >> >>> + * @return Layer 2 start offset >> >>> + * @retval ODP_PACKET_OFFSET_INVALID packet does not contain a valid >> >>> L2 >> >>> header >> >>> * >> >>> * @see odp_packet_l2_offset_set(), odp_packet_has_l2() >> >>> */ >> >>> @@ -486,8 +486,8 @@ uint32_t odp_packet_l2_offset(odp_packet_t pkt); >> >>> * @param pkt Packet handle >> >>> * @param offset Layer 2 start offset (0 ... odp_packet_len()-1) >> >>> * >> >>> - * @retval 0 Success >> >>> - * @retval Non-zero Failure >> >>> + * @retval 0 if successful >> >>> + * @retval <0 on failure >> >>> */ >> >>> int odp_packet_l2_offset_set(odp_packet_t pkt, uint32_t offset); >> >>> >> >>> @@ -501,8 +501,8 @@ int odp_packet_l2_offset_set(odp_packet_t pkt, >> >>> uint32_t offset); >> >>> * @param[out] len Number of data bytes remaining in the segment >> >>> (output). >> >>> * Ignored when NULL. >> >>> * >> >>> - * @return Layer 3 start pointer, or NULL when packet does not >> >>> contain a >> >>> valid >> >>> - * L3 header. >> >>> + * @return Layer 3 start pointer >> >>> + * @retval NULL packet does not contain a valid L3 header >> >>> * >> >>> * @see odp_packet_l3_offset(), odp_packet_l3_offset_set(), >> >>> odp_packet_has_l3() >> >>> */ >> >>> @@ -536,8 +536,8 @@ uint32_t odp_packet_l3_offset(odp_packet_t pkt); >> >>> * @param pkt Packet handle >> >>> * @param offset Layer 3 start offset (0 ... odp_packet_len()-1) >> >>> * >> >>> - * @retval 0 Success >> >>> - * @retval Non-zero Failure >> >>> + * @retval 0 if successful >> >>> + * @retval <0 on failure >> >>> */ >> >>> int odp_packet_l3_offset_set(odp_packet_t pkt, uint32_t offset); >> >>> >> >>> @@ -551,8 +551,8 @@ int odp_packet_l3_offset_set(odp_packet_t pkt, >> >>> uint32_t offset); >> >>> * @param[out] len Number of data bytes remaining in the segment >> >>> (output). >> >>> * Ignored when NULL. >> >>> * >> >>> - * @return Layer 4 start pointer, or NULL when packet does not >> >>> contain a >> >>> valid >> >>> - * L4 header. >> >>> + * @return Layer 4 start pointer >> >>> + * @retval NULL packet does not contain a valid L4 header >> >>> * >> >>> * @see odp_packet_l4_offset(), odp_packet_l4_offset_set(), >> >>> odp_packet_has_l4() >> >>> */ >> >>> @@ -569,8 +569,8 @@ void *odp_packet_l4_ptr(odp_packet_t pkt, uint32_t >> >>> *len); >> >>> * >> >>> * @param pkt Packet handle >> >>> * >> >>> - * @return Layer 4 start offset, or ODP_PACKET_OFFSET_INVALID when >> >>> packet does >> >>> - * not contain a valid L4 header. >> >>> + * @return Layer 4 start offset >> >>> + * @retval ODP_PACKET_OFFSET_INVALID packet does not contain a valid >> >>> L4 >> >>> header >> >>> * >> >>> * @see odp_packet_l4_offset_set(), odp_packet_has_l4() >> >>> */ >> >>> @@ -586,8 +586,8 @@ uint32_t odp_packet_l4_offset(odp_packet_t pkt); >> >>> * @param pkt Packet handle >> >>> * @param offset Layer 4 start offset (0 ... odp_packet_len()-1) >> >>> * >> >>> - * @retval 0 Success >> >>> - * @retval Non-zero Failure >> >>> + * @retval 0 on success >> >>> + * @retval <0 on failure >> >>> */ >> >>> int odp_packet_l4_offset_set(odp_packet_t pkt, uint32_t offset); >> >>> >> >>> @@ -645,7 +645,8 @@ odp_packet_seg_t odp_packet_last_seg(odp_packet_t >> >>> pkt); >> >>> * @param pkt Packet handle >> >>> * @param seg Current segment handle >> >>> * >> >>> - * @return Handle to the next segment, or ODP_PACKET_SEG_INVALID >> >>> + * @return Handle to the next segment >> >>> + * @retval ODP_PACKET_SEG_INVALID if there are no more segments >> >>> */ >> >>> odp_packet_seg_t odp_packet_next_seg(odp_packet_t pkt, >> >>> odp_packet_seg_t >> >>> seg); >> >>> >> >>> @@ -665,7 +666,8 @@ odp_packet_seg_t odp_packet_next_seg(odp_packet_t >> >>> pkt, >> >>> odp_packet_seg_t seg); >> >>> * @param pkt Packet handle >> >>> * @param seg Segment handle >> >>> * >> >>> - * @return Start address of the segment, or NULL on an error >> >>> + * @return Start address of the segment >> >>> + * @retval NULL on failure >> >>> * >> >>> * @see odp_packet_seg_buf_len() >> >>> */ >> >>> @@ -693,7 +695,8 @@ uint32_t odp_packet_seg_buf_len(odp_packet_t pkt, >> >>> odp_packet_seg_t seg); >> >>> * @param pkt Packet handle >> >>> * @param seg Segment handle >> >>> * >> >>> - * @return Pointer to the segment data, or NULL on an error >> >>> + * @return Pointer to the segment data >> >>> + * @retval NULL on failure >> >>> * >> >>> * @see odp_packet_seg_data_len() >> >>> */ >> >>> @@ -735,7 +738,8 @@ uint32_t odp_packet_seg_data_len(odp_packet_t pkt, >> >>> odp_packet_seg_t seg); >> >>> * @param offset Byte offset into the packet >> >>> * @param len Number of bytes to add into the offset >> >>> * >> >>> - * @return New packet handle, or ODP_PACKET_INVALID in case of an >> >>> error. >> >>> + * @return New packet handle >> >>> + * @retval ODP_PACKET_INVALID on failure >> >>> */ >> >>> odp_packet_t odp_packet_add_data(odp_packet_t pkt, uint32_t offset, >> >>> uint32_t len); >> >>> @@ -753,7 +757,8 @@ odp_packet_t odp_packet_add_data(odp_packet_t pkt, >> >>> uint32_t offset, >> >>> * @param offset Byte offset into the packet >> >>> * @param len Number of bytes to remove from the offset >> >>> * >> >>> - * @return New packet handle, or ODP_PACKET_INVALID in case of an >> >>> error. >> >>> + * @return New packet handle >> >>> + * @retval ODP_PACKET_INVALID on failure >> >>> */ >> >>> odp_packet_t odp_packet_rem_data(odp_packet_t pkt, uint32_t offset, >> >>> uint32_t len); >> >>> @@ -776,7 +781,8 @@ odp_packet_t odp_packet_rem_data(odp_packet_t pkt, >> >>> uint32_t offset, >> >>> * @param pkt Packet handle >> >>> * @param pool Buffer pool for allocation of the new packet. >> >>> * >> >>> - * @return Handle to the copy of the packet, or ODP_PACKET_INVALID >> >>> + * @return Handle to the copy of the packet >> >>> + * @retval ODP_PACKET_INVALID on failure >> >>> */ >> >>> odp_packet_t odp_packet_copy(odp_packet_t pkt, odp_buffer_pool_t >> >>> pool); >> >>> >> >>> @@ -791,8 +797,8 @@ odp_packet_t odp_packet_copy(odp_packet_t pkt, >> >>> odp_buffer_pool_t pool); >> >>> * @param len Number of bytes to copy >> >>> * @param dst Destination address >> >>> * >> >>> - * @retval 0 Success >> >>> - * @retval Non-zero Failure >> >>> + * @retval 0 on success >> >>> + * @retval <0 on failure >> >>> */ >> >>> int odp_packet_copydata_out(odp_packet_t pkt, uint32_t offset, >> >>> uint32_t len, void *dst); >> >>> @@ -809,8 +815,8 @@ int odp_packet_copydata_out(odp_packet_t pkt, >> >>> uint32_t >> >>> offset, >> >>> * @param len Number of bytes to copy >> >>> * @param src Source address >> >>> * >> >>> - * @retval 0 Success >> >>> - * @retval Non-zero Failure >> >>> + * @retval 0 on success >> >>> + * @retval <0 on failure >> >>> */ >> >>> int odp_packet_copydata_in(odp_packet_t pkt, uint32_t offset, >> >>> uint32_t len, const void *src); >> >>> diff --git a/platform/linux-generic/include/api/odp_packet_flags.h >> >>> b/platform/linux-generic/include/api/odp_packet_flags.h >> >>> index 24c4065..399a0bf 100644 >> >>> --- a/platform/linux-generic/include/api/odp_packet_flags.h >> >>> +++ b/platform/linux-generic/include/api/odp_packet_flags.h >> >>> @@ -32,7 +32,8 @@ extern "C" { >> >>> * Checks all error flags at once. >> >>> * >> >>> * @param pkt Packet handle >> >>> - * @return 1 if packet has errors, 0 otherwise >> >>> + * @retval 1 if packet has errors >> >>> + * @retval 0 if packet has no errors >> >>> */ >> >>> int odp_packet_error(odp_packet_t pkt); >> >>> >> >>> @@ -40,7 +41,8 @@ int odp_packet_error(odp_packet_t pkt); >> >>> * Check if error was 'frame length' error >> >>> * >> >>> * @param pkt Packet handle >> >>> - * @return 1 if frame length error detected, 0 otherwise >> >>> + * @retval 1 if frame length error detected >> >>> + * @retval 0 if frame length error not detected >> >>> */ >> >>> int odp_packet_errflag_frame_len(odp_packet_t pkt); >> >>> >> >>> @@ -48,7 +50,8 @@ int odp_packet_errflag_frame_len(odp_packet_t pkt); >> >>> * Check for L2 header, e.g. ethernet >> >>> * >> >>> * @param pkt Packet handle >> >>> - * @return 1 if packet contains a valid & known L2 header, 0 >> >>> otherwise >> >>> + * @retval 1 if packet contains a valid & known L2 header >> >>> + * @retval 0 if packet does not contain a valid & known L2 header >> >>> */ >> >>> int odp_packet_has_l2(odp_packet_t pkt); >> >>> >> >>> @@ -56,7 +59,8 @@ int odp_packet_has_l2(odp_packet_t pkt); >> >>> * Check for L3 header, e.g. IPv4, IPv6 >> >>> * >> >>> * @param pkt Packet handle >> >>> - * @return 1 if packet contains a valid & known L3 header, 0 >> >>> otherwise >> >>> + * @retval 1 if packet contains a valid & known L3 header >> >>> + * @retval 0 if packet does not contain a valid & known L3 header >> >>> */ >> >>> int odp_packet_has_l3(odp_packet_t pkt); >> >>> >> >>> @@ -64,7 +68,8 @@ int odp_packet_has_l3(odp_packet_t pkt); >> >>> * Check for L4 header, e.g. UDP, TCP, SCTP (also ICMP) >> >>> * >> >>> * @param pkt Packet handle >> >>> - * @return 1 if packet contains a valid & known L4 header, 0 >> >>> otherwise >> >>> + * @retval 1 if packet contains a valid & known L4 header >> >>> + * @retval 0 if packet does not contain a valid & known L4 header >> >>> */ >> >>> int odp_packet_has_l4(odp_packet_t pkt); >> >>> >> >>> @@ -72,7 +77,8 @@ int odp_packet_has_l4(odp_packet_t pkt); >> >>> * Check for Ethernet header >> >>> * >> >>> * @param pkt Packet handle >> >>> - * @return 1 if packet contains a valid eth header, 0 otherwise >> >>> + * @retval 1 if packet contains a valid eth header >> >>> + * @retval 0 if packet does not contain a valid & known eth header >> >>> */ >> >>> int odp_packet_has_eth(odp_packet_t pkt); >> >>> >> >>> @@ -80,7 +86,8 @@ int odp_packet_has_eth(odp_packet_t pkt); >> >>> * Check for jumbo frame >> >>> * >> >>> * @param pkt Packet handle >> >>> - * @return 1 if packet contains jumbo frame, 0 otherwise >> >>> + * @retval 1 if packet contains a jumbo frame >> >>> + * @retval 0 if packet does not contain a jumbo frame >> >>> */ >> >>> int odp_packet_has_jumbo(odp_packet_t pkt); >> >>> >> >>> @@ -88,7 +95,8 @@ int odp_packet_has_jumbo(odp_packet_t pkt); >> >>> * Check for VLAN >> >>> * >> >>> * @param pkt Packet handle >> >>> - * @return 1 if packet contains a VLAN header, 0 otherwise >> >>> + * @retval 1 if packet contains a VLAN header >> >>> + * @retval 0 if packet does not contain a VLAN header >> >>> */ >> >>> int odp_packet_has_vlan(odp_packet_t pkt); >> >>> >> >>> @@ -96,7 +104,8 @@ int odp_packet_has_vlan(odp_packet_t pkt); >> >>> * Check for VLAN QinQ (stacked VLAN) >> >>> * >> >>> * @param pkt Packet handle >> >>> - * @return 1 if packet contains a VLAN QinQ header, 0 otherwise >> >>> + * @retval 1 if packet contains a VLAN QinQ header >> >>> + * @retval 0 if packet does not contain a VLAN QinQ header >> >>> */ >> >>> int odp_packet_has_vlan_qinq(odp_packet_t pkt); >> >>> >> >>> @@ -104,7 +113,8 @@ int odp_packet_has_vlan_qinq(odp_packet_t pkt); >> >>> * Check for ARP >> >>> * >> >>> * @param pkt Packet handle >> >>> - * @return 1 if packet contains an ARP header, 0 otherwise >> >>> + * @retval 1 if packet contains an ARP message >> >>> + * @retval 0 if packet does not contain an ARP message >> >>> */ >> >>> int odp_packet_has_arp(odp_packet_t pkt); >> >>> >> >>> @@ -112,7 +122,8 @@ int odp_packet_has_arp(odp_packet_t pkt); >> >>> * Check for IPv4 >> >>> * >> >>> * @param pkt Packet handle >> >>> - * @return 1 if packet contains an IPv4 header, 0 otherwise >> >>> + * @retval 1 if packet contains an IPv4 header >> >>> + * @retval 0 if packet does not contain an IPv4 header >> >>> */ >> >>> int odp_packet_has_ipv4(odp_packet_t pkt); >> >>> >> >>> @@ -120,7 +131,8 @@ int odp_packet_has_ipv4(odp_packet_t pkt); >> >>> * Check for IPv6 >> >>> * >> >>> * @param pkt Packet handle >> >>> - * @return 1 if packet contains an IPv6 header, 0 otherwise >> >>> + * @retval 1 if packet contains an IPv6 header >> >>> + * @retval 0 if packet does not contain an IPv6 header >> >>> */ >> >>> int odp_packet_has_ipv6(odp_packet_t pkt); >> >>> >> >>> @@ -128,7 +140,8 @@ int odp_packet_has_ipv6(odp_packet_t pkt); >> >>> * Check for IP fragment >> >>> * >> >>> * @param pkt Packet handle >> >>> - * @return 1 if packet is an IP fragment, 0 otherwise >> >>> + * @retval 1 if packet is an IP fragment >> >>> + * @retval 0 if packet is not an IP fragment >> >>> */ >> >>> int odp_packet_has_ipfrag(odp_packet_t pkt); >> >>> >> >>> @@ -136,7 +149,8 @@ int odp_packet_has_ipfrag(odp_packet_t pkt); >> >>> * Check for IP options >> >>> * >> >>> * @param pkt Packet handle >> >>> - * @return 1 if packet contains IP options, 0 otherwise >> >>> + * @retval 1 if packet contains IP options >> >>> + * @retval 0 if packet does not contain IP options >> >>> */ >> >>> int odp_packet_has_ipopt(odp_packet_t pkt); >> >>> >> >>> @@ -144,7 +158,8 @@ int odp_packet_has_ipopt(odp_packet_t pkt); >> >>> * Check for IPSec >> >>> * >> >>> * @param pkt Packet handle >> >>> - * @return 1 if packet requires IPSec processing, 0 otherwise >> >>> + * @retval 1 if packet requires IPSec processing >> >>> + * @retval 0 if packet does not require IPSec processing >> >>> */ >> >>> int odp_packet_has_ipsec(odp_packet_t pkt); >> >>> >> >>> @@ -152,7 +167,8 @@ int odp_packet_has_ipsec(odp_packet_t pkt); >> >>> * Check for UDP >> >>> * >> >>> * @param pkt Packet handle >> >>> - * @return 1 if packet contains a UDP header, 0 otherwise >> >>> + * @retval 1 if packet contains a UDP header >> >>> + * @retval 0 if packet does not contain a UDP header >> >>> */ >> >>> int odp_packet_has_udp(odp_packet_t pkt); >> >>> >> >>> @@ -160,7 +176,8 @@ int odp_packet_has_udp(odp_packet_t pkt); >> >>> * Check for TCP >> >>> * >> >>> * @param pkt Packet handle >> >>> - * @return 1 if packet contains a TCP header, 0 otherwise >> >>> + * @retval 1 if packet contains a TCP header >> >>> + * @retval 0 if packet does not contain a TCP header >> >>> */ >> >>> int odp_packet_has_tcp(odp_packet_t pkt); >> >>> >> >>> @@ -168,7 +185,8 @@ int odp_packet_has_tcp(odp_packet_t pkt); >> >>> * Check for SCTP >> >>> * >> >>> * @param pkt Packet handle >> >>> - * @return 1 if packet contains an SCTP header, 0 otherwise >> >>> + * @retval 1 if packet contains a SCTP header >> >>> + * @retval 0 if packet does not contain a SCTP header >> >>> */ >> >>> int odp_packet_has_sctp(odp_packet_t pkt); >> >>> >> >>> @@ -176,7 +194,8 @@ int odp_packet_has_sctp(odp_packet_t pkt); >> >>> * Check for ICMP >> >>> * >> >>> * @param pkt Packet handle >> >>> - * @return 1 if packet contains an ICMP header, 0 otherwise >> >>> + * @retval 1 if packet contains an ICMP header >> >>> + * @retval 0 if packet does not contain an ICMP header >> >>> */ >> >>> int odp_packet_has_icmp(odp_packet_t pkt); >> >>> >> >>> diff --git a/platform/linux-generic/include/api/odp_packet_io.h >> >>> b/platform/linux-generic/include/api/odp_packet_io.h >> >>> index 4835f4d..1a770b6 100644 >> >>> --- a/platform/linux-generic/include/api/odp_packet_io.h >> >>> +++ b/platform/linux-generic/include/api/odp_packet_io.h >> >>> @@ -40,7 +40,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 >> >>> @@ -53,7 +54,8 @@ odp_pktio_t odp_pktio_open(const char *dev, >> >>> odp_buffer_pool_t pool); >> >>> * >> >>> * @param id 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); >> >>> >> >>> @@ -62,7 +64,8 @@ int odp_pktio_close(odp_pktio_t id); >> >>> * >> >>> * @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); >> >>> >> >>> @@ -73,7 +76,8 @@ odp_pktio_t odp_pktio_lookup(const char *dev); >> >>> * @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); >> >>> >> >>> @@ -84,7 +88,8 @@ int odp_pktio_recv(odp_pktio_t id, odp_packet_t >> >>> pkt_table[], unsigned len); >> >>> * @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); >> >>> >> >>> @@ -93,7 +98,8 @@ int odp_pktio_send(odp_pktio_t id, odp_packet_t >> >>> pkt_table[], unsigned len); >> >>> * >> >>> * @param id 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); >> >>> >> >>> @@ -102,7 +108,8 @@ int odp_pktio_inq_setdef(odp_pktio_t id, >> >>> odp_queue_t >> >>> queue); >> >>> * >> >>> * @param id 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); >> >>> >> >>> @@ -111,7 +118,8 @@ odp_queue_t odp_pktio_inq_getdef(odp_pktio_t id); >> >>> * >> >>> * @param id 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); >> >>> >> >>> @@ -120,7 +128,8 @@ int odp_pktio_inq_remdef(odp_pktio_t id); >> >>> * >> >>> * @param id 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); >> >>> >> >>> @@ -129,8 +138,8 @@ odp_queue_t odp_pktio_outq_getdef(odp_pktio_t id); >> >>> * >> >>> * @param[in] id 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); >> >>> >> >>> @@ -140,8 +149,8 @@ int odp_pktio_mtu(odp_pktio_t id); >> >>> * @param[in] id 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); >> >>> >> >>> @@ -152,7 +161,7 @@ int odp_pktio_promisc_mode_set(odp_pktio_t id, >> >>> odp_bool_t enable); >> >>> * >> >>> * @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); >> >>> >> >>> @@ -163,9 +172,10 @@ int odp_pktio_promisc_mode(odp_pktio_t id); >> >>> * @param[out] mac_addr Storage for MAC address of the packet IO >> >>> interface. >> >>> * @param addr_size Storage size for the address >> >>> * >> >>> - * @retval Number of bytes written on success, 0 on failure. >> >>> + * @return Number of bytes written on success >> >>> + * @retval <0 on failure >> >>> */ >> >>> -size_t odp_pktio_mac_addr(odp_pktio_t id, void *mac_addr, >> >>> +int odp_pktio_mac_addr(odp_pktio_t id, void *mac_addr, >> >>> size_t addr_size); >> >>> >> >>> /** >> >>> @@ -177,7 +187,8 @@ size_t odp_pktio_mac_addr(odp_pktio_t id, void >> >>> *mac_addr, >> >>> * 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); >> >>> >> >>> @@ -189,7 +200,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. >> >>> */ >> >>> @@ -201,7 +213,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. >> >>> * >> >>> */ >> >>> @@ -216,7 +229,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. >> >>> */ >> >>> diff --git a/platform/linux-generic/include/api/odp_queue.h >> >>> b/platform/linux-generic/include/api/odp_queue.h >> >>> index b0f7185..25633e0 100644 >> >>> --- a/platform/linux-generic/include/api/odp_queue.h >> >>> +++ b/platform/linux-generic/include/api/odp_queue.h >> >>> @@ -118,7 +118,8 @@ typedef struct odp_queue_param_t { >> >>> * @param type Queue type >> >>> * @param param Queue parameters. Uses defaults if NULL. >> >>> * >> >>> - * @return Queue handle or ODP_QUEUE_INVALID >> >>> + * @return Queue handle >> >>> + * @retval ODP_QUEUE_INVALID on failure >> >>> */ >> >>> odp_queue_t odp_queue_create(const char *name, odp_queue_type_t type, >> >>> odp_queue_param_t *param); >> >>> @@ -133,7 +134,8 @@ odp_queue_t odp_queue_create(const char *name, >> >>> odp_queue_type_t type, >> >>> * >> >>> * @param queue Queue handle >> >>> * >> >>> - * @return 0 if successful >> >>> + * @retval 0 on success >> >>> + * @retval <0 on failure >> >>> */ >> >>> int odp_queue_destroy(odp_queue_t queue); >> >>> >> >>> @@ -142,7 +144,8 @@ int odp_queue_destroy(odp_queue_t queue); >> >>> * >> >>> * @param name Queue name >> >>> * >> >>> - * @return Queue handle or ODP_QUEUE_INVALID >> >>> + * @return Queue handle >> >>> + * @retval ODP_QUEUE_INVALID on failure >> >>> */ >> >>> odp_queue_t odp_queue_lookup(const char *name); >> >>> >> >>> @@ -156,7 +159,8 @@ odp_queue_t odp_queue_lookup(const char *name); >> >>> * @param queue Queue handle >> >>> * @param context Address to the queue context >> >>> * >> >>> - * @return 0 if successful >> >>> + * @retval 0 on success >> >>> + * @retval <0 on failure >> >>> */ >> >>> int odp_queue_set_context(odp_queue_t queue, void *context); >> >>> >> >>> @@ -165,8 +169,8 @@ int odp_queue_set_context(odp_queue_t queue, void >> >>> *context); >> >>> * >> >>> * @param queue Queue handle >> >>> * >> >>> - * @return If successful, a pointer to the queue context, >> >>> - * NULL for failure. >> >>> + * @return pointer to the queue context >> >>> + * @retval NULL on failure >> >>> */ >> >>> void *odp_queue_get_context(odp_queue_t queue); >> >>> >> >>> @@ -176,7 +180,8 @@ void *odp_queue_get_context(odp_queue_t queue); >> >>> * @param queue Queue handle >> >>> * @param buf Buffer handle >> >>> * >> >>> - * @return 0 if succesful >> >>> + * @retval 0 on success >> >>> + * @retval <0 on failure >> >>> */ >> >>> int odp_queue_enq(odp_queue_t queue, odp_buffer_t buf); >> >>> >> >>> @@ -187,7 +192,8 @@ int odp_queue_enq(odp_queue_t queue, odp_buffer_t >> >>> buf); >> >>> * @param buf Buffer handles >> >>> * @param num Number of buffer handles >> >>> * >> >>> - * @return 0 if succesful >> >>> + * @retval 0 on success >> >>> + * @retval <0 on failure >> >>> */ >> >>> int odp_queue_enq_multi(odp_queue_t queue, odp_buffer_t buf[], int >> >>> num); >> >>> >> >>> @@ -199,7 +205,8 @@ int odp_queue_enq_multi(odp_queue_t queue, >> >>> odp_buffer_t buf[], int num); >> >>> * >> >>> * @param queue Queue handle >> >>> * >> >>> - * @return Buffer handle, or ODP_BUFFER_INVALID >> >>> + * @return Buffer handle >> >>> + * @retval ODP_BUFFER_INVALID on failure >> >>> */ >> >>> odp_buffer_t odp_queue_deq(odp_queue_t queue); >> >>> >> >>> diff --git a/platform/linux-generic/include/api/odp_schedule.h >> >>> b/platform/linux-generic/include/api/odp_schedule.h >> >>> index cdf6705..36fbba3 100644 >> >>> --- a/platform/linux-generic/include/api/odp_schedule.h >> >>> +++ b/platform/linux-generic/include/api/odp_schedule.h >> >>> @@ -59,7 +59,8 @@ uint64_t odp_schedule_wait_time(uint64_t ns); >> >>> * Use odp_schedule_wait_time() to convert time to >> >>> other >> >>> wait >> >>> * values. >> >>> * >> >>> - * @return Next highest priority buffer, or ODP_BUFFER_INVALID >> >>> + * @return Next highest priority buffer >> >>> + * @retval ODP_BUFFER_INVALID on timeout >> >>> */ >> >>> odp_buffer_t odp_schedule(odp_queue_t *from, uint64_t wait); >> >>> >> >>> diff --git a/platform/linux-generic/include/api/odp_shared_memory.h >> >>> b/platform/linux-generic/include/api/odp_shared_memory.h >> >>> index f70db5a..78d108a 100644 >> >>> --- a/platform/linux-generic/include/api/odp_shared_memory.h >> >>> +++ b/platform/linux-generic/include/api/odp_shared_memory.h >> >>> @@ -59,7 +59,8 @@ typedef struct odp_shm_info_t { >> >>> * @param[in] flags Shared memory parameter flags (ODP_SHM_*). >> >>> * Default value is 0. >> >>> * >> >>> - * @return Pointer to the reserved block, or NULL >> >>> + * @return Handle of the reserved block >> >>> + * @retval NULL on failure >> >>> */ >> >>> odp_shm_t odp_shm_reserve(const char *name, uint64_t size, uint64_t >> >>> align, >> >>> uint32_t flags); >> >>> @@ -72,9 +73,9 @@ odp_shm_t odp_shm_reserve(const char *name, uint64_t >> >>> size, uint64_t align, >> >>> * >> >>> * @param[in] shm Block handle >> >>> * >> >>> - * @retval 0 if the handle is already free >> >>> + * @retval 0 if the handle is already free (FIXME how can we know >> >>> this?) >> >> >> >> >> >> The linux-generic implementation tracks block allocation status. Good >> >> point >> >> as to whether this should be part of the spec, however. >> > The above definition puts some more restrictions on the ODP >> > implementation. It must remember all past shm handles and their >> > current status. How does this work if shm regions are created and >> > destroyed repeatedly (an unlikely use case I agree). Possibly there is >> > a fixed array of shm handles with generation counters for each handle >> > but this will eventually wrap around and old stale handles become >> > fresh again. >> > >> > Resource cleanup (e.g. for controlled program termination) has to be a >> > highly synchronized operation anyway, you can't have worker threads >> > continuing their execution, allocating buffers and timers, interacting >> > with HW etc. when you are tearing down those resources. >> > >> > Specifying undefined behavior is better in my opinion. linux-generic >> > only has to be changed so that it does not return 0 for an already >> > freed shm region (because this would be a bad example and we want >> > linux-generic to be a good example), instead it could call ODP_ABORT. >> > >> >> >> >>> >> >>> * @retval 0 if the handle free succeeds >> >>> - * @retval -1 on failure to free the handle >> >>> + * @retval <0 on failure to free the handle >> >>> */ >> >>> int odp_shm_free(odp_shm_t shm); >> >>> >> >>> @@ -84,7 +85,7 @@ int odp_shm_free(odp_shm_t shm); >> >>> * @param[in] name Name of the block >> >>> * >> >>> * @return A handle to the block if it is found by name >> >>> - * @retval #ODP_SHM_INVALID if the block is not found >> >>> + * @retval ODP_SHM_INVALID on failure >> >>> */ >> >>> odp_shm_t odp_shm_lookup(const char *name); >> >>> >> >>> @@ -94,7 +95,8 @@ odp_shm_t odp_shm_lookup(const char *name); >> >>> * >> >>> * @param[in] shm Block handle >> >>> * >> >>> - * @return Memory block address, or NULL on error >> >>> + * @return Memory block address >> >>> + * @retval NULL on failure (FIXME: when?) >> >> >> >> >> >> Why the FIXME? NULL is returned if the operation is unable to succeed. >> > Yes but when can the translation from shm handle to virtual address >> > fail? Are there any situations where we think this is normal behavior? >> > Shared memory regions that are not mapped to virtual memory? >> > >> > Passing invalid shm handles cause undefined behavior, not well-defined >> > failures. >> > So I am questioning why we need a @retval NULL for this function. >> > >> > >> >> >> >>> >> >>> */ >> >>> void *odp_shm_addr(odp_shm_t shm); >> >>> >> >>> @@ -105,7 +107,8 @@ void *odp_shm_addr(odp_shm_t shm); >> >>> * @param[in] shm Block handle >> >>> * @param[out] info Block info pointer for output >> >>> * >> >>> - * @return 0 on success, otherwise non-zero >> >>> + * @retval 0 on success >> >>> + * @retval <0 on failure >> >>> */ >> >>> int odp_shm_info(odp_shm_t shm, odp_shm_info_t *info); >> >>> >> >>> diff --git a/platform/linux-generic/include/api/odp_timer.h >> >>> b/platform/linux-generic/include/api/odp_timer.h >> >>> index 69402ef..c8c3270 100644 >> >>> --- a/platform/linux-generic/include/api/odp_timer.h >> >>> +++ b/platform/linux-generic/include/api/odp_timer.h >> >>> @@ -112,8 +112,8 @@ typedef struct { >> >>> * @param name Name of the timer pool. The string will be >> >>> copied. >> >>> * @param params Timer pool parameters. The content will be >> >>> copied. >> >>> * >> >>> - * @return Timer pool handle if successful, otherwise >> >>> ODP_TIMER_POOL_INVALID >> >>> - * and errno set >> >>> + * @return Timer pool handle on success >> >>> + * @retval ODP_TIMER_POOL_INVALID on failure and errno set >> >>> */ >> >>> odp_timer_pool_t >> >>> odp_timer_pool_create(const char *name, >> >>> @@ -185,8 +185,8 @@ typedef struct { >> >>> * @param tpid Timer pool identifier >> >>> * @param[out] info Pointer to information buffer >> >>> * >> >>> - * @retval 0 Success >> >>> - * @retval -1 Failure. Info could not be retrieved. >> >>> + * @retval 0 on success >> >>> + * @retval <0 on failure. Info could not be retrieved. >> >>> */ >> >>> int odp_timer_pool_info(odp_timer_pool_t tpid, >> >>> odp_timer_pool_info_t *info); >> >>> @@ -202,8 +202,8 @@ int odp_timer_pool_info(odp_timer_pool_t tpid, >> >>> * @param queue Destination queue for timeout notifications >> >>> * @param user_ptr User defined pointer or NULL to be copied to >> >>> timeouts >> >>> * >> >>> - * @return Timer handle if successful, otherwise ODP_TIMER_INVALID >> >>> and >> >>> - * errno set. >> >>> + * @return Timer handle on success >> >>> + * @retval ODP_TIMER_INVALID on failure and errno set. >> >>> */ >> >>> odp_timer_t odp_timer_alloc(odp_timer_pool_t tpid, >> >>> odp_queue_t queue, >> >>> @@ -218,7 +218,8 @@ odp_timer_t odp_timer_alloc(odp_timer_pool_t tpid, >> >>> * responsibility of the application to handle this timeout when it >> >>> is >> >>> received. >> >>> * >> >>> * @param tim Timer handle >> >>> - * @return Buffer handle of timeout buffer or ODP_BUFFER_INVALID >> >>> + * @return Buffer handle of timeout buffer >> >>> + * @retval ODP_BUFFER_INVALID on failure >> >>> */ >> >>> odp_buffer_t odp_timer_free(odp_timer_t tim); >> >>> >> >>> @@ -292,8 +293,8 @@ int odp_timer_set_rel(odp_timer_t tim, >> >>> * >> >>> * @param tim Timer >> >>> * @param[out] tmo_buf Pointer to a buffer variable >> >>> - * @retval 0 Success, active timer cancelled, timeout returned in >> >>> '*tmo_buf' >> >>> - * @retval -1 Failure, timer already expired (or inactive) >> >>> + * @retval 0 on success, active timer cancelled, timeout returned in >> >>> '*tmo_buf' >> >>> + * @retval <0 on failure, timer already expired (or inactive) >> >>> */ >> >>> int odp_timer_cancel(odp_timer_t tim, odp_buffer_t *tmo_buf); >> >>> >> >>> diff --git a/platform/linux-generic/odp_crypto.c >> >>> b/platform/linux-generic/odp_crypto.c >> >>> index 2f95cbe..ded3b62 100644 >> >>> --- a/platform/linux-generic/odp_crypto.c >> >>> +++ b/platform/linux-generic/odp_crypto.c >> >>> @@ -343,7 +343,7 @@ >> >>> odp_crypto_session_create(odp_crypto_session_params_t >> >>> *params, >> >>> >> >>> int >> >>> odp_crypto_operation(odp_crypto_op_params_t *params, >> >>> - bool *posted, >> >>> + odp_bool_t *posted, >> >>> odp_buffer_t completion_event) >> >>> { >> >>> enum crypto_alg_err rc_cipher = ODP_CRYPTO_ALG_ERR_NONE; >> >>> @@ -423,7 +423,7 @@ odp_crypto_init_global(void) >> >>> } >> >>> >> >>> int >> >>> -odp_hw_random_get(uint8_t *buf, size_t *len, bool use_entropy >> >>> ODP_UNUSED) >> >>> +odp_hw_random_get(uint8_t *buf, size_t *len, odp_bool_t use_entropy >> >>> ODP_UNUSED) >> >>> { >> >>> int rc; >> >>> rc = RAND_bytes(buf, *len); >> >>> diff --git a/platform/linux-generic/odp_packet_io.c >> >>> b/platform/linux-generic/odp_packet_io.c >> >>> index 0efa3d0..c51098f 100644 >> >>> --- a/platform/linux-generic/odp_packet_io.c >> >>> +++ b/platform/linux-generic/odp_packet_io.c >> >>> @@ -797,18 +797,18 @@ int odp_pktio_promisc_mode(odp_pktio_t id) >> >>> } >> >>> >> >>> >> >>> -size_t odp_pktio_mac_addr(odp_pktio_t id, void *mac_addr, >> >>> +int odp_pktio_mac_addr(odp_pktio_t id, void *mac_addr, >> >>> size_t addr_size) >> >>> { >> >>> pktio_entry_t *entry; >> >>> >> >>> if (addr_size < ETH_ALEN) >> >>> - return 0; >> >>> + return -1; >> >>> >> >>> entry = get_pktio_entry(id); >> >>> if (entry == NULL) { >> >>> ODP_DBG("pktio entry %d does not exist\n", id); >> >>> - return 0; >> >>> + return -1; >> >>> } >> >>> >> >>> lock_entry(entry); >> >>> diff --git a/test/validation/crypto/odp_crypto_test_async_inp.c >> >>> b/test/validation/crypto/odp_crypto_test_async_inp.c >> >>> index 96d4c3f..1db7844 100644 >> >>> --- a/test/validation/crypto/odp_crypto_test_async_inp.c >> >>> +++ b/test/validation/crypto/odp_crypto_test_async_inp.c >> >>> @@ -34,7 +34,7 @@ static void alg_test(enum odp_crypto_op op, >> >>> odp_crypto_session_t session; >> >>> int rc; >> >>> enum odp_crypto_ses_create_err status; >> >>> - bool posted; >> >>> + odp_bool_t posted; >> >>> odp_buffer_t compl_event; >> >>> >> >>> odp_queue_t compl_queue = odp_queue_lookup("crypto-out"); >> >>> diff --git a/test/validation/crypto/odp_crypto_test_sync_inp.c >> >>> b/test/validation/crypto/odp_crypto_test_sync_inp.c >> >>> index f37ad54..5082f13 100644 >> >>> --- a/test/validation/crypto/odp_crypto_test_sync_inp.c >> >>> +++ b/test/validation/crypto/odp_crypto_test_sync_inp.c >> >>> @@ -23,7 +23,7 @@ static void alg_test(enum odp_crypto_op op, >> >>> odp_crypto_session_t session; >> >>> int rc; >> >>> enum odp_crypto_ses_create_err status; >> >>> - bool posted; >> >>> + odp_bool_t posted; >> >>> >> >>> odp_queue_t compl_queue = odp_queue_lookup("crypto-out"); >> >>> CU_ASSERT(compl_queue != ODP_QUEUE_INVALID); >> >>> -- >> >>> 1.9.1 >> >>> >> >>> >> >>> _______________________________________________ >> >>> lng-odp mailing list >> >>> lng-odp@lists.linaro.org >> >>> http://lists.linaro.org/mailman/listinfo/lng-odp >> >> >> >> > >
I agree an Erlang-style supervisory structure where components fail on errors that are then handled at a higher level can lead to elegant and robust system designs. It does require a different application design philosophy to do well, however, and that's seldom found in legacy code that might want to introduce ODP on an incremental basis. There's a lot of code out there that expects to crawl forward checking return codes rigorously at each step, so we're striking a balance here. On Tue, Jan 27, 2015 at 6:43 AM, Ola Liljedahl <ola.liljedahl@linaro.org> wrote: > On 27 January 2015 at 12:52, Bill Fischofer <bill.fischofer@linaro.org> > wrote: > > I think it's good practice for functions to be robust in parameter > handling > > unless they are expected to be used in performance paths. That's the > reason > > why we've said that things like odp_buffer_addr() etc. have undefined > > behavior if they're passed invalid handles. But shm and pools are things > > that will typically get set up once during init, and seldom changed > (maybe > > as part of reconfig) so the performance argument is less compelling > there. > I agree but this is not only about performance. Sprinkling the API's > with error codes also forces the user to check those return values > which complicates the application logic and probably creates code that > will be difficult to get test coverage for. I have a lot of experience > with API's that cannot return errors and I really prefer this style. > Applications becomes so much simpler. > > Why should odp_shm_addr() be allowed to return an error code? Most > implementations most likely will not even utilize the possibility and > applications will not expect an error to happen and so might not even > check the return value. How often do you check the return value of > printf or close? > > Just because the functions do not have to check for valid parameters > so that they can return corresponding error indications does not mean > that implementations cannot and should not check for (in)valid > parameters. But if invalid parameters are detected, the error has to > be signaled in some other way, e.g. by calling ODP_ABORT (as ODP > doesn't have any error handling mechanism for users to hook into). > > The timer implementation always checks timer pool handles and timer > handles for validity. As ODP_ABORT (which does not return control to > the caller) is used to report invalid parameters, the applications > cannot rely on the ODP implementation handling invalid parameters. In > another implementation, the checks could be removed with no change of > semantics. As you say that should only be considered for truly > performance critical functions. > > > > > > > On Tue, Jan 27, 2015 at 4:54 AM, Ola Liljedahl <ola.liljedahl@linaro.org > > > > wrote: > >> > >> As a general rule, all functions that return information about e.g. > >> shared memory areas, buffer/event pools and timer pools should be > >> robust in the presence of invalid parameters (handles). The reason is > >> that you might want to implement a form of post-mortem dump which > >> examines all ODP objects and saves the information in some dump area > >> and you don't want this post-mortem dump function to crash. The system > >> is already in a bad state (that's why we need a dump so we can debug > >> it) and not all data can be trusted. > >> Buffers/events are special, we have a special function for checking > >> the validity of such handles so that all other (performance critical) > >> buffer/event operations can expect the handle to be valid and avoid > >> any checks. > >> > >> > >> > >> On 27 January 2015 at 11:43, Ola Liljedahl <ola.liljedahl@linaro.org> > >> wrote: > >> > On 27 January 2015 at 02:14, Bill Fischofer < > bill.fischofer@linaro.org> > >> > wrote: > >> >> This looks good. It will need to be rebased following the event > patch > >> >> merge > >> >> (all merges currently blocked until that happens). See additional > >> >> comments > >> >> inline: > >> > I'll rebase as necessary and post updated patches. > >> > > >> >> > >> >> On Mon, Jan 26, 2015 at 6:20 PM, Ola Liljedahl > >> >> <ola.liljedahl@linaro.org> > >> >> wrote: > >> >>> > >> >>> Unify @return and @retval descriptions. > >> >>> @return used for values that cannot (meaningfully) be enumerated > (e.g > >> >>> pointers, > >> >>> ODP handles) or simply tested for correctness. > >> >>> @retval used for values that can be enumerated and should be tested > by > >> >>> validation programs. > >> >>> Changed from bool to odp_bool_t in odp_crypto.h and dependent source > >> >>> files. > >> >>> Changed return type and value of odp_pktio_mac_addr() to match other > >> >>> similar > >> >>> functions. Use int as return type, <0 to indicate failure. > >> >>> > >> >>> Signed-off-by: Ola Liljedahl <ola.liljedahl@linaro.org> > >> >>> --- > >> >>> (This document/code contribution attached is provided under the > terms > >> >>> of > >> >>> agreement LES-LTM-21309) > >> >>> > >> >>> example/ipsec/odp_ipsec.c | 4 +- > >> >>> platform/linux-generic/include/api/odp_buffer.h | 9 ++- > >> >>> .../linux-generic/include/api/odp_buffer_pool.h | 21 ++++--- > >> >>> platform/linux-generic/include/api/odp_byteorder.h | 2 +- > >> >>> .../linux-generic/include/api/odp_classification.h | 48 > >> >>> +++++++++------- > >> >>> platform/linux-generic/include/api/odp_cpumask.h | 12 ++-- > >> >>> platform/linux-generic/include/api/odp_crypto.h | 15 +++-- > >> >>> platform/linux-generic/include/api/odp_init.h | 10 ++-- > >> >>> platform/linux-generic/include/api/odp_packet.h | 66 > >> >>> ++++++++++++---------- > >> >>> .../linux-generic/include/api/odp_packet_flags.h | 57 > >> >>> ++++++++++++------- > >> >>> platform/linux-generic/include/api/odp_packet_io.h | 54 > >> >>> +++++++++++------- > >> >>> platform/linux-generic/include/api/odp_queue.h | 25 +++++--- > >> >>> platform/linux-generic/include/api/odp_schedule.h | 3 +- > >> >>> .../linux-generic/include/api/odp_shared_memory.h | 15 +++-- > >> >>> platform/linux-generic/include/api/odp_timer.h | 19 ++++--- > >> >>> platform/linux-generic/odp_crypto.c | 4 +- > >> >>> platform/linux-generic/odp_packet_io.c | 6 +- > >> >>> test/validation/crypto/odp_crypto_test_async_inp.c | 2 +- > >> >>> test/validation/crypto/odp_crypto_test_sync_inp.c | 2 +- > >> >>> 19 files changed, 226 insertions(+), 148 deletions(-) > >> >>> > >> >>> diff --git a/example/ipsec/odp_ipsec.c b/example/ipsec/odp_ipsec.c > >> >>> index f2fac8a..066dc40 100644 > >> >>> --- a/example/ipsec/odp_ipsec.c > >> >>> +++ b/example/ipsec/odp_ipsec.c > >> >>> @@ -683,7 +683,7 @@ pkt_disposition_e > >> >>> do_ipsec_in_classify(odp_packet_t > >> >>> pkt, > >> >>> odph_esphdr_t *esp = NULL; > >> >>> ipsec_cache_entry_t *entry; > >> >>> odp_crypto_op_params_t params; > >> >>> - bool posted = 0; > >> >>> + odp_bool_t posted = 0; > >> >>> > >> >>> /* Default to skip IPsec */ > >> >>> *skip = TRUE; > >> >>> @@ -955,7 +955,7 @@ pkt_disposition_e do_ipsec_out_seq(odp_packet_t > >> >>> pkt, > >> >>> pkt_ctx_t *ctx) > >> >>> { > >> >>> uint8_t *buf = odp_packet_data(pkt); > >> >>> - bool posted = 0; > >> >>> + odp_bool_t posted = 0; > >> >>> > >> >>> /* We were dispatched from atomic queue, assign sequence > >> >>> numbers > >> >>> */ > >> >>> if (ctx->ipsec.ah_offset) { > >> >>> diff --git a/platform/linux-generic/include/api/odp_buffer.h > >> >>> b/platform/linux-generic/include/api/odp_buffer.h > >> >>> index 0670464..fd0871b 100644 > >> >>> --- a/platform/linux-generic/include/api/odp_buffer.h > >> >>> +++ b/platform/linux-generic/include/api/odp_buffer.h > >> >>> @@ -32,6 +32,7 @@ extern "C" { > >> >>> * Buffer start address > >> >>> * > >> >>> * @param buf Buffer handle > >> >>> + * Note: Buffer handle must be valid or the behavior will be > >> >>> undefined. > >> >> > >> >> > >> >> Should these be @note ? Same comment for similar Note: adds. > >> > Yes should use @note. > >> > > >> >> Phrasing in > >> >> present tense (...or behavior is undefined) seems more natural, but > >> >> that's a > >> >> stylistic point that's I won't argue. > >> > You are probably better at English than I am... I am following your > >> > suggestion without argument. > >> > > >> > The language is a bit mixed with these undefined warnings. > >> > > >> > One problem I see is that if we make a @note for undefined behavior > >> > for each function, we need to make that note for *all* relevant > >> > functions. The omission of this note for some functions could indicate > >> > that undefined behavior is not present (even in the presence of > >> > invalid parameters). But I also think a global definition and > >> > documentation of undefined behavior in the ODP documentation might not > >> > be sufficient. Most programmers will go straight at the documentation > >> > of individual functions they want to use. > >> > > >> > > >> >> > >> >>> > >> >>> * > >> >>> * @return Buffer start address > >> >>> */ > >> >>> @@ -41,6 +42,7 @@ void *odp_buffer_addr(odp_buffer_t buf); > >> >>> * Buffer maximum data size > >> >>> * > >> >>> * @param buf Buffer handle > >> >>> + * Note: Buffer handle must be valid or the behavior will be > >> >>> undefined. > >> >>> * > >> >>> * @return Buffer maximum data size > >> >>> */ > >> >>> @@ -50,12 +52,12 @@ uint32_t odp_buffer_size(odp_buffer_t buf); > >> >>> * Buffer type > >> >>> * > >> >>> * @param buf Buffer handle > >> >>> + * Note: Buffer handle must be valid or the behavior will be > >> >>> undefined. > >> >>> * > >> >>> * @return Buffer type > >> >>> */ > >> >>> int odp_buffer_type(odp_buffer_t buf); > >> >>> > >> >>> -#define ODP_BUFFER_TYPE_INVALID (-1) /**< Buffer type invalid */ > >> >>> #define ODP_BUFFER_TYPE_ANY 0 /**< Buffer that can hold any > >> >>> other > >> >>> buffer type */ > >> >>> #define ODP_BUFFER_TYPE_RAW 1 /**< Raw buffer, no additional > >> >>> metadata */ > >> >>> @@ -65,7 +67,9 @@ int odp_buffer_type(odp_buffer_t buf); > >> >>> /** > >> >>> * Tests if buffer is valid > >> >>> * > >> >>> - * @param buf Buffer handle > >> >>> + * @param buf Buffer handle (possibly invalid) > >> >>> + * Note: This is the only call which accepts invalid buffer handles > >> >>> (any > >> >>> bit > >> >>> + * value) without causing undefined behavior. > >> >> > >> >> > >> >> Definitely should be @note for this one. Would it be clearer to say > >> >> "API" > >> >> rather than "call"? Grammar nit: that rather than which is correct > >> >> here. > >> > Well this is just one function, the whole set of functions is an API. > >> > Or is my definition of API too narrow? > >> > Maybe "this API function"? > >> > > >> >> > >> >>> > >> >>> * > >> >>> * @retval 1 Buffer handle represents a valid buffer. > >> >>> * @retval 0 Buffer handle does not represent a valid buffer. > >> >>> @@ -76,6 +80,7 @@ int odp_buffer_is_valid(odp_buffer_t buf); > >> >>> * Buffer pool of the buffer > >> >>> * > >> >>> * @param buf Buffer handle > >> >>> + * Note: Buffer handle must be valid or the behavior will be > >> >>> undefined. > >> >>> * > >> >>> * @return Handle of buffer pool buffer belongs to > >> >>> */ > >> >>> diff --git a/platform/linux-generic/include/api/odp_buffer_pool.h > >> >>> b/platform/linux-generic/include/api/odp_buffer_pool.h > >> >>> index 8380ac1..fe917a4 100644 > >> >>> --- a/platform/linux-generic/include/api/odp_buffer_pool.h > >> >>> +++ b/platform/linux-generic/include/api/odp_buffer_pool.h > >> >>> @@ -81,8 +81,8 @@ odp_buffer_pool_t odp_buffer_pool_create(const > char > >> >>> *name, > >> >>> * > >> >>> * @param pool Handle of the buffer pool to be destroyed > >> >>> * > >> >>> - * @retval 0 Success > >> >>> - * @retval -1 Failure > >> >>> + * @retval 0 if successful > >> >>> + * @retval <0 on failure > >> >>> * > >> >>> * @note This routine destroys a previously created buffer pool. > This > >> >>> call > >> >>> * does not destroy any shared memory object passed to > >> >>> @@ -117,7 +117,7 @@ typedef struct odp_buffer_pool_info_t { > >> >>> odp_shm_t shm; /**< handle of shared > memory > >> >>> area > >> >>> supplied by application > >> >>> to > >> >>> contain buffer pool, or > >> >>> - ODP_SHM_INVALID if this > >> >>> pool > >> >>> is > >> >>> + ODP_SHM_NULL if this > pool > >> >>> is > >> >>> managed by ODP */ > >> >>> odp_buffer_pool_param_t params; /**< pool parameters */ > >> >>> } odp_buffer_pool_info_t; > >> >>> @@ -125,13 +125,13 @@ typedef struct odp_buffer_pool_info_t { > >> >>> /** > >> >>> * Retrieve information about a buffer pool > >> >>> * > >> >>> - * @param pool Buffer pool handle > >> >>> + * @param pool Buffer pool handle (possibly invalid) > >> >>> * > >> >>> * @param[out] info Receives an odp_buffer_pool_info_t object > >> >>> * that describes the pool. > >> >>> * > >> >>> - * @retval 0 Success > >> >>> - * @retval -1 Failure. Info could not be retrieved. > >> >>> + * @retval 0 if successful > >> >>> + * @retval <0 on failure. Info could not be retrieved (invalid pool > >> >>> handle) > >> >>> */ > >> >>> > >> >>> int odp_buffer_pool_info(odp_buffer_pool_t pool, > >> >>> @@ -149,17 +149,22 @@ void odp_buffer_pool_print(odp_buffer_pool_t > >> >>> pool); > >> >>> > >> >>> /** > >> >>> * Buffer alloc > >> >>> + * Note: the pool handle must be valid or the behavior is > undefined. > >> >>> + * > >> >>> + * The validity of a buffer handle can be checked at any time using > >> >>> + * odp_buffer_is_valid() > >> >>> * > >> >>> - * The validity of a buffer can be cheked at any time with > >> >>> odp_buffer_is_valid() > >> >>> * @param pool Pool handle > >> >>> * > >> >>> * @return Handle of allocated buffer > >> >>> - * @retval ODP_BUFFER_INVALID Buffer could not be allocated > >> >>> + * @retval ODP_BUFFER_INVALID Buffer could not be allocated (e.g. > >> >>> pool > >> >>> + * exhausted) > >> >>> */ > >> >>> odp_buffer_t odp_buffer_alloc(odp_buffer_pool_t pool); > >> >>> > >> >>> /** > >> >>> * Buffer free > >> >>> + * Note: the buffer handle must be valid or the behavior is > >> >>> undefined. > >> >>> * > >> >>> * @param buf Buffer handle > >> >>> * > >> >>> diff --git a/platform/linux-generic/include/api/odp_byteorder.h > >> >>> b/platform/linux-generic/include/api/odp_byteorder.h > >> >>> index 5890011..8e38937 100644 > >> >>> --- a/platform/linux-generic/include/api/odp_byteorder.h > >> >>> +++ b/platform/linux-generic/include/api/odp_byteorder.h > >> >>> @@ -24,7 +24,7 @@ extern "C" { > >> >>> #include <odp_compiler.h> > >> >>> > >> >>> /** @defgroup odp_compiler_optim ODP COMPILER / OPTIMIZATION > >> >>> - * Macros that check byte order and byte converting operations. > >> >>> + * Macros that check and convert byte order. > >> >>> * @{ > >> >>> */ > >> >>> > >> >>> diff --git a/platform/linux-generic/include/api/odp_classification.h > >> >>> b/platform/linux-generic/include/api/odp_classification.h > >> >>> index 46189bc..6bca8fc 100644 > >> >>> --- a/platform/linux-generic/include/api/odp_classification.h > >> >>> +++ b/platform/linux-generic/include/api/odp_classification.h > >> >>> @@ -79,8 +79,8 @@ typedef enum odp_cos_hdr_flow_fields { > >> >>> * > >> >>> * @param[in] name String intended for debugging purposes. > >> >>> * > >> >>> - * @return Class of service instance identifier, > >> >>> - * or ODP_COS_INVALID on error. > >> >>> + * @return Class of service instance identifier > >> >>> + * @retval ODP_COS_INVALID on failure. > >> >>> */ > >> >>> odp_cos_t odp_cos_create(const char *name); > >> >>> > >> >>> @@ -89,7 +89,8 @@ odp_cos_t odp_cos_create(const char *name); > >> >>> * > >> >>> * @param[in] cos_id class-of-service instance. > >> >>> * > >> >>> - * @return 0 on success, non-zero on error. > >> >>> + * @retval 0 if successful > >> >>> + * @retval <0 on failure > >> >>> */ > >> >>> int odp_cos_destroy(odp_cos_t cos_id); > >> >>> > >> >>> @@ -102,7 +103,8 @@ int odp_cos_destroy(odp_cos_t cos_id); > >> >>> * of this specific class of service > >> >>> * will be enqueued. > >> >>> * > >> >>> - * @return 0 on success, non-zero on error. > >> >>> + * @retval 0 if successful > >> >>> + * @retval <0 on failure > >> >>> */ > >> >>> int odp_cos_set_queue(odp_cos_t cos_id, odp_queue_t queue_id); > >> >>> > >> >>> @@ -112,7 +114,8 @@ int odp_cos_set_queue(odp_cos_t cos_id, > >> >>> odp_queue_t > >> >>> queue_id); > >> >>> * @param[in] cos_id class-of-service instance. > >> >>> * @param[in] drop_policy Desired packet drop policy for this > >> >>> class. > >> >>> * > >> >>> - * @return 0 on success, non-zero on error. > >> >>> + * @retval 0 if successful > >> >>> + * @retval <0 on failure > >> >>> * > >> >>> * @note Optional. > >> >>> */ > >> >>> @@ -127,7 +130,8 @@ int odp_cos_set_drop(odp_cos_t cos_id, > odp_drop_e > >> >>> drop_policy); > >> >>> * @param[in] qos_table Values of the Layer-2 QoS header > >> >>> field. > >> >>> * @param[in] cos_table Class-of-service assigned to each of > >> >>> the > >> >>> * allowed Layer-2 QOS levels. > >> >>> - * @return 0 on success, non-zero on error. > >> >>> + * @retval 0 if successful > >> >>> + * @retval <0 on failure > >> >>> */ > >> >>> int odp_cos_with_l2_priority(odp_pktio_t pktio_in, > >> >>> uint8_t num_qos, > >> >>> @@ -146,7 +150,8 @@ int odp_cos_with_l2_priority(odp_pktio_t > pktio_in, > >> >>> * @param[in] l3_preference when true, Layer-3 QoS overrides > >> >>> * L2 QoS when present. > >> >>> * > >> >>> - * @return 0 on success, non-zero on error. > >> >>> + * @retval 0 if successful > >> >>> + * @retval <0 on failure > >> >>> * > >> >>> * @note Optional. > >> >>> */ > >> >>> @@ -219,7 +224,8 @@ typedef enum odp_pmr_term { > >> >>> * that must match the value size requirement > of > >> >>> the > >> >>> * specific term. > >> >>> * > >> >>> - * @return Handle of the matching rule or ODP_PMR_INVAL > >> >>> on > >> >>> error > >> >>> + * @return Handle of the matching rule > >> >>> + * @retval ODP_PMR_INVAL on failure > >> >>> */ > >> >>> odp_pmr_t odp_pmr_create_match(odp_pmr_term_e term, > >> >>> const void *val, > >> >>> @@ -236,7 +242,8 @@ odp_pmr_t odp_pmr_create_match(odp_pmr_term_e > >> >>> term, > >> >>> * that must match the value size requirement > of > >> >>> the > >> >>> * specific term. > >> >>> * > >> >>> - * @return Handle of the matching rule or ODP_PMR_INVAL > >> >>> on > >> >>> error > >> >>> + * @return Handle of the matching rule > >> >>> + * @retval ODP_PMR_INVAL on failure > >> >>> * @note: Range is inclusive [val1..val2]. > >> >>> */ > >> >>> odp_pmr_t odp_pmr_create_range(odp_pmr_term_e term, > >> >>> @@ -248,7 +255,8 @@ odp_pmr_t odp_pmr_create_range(odp_pmr_term_e > >> >>> term, > >> >>> * > >> >>> * @param[in] pmr_id Identifier of the PMR to be destroyed > >> >>> * > >> >>> - * @return 0 on success, non-zero or error. > >> >>> + * @retval 0 if successful > >> >>> + * @retval <0 on failure > >> >>> */ > >> >>> int odp_pmr_destroy(odp_pmr_t pmr_id); > >> >>> > >> >>> @@ -259,7 +267,8 @@ int odp_pmr_destroy(odp_pmr_t pmr_id); > >> >>> * @param[in] src_pktio pktio to which this PMR is to be > >> >>> applied > >> >>> * @param[in] dst_cos CoS to be assigned by this PMR > >> >>> * > >> >>> - * @return 0 on success, non-zero or error. > >> >>> + * @retval 0 if successful > >> >>> + * @retval <0 on failure > >> >>> */ > >> >>> int odp_pktio_pmr_cos(odp_pmr_t pmr_id, > >> >>> odp_pktio_t src_pktio, odp_cos_t dst_cos); > >> >>> @@ -272,7 +281,8 @@ int odp_pktio_pmr_cos(odp_pmr_t pmr_id, > >> >>> * @param[in] dst_cos CoS to be assigned to packets > filtered > >> >>> * from src_cos that match pmr_id. > >> >>> * > >> >>> - * @return 0 on success, non-zero on error. > >> >>> + * @retval 0 if successful > >> >>> + * @retval <0 on failure > >> >>> */ > >> >>> int odp_cos_pmr_cos(odp_pmr_t pmr_id, odp_cos_t src_cos, odp_cos_t > >> >>> dst_cos); > >> >>> > >> >>> @@ -346,12 +356,10 @@ typedef uint32_t odp_pmr_set_t; > >> >>> * term desired. > >> >>> * @param[out] pmr_set_id Returned handle to the composite > rule > >> >>> set. > >> >>> * > >> >>> - * @return Return value may be a positive > number > >> >>> - * indicating the number of terms > >> >>> elements > >> >>> + * @return the number of terms elements > >> >>> * that have been successfully mapped > to > >> >>> the > >> >>> - * underlying platform classification > >> >>> engine > >> >>> and > >> >>> - * may be in the range from 1 to > >> >>> num_terms, > >> >>> - * or non-zero for error. > >> >>> + * underlying platform classification > >> >>> engine > >> >>> + * @retval <0 on failure > >> >>> */ > >> >>> int odp_pmr_match_set_create(int num_terms, odp_pmr_match_t *terms, > >> >>> odp_pmr_set_t *pmr_set_id); > >> >>> @@ -369,7 +377,8 @@ int odp_pmr_match_set_create(int num_terms, > >> >>> odp_pmr_match_t *terms, > >> >>> * @param[in] pmr_set_id A composite rule-set handle > >> >>> * returned when created. > >> >>> * > >> >>> - * @return 0 on success, non-zero on error. > >> >>> + * @retval 0 if successful > >> >>> + * @retval <0 on failure > >> >>> */ > >> >>> int odp_pmr_match_set_destroy(odp_pmr_set_t pmr_set_id); > >> >>> > >> >>> @@ -381,7 +390,8 @@ int odp_pmr_match_set_destroy(odp_pmr_set_t > >> >>> pmr_set_id); > >> >>> * set is to be applied > >> >>> * @param[in] dst_cos CoS to be assigned by this PMR match > >> >>> set > >> >>> * > >> >>> - * @return 0 on success, non-zero or error. > >> >>> + * @retval 0 if successful > >> >>> + * @retval <0 on failure > >> >>> */ > >> >>> int odp_pktio_pmr_match_set_cos(odp_pmr_set_t pmr_set_id, > odp_pktio_t > >> >>> src_pktio, > >> >>> odp_cos_t dst_cos); > >> >>> diff --git a/platform/linux-generic/include/api/odp_cpumask.h > >> >>> b/platform/linux-generic/include/api/odp_cpumask.h > >> >>> index ebff9b0..5c5bcd7 100644 > >> >>> --- a/platform/linux-generic/include/api/odp_cpumask.h > >> >>> +++ b/platform/linux-generic/include/api/odp_cpumask.h > >> >>> @@ -79,7 +79,8 @@ void odp_cpumask_clr(odp_cpumask_t *mask, int > cpu); > >> >>> * Test if cpu is a member of mask > >> >>> * @param mask CPU mask to check if cpu num set or not > >> >>> * @param cpu CPU number > >> >>> - * @return non-zero if set otherwise 0 > >> >>> + * @return non-zero if set > >> >>> + * @retval 0 if not set > >> >>> */ > >> >>> int odp_cpumask_isset(const odp_cpumask_t *mask, int cpu); > >> >>> > >> >>> @@ -134,14 +135,16 @@ void odp_cpumask_copy(odp_cpumask_t *dest, > const > >> >>> odp_cpumask_t *src); > >> >>> /** > >> >>> * Find first bit set in mask > >> >>> * > >> >>> - * @return cpu else -1 if no bits set in cpumask > >> >>> + * @return cpu > >> >>> + * @retval -1 if no bits set in cpumask > >> >> > >> >> > >> >> Should this be <0 for consistency with other error RC descriptions? > >> > Possibly. I was a little loath at changing the definitions of these > >> > basically bit set operations (where return values might be the direct > >> > results of binary/arithmetic operations) but this one could be unified > >> > with the rest without any problems. It was also getting rather late in > >> > the evening, I was probably not thinking too clearly at the end. > >> > I changed all three remaining instances in this file. > >> > > >> >> > >> >>> > >> >>> */ > >> >>> int odp_cpumask_first(const odp_cpumask_t *mask); > >> >>> > >> >>> /** > >> >>> * Find last bit set in mask > >> >>> * > >> >>> - * @return cpu else -1 if no bits set in cpumask > >> >>> + * @return cpu > >> >>> + * @retval -1 if no bits set in cpumask > >> >> > >> >> > >> >> Same here. <0 ? > >> > yes > >> > > >> >> > >> >>> > >> >>> */ > >> >>> int odp_cpumask_last(const odp_cpumask_t *mask); > >> >>> > >> >>> @@ -160,7 +163,8 @@ int odp_cpumask_last(const odp_cpumask_t *mask); > >> >>> * > >> >>> * @param mask CPU mask to find next cpu in > >> >>> * @param cpu CPU to start from > >> >>> - * @return cpu found else -1 > >> >>> + * @return cpu found > >> >>> + * @retval -1 if not found > >> >> > >> >> > >> >> And again here. > >> > yes > >> > > >> >> > >> >>> > >> >>> * > >> >>> * @see odp_cpumask_first() > >> >>> */ > >> >>> diff --git a/platform/linux-generic/include/api/odp_crypto.h > >> >>> b/platform/linux-generic/include/api/odp_crypto.h > >> >>> index 337e7cf..2f00f95 100644 > >> >>> --- a/platform/linux-generic/include/api/odp_crypto.h > >> >>> +++ b/platform/linux-generic/include/api/odp_crypto.h > >> >>> @@ -218,7 +218,8 @@ typedef struct odp_crypto_compl_status { > >> >>> * @param session Created session else > >> >>> ODP_CRYPTO_SESSION_INVALID > >> >>> * @param status Failure code if unsuccessful > >> >>> * > >> >>> - * @return 0 if successful else -1 > >> >>> + * @retval 0 if successful > >> >>> + * @retval <0 on failure > >> >>> */ > >> >>> int > >> >>> odp_crypto_session_create(odp_crypto_session_params_t *params, > >> >>> @@ -242,11 +243,12 @@ > >> >>> odp_crypto_session_create(odp_crypto_session_params_t *params, > >> >>> * @param posted Pointer to return posted, TRUE for > async > >> >>> operation > >> >>> * @param completion_event Event by which the operation results > are > >> >>> delivered. > >> >>> * > >> >>> - * @return 0 if successful else -1 > >> >>> + * @retval 0 if successful > >> >>> + * @retval <0 on failure > >> >>> */ > >> >>> int > >> >>> odp_crypto_operation(odp_crypto_op_params_t *params, > >> >>> - bool *posted, > >> >>> + odp_bool_t *posted, > >> >>> odp_buffer_t completion_event); > >> >>> > >> >>> /** > >> >>> @@ -281,7 +283,7 @@ > odp_crypto_get_operation_compl_status(odp_buffer_t > >> >>> completion_event, > >> >>> * > >> >>> * @param completion_event Event containing operation results > >> >>> * > >> >>> - * @return Packet structure where data now resides > >> >>> + * @return Handle for packet where data now resides > >> >>> */ > >> >>> odp_packet_t > >> >>> odp_crypto_get_operation_compl_packet(odp_buffer_t > completion_event); > >> >>> @@ -305,10 +307,11 @@ > odp_crypto_get_operation_compl_ctx(odp_buffer_t > >> >>> completion_event); > >> >>> * > >> >>> * @todo Define the implication of the use_entropy parameter > >> >>> * > >> >>> - * @return 0 if succesful > >> >>> + * @retval 0 if successful > >> >>> + * @retval <0 on failure > >> >>> */ > >> >>> int > >> >>> -odp_hw_random_get(uint8_t *buf, size_t *len, bool use_entropy); > >> >>> +odp_hw_random_get(uint8_t *buf, size_t *len, odp_bool_t > use_entropy); > >> >>> > >> >>> /** > >> >>> * @} > >> >>> diff --git a/platform/linux-generic/include/api/odp_init.h > >> >>> b/platform/linux-generic/include/api/odp_init.h > >> >>> index ac856df..4a98717 100644 > >> >>> --- a/platform/linux-generic/include/api/odp_init.h > >> >>> +++ b/platform/linux-generic/include/api/odp_init.h > >> >>> @@ -66,8 +66,8 @@ typedef enum odp_log_level { > >> >>> * @param[in] level Log level > >> >>> * @param[in] fmt printf-style message format > >> >>> * > >> >>> - * @return The number of characters logged if succeeded. Otherwise > >> >>> returns > >> >>> - * a negative number. > >> >>> + * @return The number of characters logged if successful > >> >>> + * @retval <0 on failure > >> >>> */ > >> >>> int odp_override_log(odp_log_level_e level, const char *fmt, ...); > >> >>> > >> >>> @@ -109,7 +109,7 @@ typedef struct odp_platform_init_t { > >> >>> * interpretation by the ODP API to the implementation. > >> >>> * > >> >>> * @retval 0 if successful > >> >>> - * @retval -1 on failure > >> >>> + * @retval <0 on failure > >> >>> */ > >> >>> int odp_init_global(odp_init_t *params, odp_platform_init_t > >> >>> *platform_params); > >> >>> > >> >>> @@ -134,7 +134,7 @@ int odp_init_global(odp_init_t *params, > >> >>> odp_platform_init_t *platform_params); > >> >>> * @sa odp_term_local() which must have been called prior to this. > >> >>> * > >> >>> * @retval 0 if successful > >> >>> - * @retval -1 on failure > >> >>> + * @retval <0 on failure > >> >>> */ > >> >>> int odp_term_global(void); > >> >>> > >> >>> @@ -148,7 +148,7 @@ int odp_term_global(void); > >> >>> * @sa odp_init_global() which must have been called prior to this. > >> >>> * > >> >>> * @retval 0 if successful > >> >>> - * @retval -1 on failure > >> >>> + * @retval <0 on failure > >> >>> */ > >> >>> int odp_init_local(void); > >> >>> > >> >>> diff --git a/platform/linux-generic/include/api/odp_packet.h > >> >>> b/platform/linux-generic/include/api/odp_packet.h > >> >>> index 920a593..b471d07 100644 > >> >>> --- a/platform/linux-generic/include/api/odp_packet.h > >> >>> +++ b/platform/linux-generic/include/api/odp_packet.h > >> >>> @@ -88,8 +88,8 @@ void odp_packet_free(odp_packet_t pkt); > >> >>> * @param pkt Packet handle > >> >>> * @param len Packet data length > >> >>> * > >> >>> - * @retval 0 Success > >> >>> - * @retval Non-zero Failure > >> >>> + * @retval 0 if successful > >> >>> + * @retval <0 on failure > >> >>> * > >> >>> * @see odp_packet_buf_len() > >> >>> */ > >> >>> @@ -279,7 +279,7 @@ void *odp_packet_push_head(odp_packet_t pkt, > >> >>> uint32_t > >> >>> len); > >> >>> * @param pkt Packet handle > >> >>> * @param len Number of bytes to pull the head (0 ... seg_len - 1) > >> >>> * > >> >>> - * @return The new data pointer, or NULL in case of an error. > >> >>> + * @return The new data pointer > >> >>> * @retval NULL Requested offset exceeds packet segment length > >> >>> > >> >>> * > >> >>> * @see odp_packet_seg_len(), odp_packet_push_head() > >> >>> @@ -391,7 +391,7 @@ odp_buffer_pool_t odp_packet_pool(odp_packet_t > >> >>> pkt); > >> >>> * @param pkt Packet handle > >> >>> * > >> >>> * @return Packet interface handle > >> >>> - * @retval ODP_PKTIO_INVALID Packet was not received > >> >>> + * @retval ODP_PKTIO_INVALID Packet was not received on any > >> >>> interface > >> >>> */ > >> >>> odp_pktio_t odp_packet_input(odp_packet_t pkt); > >> >>> > >> >>> @@ -451,8 +451,8 @@ void odp_packet_user_u64_set(odp_packet_t pkt, > >> >>> uint64_t ctx); > >> >>> * @param[out] len Number of data bytes remaining in the > segment > >> >>> (output). > >> >>> * Ignored when NULL. > >> >>> * > >> >>> - * @return Layer 2 start pointer, or NULL when packet does not > >> >>> contain a > >> >>> valid > >> >>> - * L2 header. > >> >>> + * @return Layer 2 start pointer > >> >>> + * @retval NULL packet does not contain a valid L2 header > >> >>> * > >> >>> * @see odp_packet_l2_offset(), odp_packet_l2_offset_set(), > >> >>> odp_packet_has_l2() > >> >>> */ > >> >>> @@ -469,8 +469,8 @@ void *odp_packet_l2_ptr(odp_packet_t pkt, > uint32_t > >> >>> *len); > >> >>> * > >> >>> * @param pkt Packet handle > >> >>> * > >> >>> - * @return Layer 2 start offset, or ODP_PACKET_OFFSET_INVALID when > >> >>> packet does > >> >>> - * not contain a valid L2 header. > >> >>> + * @return Layer 2 start offset > >> >>> + * @retval ODP_PACKET_OFFSET_INVALID packet does not contain a > valid > >> >>> L2 > >> >>> header > >> >>> * > >> >>> * @see odp_packet_l2_offset_set(), odp_packet_has_l2() > >> >>> */ > >> >>> @@ -486,8 +486,8 @@ uint32_t odp_packet_l2_offset(odp_packet_t pkt); > >> >>> * @param pkt Packet handle > >> >>> * @param offset Layer 2 start offset (0 ... odp_packet_len()-1) > >> >>> * > >> >>> - * @retval 0 Success > >> >>> - * @retval Non-zero Failure > >> >>> + * @retval 0 if successful > >> >>> + * @retval <0 on failure > >> >>> */ > >> >>> int odp_packet_l2_offset_set(odp_packet_t pkt, uint32_t offset); > >> >>> > >> >>> @@ -501,8 +501,8 @@ int odp_packet_l2_offset_set(odp_packet_t pkt, > >> >>> uint32_t offset); > >> >>> * @param[out] len Number of data bytes remaining in the > segment > >> >>> (output). > >> >>> * Ignored when NULL. > >> >>> * > >> >>> - * @return Layer 3 start pointer, or NULL when packet does not > >> >>> contain a > >> >>> valid > >> >>> - * L3 header. > >> >>> + * @return Layer 3 start pointer > >> >>> + * @retval NULL packet does not contain a valid L3 header > >> >>> * > >> >>> * @see odp_packet_l3_offset(), odp_packet_l3_offset_set(), > >> >>> odp_packet_has_l3() > >> >>> */ > >> >>> @@ -536,8 +536,8 @@ uint32_t odp_packet_l3_offset(odp_packet_t pkt); > >> >>> * @param pkt Packet handle > >> >>> * @param offset Layer 3 start offset (0 ... odp_packet_len()-1) > >> >>> * > >> >>> - * @retval 0 Success > >> >>> - * @retval Non-zero Failure > >> >>> + * @retval 0 if successful > >> >>> + * @retval <0 on failure > >> >>> */ > >> >>> int odp_packet_l3_offset_set(odp_packet_t pkt, uint32_t offset); > >> >>> > >> >>> @@ -551,8 +551,8 @@ int odp_packet_l3_offset_set(odp_packet_t pkt, > >> >>> uint32_t offset); > >> >>> * @param[out] len Number of data bytes remaining in the > segment > >> >>> (output). > >> >>> * Ignored when NULL. > >> >>> * > >> >>> - * @return Layer 4 start pointer, or NULL when packet does not > >> >>> contain a > >> >>> valid > >> >>> - * L4 header. > >> >>> + * @return Layer 4 start pointer > >> >>> + * @retval NULL packet does not contain a valid L4 header > >> >>> * > >> >>> * @see odp_packet_l4_offset(), odp_packet_l4_offset_set(), > >> >>> odp_packet_has_l4() > >> >>> */ > >> >>> @@ -569,8 +569,8 @@ void *odp_packet_l4_ptr(odp_packet_t pkt, > uint32_t > >> >>> *len); > >> >>> * > >> >>> * @param pkt Packet handle > >> >>> * > >> >>> - * @return Layer 4 start offset, or ODP_PACKET_OFFSET_INVALID when > >> >>> packet does > >> >>> - * not contain a valid L4 header. > >> >>> + * @return Layer 4 start offset > >> >>> + * @retval ODP_PACKET_OFFSET_INVALID packet does not contain a > valid > >> >>> L4 > >> >>> header > >> >>> * > >> >>> * @see odp_packet_l4_offset_set(), odp_packet_has_l4() > >> >>> */ > >> >>> @@ -586,8 +586,8 @@ uint32_t odp_packet_l4_offset(odp_packet_t pkt); > >> >>> * @param pkt Packet handle > >> >>> * @param offset Layer 4 start offset (0 ... odp_packet_len()-1) > >> >>> * > >> >>> - * @retval 0 Success > >> >>> - * @retval Non-zero Failure > >> >>> + * @retval 0 on success > >> >>> + * @retval <0 on failure > >> >>> */ > >> >>> int odp_packet_l4_offset_set(odp_packet_t pkt, uint32_t offset); > >> >>> > >> >>> @@ -645,7 +645,8 @@ odp_packet_seg_t > odp_packet_last_seg(odp_packet_t > >> >>> pkt); > >> >>> * @param pkt Packet handle > >> >>> * @param seg Current segment handle > >> >>> * > >> >>> - * @return Handle to the next segment, or ODP_PACKET_SEG_INVALID > >> >>> + * @return Handle to the next segment > >> >>> + * @retval ODP_PACKET_SEG_INVALID if there are no more segments > >> >>> */ > >> >>> odp_packet_seg_t odp_packet_next_seg(odp_packet_t pkt, > >> >>> odp_packet_seg_t > >> >>> seg); > >> >>> > >> >>> @@ -665,7 +666,8 @@ odp_packet_seg_t > odp_packet_next_seg(odp_packet_t > >> >>> pkt, > >> >>> odp_packet_seg_t seg); > >> >>> * @param pkt Packet handle > >> >>> * @param seg Segment handle > >> >>> * > >> >>> - * @return Start address of the segment, or NULL on an error > >> >>> + * @return Start address of the segment > >> >>> + * @retval NULL on failure > >> >>> * > >> >>> * @see odp_packet_seg_buf_len() > >> >>> */ > >> >>> @@ -693,7 +695,8 @@ uint32_t odp_packet_seg_buf_len(odp_packet_t > pkt, > >> >>> odp_packet_seg_t seg); > >> >>> * @param pkt Packet handle > >> >>> * @param seg Segment handle > >> >>> * > >> >>> - * @return Pointer to the segment data, or NULL on an error > >> >>> + * @return Pointer to the segment data > >> >>> + * @retval NULL on failure > >> >>> * > >> >>> * @see odp_packet_seg_data_len() > >> >>> */ > >> >>> @@ -735,7 +738,8 @@ uint32_t odp_packet_seg_data_len(odp_packet_t > pkt, > >> >>> odp_packet_seg_t seg); > >> >>> * @param offset Byte offset into the packet > >> >>> * @param len Number of bytes to add into the offset > >> >>> * > >> >>> - * @return New packet handle, or ODP_PACKET_INVALID in case of an > >> >>> error. > >> >>> + * @return New packet handle > >> >>> + * @retval ODP_PACKET_INVALID on failure > >> >>> */ > >> >>> odp_packet_t odp_packet_add_data(odp_packet_t pkt, uint32_t offset, > >> >>> uint32_t len); > >> >>> @@ -753,7 +757,8 @@ odp_packet_t odp_packet_add_data(odp_packet_t > pkt, > >> >>> uint32_t offset, > >> >>> * @param offset Byte offset into the packet > >> >>> * @param len Number of bytes to remove from the offset > >> >>> * > >> >>> - * @return New packet handle, or ODP_PACKET_INVALID in case of an > >> >>> error. > >> >>> + * @return New packet handle > >> >>> + * @retval ODP_PACKET_INVALID on failure > >> >>> */ > >> >>> odp_packet_t odp_packet_rem_data(odp_packet_t pkt, uint32_t offset, > >> >>> uint32_t len); > >> >>> @@ -776,7 +781,8 @@ odp_packet_t odp_packet_rem_data(odp_packet_t > pkt, > >> >>> uint32_t offset, > >> >>> * @param pkt Packet handle > >> >>> * @param pool Buffer pool for allocation of the new packet. > >> >>> * > >> >>> - * @return Handle to the copy of the packet, or ODP_PACKET_INVALID > >> >>> + * @return Handle to the copy of the packet > >> >>> + * @retval ODP_PACKET_INVALID on failure > >> >>> */ > >> >>> odp_packet_t odp_packet_copy(odp_packet_t pkt, odp_buffer_pool_t > >> >>> pool); > >> >>> > >> >>> @@ -791,8 +797,8 @@ odp_packet_t odp_packet_copy(odp_packet_t pkt, > >> >>> odp_buffer_pool_t pool); > >> >>> * @param len Number of bytes to copy > >> >>> * @param dst Destination address > >> >>> * > >> >>> - * @retval 0 Success > >> >>> - * @retval Non-zero Failure > >> >>> + * @retval 0 on success > >> >>> + * @retval <0 on failure > >> >>> */ > >> >>> int odp_packet_copydata_out(odp_packet_t pkt, uint32_t offset, > >> >>> uint32_t len, void *dst); > >> >>> @@ -809,8 +815,8 @@ int odp_packet_copydata_out(odp_packet_t pkt, > >> >>> uint32_t > >> >>> offset, > >> >>> * @param len Number of bytes to copy > >> >>> * @param src Source address > >> >>> * > >> >>> - * @retval 0 Success > >> >>> - * @retval Non-zero Failure > >> >>> + * @retval 0 on success > >> >>> + * @retval <0 on failure > >> >>> */ > >> >>> int odp_packet_copydata_in(odp_packet_t pkt, uint32_t offset, > >> >>> uint32_t len, const void *src); > >> >>> diff --git a/platform/linux-generic/include/api/odp_packet_flags.h > >> >>> b/platform/linux-generic/include/api/odp_packet_flags.h > >> >>> index 24c4065..399a0bf 100644 > >> >>> --- a/platform/linux-generic/include/api/odp_packet_flags.h > >> >>> +++ b/platform/linux-generic/include/api/odp_packet_flags.h > >> >>> @@ -32,7 +32,8 @@ extern "C" { > >> >>> * Checks all error flags at once. > >> >>> * > >> >>> * @param pkt Packet handle > >> >>> - * @return 1 if packet has errors, 0 otherwise > >> >>> + * @retval 1 if packet has errors > >> >>> + * @retval 0 if packet has no errors > >> >>> */ > >> >>> int odp_packet_error(odp_packet_t pkt); > >> >>> > >> >>> @@ -40,7 +41,8 @@ int odp_packet_error(odp_packet_t pkt); > >> >>> * Check if error was 'frame length' error > >> >>> * > >> >>> * @param pkt Packet handle > >> >>> - * @return 1 if frame length error detected, 0 otherwise > >> >>> + * @retval 1 if frame length error detected > >> >>> + * @retval 0 if frame length error not detected > >> >>> */ > >> >>> int odp_packet_errflag_frame_len(odp_packet_t pkt); > >> >>> > >> >>> @@ -48,7 +50,8 @@ int odp_packet_errflag_frame_len(odp_packet_t > pkt); > >> >>> * Check for L2 header, e.g. ethernet > >> >>> * > >> >>> * @param pkt Packet handle > >> >>> - * @return 1 if packet contains a valid & known L2 header, 0 > >> >>> otherwise > >> >>> + * @retval 1 if packet contains a valid & known L2 header > >> >>> + * @retval 0 if packet does not contain a valid & known L2 header > >> >>> */ > >> >>> int odp_packet_has_l2(odp_packet_t pkt); > >> >>> > >> >>> @@ -56,7 +59,8 @@ int odp_packet_has_l2(odp_packet_t pkt); > >> >>> * Check for L3 header, e.g. IPv4, IPv6 > >> >>> * > >> >>> * @param pkt Packet handle > >> >>> - * @return 1 if packet contains a valid & known L3 header, 0 > >> >>> otherwise > >> >>> + * @retval 1 if packet contains a valid & known L3 header > >> >>> + * @retval 0 if packet does not contain a valid & known L3 header > >> >>> */ > >> >>> int odp_packet_has_l3(odp_packet_t pkt); > >> >>> > >> >>> @@ -64,7 +68,8 @@ int odp_packet_has_l3(odp_packet_t pkt); > >> >>> * Check for L4 header, e.g. UDP, TCP, SCTP (also ICMP) > >> >>> * > >> >>> * @param pkt Packet handle > >> >>> - * @return 1 if packet contains a valid & known L4 header, 0 > >> >>> otherwise > >> >>> + * @retval 1 if packet contains a valid & known L4 header > >> >>> + * @retval 0 if packet does not contain a valid & known L4 header > >> >>> */ > >> >>> int odp_packet_has_l4(odp_packet_t pkt); > >> >>> > >> >>> @@ -72,7 +77,8 @@ int odp_packet_has_l4(odp_packet_t pkt); > >> >>> * Check for Ethernet header > >> >>> * > >> >>> * @param pkt Packet handle > >> >>> - * @return 1 if packet contains a valid eth header, 0 otherwise > >> >>> + * @retval 1 if packet contains a valid eth header > >> >>> + * @retval 0 if packet does not contain a valid & known eth header > >> >>> */ > >> >>> int odp_packet_has_eth(odp_packet_t pkt); > >> >>> > >> >>> @@ -80,7 +86,8 @@ int odp_packet_has_eth(odp_packet_t pkt); > >> >>> * Check for jumbo frame > >> >>> * > >> >>> * @param pkt Packet handle > >> >>> - * @return 1 if packet contains jumbo frame, 0 otherwise > >> >>> + * @retval 1 if packet contains a jumbo frame > >> >>> + * @retval 0 if packet does not contain a jumbo frame > >> >>> */ > >> >>> int odp_packet_has_jumbo(odp_packet_t pkt); > >> >>> > >> >>> @@ -88,7 +95,8 @@ int odp_packet_has_jumbo(odp_packet_t pkt); > >> >>> * Check for VLAN > >> >>> * > >> >>> * @param pkt Packet handle > >> >>> - * @return 1 if packet contains a VLAN header, 0 otherwise > >> >>> + * @retval 1 if packet contains a VLAN header > >> >>> + * @retval 0 if packet does not contain a VLAN header > >> >>> */ > >> >>> int odp_packet_has_vlan(odp_packet_t pkt); > >> >>> > >> >>> @@ -96,7 +104,8 @@ int odp_packet_has_vlan(odp_packet_t pkt); > >> >>> * Check for VLAN QinQ (stacked VLAN) > >> >>> * > >> >>> * @param pkt Packet handle > >> >>> - * @return 1 if packet contains a VLAN QinQ header, 0 otherwise > >> >>> + * @retval 1 if packet contains a VLAN QinQ header > >> >>> + * @retval 0 if packet does not contain a VLAN QinQ header > >> >>> */ > >> >>> int odp_packet_has_vlan_qinq(odp_packet_t pkt); > >> >>> > >> >>> @@ -104,7 +113,8 @@ int odp_packet_has_vlan_qinq(odp_packet_t pkt); > >> >>> * Check for ARP > >> >>> * > >> >>> * @param pkt Packet handle > >> >>> - * @return 1 if packet contains an ARP header, 0 otherwise > >> >>> + * @retval 1 if packet contains an ARP message > >> >>> + * @retval 0 if packet does not contain an ARP message > >> >>> */ > >> >>> int odp_packet_has_arp(odp_packet_t pkt); > >> >>> > >> >>> @@ -112,7 +122,8 @@ int odp_packet_has_arp(odp_packet_t pkt); > >> >>> * Check for IPv4 > >> >>> * > >> >>> * @param pkt Packet handle > >> >>> - * @return 1 if packet contains an IPv4 header, 0 otherwise > >> >>> + * @retval 1 if packet contains an IPv4 header > >> >>> + * @retval 0 if packet does not contain an IPv4 header > >> >>> */ > >> >>> int odp_packet_has_ipv4(odp_packet_t pkt); > >> >>> > >> >>> @@ -120,7 +131,8 @@ int odp_packet_has_ipv4(odp_packet_t pkt); > >> >>> * Check for IPv6 > >> >>> * > >> >>> * @param pkt Packet handle > >> >>> - * @return 1 if packet contains an IPv6 header, 0 otherwise > >> >>> + * @retval 1 if packet contains an IPv6 header > >> >>> + * @retval 0 if packet does not contain an IPv6 header > >> >>> */ > >> >>> int odp_packet_has_ipv6(odp_packet_t pkt); > >> >>> > >> >>> @@ -128,7 +140,8 @@ int odp_packet_has_ipv6(odp_packet_t pkt); > >> >>> * Check for IP fragment > >> >>> * > >> >>> * @param pkt Packet handle > >> >>> - * @return 1 if packet is an IP fragment, 0 otherwise > >> >>> + * @retval 1 if packet is an IP fragment > >> >>> + * @retval 0 if packet is not an IP fragment > >> >>> */ > >> >>> int odp_packet_has_ipfrag(odp_packet_t pkt); > >> >>> > >> >>> @@ -136,7 +149,8 @@ int odp_packet_has_ipfrag(odp_packet_t pkt); > >> >>> * Check for IP options > >> >>> * > >> >>> * @param pkt Packet handle > >> >>> - * @return 1 if packet contains IP options, 0 otherwise > >> >>> + * @retval 1 if packet contains IP options > >> >>> + * @retval 0 if packet does not contain IP options > >> >>> */ > >> >>> int odp_packet_has_ipopt(odp_packet_t pkt); > >> >>> > >> >>> @@ -144,7 +158,8 @@ int odp_packet_has_ipopt(odp_packet_t pkt); > >> >>> * Check for IPSec > >> >>> * > >> >>> * @param pkt Packet handle > >> >>> - * @return 1 if packet requires IPSec processing, 0 otherwise > >> >>> + * @retval 1 if packet requires IPSec processing > >> >>> + * @retval 0 if packet does not require IPSec processing > >> >>> */ > >> >>> int odp_packet_has_ipsec(odp_packet_t pkt); > >> >>> > >> >>> @@ -152,7 +167,8 @@ int odp_packet_has_ipsec(odp_packet_t pkt); > >> >>> * Check for UDP > >> >>> * > >> >>> * @param pkt Packet handle > >> >>> - * @return 1 if packet contains a UDP header, 0 otherwise > >> >>> + * @retval 1 if packet contains a UDP header > >> >>> + * @retval 0 if packet does not contain a UDP header > >> >>> */ > >> >>> int odp_packet_has_udp(odp_packet_t pkt); > >> >>> > >> >>> @@ -160,7 +176,8 @@ int odp_packet_has_udp(odp_packet_t pkt); > >> >>> * Check for TCP > >> >>> * > >> >>> * @param pkt Packet handle > >> >>> - * @return 1 if packet contains a TCP header, 0 otherwise > >> >>> + * @retval 1 if packet contains a TCP header > >> >>> + * @retval 0 if packet does not contain a TCP header > >> >>> */ > >> >>> int odp_packet_has_tcp(odp_packet_t pkt); > >> >>> > >> >>> @@ -168,7 +185,8 @@ int odp_packet_has_tcp(odp_packet_t pkt); > >> >>> * Check for SCTP > >> >>> * > >> >>> * @param pkt Packet handle > >> >>> - * @return 1 if packet contains an SCTP header, 0 otherwise > >> >>> + * @retval 1 if packet contains a SCTP header > >> >>> + * @retval 0 if packet does not contain a SCTP header > >> >>> */ > >> >>> int odp_packet_has_sctp(odp_packet_t pkt); > >> >>> > >> >>> @@ -176,7 +194,8 @@ int odp_packet_has_sctp(odp_packet_t pkt); > >> >>> * Check for ICMP > >> >>> * > >> >>> * @param pkt Packet handle > >> >>> - * @return 1 if packet contains an ICMP header, 0 otherwise > >> >>> + * @retval 1 if packet contains an ICMP header > >> >>> + * @retval 0 if packet does not contain an ICMP header > >> >>> */ > >> >>> int odp_packet_has_icmp(odp_packet_t pkt); > >> >>> > >> >>> diff --git a/platform/linux-generic/include/api/odp_packet_io.h > >> >>> b/platform/linux-generic/include/api/odp_packet_io.h > >> >>> index 4835f4d..1a770b6 100644 > >> >>> --- a/platform/linux-generic/include/api/odp_packet_io.h > >> >>> +++ b/platform/linux-generic/include/api/odp_packet_io.h > >> >>> @@ -40,7 +40,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 > >> >>> @@ -53,7 +54,8 @@ odp_pktio_t odp_pktio_open(const char *dev, > >> >>> odp_buffer_pool_t pool); > >> >>> * > >> >>> * @param id 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); > >> >>> > >> >>> @@ -62,7 +64,8 @@ int odp_pktio_close(odp_pktio_t id); > >> >>> * > >> >>> * @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); > >> >>> > >> >>> @@ -73,7 +76,8 @@ odp_pktio_t odp_pktio_lookup(const char *dev); > >> >>> * @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); > >> >>> > >> >>> @@ -84,7 +88,8 @@ int odp_pktio_recv(odp_pktio_t id, odp_packet_t > >> >>> pkt_table[], unsigned len); > >> >>> * @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); > >> >>> > >> >>> @@ -93,7 +98,8 @@ int odp_pktio_send(odp_pktio_t id, odp_packet_t > >> >>> pkt_table[], unsigned len); > >> >>> * > >> >>> * @param id 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); > >> >>> > >> >>> @@ -102,7 +108,8 @@ int odp_pktio_inq_setdef(odp_pktio_t id, > >> >>> odp_queue_t > >> >>> queue); > >> >>> * > >> >>> * @param id 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); > >> >>> > >> >>> @@ -111,7 +118,8 @@ odp_queue_t odp_pktio_inq_getdef(odp_pktio_t > id); > >> >>> * > >> >>> * @param id 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); > >> >>> > >> >>> @@ -120,7 +128,8 @@ int odp_pktio_inq_remdef(odp_pktio_t id); > >> >>> * > >> >>> * @param id 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); > >> >>> > >> >>> @@ -129,8 +138,8 @@ odp_queue_t odp_pktio_outq_getdef(odp_pktio_t > id); > >> >>> * > >> >>> * @param[in] id 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); > >> >>> > >> >>> @@ -140,8 +149,8 @@ int odp_pktio_mtu(odp_pktio_t id); > >> >>> * @param[in] id 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); > >> >>> > >> >>> @@ -152,7 +161,7 @@ int odp_pktio_promisc_mode_set(odp_pktio_t id, > >> >>> odp_bool_t enable); > >> >>> * > >> >>> * @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); > >> >>> > >> >>> @@ -163,9 +172,10 @@ int odp_pktio_promisc_mode(odp_pktio_t id); > >> >>> * @param[out] mac_addr Storage for MAC address of the packet IO > >> >>> interface. > >> >>> * @param addr_size Storage size for the address > >> >>> * > >> >>> - * @retval Number of bytes written on success, 0 on failure. > >> >>> + * @return Number of bytes written on success > >> >>> + * @retval <0 on failure > >> >>> */ > >> >>> -size_t odp_pktio_mac_addr(odp_pktio_t id, void *mac_addr, > >> >>> +int odp_pktio_mac_addr(odp_pktio_t id, void *mac_addr, > >> >>> size_t addr_size); > >> >>> > >> >>> /** > >> >>> @@ -177,7 +187,8 @@ size_t odp_pktio_mac_addr(odp_pktio_t id, void > >> >>> *mac_addr, > >> >>> * 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); > >> >>> > >> >>> @@ -189,7 +200,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. > >> >>> */ > >> >>> @@ -201,7 +213,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. > >> >>> * > >> >>> */ > >> >>> @@ -216,7 +229,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. > >> >>> */ > >> >>> diff --git a/platform/linux-generic/include/api/odp_queue.h > >> >>> b/platform/linux-generic/include/api/odp_queue.h > >> >>> index b0f7185..25633e0 100644 > >> >>> --- a/platform/linux-generic/include/api/odp_queue.h > >> >>> +++ b/platform/linux-generic/include/api/odp_queue.h > >> >>> @@ -118,7 +118,8 @@ typedef struct odp_queue_param_t { > >> >>> * @param type Queue type > >> >>> * @param param Queue parameters. Uses defaults if NULL. > >> >>> * > >> >>> - * @return Queue handle or ODP_QUEUE_INVALID > >> >>> + * @return Queue handle > >> >>> + * @retval ODP_QUEUE_INVALID on failure > >> >>> */ > >> >>> odp_queue_t odp_queue_create(const char *name, odp_queue_type_t > type, > >> >>> odp_queue_param_t *param); > >> >>> @@ -133,7 +134,8 @@ odp_queue_t odp_queue_create(const char *name, > >> >>> odp_queue_type_t type, > >> >>> * > >> >>> * @param queue Queue handle > >> >>> * > >> >>> - * @return 0 if successful > >> >>> + * @retval 0 on success > >> >>> + * @retval <0 on failure > >> >>> */ > >> >>> int odp_queue_destroy(odp_queue_t queue); > >> >>> > >> >>> @@ -142,7 +144,8 @@ int odp_queue_destroy(odp_queue_t queue); > >> >>> * > >> >>> * @param name Queue name > >> >>> * > >> >>> - * @return Queue handle or ODP_QUEUE_INVALID > >> >>> + * @return Queue handle > >> >>> + * @retval ODP_QUEUE_INVALID on failure > >> >>> */ > >> >>> odp_queue_t odp_queue_lookup(const char *name); > >> >>> > >> >>> @@ -156,7 +159,8 @@ odp_queue_t odp_queue_lookup(const char *name); > >> >>> * @param queue Queue handle > >> >>> * @param context Address to the queue context > >> >>> * > >> >>> - * @return 0 if successful > >> >>> + * @retval 0 on success > >> >>> + * @retval <0 on failure > >> >>> */ > >> >>> int odp_queue_set_context(odp_queue_t queue, void *context); > >> >>> > >> >>> @@ -165,8 +169,8 @@ int odp_queue_set_context(odp_queue_t queue, > void > >> >>> *context); > >> >>> * > >> >>> * @param queue Queue handle > >> >>> * > >> >>> - * @return If successful, a pointer to the queue context, > >> >>> - * NULL for failure. > >> >>> + * @return pointer to the queue context > >> >>> + * @retval NULL on failure > >> >>> */ > >> >>> void *odp_queue_get_context(odp_queue_t queue); > >> >>> > >> >>> @@ -176,7 +180,8 @@ void *odp_queue_get_context(odp_queue_t queue); > >> >>> * @param queue Queue handle > >> >>> * @param buf Buffer handle > >> >>> * > >> >>> - * @return 0 if succesful > >> >>> + * @retval 0 on success > >> >>> + * @retval <0 on failure > >> >>> */ > >> >>> int odp_queue_enq(odp_queue_t queue, odp_buffer_t buf); > >> >>> > >> >>> @@ -187,7 +192,8 @@ int odp_queue_enq(odp_queue_t queue, > odp_buffer_t > >> >>> buf); > >> >>> * @param buf Buffer handles > >> >>> * @param num Number of buffer handles > >> >>> * > >> >>> - * @return 0 if succesful > >> >>> + * @retval 0 on success > >> >>> + * @retval <0 on failure > >> >>> */ > >> >>> int odp_queue_enq_multi(odp_queue_t queue, odp_buffer_t buf[], int > >> >>> num); > >> >>> > >> >>> @@ -199,7 +205,8 @@ int odp_queue_enq_multi(odp_queue_t queue, > >> >>> odp_buffer_t buf[], int num); > >> >>> * > >> >>> * @param queue Queue handle > >> >>> * > >> >>> - * @return Buffer handle, or ODP_BUFFER_INVALID > >> >>> + * @return Buffer handle > >> >>> + * @retval ODP_BUFFER_INVALID on failure > >> >>> */ > >> >>> odp_buffer_t odp_queue_deq(odp_queue_t queue); > >> >>> > >> >>> diff --git a/platform/linux-generic/include/api/odp_schedule.h > >> >>> b/platform/linux-generic/include/api/odp_schedule.h > >> >>> index cdf6705..36fbba3 100644 > >> >>> --- a/platform/linux-generic/include/api/odp_schedule.h > >> >>> +++ b/platform/linux-generic/include/api/odp_schedule.h > >> >>> @@ -59,7 +59,8 @@ uint64_t odp_schedule_wait_time(uint64_t ns); > >> >>> * Use odp_schedule_wait_time() to convert time to > >> >>> other > >> >>> wait > >> >>> * values. > >> >>> * > >> >>> - * @return Next highest priority buffer, or ODP_BUFFER_INVALID > >> >>> + * @return Next highest priority buffer > >> >>> + * @retval ODP_BUFFER_INVALID on timeout > >> >>> */ > >> >>> odp_buffer_t odp_schedule(odp_queue_t *from, uint64_t wait); > >> >>> > >> >>> diff --git a/platform/linux-generic/include/api/odp_shared_memory.h > >> >>> b/platform/linux-generic/include/api/odp_shared_memory.h > >> >>> index f70db5a..78d108a 100644 > >> >>> --- a/platform/linux-generic/include/api/odp_shared_memory.h > >> >>> +++ b/platform/linux-generic/include/api/odp_shared_memory.h > >> >>> @@ -59,7 +59,8 @@ typedef struct odp_shm_info_t { > >> >>> * @param[in] flags Shared memory parameter flags (ODP_SHM_*). > >> >>> * Default value is 0. > >> >>> * > >> >>> - * @return Pointer to the reserved block, or NULL > >> >>> + * @return Handle of the reserved block > >> >>> + * @retval NULL on failure > >> >>> */ > >> >>> odp_shm_t odp_shm_reserve(const char *name, uint64_t size, uint64_t > >> >>> align, > >> >>> uint32_t flags); > >> >>> @@ -72,9 +73,9 @@ odp_shm_t odp_shm_reserve(const char *name, > uint64_t > >> >>> size, uint64_t align, > >> >>> * > >> >>> * @param[in] shm Block handle > >> >>> * > >> >>> - * @retval 0 if the handle is already free > >> >>> + * @retval 0 if the handle is already free (FIXME how can we know > >> >>> this?) > >> >> > >> >> > >> >> The linux-generic implementation tracks block allocation status. > Good > >> >> point > >> >> as to whether this should be part of the spec, however. > >> > The above definition puts some more restrictions on the ODP > >> > implementation. It must remember all past shm handles and their > >> > current status. How does this work if shm regions are created and > >> > destroyed repeatedly (an unlikely use case I agree). Possibly there is > >> > a fixed array of shm handles with generation counters for each handle > >> > but this will eventually wrap around and old stale handles become > >> > fresh again. > >> > > >> > Resource cleanup (e.g. for controlled program termination) has to be a > >> > highly synchronized operation anyway, you can't have worker threads > >> > continuing their execution, allocating buffers and timers, interacting > >> > with HW etc. when you are tearing down those resources. > >> > > >> > Specifying undefined behavior is better in my opinion. linux-generic > >> > only has to be changed so that it does not return 0 for an already > >> > freed shm region (because this would be a bad example and we want > >> > linux-generic to be a good example), instead it could call ODP_ABORT. > >> > > >> >> > >> >>> > >> >>> * @retval 0 if the handle free succeeds > >> >>> - * @retval -1 on failure to free the handle > >> >>> + * @retval <0 on failure to free the handle > >> >>> */ > >> >>> int odp_shm_free(odp_shm_t shm); > >> >>> > >> >>> @@ -84,7 +85,7 @@ int odp_shm_free(odp_shm_t shm); > >> >>> * @param[in] name Name of the block > >> >>> * > >> >>> * @return A handle to the block if it is found by name > >> >>> - * @retval #ODP_SHM_INVALID if the block is not found > >> >>> + * @retval ODP_SHM_INVALID on failure > >> >>> */ > >> >>> odp_shm_t odp_shm_lookup(const char *name); > >> >>> > >> >>> @@ -94,7 +95,8 @@ odp_shm_t odp_shm_lookup(const char *name); > >> >>> * > >> >>> * @param[in] shm Block handle > >> >>> * > >> >>> - * @return Memory block address, or NULL on error > >> >>> + * @return Memory block address > >> >>> + * @retval NULL on failure (FIXME: when?) > >> >> > >> >> > >> >> Why the FIXME? NULL is returned if the operation is unable to > succeed. > >> > Yes but when can the translation from shm handle to virtual address > >> > fail? Are there any situations where we think this is normal behavior? > >> > Shared memory regions that are not mapped to virtual memory? > >> > > >> > Passing invalid shm handles cause undefined behavior, not well-defined > >> > failures. > >> > So I am questioning why we need a @retval NULL for this function. > >> > > >> > > >> >> > >> >>> > >> >>> */ > >> >>> void *odp_shm_addr(odp_shm_t shm); > >> >>> > >> >>> @@ -105,7 +107,8 @@ void *odp_shm_addr(odp_shm_t shm); > >> >>> * @param[in] shm Block handle > >> >>> * @param[out] info Block info pointer for output > >> >>> * > >> >>> - * @return 0 on success, otherwise non-zero > >> >>> + * @retval 0 on success > >> >>> + * @retval <0 on failure > >> >>> */ > >> >>> int odp_shm_info(odp_shm_t shm, odp_shm_info_t *info); > >> >>> > >> >>> diff --git a/platform/linux-generic/include/api/odp_timer.h > >> >>> b/platform/linux-generic/include/api/odp_timer.h > >> >>> index 69402ef..c8c3270 100644 > >> >>> --- a/platform/linux-generic/include/api/odp_timer.h > >> >>> +++ b/platform/linux-generic/include/api/odp_timer.h > >> >>> @@ -112,8 +112,8 @@ typedef struct { > >> >>> * @param name Name of the timer pool. The string will be > >> >>> copied. > >> >>> * @param params Timer pool parameters. The content will be > >> >>> copied. > >> >>> * > >> >>> - * @return Timer pool handle if successful, otherwise > >> >>> ODP_TIMER_POOL_INVALID > >> >>> - * and errno set > >> >>> + * @return Timer pool handle on success > >> >>> + * @retval ODP_TIMER_POOL_INVALID on failure and errno set > >> >>> */ > >> >>> odp_timer_pool_t > >> >>> odp_timer_pool_create(const char *name, > >> >>> @@ -185,8 +185,8 @@ typedef struct { > >> >>> * @param tpid Timer pool identifier > >> >>> * @param[out] info Pointer to information buffer > >> >>> * > >> >>> - * @retval 0 Success > >> >>> - * @retval -1 Failure. Info could not be retrieved. > >> >>> + * @retval 0 on success > >> >>> + * @retval <0 on failure. Info could not be retrieved. > >> >>> */ > >> >>> int odp_timer_pool_info(odp_timer_pool_t tpid, > >> >>> odp_timer_pool_info_t *info); > >> >>> @@ -202,8 +202,8 @@ int odp_timer_pool_info(odp_timer_pool_t tpid, > >> >>> * @param queue Destination queue for timeout notifications > >> >>> * @param user_ptr User defined pointer or NULL to be copied to > >> >>> timeouts > >> >>> * > >> >>> - * @return Timer handle if successful, otherwise ODP_TIMER_INVALID > >> >>> and > >> >>> - * errno set. > >> >>> + * @return Timer handle on success > >> >>> + * @retval ODP_TIMER_INVALID on failure and errno set. > >> >>> */ > >> >>> odp_timer_t odp_timer_alloc(odp_timer_pool_t tpid, > >> >>> odp_queue_t queue, > >> >>> @@ -218,7 +218,8 @@ odp_timer_t odp_timer_alloc(odp_timer_pool_t > tpid, > >> >>> * responsibility of the application to handle this timeout when it > >> >>> is > >> >>> received. > >> >>> * > >> >>> * @param tim Timer handle > >> >>> - * @return Buffer handle of timeout buffer or ODP_BUFFER_INVALID > >> >>> + * @return Buffer handle of timeout buffer > >> >>> + * @retval ODP_BUFFER_INVALID on failure > >> >>> */ > >> >>> odp_buffer_t odp_timer_free(odp_timer_t tim); > >> >>> > >> >>> @@ -292,8 +293,8 @@ int odp_timer_set_rel(odp_timer_t tim, > >> >>> * > >> >>> * @param tim Timer > >> >>> * @param[out] tmo_buf Pointer to a buffer variable > >> >>> - * @retval 0 Success, active timer cancelled, timeout returned in > >> >>> '*tmo_buf' > >> >>> - * @retval -1 Failure, timer already expired (or inactive) > >> >>> + * @retval 0 on success, active timer cancelled, timeout returned > in > >> >>> '*tmo_buf' > >> >>> + * @retval <0 on failure, timer already expired (or inactive) > >> >>> */ > >> >>> int odp_timer_cancel(odp_timer_t tim, odp_buffer_t *tmo_buf); > >> >>> > >> >>> diff --git a/platform/linux-generic/odp_crypto.c > >> >>> b/platform/linux-generic/odp_crypto.c > >> >>> index 2f95cbe..ded3b62 100644 > >> >>> --- a/platform/linux-generic/odp_crypto.c > >> >>> +++ b/platform/linux-generic/odp_crypto.c > >> >>> @@ -343,7 +343,7 @@ > >> >>> odp_crypto_session_create(odp_crypto_session_params_t > >> >>> *params, > >> >>> > >> >>> int > >> >>> odp_crypto_operation(odp_crypto_op_params_t *params, > >> >>> - bool *posted, > >> >>> + odp_bool_t *posted, > >> >>> odp_buffer_t completion_event) > >> >>> { > >> >>> enum crypto_alg_err rc_cipher = ODP_CRYPTO_ALG_ERR_NONE; > >> >>> @@ -423,7 +423,7 @@ odp_crypto_init_global(void) > >> >>> } > >> >>> > >> >>> int > >> >>> -odp_hw_random_get(uint8_t *buf, size_t *len, bool use_entropy > >> >>> ODP_UNUSED) > >> >>> +odp_hw_random_get(uint8_t *buf, size_t *len, odp_bool_t use_entropy > >> >>> ODP_UNUSED) > >> >>> { > >> >>> int rc; > >> >>> rc = RAND_bytes(buf, *len); > >> >>> diff --git a/platform/linux-generic/odp_packet_io.c > >> >>> b/platform/linux-generic/odp_packet_io.c > >> >>> index 0efa3d0..c51098f 100644 > >> >>> --- a/platform/linux-generic/odp_packet_io.c > >> >>> +++ b/platform/linux-generic/odp_packet_io.c > >> >>> @@ -797,18 +797,18 @@ int odp_pktio_promisc_mode(odp_pktio_t id) > >> >>> } > >> >>> > >> >>> > >> >>> -size_t odp_pktio_mac_addr(odp_pktio_t id, void *mac_addr, > >> >>> +int odp_pktio_mac_addr(odp_pktio_t id, void *mac_addr, > >> >>> size_t addr_size) > >> >>> { > >> >>> pktio_entry_t *entry; > >> >>> > >> >>> if (addr_size < ETH_ALEN) > >> >>> - return 0; > >> >>> + return -1; > >> >>> > >> >>> entry = get_pktio_entry(id); > >> >>> if (entry == NULL) { > >> >>> ODP_DBG("pktio entry %d does not exist\n", id); > >> >>> - return 0; > >> >>> + return -1; > >> >>> } > >> >>> > >> >>> lock_entry(entry); > >> >>> diff --git a/test/validation/crypto/odp_crypto_test_async_inp.c > >> >>> b/test/validation/crypto/odp_crypto_test_async_inp.c > >> >>> index 96d4c3f..1db7844 100644 > >> >>> --- a/test/validation/crypto/odp_crypto_test_async_inp.c > >> >>> +++ b/test/validation/crypto/odp_crypto_test_async_inp.c > >> >>> @@ -34,7 +34,7 @@ static void alg_test(enum odp_crypto_op op, > >> >>> odp_crypto_session_t session; > >> >>> int rc; > >> >>> enum odp_crypto_ses_create_err status; > >> >>> - bool posted; > >> >>> + odp_bool_t posted; > >> >>> odp_buffer_t compl_event; > >> >>> > >> >>> odp_queue_t compl_queue = odp_queue_lookup("crypto-out"); > >> >>> diff --git a/test/validation/crypto/odp_crypto_test_sync_inp.c > >> >>> b/test/validation/crypto/odp_crypto_test_sync_inp.c > >> >>> index f37ad54..5082f13 100644 > >> >>> --- a/test/validation/crypto/odp_crypto_test_sync_inp.c > >> >>> +++ b/test/validation/crypto/odp_crypto_test_sync_inp.c > >> >>> @@ -23,7 +23,7 @@ static void alg_test(enum odp_crypto_op op, > >> >>> odp_crypto_session_t session; > >> >>> int rc; > >> >>> enum odp_crypto_ses_create_err status; > >> >>> - bool posted; > >> >>> + odp_bool_t posted; > >> >>> > >> >>> odp_queue_t compl_queue = odp_queue_lookup("crypto-out"); > >> >>> CU_ASSERT(compl_queue != ODP_QUEUE_INVALID); > >> >>> -- > >> >>> 1.9.1 > >> >>> > >> >>> > >> >>> _______________________________________________ > >> >>> lng-odp mailing list > >> >>> lng-odp@lists.linaro.org > >> >>> http://lists.linaro.org/mailman/listinfo/lng-odp > >> >> > >> >> > > > > >
On 27 January 2015 at 14:32, 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, January 27, 2015 2:44 PM >> To: Bill Fischofer >> Cc: LNG ODP Mailman List >> Subject: Re: [lng-odp] [PATCH] api: unify @return/@retval descriptions and >> return types >> >> On 27 January 2015 at 12:52, Bill Fischofer <bill.fischofer@linaro.org> >> wrote: >> > I think it's good practice for functions to be robust in parameter >> handling >> > unless they are expected to be used in performance paths. That's the >> reason >> > why we've said that things like odp_buffer_addr() etc. have undefined >> > behavior if they're passed invalid handles. But shm and pools are >> things >> > that will typically get set up once during init, and seldom changed >> (maybe >> > as part of reconfig) so the performance argument is less compelling >> there. >> I agree but this is not only about performance. Sprinkling the API's >> with error codes also forces the user to check those return values >> which complicates the application logic and probably creates code that >> will be difficult to get test coverage for. I have a lot of experience >> with API's that cannot return errors and I really prefer this style. >> Applications becomes so much simpler. >> >> Why should odp_shm_addr() be allowed to return an error code? Most >> implementations most likely will not even utilize the possibility and >> applications will not expect an error to happen and so might not even >> check the return value. How often do you check the return value of >> printf or close? >> >> Just because the functions do not have to check for valid parameters >> so that they can return corresponding error indications does not mean >> that implementations cannot and should not check for (in)valid >> parameters. But if invalid parameters are detected, the error has to >> be signaled in some other way, e.g. by calling ODP_ABORT (as ODP >> doesn't have any error handling mechanism for users to hook into). >> >> The timer implementation always checks timer pool handles and timer >> handles for validity. As ODP_ABORT (which does not return control to >> the caller) is used to report invalid parameters, the applications >> cannot rely on the ODP implementation handling invalid parameters. In >> another implementation, the checks could be removed with no change of >> semantics. As you say that should only be considered for truly >> performance critical functions. >> >> > > > I have also experience with (the same) API that cannot return errors and didn't like it always. Sometimes application has better idea about the severity of the failure and could prefer to back off or retry (the API call), instead of just crashing right there. We are talking about how to handle invalid parameters. Not e.g. out of resource situations. I agree that the OSE alloc() semantics are not ideal, especially not for dataplane applications which can easily and uncontrollably experience overload situations. That's why ODP does return error codes when it cannot satisfy e.g. buffer and timer allocations. > > Also if every call fails through an error handler, it will contain large part of the application logic (without exact information about the error context). I don't advocate that we implement an error handler in ODP. As long as the current model works we are fine. The OSE error handling mechanism might also not be the ideal to strive for (too many levels, to unrestricted what the user could do). > > There's a difference if a call failed due to a corrupt handle, or if the resource was freed/become unusable in parallel (timing / status failure). The first, should crash right there, the second could return failure (and application could decide what to do next). I agree that multithreaded scenarios require some additional care. As we discussed, access to shared resources have more issues with concurrent access from different threads. We shouldn't automatically force race conditions involving shared resources to crash, implementations should have the potential to notify the caller of failures. But in general stale handles (e.g. when pointers are used) cannot be separated from corrupt handles unless you maintain a list of all formerly valid handles. > > > -Petri > > > > >
diff --git a/example/ipsec/odp_ipsec.c b/example/ipsec/odp_ipsec.c index f2fac8a..066dc40 100644 --- a/example/ipsec/odp_ipsec.c +++ b/example/ipsec/odp_ipsec.c @@ -683,7 +683,7 @@ pkt_disposition_e do_ipsec_in_classify(odp_packet_t pkt, odph_esphdr_t *esp = NULL; ipsec_cache_entry_t *entry; odp_crypto_op_params_t params; - bool posted = 0; + odp_bool_t posted = 0; /* Default to skip IPsec */ *skip = TRUE; @@ -955,7 +955,7 @@ pkt_disposition_e do_ipsec_out_seq(odp_packet_t pkt, pkt_ctx_t *ctx) { uint8_t *buf = odp_packet_data(pkt); - bool posted = 0; + odp_bool_t posted = 0; /* We were dispatched from atomic queue, assign sequence numbers */ if (ctx->ipsec.ah_offset) { diff --git a/platform/linux-generic/include/api/odp_buffer.h b/platform/linux-generic/include/api/odp_buffer.h index 0670464..fd0871b 100644 --- a/platform/linux-generic/include/api/odp_buffer.h +++ b/platform/linux-generic/include/api/odp_buffer.h @@ -32,6 +32,7 @@ extern "C" { * Buffer start address * * @param buf Buffer handle + * Note: Buffer handle must be valid or the behavior will be undefined. * * @return Buffer start address */ @@ -41,6 +42,7 @@ void *odp_buffer_addr(odp_buffer_t buf); * Buffer maximum data size * * @param buf Buffer handle + * Note: Buffer handle must be valid or the behavior will be undefined. * * @return Buffer maximum data size */ @@ -50,12 +52,12 @@ uint32_t odp_buffer_size(odp_buffer_t buf); * Buffer type * * @param buf Buffer handle + * Note: Buffer handle must be valid or the behavior will be undefined. * * @return Buffer type */ int odp_buffer_type(odp_buffer_t buf); -#define ODP_BUFFER_TYPE_INVALID (-1) /**< Buffer type invalid */ #define ODP_BUFFER_TYPE_ANY 0 /**< Buffer that can hold any other buffer type */ #define ODP_BUFFER_TYPE_RAW 1 /**< Raw buffer, no additional metadata */ @@ -65,7 +67,9 @@ int odp_buffer_type(odp_buffer_t buf); /** * Tests if buffer is valid * - * @param buf Buffer handle + * @param buf Buffer handle (possibly invalid) + * Note: This is the only call which accepts invalid buffer handles (any bit + * value) without causing undefined behavior. * * @retval 1 Buffer handle represents a valid buffer. * @retval 0 Buffer handle does not represent a valid buffer. @@ -76,6 +80,7 @@ int odp_buffer_is_valid(odp_buffer_t buf); * Buffer pool of the buffer * * @param buf Buffer handle + * Note: Buffer handle must be valid or the behavior will be undefined. * * @return Handle of buffer pool buffer belongs to */ diff --git a/platform/linux-generic/include/api/odp_buffer_pool.h b/platform/linux-generic/include/api/odp_buffer_pool.h index 8380ac1..fe917a4 100644 --- a/platform/linux-generic/include/api/odp_buffer_pool.h +++ b/platform/linux-generic/include/api/odp_buffer_pool.h @@ -81,8 +81,8 @@ odp_buffer_pool_t odp_buffer_pool_create(const char *name, * * @param pool Handle of the buffer pool to be destroyed * - * @retval 0 Success - * @retval -1 Failure + * @retval 0 if successful + * @retval <0 on failure * * @note This routine destroys a previously created buffer pool. This call * does not destroy any shared memory object passed to @@ -117,7 +117,7 @@ typedef struct odp_buffer_pool_info_t { odp_shm_t shm; /**< handle of shared memory area supplied by application to contain buffer pool, or - ODP_SHM_INVALID if this pool is + ODP_SHM_NULL if this pool is managed by ODP */ odp_buffer_pool_param_t params; /**< pool parameters */ } odp_buffer_pool_info_t; @@ -125,13 +125,13 @@ typedef struct odp_buffer_pool_info_t { /** * Retrieve information about a buffer pool * - * @param pool Buffer pool handle + * @param pool Buffer pool handle (possibly invalid) * * @param[out] info Receives an odp_buffer_pool_info_t object * that describes the pool. * - * @retval 0 Success - * @retval -1 Failure. Info could not be retrieved. + * @retval 0 if successful + * @retval <0 on failure. Info could not be retrieved (invalid pool handle) */ int odp_buffer_pool_info(odp_buffer_pool_t pool, @@ -149,17 +149,22 @@ void odp_buffer_pool_print(odp_buffer_pool_t pool); /** * Buffer alloc + * Note: the pool handle must be valid or the behavior is undefined. + * + * The validity of a buffer handle can be checked at any time using + * odp_buffer_is_valid() * - * The validity of a buffer can be cheked at any time with odp_buffer_is_valid() * @param pool Pool handle * * @return Handle of allocated buffer - * @retval ODP_BUFFER_INVALID Buffer could not be allocated + * @retval ODP_BUFFER_INVALID Buffer could not be allocated (e.g. pool + * exhausted) */ odp_buffer_t odp_buffer_alloc(odp_buffer_pool_t pool); /** * Buffer free + * Note: the buffer handle must be valid or the behavior is undefined. * * @param buf Buffer handle * diff --git a/platform/linux-generic/include/api/odp_byteorder.h b/platform/linux-generic/include/api/odp_byteorder.h index 5890011..8e38937 100644 --- a/platform/linux-generic/include/api/odp_byteorder.h +++ b/platform/linux-generic/include/api/odp_byteorder.h @@ -24,7 +24,7 @@ extern "C" { #include <odp_compiler.h> /** @defgroup odp_compiler_optim ODP COMPILER / OPTIMIZATION - * Macros that check byte order and byte converting operations. + * Macros that check and convert byte order. * @{ */ diff --git a/platform/linux-generic/include/api/odp_classification.h b/platform/linux-generic/include/api/odp_classification.h index 46189bc..6bca8fc 100644 --- a/platform/linux-generic/include/api/odp_classification.h +++ b/platform/linux-generic/include/api/odp_classification.h @@ -79,8 +79,8 @@ typedef enum odp_cos_hdr_flow_fields { * * @param[in] name String intended for debugging purposes. * - * @return Class of service instance identifier, - * or ODP_COS_INVALID on error. + * @return Class of service instance identifier + * @retval ODP_COS_INVALID on failure. */ odp_cos_t odp_cos_create(const char *name); @@ -89,7 +89,8 @@ odp_cos_t odp_cos_create(const char *name); * * @param[in] cos_id class-of-service instance. * - * @return 0 on success, non-zero on error. + * @retval 0 if successful + * @retval <0 on failure */ int odp_cos_destroy(odp_cos_t cos_id); @@ -102,7 +103,8 @@ int odp_cos_destroy(odp_cos_t cos_id); * of this specific class of service * will be enqueued. * - * @return 0 on success, non-zero on error. + * @retval 0 if successful + * @retval <0 on failure */ int odp_cos_set_queue(odp_cos_t cos_id, odp_queue_t queue_id); @@ -112,7 +114,8 @@ int odp_cos_set_queue(odp_cos_t cos_id, odp_queue_t queue_id); * @param[in] cos_id class-of-service instance. * @param[in] drop_policy Desired packet drop policy for this class. * - * @return 0 on success, non-zero on error. + * @retval 0 if successful + * @retval <0 on failure * * @note Optional. */ @@ -127,7 +130,8 @@ int odp_cos_set_drop(odp_cos_t cos_id, odp_drop_e drop_policy); * @param[in] qos_table Values of the Layer-2 QoS header field. * @param[in] cos_table Class-of-service assigned to each of the * allowed Layer-2 QOS levels. - * @return 0 on success, non-zero on error. + * @retval 0 if successful + * @retval <0 on failure */ int odp_cos_with_l2_priority(odp_pktio_t pktio_in, uint8_t num_qos, @@ -146,7 +150,8 @@ int odp_cos_with_l2_priority(odp_pktio_t pktio_in, * @param[in] l3_preference when true, Layer-3 QoS overrides * L2 QoS when present. * - * @return 0 on success, non-zero on error. + * @retval 0 if successful + * @retval <0 on failure * * @note Optional. */ @@ -219,7 +224,8 @@ typedef enum odp_pmr_term { * that must match the value size requirement of the * specific term. * - * @return Handle of the matching rule or ODP_PMR_INVAL on error + * @return Handle of the matching rule + * @retval ODP_PMR_INVAL on failure */ odp_pmr_t odp_pmr_create_match(odp_pmr_term_e term, const void *val, @@ -236,7 +242,8 @@ odp_pmr_t odp_pmr_create_match(odp_pmr_term_e term, * that must match the value size requirement of the * specific term. * - * @return Handle of the matching rule or ODP_PMR_INVAL on error + * @return Handle of the matching rule + * @retval ODP_PMR_INVAL on failure * @note: Range is inclusive [val1..val2]. */ odp_pmr_t odp_pmr_create_range(odp_pmr_term_e term, @@ -248,7 +255,8 @@ odp_pmr_t odp_pmr_create_range(odp_pmr_term_e term, * * @param[in] pmr_id Identifier of the PMR to be destroyed * - * @return 0 on success, non-zero or error. + * @retval 0 if successful + * @retval <0 on failure */ int odp_pmr_destroy(odp_pmr_t pmr_id); @@ -259,7 +267,8 @@ int odp_pmr_destroy(odp_pmr_t pmr_id); * @param[in] src_pktio pktio to which this PMR is to be applied * @param[in] dst_cos CoS to be assigned by this PMR * - * @return 0 on success, non-zero or error. + * @retval 0 if successful + * @retval <0 on failure */ int odp_pktio_pmr_cos(odp_pmr_t pmr_id, odp_pktio_t src_pktio, odp_cos_t dst_cos); @@ -272,7 +281,8 @@ int odp_pktio_pmr_cos(odp_pmr_t pmr_id, * @param[in] dst_cos CoS to be assigned to packets filtered * from src_cos that match pmr_id. * - * @return 0 on success, non-zero on error. + * @retval 0 if successful + * @retval <0 on failure */ int odp_cos_pmr_cos(odp_pmr_t pmr_id, odp_cos_t src_cos, odp_cos_t dst_cos); @@ -346,12 +356,10 @@ typedef uint32_t odp_pmr_set_t; * term desired. * @param[out] pmr_set_id Returned handle to the composite rule set. * - * @return Return value may be a positive number - * indicating the number of terms elements + * @return the number of terms elements * that have been successfully mapped to the - * underlying platform classification engine and - * may be in the range from 1 to num_terms, - * or non-zero for error. + * underlying platform classification engine + * @retval <0 on failure */ int odp_pmr_match_set_create(int num_terms, odp_pmr_match_t *terms, odp_pmr_set_t *pmr_set_id); @@ -369,7 +377,8 @@ int odp_pmr_match_set_create(int num_terms, odp_pmr_match_t *terms, * @param[in] pmr_set_id A composite rule-set handle * returned when created. * - * @return 0 on success, non-zero on error. + * @retval 0 if successful + * @retval <0 on failure */ int odp_pmr_match_set_destroy(odp_pmr_set_t pmr_set_id); @@ -381,7 +390,8 @@ int odp_pmr_match_set_destroy(odp_pmr_set_t pmr_set_id); * set is to be applied * @param[in] dst_cos CoS to be assigned by this PMR match set * - * @return 0 on success, non-zero or error. + * @retval 0 if successful + * @retval <0 on failure */ int odp_pktio_pmr_match_set_cos(odp_pmr_set_t pmr_set_id, odp_pktio_t src_pktio, odp_cos_t dst_cos); diff --git a/platform/linux-generic/include/api/odp_cpumask.h b/platform/linux-generic/include/api/odp_cpumask.h index ebff9b0..5c5bcd7 100644 --- a/platform/linux-generic/include/api/odp_cpumask.h +++ b/platform/linux-generic/include/api/odp_cpumask.h @@ -79,7 +79,8 @@ void odp_cpumask_clr(odp_cpumask_t *mask, int cpu); * Test if cpu is a member of mask * @param mask CPU mask to check if cpu num set or not * @param cpu CPU number - * @return non-zero if set otherwise 0 + * @return non-zero if set + * @retval 0 if not set */ int odp_cpumask_isset(const odp_cpumask_t *mask, int cpu); @@ -134,14 +135,16 @@ void odp_cpumask_copy(odp_cpumask_t *dest, const odp_cpumask_t *src); /** * Find first bit set in mask * - * @return cpu else -1 if no bits set in cpumask + * @return cpu + * @retval -1 if no bits set in cpumask */ int odp_cpumask_first(const odp_cpumask_t *mask); /** * Find last bit set in mask * - * @return cpu else -1 if no bits set in cpumask + * @return cpu + * @retval -1 if no bits set in cpumask */ int odp_cpumask_last(const odp_cpumask_t *mask); @@ -160,7 +163,8 @@ int odp_cpumask_last(const odp_cpumask_t *mask); * * @param mask CPU mask to find next cpu in * @param cpu CPU to start from - * @return cpu found else -1 + * @return cpu found + * @retval -1 if not found * * @see odp_cpumask_first() */ diff --git a/platform/linux-generic/include/api/odp_crypto.h b/platform/linux-generic/include/api/odp_crypto.h index 337e7cf..2f00f95 100644 --- a/platform/linux-generic/include/api/odp_crypto.h +++ b/platform/linux-generic/include/api/odp_crypto.h @@ -218,7 +218,8 @@ typedef struct odp_crypto_compl_status { * @param session Created session else ODP_CRYPTO_SESSION_INVALID * @param status Failure code if unsuccessful * - * @return 0 if successful else -1 + * @retval 0 if successful + * @retval <0 on failure */ int odp_crypto_session_create(odp_crypto_session_params_t *params, @@ -242,11 +243,12 @@ odp_crypto_session_create(odp_crypto_session_params_t *params, * @param posted Pointer to return posted, TRUE for async operation * @param completion_event Event by which the operation results are delivered. * - * @return 0 if successful else -1 + * @retval 0 if successful + * @retval <0 on failure */ int odp_crypto_operation(odp_crypto_op_params_t *params, - bool *posted, + odp_bool_t *posted, odp_buffer_t completion_event); /** @@ -281,7 +283,7 @@ odp_crypto_get_operation_compl_status(odp_buffer_t completion_event, * * @param completion_event Event containing operation results * - * @return Packet structure where data now resides + * @return Handle for packet where data now resides */ odp_packet_t odp_crypto_get_operation_compl_packet(odp_buffer_t completion_event); @@ -305,10 +307,11 @@ odp_crypto_get_operation_compl_ctx(odp_buffer_t completion_event); * * @todo Define the implication of the use_entropy parameter * - * @return 0 if succesful + * @retval 0 if successful + * @retval <0 on failure */ int -odp_hw_random_get(uint8_t *buf, size_t *len, bool use_entropy); +odp_hw_random_get(uint8_t *buf, size_t *len, odp_bool_t use_entropy); /** * @} diff --git a/platform/linux-generic/include/api/odp_init.h b/platform/linux-generic/include/api/odp_init.h index ac856df..4a98717 100644 --- a/platform/linux-generic/include/api/odp_init.h +++ b/platform/linux-generic/include/api/odp_init.h @@ -66,8 +66,8 @@ typedef enum odp_log_level { * @param[in] level Log level * @param[in] fmt printf-style message format * - * @return The number of characters logged if succeeded. Otherwise returns - * a negative number. + * @return The number of characters logged if successful + * @retval <0 on failure */ int odp_override_log(odp_log_level_e level, const char *fmt, ...); @@ -109,7 +109,7 @@ typedef struct odp_platform_init_t { * interpretation by the ODP API to the implementation. * * @retval 0 if successful - * @retval -1 on failure + * @retval <0 on failure */ int odp_init_global(odp_init_t *params, odp_platform_init_t *platform_params); @@ -134,7 +134,7 @@ int odp_init_global(odp_init_t *params, odp_platform_init_t *platform_params); * @sa odp_term_local() which must have been called prior to this. * * @retval 0 if successful - * @retval -1 on failure + * @retval <0 on failure */ int odp_term_global(void); @@ -148,7 +148,7 @@ int odp_term_global(void); * @sa odp_init_global() which must have been called prior to this. * * @retval 0 if successful - * @retval -1 on failure + * @retval <0 on failure */ int odp_init_local(void); diff --git a/platform/linux-generic/include/api/odp_packet.h b/platform/linux-generic/include/api/odp_packet.h index 920a593..b471d07 100644 --- a/platform/linux-generic/include/api/odp_packet.h +++ b/platform/linux-generic/include/api/odp_packet.h @@ -88,8 +88,8 @@ void odp_packet_free(odp_packet_t pkt); * @param pkt Packet handle * @param len Packet data length * - * @retval 0 Success - * @retval Non-zero Failure + * @retval 0 if successful + * @retval <0 on failure * * @see odp_packet_buf_len() */ @@ -279,7 +279,7 @@ void *odp_packet_push_head(odp_packet_t pkt, uint32_t len); * @param pkt Packet handle * @param len Number of bytes to pull the head (0 ... seg_len - 1) * - * @return The new data pointer, or NULL in case of an error. + * @return The new data pointer * @retval NULL Requested offset exceeds packet segment length * * @see odp_packet_seg_len(), odp_packet_push_head() @@ -391,7 +391,7 @@ odp_buffer_pool_t odp_packet_pool(odp_packet_t pkt); * @param pkt Packet handle * * @return Packet interface handle - * @retval ODP_PKTIO_INVALID Packet was not received + * @retval ODP_PKTIO_INVALID Packet was not received on any interface */ odp_pktio_t odp_packet_input(odp_packet_t pkt); @@ -451,8 +451,8 @@ void odp_packet_user_u64_set(odp_packet_t pkt, uint64_t ctx); * @param[out] len Number of data bytes remaining in the segment (output). * Ignored when NULL. * - * @return Layer 2 start pointer, or NULL when packet does not contain a valid - * L2 header. + * @return Layer 2 start pointer + * @retval NULL packet does not contain a valid L2 header * * @see odp_packet_l2_offset(), odp_packet_l2_offset_set(), odp_packet_has_l2() */ @@ -469,8 +469,8 @@ void *odp_packet_l2_ptr(odp_packet_t pkt, uint32_t *len); * * @param pkt Packet handle * - * @return Layer 2 start offset, or ODP_PACKET_OFFSET_INVALID when packet does - * not contain a valid L2 header. + * @return Layer 2 start offset + * @retval ODP_PACKET_OFFSET_INVALID packet does not contain a valid L2 header * * @see odp_packet_l2_offset_set(), odp_packet_has_l2() */ @@ -486,8 +486,8 @@ uint32_t odp_packet_l2_offset(odp_packet_t pkt); * @param pkt Packet handle * @param offset Layer 2 start offset (0 ... odp_packet_len()-1) * - * @retval 0 Success - * @retval Non-zero Failure + * @retval 0 if successful + * @retval <0 on failure */ int odp_packet_l2_offset_set(odp_packet_t pkt, uint32_t offset); @@ -501,8 +501,8 @@ int odp_packet_l2_offset_set(odp_packet_t pkt, uint32_t offset); * @param[out] len Number of data bytes remaining in the segment (output). * Ignored when NULL. * - * @return Layer 3 start pointer, or NULL when packet does not contain a valid - * L3 header. + * @return Layer 3 start pointer + * @retval NULL packet does not contain a valid L3 header * * @see odp_packet_l3_offset(), odp_packet_l3_offset_set(), odp_packet_has_l3() */ @@ -536,8 +536,8 @@ uint32_t odp_packet_l3_offset(odp_packet_t pkt); * @param pkt Packet handle * @param offset Layer 3 start offset (0 ... odp_packet_len()-1) * - * @retval 0 Success - * @retval Non-zero Failure + * @retval 0 if successful + * @retval <0 on failure */ int odp_packet_l3_offset_set(odp_packet_t pkt, uint32_t offset); @@ -551,8 +551,8 @@ int odp_packet_l3_offset_set(odp_packet_t pkt, uint32_t offset); * @param[out] len Number of data bytes remaining in the segment (output). * Ignored when NULL. * - * @return Layer 4 start pointer, or NULL when packet does not contain a valid - * L4 header. + * @return Layer 4 start pointer + * @retval NULL packet does not contain a valid L4 header * * @see odp_packet_l4_offset(), odp_packet_l4_offset_set(), odp_packet_has_l4() */ @@ -569,8 +569,8 @@ void *odp_packet_l4_ptr(odp_packet_t pkt, uint32_t *len); * * @param pkt Packet handle * - * @return Layer 4 start offset, or ODP_PACKET_OFFSET_INVALID when packet does - * not contain a valid L4 header. + * @return Layer 4 start offset + * @retval ODP_PACKET_OFFSET_INVALID packet does not contain a valid L4 header * * @see odp_packet_l4_offset_set(), odp_packet_has_l4() */ @@ -586,8 +586,8 @@ uint32_t odp_packet_l4_offset(odp_packet_t pkt); * @param pkt Packet handle * @param offset Layer 4 start offset (0 ... odp_packet_len()-1) * - * @retval 0 Success - * @retval Non-zero Failure + * @retval 0 on success + * @retval <0 on failure */ int odp_packet_l4_offset_set(odp_packet_t pkt, uint32_t offset); @@ -645,7 +645,8 @@ odp_packet_seg_t odp_packet_last_seg(odp_packet_t pkt); * @param pkt Packet handle * @param seg Current segment handle * - * @return Handle to the next segment, or ODP_PACKET_SEG_INVALID + * @return Handle to the next segment + * @retval ODP_PACKET_SEG_INVALID if there are no more segments */ odp_packet_seg_t odp_packet_next_seg(odp_packet_t pkt, odp_packet_seg_t seg); @@ -665,7 +666,8 @@ odp_packet_seg_t odp_packet_next_seg(odp_packet_t pkt, odp_packet_seg_t seg); * @param pkt Packet handle * @param seg Segment handle * - * @return Start address of the segment, or NULL on an error + * @return Start address of the segment + * @retval NULL on failure * * @see odp_packet_seg_buf_len() */ @@ -693,7 +695,8 @@ uint32_t odp_packet_seg_buf_len(odp_packet_t pkt, odp_packet_seg_t seg); * @param pkt Packet handle * @param seg Segment handle * - * @return Pointer to the segment data, or NULL on an error + * @return Pointer to the segment data + * @retval NULL on failure * * @see odp_packet_seg_data_len() */ @@ -735,7 +738,8 @@ uint32_t odp_packet_seg_data_len(odp_packet_t pkt, odp_packet_seg_t seg); * @param offset Byte offset into the packet * @param len Number of bytes to add into the offset * - * @return New packet handle, or ODP_PACKET_INVALID in case of an error. + * @return New packet handle + * @retval ODP_PACKET_INVALID on failure */ odp_packet_t odp_packet_add_data(odp_packet_t pkt, uint32_t offset, uint32_t len); @@ -753,7 +757,8 @@ odp_packet_t odp_packet_add_data(odp_packet_t pkt, uint32_t offset, * @param offset Byte offset into the packet * @param len Number of bytes to remove from the offset * - * @return New packet handle, or ODP_PACKET_INVALID in case of an error. + * @return New packet handle + * @retval ODP_PACKET_INVALID on failure */ odp_packet_t odp_packet_rem_data(odp_packet_t pkt, uint32_t offset, uint32_t len); @@ -776,7 +781,8 @@ odp_packet_t odp_packet_rem_data(odp_packet_t pkt, uint32_t offset, * @param pkt Packet handle * @param pool Buffer pool for allocation of the new packet. * - * @return Handle to the copy of the packet, or ODP_PACKET_INVALID + * @return Handle to the copy of the packet + * @retval ODP_PACKET_INVALID on failure */ odp_packet_t odp_packet_copy(odp_packet_t pkt, odp_buffer_pool_t pool); @@ -791,8 +797,8 @@ odp_packet_t odp_packet_copy(odp_packet_t pkt, odp_buffer_pool_t pool); * @param len Number of bytes to copy * @param dst Destination address * - * @retval 0 Success - * @retval Non-zero Failure + * @retval 0 on success + * @retval <0 on failure */ int odp_packet_copydata_out(odp_packet_t pkt, uint32_t offset, uint32_t len, void *dst); @@ -809,8 +815,8 @@ int odp_packet_copydata_out(odp_packet_t pkt, uint32_t offset, * @param len Number of bytes to copy * @param src Source address * - * @retval 0 Success - * @retval Non-zero Failure + * @retval 0 on success + * @retval <0 on failure */ int odp_packet_copydata_in(odp_packet_t pkt, uint32_t offset, uint32_t len, const void *src); diff --git a/platform/linux-generic/include/api/odp_packet_flags.h b/platform/linux-generic/include/api/odp_packet_flags.h index 24c4065..399a0bf 100644 --- a/platform/linux-generic/include/api/odp_packet_flags.h +++ b/platform/linux-generic/include/api/odp_packet_flags.h @@ -32,7 +32,8 @@ extern "C" { * Checks all error flags at once. * * @param pkt Packet handle - * @return 1 if packet has errors, 0 otherwise + * @retval 1 if packet has errors + * @retval 0 if packet has no errors */ int odp_packet_error(odp_packet_t pkt); @@ -40,7 +41,8 @@ int odp_packet_error(odp_packet_t pkt); * Check if error was 'frame length' error * * @param pkt Packet handle - * @return 1 if frame length error detected, 0 otherwise + * @retval 1 if frame length error detected + * @retval 0 if frame length error not detected */ int odp_packet_errflag_frame_len(odp_packet_t pkt); @@ -48,7 +50,8 @@ int odp_packet_errflag_frame_len(odp_packet_t pkt); * Check for L2 header, e.g. ethernet * * @param pkt Packet handle - * @return 1 if packet contains a valid & known L2 header, 0 otherwise + * @retval 1 if packet contains a valid & known L2 header + * @retval 0 if packet does not contain a valid & known L2 header */ int odp_packet_has_l2(odp_packet_t pkt); @@ -56,7 +59,8 @@ int odp_packet_has_l2(odp_packet_t pkt); * Check for L3 header, e.g. IPv4, IPv6 * * @param pkt Packet handle - * @return 1 if packet contains a valid & known L3 header, 0 otherwise + * @retval 1 if packet contains a valid & known L3 header + * @retval 0 if packet does not contain a valid & known L3 header */ int odp_packet_has_l3(odp_packet_t pkt); @@ -64,7 +68,8 @@ int odp_packet_has_l3(odp_packet_t pkt); * Check for L4 header, e.g. UDP, TCP, SCTP (also ICMP) * * @param pkt Packet handle - * @return 1 if packet contains a valid & known L4 header, 0 otherwise + * @retval 1 if packet contains a valid & known L4 header + * @retval 0 if packet does not contain a valid & known L4 header */ int odp_packet_has_l4(odp_packet_t pkt); @@ -72,7 +77,8 @@ int odp_packet_has_l4(odp_packet_t pkt); * Check for Ethernet header * * @param pkt Packet handle - * @return 1 if packet contains a valid eth header, 0 otherwise + * @retval 1 if packet contains a valid eth header + * @retval 0 if packet does not contain a valid & known eth header */ int odp_packet_has_eth(odp_packet_t pkt); @@ -80,7 +86,8 @@ int odp_packet_has_eth(odp_packet_t pkt); * Check for jumbo frame * * @param pkt Packet handle - * @return 1 if packet contains jumbo frame, 0 otherwise + * @retval 1 if packet contains a jumbo frame + * @retval 0 if packet does not contain a jumbo frame */ int odp_packet_has_jumbo(odp_packet_t pkt); @@ -88,7 +95,8 @@ int odp_packet_has_jumbo(odp_packet_t pkt); * Check for VLAN * * @param pkt Packet handle - * @return 1 if packet contains a VLAN header, 0 otherwise + * @retval 1 if packet contains a VLAN header + * @retval 0 if packet does not contain a VLAN header */ int odp_packet_has_vlan(odp_packet_t pkt); @@ -96,7 +104,8 @@ int odp_packet_has_vlan(odp_packet_t pkt); * Check for VLAN QinQ (stacked VLAN) * * @param pkt Packet handle - * @return 1 if packet contains a VLAN QinQ header, 0 otherwise + * @retval 1 if packet contains a VLAN QinQ header + * @retval 0 if packet does not contain a VLAN QinQ header */ int odp_packet_has_vlan_qinq(odp_packet_t pkt); @@ -104,7 +113,8 @@ int odp_packet_has_vlan_qinq(odp_packet_t pkt); * Check for ARP * * @param pkt Packet handle - * @return 1 if packet contains an ARP header, 0 otherwise + * @retval 1 if packet contains an ARP message + * @retval 0 if packet does not contain an ARP message */ int odp_packet_has_arp(odp_packet_t pkt); @@ -112,7 +122,8 @@ int odp_packet_has_arp(odp_packet_t pkt); * Check for IPv4 * * @param pkt Packet handle - * @return 1 if packet contains an IPv4 header, 0 otherwise + * @retval 1 if packet contains an IPv4 header + * @retval 0 if packet does not contain an IPv4 header */ int odp_packet_has_ipv4(odp_packet_t pkt); @@ -120,7 +131,8 @@ int odp_packet_has_ipv4(odp_packet_t pkt); * Check for IPv6 * * @param pkt Packet handle - * @return 1 if packet contains an IPv6 header, 0 otherwise + * @retval 1 if packet contains an IPv6 header + * @retval 0 if packet does not contain an IPv6 header */ int odp_packet_has_ipv6(odp_packet_t pkt); @@ -128,7 +140,8 @@ int odp_packet_has_ipv6(odp_packet_t pkt); * Check for IP fragment * * @param pkt Packet handle - * @return 1 if packet is an IP fragment, 0 otherwise + * @retval 1 if packet is an IP fragment + * @retval 0 if packet is not an IP fragment */ int odp_packet_has_ipfrag(odp_packet_t pkt); @@ -136,7 +149,8 @@ int odp_packet_has_ipfrag(odp_packet_t pkt); * Check for IP options * * @param pkt Packet handle - * @return 1 if packet contains IP options, 0 otherwise + * @retval 1 if packet contains IP options + * @retval 0 if packet does not contain IP options */ int odp_packet_has_ipopt(odp_packet_t pkt); @@ -144,7 +158,8 @@ int odp_packet_has_ipopt(odp_packet_t pkt); * Check for IPSec * * @param pkt Packet handle - * @return 1 if packet requires IPSec processing, 0 otherwise + * @retval 1 if packet requires IPSec processing + * @retval 0 if packet does not require IPSec processing */ int odp_packet_has_ipsec(odp_packet_t pkt); @@ -152,7 +167,8 @@ int odp_packet_has_ipsec(odp_packet_t pkt); * Check for UDP * * @param pkt Packet handle - * @return 1 if packet contains a UDP header, 0 otherwise + * @retval 1 if packet contains a UDP header + * @retval 0 if packet does not contain a UDP header */ int odp_packet_has_udp(odp_packet_t pkt); @@ -160,7 +176,8 @@ int odp_packet_has_udp(odp_packet_t pkt); * Check for TCP * * @param pkt Packet handle - * @return 1 if packet contains a TCP header, 0 otherwise + * @retval 1 if packet contains a TCP header + * @retval 0 if packet does not contain a TCP header */ int odp_packet_has_tcp(odp_packet_t pkt); @@ -168,7 +185,8 @@ int odp_packet_has_tcp(odp_packet_t pkt); * Check for SCTP * * @param pkt Packet handle - * @return 1 if packet contains an SCTP header, 0 otherwise + * @retval 1 if packet contains a SCTP header + * @retval 0 if packet does not contain a SCTP header */ int odp_packet_has_sctp(odp_packet_t pkt); @@ -176,7 +194,8 @@ int odp_packet_has_sctp(odp_packet_t pkt); * Check for ICMP * * @param pkt Packet handle - * @return 1 if packet contains an ICMP header, 0 otherwise + * @retval 1 if packet contains an ICMP header + * @retval 0 if packet does not contain an ICMP header */ int odp_packet_has_icmp(odp_packet_t pkt); diff --git a/platform/linux-generic/include/api/odp_packet_io.h b/platform/linux-generic/include/api/odp_packet_io.h index 4835f4d..1a770b6 100644 --- a/platform/linux-generic/include/api/odp_packet_io.h +++ b/platform/linux-generic/include/api/odp_packet_io.h @@ -40,7 +40,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 @@ -53,7 +54,8 @@ odp_pktio_t odp_pktio_open(const char *dev, odp_buffer_pool_t pool); * * @param id 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); @@ -62,7 +64,8 @@ int odp_pktio_close(odp_pktio_t id); * * @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); @@ -73,7 +76,8 @@ odp_pktio_t odp_pktio_lookup(const char *dev); * @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); @@ -84,7 +88,8 @@ int odp_pktio_recv(odp_pktio_t id, odp_packet_t pkt_table[], unsigned len); * @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); @@ -93,7 +98,8 @@ int odp_pktio_send(odp_pktio_t id, odp_packet_t pkt_table[], unsigned len); * * @param id 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); @@ -102,7 +108,8 @@ int odp_pktio_inq_setdef(odp_pktio_t id, odp_queue_t queue); * * @param id 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); @@ -111,7 +118,8 @@ odp_queue_t odp_pktio_inq_getdef(odp_pktio_t id); * * @param id 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); @@ -120,7 +128,8 @@ int odp_pktio_inq_remdef(odp_pktio_t id); * * @param id 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); @@ -129,8 +138,8 @@ odp_queue_t odp_pktio_outq_getdef(odp_pktio_t id); * * @param[in] id 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); @@ -140,8 +149,8 @@ int odp_pktio_mtu(odp_pktio_t id); * @param[in] id 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); @@ -152,7 +161,7 @@ int odp_pktio_promisc_mode_set(odp_pktio_t id, odp_bool_t enable); * * @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); @@ -163,9 +172,10 @@ int odp_pktio_promisc_mode(odp_pktio_t id); * @param[out] mac_addr Storage for MAC address of the packet IO interface. * @param addr_size Storage size for the address * - * @retval Number of bytes written on success, 0 on failure. + * @return Number of bytes written on success + * @retval <0 on failure */ -size_t odp_pktio_mac_addr(odp_pktio_t id, void *mac_addr, +int odp_pktio_mac_addr(odp_pktio_t id, void *mac_addr, size_t addr_size); /** @@ -177,7 +187,8 @@ size_t odp_pktio_mac_addr(odp_pktio_t id, void *mac_addr, * 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); @@ -189,7 +200,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. */ @@ -201,7 +213,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. * */ @@ -216,7 +229,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. */ diff --git a/platform/linux-generic/include/api/odp_queue.h b/platform/linux-generic/include/api/odp_queue.h index b0f7185..25633e0 100644 --- a/platform/linux-generic/include/api/odp_queue.h +++ b/platform/linux-generic/include/api/odp_queue.h @@ -118,7 +118,8 @@ typedef struct odp_queue_param_t { * @param type Queue type * @param param Queue parameters. Uses defaults if NULL. * - * @return Queue handle or ODP_QUEUE_INVALID + * @return Queue handle + * @retval ODP_QUEUE_INVALID on failure */ odp_queue_t odp_queue_create(const char *name, odp_queue_type_t type, odp_queue_param_t *param); @@ -133,7 +134,8 @@ odp_queue_t odp_queue_create(const char *name, odp_queue_type_t type, * * @param queue Queue handle * - * @return 0 if successful + * @retval 0 on success + * @retval <0 on failure */ int odp_queue_destroy(odp_queue_t queue); @@ -142,7 +144,8 @@ int odp_queue_destroy(odp_queue_t queue); * * @param name Queue name * - * @return Queue handle or ODP_QUEUE_INVALID + * @return Queue handle + * @retval ODP_QUEUE_INVALID on failure */ odp_queue_t odp_queue_lookup(const char *name); @@ -156,7 +159,8 @@ odp_queue_t odp_queue_lookup(const char *name); * @param queue Queue handle * @param context Address to the queue context * - * @return 0 if successful + * @retval 0 on success + * @retval <0 on failure */ int odp_queue_set_context(odp_queue_t queue, void *context); @@ -165,8 +169,8 @@ int odp_queue_set_context(odp_queue_t queue, void *context); * * @param queue Queue handle * - * @return If successful, a pointer to the queue context, - * NULL for failure. + * @return pointer to the queue context + * @retval NULL on failure */ void *odp_queue_get_context(odp_queue_t queue); @@ -176,7 +180,8 @@ void *odp_queue_get_context(odp_queue_t queue); * @param queue Queue handle * @param buf Buffer handle * - * @return 0 if succesful + * @retval 0 on success + * @retval <0 on failure */ int odp_queue_enq(odp_queue_t queue, odp_buffer_t buf); @@ -187,7 +192,8 @@ int odp_queue_enq(odp_queue_t queue, odp_buffer_t buf); * @param buf Buffer handles * @param num Number of buffer handles * - * @return 0 if succesful + * @retval 0 on success + * @retval <0 on failure */ int odp_queue_enq_multi(odp_queue_t queue, odp_buffer_t buf[], int num); @@ -199,7 +205,8 @@ int odp_queue_enq_multi(odp_queue_t queue, odp_buffer_t buf[], int num); * * @param queue Queue handle * - * @return Buffer handle, or ODP_BUFFER_INVALID + * @return Buffer handle + * @retval ODP_BUFFER_INVALID on failure */ odp_buffer_t odp_queue_deq(odp_queue_t queue); diff --git a/platform/linux-generic/include/api/odp_schedule.h b/platform/linux-generic/include/api/odp_schedule.h index cdf6705..36fbba3 100644 --- a/platform/linux-generic/include/api/odp_schedule.h +++ b/platform/linux-generic/include/api/odp_schedule.h @@ -59,7 +59,8 @@ uint64_t odp_schedule_wait_time(uint64_t ns); * Use odp_schedule_wait_time() to convert time to other wait * values. * - * @return Next highest priority buffer, or ODP_BUFFER_INVALID + * @return Next highest priority buffer + * @retval ODP_BUFFER_INVALID on timeout */ odp_buffer_t odp_schedule(odp_queue_t *from, uint64_t wait); diff --git a/platform/linux-generic/include/api/odp_shared_memory.h b/platform/linux-generic/include/api/odp_shared_memory.h index f70db5a..78d108a 100644 --- a/platform/linux-generic/include/api/odp_shared_memory.h +++ b/platform/linux-generic/include/api/odp_shared_memory.h @@ -59,7 +59,8 @@ typedef struct odp_shm_info_t { * @param[in] flags Shared memory parameter flags (ODP_SHM_*). * Default value is 0. * - * @return Pointer to the reserved block, or NULL + * @return Handle of the reserved block + * @retval NULL on failure */ odp_shm_t odp_shm_reserve(const char *name, uint64_t size, uint64_t align, uint32_t flags); @@ -72,9 +73,9 @@ odp_shm_t odp_shm_reserve(const char *name, uint64_t size, uint64_t align, * * @param[in] shm Block handle * - * @retval 0 if the handle is already free + * @retval 0 if the handle is already free (FIXME how can we know this?) * @retval 0 if the handle free succeeds - * @retval -1 on failure to free the handle + * @retval <0 on failure to free the handle */ int odp_shm_free(odp_shm_t shm); @@ -84,7 +85,7 @@ int odp_shm_free(odp_shm_t shm); * @param[in] name Name of the block * * @return A handle to the block if it is found by name - * @retval #ODP_SHM_INVALID if the block is not found + * @retval ODP_SHM_INVALID on failure */ odp_shm_t odp_shm_lookup(const char *name); @@ -94,7 +95,8 @@ odp_shm_t odp_shm_lookup(const char *name); * * @param[in] shm Block handle * - * @return Memory block address, or NULL on error + * @return Memory block address + * @retval NULL on failure (FIXME: when?) */ void *odp_shm_addr(odp_shm_t shm); @@ -105,7 +107,8 @@ void *odp_shm_addr(odp_shm_t shm); * @param[in] shm Block handle * @param[out] info Block info pointer for output * - * @return 0 on success, otherwise non-zero + * @retval 0 on success + * @retval <0 on failure */ int odp_shm_info(odp_shm_t shm, odp_shm_info_t *info); diff --git a/platform/linux-generic/include/api/odp_timer.h b/platform/linux-generic/include/api/odp_timer.h index 69402ef..c8c3270 100644 --- a/platform/linux-generic/include/api/odp_timer.h +++ b/platform/linux-generic/include/api/odp_timer.h @@ -112,8 +112,8 @@ typedef struct { * @param name Name of the timer pool. The string will be copied. * @param params Timer pool parameters. The content will be copied. * - * @return Timer pool handle if successful, otherwise ODP_TIMER_POOL_INVALID - * and errno set + * @return Timer pool handle on success + * @retval ODP_TIMER_POOL_INVALID on failure and errno set */ odp_timer_pool_t odp_timer_pool_create(const char *name, @@ -185,8 +185,8 @@ typedef struct { * @param tpid Timer pool identifier * @param[out] info Pointer to information buffer * - * @retval 0 Success - * @retval -1 Failure. Info could not be retrieved. + * @retval 0 on success + * @retval <0 on failure. Info could not be retrieved. */ int odp_timer_pool_info(odp_timer_pool_t tpid, odp_timer_pool_info_t *info); @@ -202,8 +202,8 @@ int odp_timer_pool_info(odp_timer_pool_t tpid, * @param queue Destination queue for timeout notifications * @param user_ptr User defined pointer or NULL to be copied to timeouts * - * @return Timer handle if successful, otherwise ODP_TIMER_INVALID and - * errno set. + * @return Timer handle on success + * @retval ODP_TIMER_INVALID on failure and errno set. */ odp_timer_t odp_timer_alloc(odp_timer_pool_t tpid, odp_queue_t queue, @@ -218,7 +218,8 @@ odp_timer_t odp_timer_alloc(odp_timer_pool_t tpid, * responsibility of the application to handle this timeout when it is received. * * @param tim Timer handle - * @return Buffer handle of timeout buffer or ODP_BUFFER_INVALID + * @return Buffer handle of timeout buffer + * @retval ODP_BUFFER_INVALID on failure */ odp_buffer_t odp_timer_free(odp_timer_t tim); @@ -292,8 +293,8 @@ int odp_timer_set_rel(odp_timer_t tim, * * @param tim Timer * @param[out] tmo_buf Pointer to a buffer variable - * @retval 0 Success, active timer cancelled, timeout returned in '*tmo_buf' - * @retval -1 Failure, timer already expired (or inactive) + * @retval 0 on success, active timer cancelled, timeout returned in '*tmo_buf' + * @retval <0 on failure, timer already expired (or inactive) */ int odp_timer_cancel(odp_timer_t tim, odp_buffer_t *tmo_buf); diff --git a/platform/linux-generic/odp_crypto.c b/platform/linux-generic/odp_crypto.c index 2f95cbe..ded3b62 100644 --- a/platform/linux-generic/odp_crypto.c +++ b/platform/linux-generic/odp_crypto.c @@ -343,7 +343,7 @@ odp_crypto_session_create(odp_crypto_session_params_t *params, int odp_crypto_operation(odp_crypto_op_params_t *params, - bool *posted, + odp_bool_t *posted, odp_buffer_t completion_event) { enum crypto_alg_err rc_cipher = ODP_CRYPTO_ALG_ERR_NONE; @@ -423,7 +423,7 @@ odp_crypto_init_global(void) } int -odp_hw_random_get(uint8_t *buf, size_t *len, bool use_entropy ODP_UNUSED) +odp_hw_random_get(uint8_t *buf, size_t *len, odp_bool_t use_entropy ODP_UNUSED) { int rc; rc = RAND_bytes(buf, *len); diff --git a/platform/linux-generic/odp_packet_io.c b/platform/linux-generic/odp_packet_io.c index 0efa3d0..c51098f 100644 --- a/platform/linux-generic/odp_packet_io.c +++ b/platform/linux-generic/odp_packet_io.c @@ -797,18 +797,18 @@ int odp_pktio_promisc_mode(odp_pktio_t id) } -size_t odp_pktio_mac_addr(odp_pktio_t id, void *mac_addr, +int odp_pktio_mac_addr(odp_pktio_t id, void *mac_addr, size_t addr_size) { pktio_entry_t *entry; if (addr_size < ETH_ALEN) - return 0; + return -1; entry = get_pktio_entry(id); if (entry == NULL) { ODP_DBG("pktio entry %d does not exist\n", id); - return 0; + return -1; } lock_entry(entry); diff --git a/test/validation/crypto/odp_crypto_test_async_inp.c b/test/validation/crypto/odp_crypto_test_async_inp.c index 96d4c3f..1db7844 100644 --- a/test/validation/crypto/odp_crypto_test_async_inp.c +++ b/test/validation/crypto/odp_crypto_test_async_inp.c @@ -34,7 +34,7 @@ static void alg_test(enum odp_crypto_op op, odp_crypto_session_t session; int rc; enum odp_crypto_ses_create_err status; - bool posted; + odp_bool_t posted; odp_buffer_t compl_event; odp_queue_t compl_queue = odp_queue_lookup("crypto-out"); diff --git a/test/validation/crypto/odp_crypto_test_sync_inp.c b/test/validation/crypto/odp_crypto_test_sync_inp.c index f37ad54..5082f13 100644 --- a/test/validation/crypto/odp_crypto_test_sync_inp.c +++ b/test/validation/crypto/odp_crypto_test_sync_inp.c @@ -23,7 +23,7 @@ static void alg_test(enum odp_crypto_op op, odp_crypto_session_t session; int rc; enum odp_crypto_ses_create_err status; - bool posted; + odp_bool_t posted; odp_queue_t compl_queue = odp_queue_lookup("crypto-out"); CU_ASSERT(compl_queue != ODP_QUEUE_INVALID);
Unify @return and @retval descriptions. @return used for values that cannot (meaningfully) be enumerated (e.g pointers, ODP handles) or simply tested for correctness. @retval used for values that can be enumerated and should be tested by validation programs. Changed from bool to odp_bool_t in odp_crypto.h and dependent source files. Changed return type and value of odp_pktio_mac_addr() to match other similar functions. Use int as return type, <0 to indicate failure. Signed-off-by: Ola Liljedahl <ola.liljedahl@linaro.org> --- (This document/code contribution attached is provided under the terms of agreement LES-LTM-21309) example/ipsec/odp_ipsec.c | 4 +- platform/linux-generic/include/api/odp_buffer.h | 9 ++- .../linux-generic/include/api/odp_buffer_pool.h | 21 ++++--- platform/linux-generic/include/api/odp_byteorder.h | 2 +- .../linux-generic/include/api/odp_classification.h | 48 +++++++++------- platform/linux-generic/include/api/odp_cpumask.h | 12 ++-- platform/linux-generic/include/api/odp_crypto.h | 15 +++-- platform/linux-generic/include/api/odp_init.h | 10 ++-- platform/linux-generic/include/api/odp_packet.h | 66 ++++++++++++---------- .../linux-generic/include/api/odp_packet_flags.h | 57 ++++++++++++------- platform/linux-generic/include/api/odp_packet_io.h | 54 +++++++++++------- platform/linux-generic/include/api/odp_queue.h | 25 +++++--- platform/linux-generic/include/api/odp_schedule.h | 3 +- .../linux-generic/include/api/odp_shared_memory.h | 15 +++-- platform/linux-generic/include/api/odp_timer.h | 19 ++++--- platform/linux-generic/odp_crypto.c | 4 +- platform/linux-generic/odp_packet_io.c | 6 +- test/validation/crypto/odp_crypto_test_async_inp.c | 2 +- test/validation/crypto/odp_crypto_test_sync_inp.c | 2 +- 19 files changed, 226 insertions(+), 148 deletions(-)