From patchwork Mon Dec 4 13:00:06 2017 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Github ODP bot X-Patchwork-Id: 120531 Delivered-To: patch@linaro.org Received: by 10.140.22.227 with SMTP id 90csp4400530qgn; Mon, 4 Dec 2017 05:01:59 -0800 (PST) X-Google-Smtp-Source: AGs4zMbyYR6QWSMK8QjPme5DcRmyZv3zz9RrhLlXm8+H/Im+79oZAX0vbfiA8Snt6P+iCudxIf31 X-Received: by 10.55.21.213 with SMTP id 82mr20856431qkv.110.1512392519646; Mon, 04 Dec 2017 05:01:59 -0800 (PST) ARC-Seal: i=1; a=rsa-sha256; t=1512392519; cv=none; d=google.com; s=arc-20160816; b=skn6Cvc2RDjHLpFKjz67YJ7yi8qH1gY0ywAsxOsmkbfjV05TPSFhTtyfbKiKhpG6CA A09Fs5EiXOvvKw1Ds6HdHCeCCegX7xF2oIIvJy2bX9wAtWQrlSqkSr/1u4MofBG8sade OG92UnEBlJ1uYM4Digp06hg+Unn+gOwHg6ylcYe2BRKMRUNxengtipSiaulTz96okOZN m5R7as8NC4cug+y7y6vU65xbe9llaa7To245JIDKnjNlHOnrWFx3LbN2yMdPUkrTZ4Ju ValEpixQCHWb6oX/WevytFRNdmK4jJdGy86vgchAJBTiLkruwXV6mMkyvhAMYXpEvVCE YZWg== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=sender:errors-to:list-subscribe:list-help:list-post:list-archive :list-unsubscribe:list-id:precedence:subject:github-pr-num :references:in-reply-to:message-id:date:to:from:delivered-to :arc-authentication-results; bh=1CSXlxST2FkPz/Ecie7PvGUNFcbZfJOe3cwXAE6AFlc=; b=nuR56KlFxfApwZUtiGhQs7ARUoB+puKN8CcSw+m2u5y9DQTisFaYETzSSCw3qWM5za Yp7h67ye7HDSdl6XJZFEBe0TInLdB1RmMQjV92UPFK/POczHBntaMAIX9YUKgsJRaKqs RzwVSwuXojA+UWKjyJWSHbgMxATN572Ug/HiICRuXKSQfTW5RBj+LR1hw0Vgsx0rAx7E j263aqZqx5XYOzzf/CeRjBAUfN+bbAqFpzMfrlFJDxT1bAFZs0lUh4z+Kf6sYE1i8lLU 91E4eoPyBp1eAL6FYozJNVip2RX3FyVkGZD7VNTEFcf37zl6isQ3lQqjLhq2K93J1NfU f40g== ARC-Authentication-Results: i=1; mx.google.com; spf=pass (google.com: domain of lng-odp-bounces@lists.linaro.org designates 54.197.127.237 as permitted sender) smtp.mailfrom=lng-odp-bounces@lists.linaro.org; dmarc=fail (p=NONE sp=NONE dis=NONE) header.from=yandex.ru Return-Path: Received: from lists.linaro.org (ec2-54-197-127-237.compute-1.amazonaws.com. [54.197.127.237]) by mx.google.com with ESMTP id z22si3819462qti.73.2017.12.04.05.01.59; Mon, 04 Dec 2017 05:01:59 -0800 (PST) Received-SPF: pass (google.com: domain of lng-odp-bounces@lists.linaro.org designates 54.197.127.237 as permitted sender) client-ip=54.197.127.237; Authentication-Results: mx.google.com; spf=pass (google.com: domain of lng-odp-bounces@lists.linaro.org designates 54.197.127.237 as permitted sender) smtp.mailfrom=lng-odp-bounces@lists.linaro.org; dmarc=fail (p=NONE sp=NONE dis=NONE) header.from=yandex.ru Received: by lists.linaro.org (Postfix, from userid 109) id 4BD4B608D5; Mon, 4 Dec 2017 13:01:59 +0000 (UTC) X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on ip-10-142-244-252 X-Spam-Level: X-Spam-Status: No, score=-0.6 required=5.0 tests=BAYES_00,FREEMAIL_FROM, RCVD_IN_DNSWL_LOW, URIBL_BLOCKED, URIBL_DBL_ABUSE_SPAM autolearn=disabled version=3.4.0 Received: from [127.0.0.1] (localhost [127.0.0.1]) by lists.linaro.org (Postfix) with ESMTP id 36414608DE; Mon, 4 Dec 2017 13:00:37 +0000 (UTC) X-Original-To: lng-odp@lists.linaro.org Delivered-To: lng-odp@lists.linaro.org Received: by lists.linaro.org (Postfix, from userid 109) id E5DDC608DE; Mon, 4 Dec 2017 13:00:20 +0000 (UTC) Received: from forward100j.mail.yandex.net (forward100j.mail.yandex.net [5.45.198.240]) by lists.linaro.org (Postfix) with ESMTPS id 2ED8D608CC for ; Mon, 4 Dec 2017 13:00:13 +0000 (UTC) Received: from mxback5g.mail.yandex.net (mxback5g.mail.yandex.net [IPv6:2a02:6b8:0:1472:2741:0:8b7:166]) by forward100j.mail.yandex.net (Yandex) with ESMTP id 147105D84BA3 for ; Mon, 4 Dec 2017 16:00:11 +0300 (MSK) Received: from smtp1j.mail.yandex.net (smtp1j.mail.yandex.net [2a02:6b8:0:801::ab]) by mxback5g.mail.yandex.net (nwsmtp/Yandex) with ESMTP id KDiUILABru-0Ag40rEA; Mon, 04 Dec 2017 16:00:11 +0300 Received: by smtp1j.mail.yandex.net (nwsmtp/Yandex) with ESMTPSA id DFapD8NBJm-09OWlNFa; Mon, 04 Dec 2017 16:00:09 +0300 (using TLSv1.2 with cipher ECDHE-RSA-AES128-SHA256 (128/128 bits)) (Client certificate not present) From: Github ODP bot To: lng-odp@lists.linaro.org Date: Mon, 4 Dec 2017 16:00:06 +0300 Message-Id: <1512392407-5651-3-git-send-email-odpbot@yandex.ru> X-Mailer: git-send-email 2.7.4 In-Reply-To: <1512392407-5651-1-git-send-email-odpbot@yandex.ru> References: <1512392407-5651-1-git-send-email-odpbot@yandex.ru> Github-pr-num: 322 Subject: [lng-odp] [PATCH API-NEXT v1 2/3] api: cls: remove param-in doxygen tag X-BeenThere: lng-odp@lists.linaro.org X-Mailman-Version: 2.1.16 Precedence: list List-Id: "The OpenDataPlane \(ODP\) List" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: lng-odp-bounces@lists.linaro.org Sender: "lng-odp" From: Petri Savolainen All parameters are input only (tag [in]) by default. Output parameters are better highlighted, when only those are tagged. Also changed tab to spaces inside documentation. Text is more readable on various editors when tabs and spaces are not mixed. Signed-off-by: Petri Savolainen --- /** Email created from pull request 322 (psavol:next-delete-param-in) ** https://github.com/Linaro/odp/pull/322 ** Patch: https://github.com/Linaro/odp/pull/322.patch ** Base sha: bdb7cbf620ada8682c89b5ae5a97cb84f16c0ed0 ** Merge commit sha: 1b785f059a15f6ead9fa5d3e8abc30745e0cf954 **/ include/odp/api/spec/classification.h | 166 ++++++++++++++++------------------ 1 file changed, 78 insertions(+), 88 deletions(-) diff --git a/include/odp/api/spec/classification.h b/include/odp/api/spec/classification.h index 16bf3e6ea..4db046fc3 100644 --- a/include/odp/api/spec/classification.h +++ b/include/odp/api/spec/classification.h @@ -287,7 +287,7 @@ typedef struct odp_cls_cos_param { * * Initialize an odp_cls_cos_param_t to its default value for all fields * - * @param param Address of the odp_cls_cos_param_t to be initialized + * @param param Address of the odp_cls_cos_param_t to be initialized */ void odp_cls_cos_param_init(odp_cls_cos_param_t *param); @@ -296,10 +296,10 @@ void odp_cls_cos_param_init(odp_cls_cos_param_t *param); * * Outputs classification capabilities on success. * - * @param[out] capability Pointer to classification capability structure. + * @param[out] capability Pointer to classification capability structure. * - * @retval 0 on success - * @retval <0 on failure + * @retval 0 on success + * @retval <0 on failure */ int odp_cls_capability(odp_cls_capability_t *capability); @@ -308,12 +308,12 @@ int odp_cls_capability(odp_cls_capability_t *capability); * * The use of class-of-service name is optional. Unique names are not required. * - * @param name Name of the class-of-service or NULL. Maximum string - * length is ODP_COS_NAME_LEN. - * @param param Class-of-service parameters + * @param name Name of the class-of-service or NULL. Maximum string + * length is ODP_COS_NAME_LEN. + * @param param Class-of-service parameters * - * @retval Class-of-service handle - * @retval ODP_COS_INVALID on failure. + * @retval Class-of-service handle + * @retval ODP_COS_INVALID on failure. * * @note ODP_QUEUE_INVALID and ODP_POOL_INVALID are valid values for queue * and pool associated with a class of service and when any one of these values @@ -327,12 +327,11 @@ odp_cos_t odp_cls_cos_create(const char *name, odp_cls_cos_param_t *param); * based on the packet parameters and hash protocol field configured with the * class of service. * - * @param cos class of service - * @param packet Packet handle + * @param cos class of service + * @param packet Packet handle * - * @retval Returns the queue handle on which this packet will be - * enqueued. - * @retval ODP_QUEUE_INVALID for error case + * @retval Returns the queue handle on which this packet will be enqueued. + * @retval ODP_QUEUE_INVALID for error case * * @note The packet has to be updated with valid header pointers L2, L3 and L4. */ @@ -341,60 +340,54 @@ odp_queue_t odp_cls_hash_result(odp_cos_t cos, odp_packet_t packet); /** * Discard a class-of-service along with all its associated resources * - * @param[in] cos_id class-of-service instance. + * @param cos_id class-of-service instance. * - * @retval 0 on success - * @retval <0 on failure + * @retval 0 on success + * @retval <0 on failure */ int odp_cos_destroy(odp_cos_t cos_id); /** * Assign a queue for a class-of-service * - * @param[in] cos_id class-of-service instance. + * @param cos_id class-of-service instance. + * @param queue_id Identifier of a queue where all packets of this specific + * class of service will be enqueued. * - * @param[in] queue_id Identifier of a queue where all packets - * of this specific class of service - * will be enqueued. - * - * @retval 0 on success - * @retval <0 on failure + * @retval 0 on success + * @retval <0 on failure */ int odp_cos_queue_set(odp_cos_t cos_id, odp_queue_t queue_id); /** * Get the queue associated with the specific class-of-service * -* @param[in] cos_id class-of-service instance. -* -* @retval queue_handle Queue handle associated with the -* given class-of-service +* @param cos_id class-of-service instance. * -* @retval ODP_QUEUE_INVALID on failure +* @retval Queue handle associated with the given class-of-service +* @retval ODP_QUEUE_INVALID on failure */ odp_queue_t odp_cos_queue(odp_cos_t cos_id); /** * Get the number of queues linked with the specific class-of-service * - * @param cos_id class-of-service instance. + * @param cos_id class-of-service instance. * - * @return Number of queues linked with the class-of-service. + * @return Number of queues linked with the class-of-service. */ uint32_t odp_cls_cos_num_queue(odp_cos_t cos_id); /** * Get the list of queue associated with the specific class-of-service * - * @param[in] cos_id class-of-service instance. - * - * @param[out] queue Array of queue handles associated - * with the class-of-service. - * - * @param[in] num Maximum number of queue handles to output. + * @param cos_id class-of-service instance. + * @param[out] queue Array of queue handles associated with + * the class-of-service. + * @param num Maximum number of queue handles to output. * - * @return Number of queues linked with CoS - * @retval 0 on failure + * @return Number of queues linked with CoS + * @retval on 0 failure */ uint32_t odp_cls_cos_queues(odp_cos_t cos_id, odp_queue_t queue[], uint32_t num); @@ -402,11 +395,11 @@ uint32_t odp_cls_cos_queues(odp_cos_t cos_id, odp_queue_t queue[], /** * Assign packet drop policy for specific class-of-service * - * @param[in] cos_id class-of-service instance. - * @param[in] drop_policy Desired packet drop policy for this class. + * @param cos_id class-of-service instance. + * @param drop_policy Desired packet drop policy for this class. * - * @retval 0 on success - * @retval <0 on failure + * @retval 0 on success + * @retval <0 on failure * * @note Optional. */ @@ -415,10 +408,9 @@ int odp_cos_drop_set(odp_cos_t cos_id, odp_cls_drop_t drop_policy); /** * Get the drop policy configured for a specific class-of-service instance. * -* @param[in] cos_id class-of-service instance. +* @param cos_id class-of-service instance. * -* @retval Drop policy configured with the given -* class-of-service +* @retval Drop policy configured with the given class-of-service */ odp_cls_drop_t odp_cos_drop(odp_cos_t cos_id); @@ -426,13 +418,14 @@ odp_cls_drop_t odp_cos_drop(odp_cos_t cos_id); * Request to override per-port class of service * based on Layer-2 priority field if present. * - * @param[in] pktio_in Ingress port identifier. - * @param[in] num_qos Number of QoS levels, typically 8. - * @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. - * @retval 0 on success - * @retval <0 on failure + * @param pktio_in Ingress port identifier. + * @param num_qos Number of QoS levels, typically 8. + * @param qos_table Values of the Layer-2 QoS header field. + * @param cos_table Class-of-service assigned to each of the allowed + * Layer-2 QOS levels. + * + * @retval 0 on success + * @retval <0 on failure */ int odp_cos_with_l2_priority(odp_pktio_t pktio_in, uint8_t num_qos, @@ -443,16 +436,15 @@ int odp_cos_with_l2_priority(odp_pktio_t pktio_in, * Request to override per-port class of service * based on Layer-3 priority field if present. * - * @param[in] pktio_in Ingress port identifier. - * @param[in] num_qos Number of allowed Layer-3 QoS levels. - * @param[in] qos_table Values of the Layer-3 QoS header field. - * @param[in] cos_table Class-of-service assigned to each of the - * allowed Layer-3 QOS levels. - * @param[in] l3_preference when true, Layer-3 QoS overrides - * L2 QoS when present. + * @param pktio_in Ingress port identifier. + * @param num_qos Number of allowed Layer-3 QoS levels. + * @param qos_table Values of the Layer-3 QoS header field. + * @param cos_table Class-of-service assigned to each of the allowed + * Layer-3 QOS levels. + * @param l3_preference when true, Layer-3 QoS overrides L2 QoS when present. * - * @retval 0 on success - * @retval <0 on failure + * @retval 0 on success + * @retval <0 on failure * * @note Optional. */ @@ -462,7 +454,6 @@ int odp_cos_with_l3_qos(odp_pktio_t pktio_in, odp_cos_t cos_table[], odp_bool_t l3_preference); - /** * @typedef odp_cos_flow_set_t * Set of header fields that take part in flow signature hash calculation: @@ -554,7 +545,7 @@ typedef struct odp_pmr_param_t { * * Initialize an odp_pmr_param_t to its default values for all fields * - * @param param Address of the odp_pmr_param_t to be initialized + * @param param Address of the odp_pmr_param_t to be initialized */ void odp_cls_pmr_param_init(odp_pmr_param_t *param); @@ -571,14 +562,14 @@ void odp_cls_pmr_param_init(odp_pmr_param_t *param); * of inspecting the return value when installing such rules, and perform * appropriate fallback action. * - * @param[in] terms Array of odp_pmr_param_t entries, one entry per - * term desired. - * @param[in] num_terms Number of terms in the match rule. - * @param[in] src_cos source CoS handle - * @param[in] dst_cos destination CoS handle + * @param terms Array of odp_pmr_param_t entries, one entry per term + * desired. + * @param num_terms Number of terms in the match rule. + * @param src_cos source CoS handle + * @param dst_cos destination CoS handle * - * @return Handle to the Packet Match Rule. - * @retval ODP_PMR_INVAL on failure + * @return Handle to the Packet Match Rule. + * @retval ODP_PMR_INVAL on failure */ odp_pmr_t odp_cls_pmr_create(const odp_pmr_param_t *terms, int num_terms, odp_cos_t src_cos, odp_cos_t dst_cos); @@ -593,10 +584,10 @@ odp_pmr_t odp_cls_pmr_create(const odp_pmr_param_t *terms, int num_terms, * may not guarantee the availability of hardware resources to create the * same or essentially similar rule. * - * @param[in] pmr_id Identifier of the PMR to be destroyed + * @param pmr_id Identifier of the PMR to be destroyed * - * @retval 0 on success - * @retval <0 on failure + * @retval 0 on success + * @retval <0 on failure */ int odp_cls_pmr_destroy(odp_pmr_t pmr_id); @@ -607,31 +598,30 @@ int odp_cls_pmr_destroy(odp_pmr_t pmr_id); * The packet pool associated with class of service will supersede the * packet pool associated with the pktio interface. * -* @param cos_id class of service handle -* @param pool_id packet pool handle +* @param cos_id class of service handle +* @param pool_id packet pool handle * -* @retval 0 on success -* @retval <0 on failure +* @retval 0 on success +* @retval <0 on failure */ int odp_cls_cos_pool_set(odp_cos_t cos_id, odp_pool_t pool_id); /** * Get the pool associated with the given class of service * -* @param cos_id class of service handle +* @param cos_id class of service handle * -* @retval pool handle of the associated pool -* @retval ODP_POOL_INVALID if no associated pool found or -* in case of an error +* @retval pool handle of the associated pool +* @retval ODP_POOL_INVALID if no associated pool found or in case of an error */ odp_pool_t odp_cls_cos_pool(odp_cos_t cos_id); /** * Get printable value for an odp_cos_t * - * @param hdl odp_cos_t handle to be printed - * @return uint64_t value that can be used to print/display this - * handle + * @param hdl odp_cos_t handle to be printed + * + * @return uint64_t value that can be used to print/display this handle * * @note This routine is intended to be used for diagnostic purposes * to enable applications to generate a printable value that represents @@ -642,9 +632,9 @@ uint64_t odp_cos_to_u64(odp_cos_t hdl); /** * Get printable value for an odp_pmr_t * - * @param hdl odp_pmr_t handle to be printed - * @return uint64_t value that can be used to print/display this - * handle + * @param hdl odp_pmr_t handle to be printed + * + * @return uint64_t value that can be used to print/display this handle * * @note This routine is intended to be used for diagnostic purposes * to enable applications to generate a printable value that represents