From patchwork Tue Jan 27 00:20:15 2015 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Ola Liljedahl X-Patchwork-Id: 43805 Return-Path: X-Original-To: linaro@patches.linaro.org Delivered-To: linaro@patches.linaro.org Received: from mail-we0-f200.google.com (mail-we0-f200.google.com [74.125.82.200]) by ip-10-151-82-157.ec2.internal (Postfix) with ESMTPS id 92C1D23FFF for ; Tue, 27 Jan 2015 00:20:43 +0000 (UTC) Received: by mail-we0-f200.google.com with SMTP id m14sf5902478wev.3 for ; Mon, 26 Jan 2015 16:20:42 -0800 (PST) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20130820; h=x-gm-message-state:delivered-to:from:to:date:message-id:subject :precedence:list-id:list-unsubscribe:list-archive:list-post :list-help:list-subscribe:mime-version:content-type :content-transfer-encoding:errors-to:sender:x-original-sender :x-original-authentication-results:mailing-list; bh=XpTaqSvAvqUCbkOY+6HT3zEDcLUwbp9ZdASJcE4oZDs=; b=UFg+chD+MF9HevXS21vgO+a/OHyfvBeROmziSDuL+tRaXReRy+h35FEMWjHN0YxoO2 N4I8EdTk3L0uUSnQAiPyiBlbqZBZ+dwjmVpaINss14jrbddKmXmVbxQ/3c2mXJ1yR/rT APiL7VCWrtyn1lxXsp0Lq5V5ui6zhWivuNn/e3n47Wc3wUeCEoqro3m8rQC46KLWHvI0 /G3yH1PgC1BF5K+hhH7GXjHBxYZ6kzKpDVBgkrLykx1E3EIZLJhgvZZhlSmAVS9KY5XT B1w+8dJTiUulIbfpv2+JNhMGa6A85N/Ie/1B7hRmfYCtOolWA8jMLlGSaVnN7MTXS6WA NvKw== X-Gm-Message-State: ALoCoQkCsumPj9JdE893E7jaBo7uxNTJJa6iQoy86NfUgq2I+dL9M6BgMrmS3/Lad2IOnRDHmzuf X-Received: by 10.194.142.174 with SMTP id rx14mr1904825wjb.4.1422318042887; Mon, 26 Jan 2015 16:20:42 -0800 (PST) X-BeenThere: patchwork-forward@linaro.org Received: by 10.152.43.66 with SMTP id u2ls498742lal.32.gmail; Mon, 26 Jan 2015 16:20:42 -0800 (PST) X-Received: by 10.152.37.234 with SMTP id b10mr1014869lak.94.1422318042498; Mon, 26 Jan 2015 16:20:42 -0800 (PST) Received: from mail-la0-f43.google.com (mail-la0-f43.google.com. [209.85.215.43]) by mx.google.com with ESMTPS id h4si2194110lag.70.2015.01.26.16.20.42 for (version=TLSv1 cipher=ECDHE-RSA-RC4-SHA bits=128/128); Mon, 26 Jan 2015 16:20:42 -0800 (PST) Received-SPF: pass (google.com: domain of patch+caf_=patchwork-forward=linaro.org@linaro.org designates 209.85.215.43 as permitted sender) client-ip=209.85.215.43; Received: by mail-la0-f43.google.com with SMTP id q1so10639341lam.2 for ; Mon, 26 Jan 2015 16:20:42 -0800 (PST) X-Received: by 10.152.197.5 with SMTP id iq5mr1051628lac.6.1422318042392; Mon, 26 Jan 2015 16:20:42 -0800 (PST) X-Forwarded-To: patchwork-forward@linaro.org X-Forwarded-For: patch@linaro.org patchwork-forward@linaro.org Delivered-To: patch@linaro.org Received: by 10.112.35.133 with SMTP id h5csp935558lbj; Mon, 26 Jan 2015 16:20:40 -0800 (PST) X-Received: by 10.224.55.71 with SMTP id t7mr2421613qag.53.1422318039944; Mon, 26 Jan 2015 16:20:39 -0800 (PST) Received: from ip-10-35-177-41.ec2.internal (lists.linaro.org. [54.225.227.206]) by mx.google.com with ESMTPS id p9si8920417qai.60.2015.01.26.16.20.37 (version=TLSv1 cipher=RC4-SHA bits=128/128); Mon, 26 Jan 2015 16:20:39 -0800 (PST) Received-SPF: none (google.com: lng-odp-bounces@lists.linaro.org does not designate permitted sender hosts) client-ip=54.225.227.206; Received: from localhost ([127.0.0.1] helo=ip-10-35-177-41.ec2.internal) by ip-10-35-177-41.ec2.internal with esmtp (Exim 4.76) (envelope-from ) id 1YFttR-0001KR-EE; Tue, 27 Jan 2015 00:20:33 +0000 Received: from mail-la0-f43.google.com ([209.85.215.43]) by ip-10-35-177-41.ec2.internal with esmtp (Exim 4.76) (envelope-from ) id 1YFttK-0001KM-W2 for lng-odp@lists.linaro.org; Tue, 27 Jan 2015 00:20:27 +0000 Received: by mail-la0-f43.google.com with SMTP id q1so10638390lam.2 for ; Mon, 26 Jan 2015 16:20:21 -0800 (PST) X-Received: by 10.112.222.135 with SMTP id qm7mr1002159lbc.19.1422318020742; Mon, 26 Jan 2015 16:20:20 -0800 (PST) Received: from macmini.lan (78-82-118-111.tn.glocalnet.net. [78.82.118.111]) by mx.google.com with ESMTPSA id zt4sm3234816lbb.3.2015.01.26.16.20.19 (version=TLSv1.2 cipher=ECDHE-RSA-AES128-SHA bits=128/128); Mon, 26 Jan 2015 16:20:20 -0800 (PST) From: Ola Liljedahl To: lng-odp@lists.linaro.org Date: Tue, 27 Jan 2015 01:20:15 +0100 Message-Id: <1422318015-729-1-git-send-email-ola.liljedahl@linaro.org> X-Mailer: git-send-email 1.9.1 X-Topics: patch Subject: [lng-odp] [PATCH] api: unify @return/@retval descriptions and return types X-BeenThere: lng-odp@lists.linaro.org X-Mailman-Version: 2.1.14 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: , List-Help: , List-Subscribe: , MIME-Version: 1.0 Errors-To: lng-odp-bounces@lists.linaro.org Sender: lng-odp-bounces@lists.linaro.org X-Removed-Original-Auth: Dkim didn't pass. X-Original-Sender: ola.liljedahl@linaro.org X-Original-Authentication-Results: mx.google.com; spf=pass (google.com: domain of patch+caf_=patchwork-forward=linaro.org@linaro.org designates 209.85.215.43 as permitted sender) smtp.mail=patch+caf_=patchwork-forward=linaro.org@linaro.org Mailing-list: list patchwork-forward@linaro.org; contact patchwork-forward+owners@linaro.org X-Google-Group-Id: 836684582541 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 --- (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. * * @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 /** @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);