From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from alln-iport-5.cisco.com (alln-iport-5.cisco.com [173.37.142.92]) by dpdk.org (Postfix) with ESMTP id 49A9A2904 for ; Thu, 20 Apr 2017 20:50:28 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=cisco.com; i=@cisco.com; l=4564; q=dns/txt; s=iport; t=1492714228; x=1493923828; h=from:to:cc:subject:date:message-id:in-reply-to: references; bh=YjN9LgrbbnR7ERWquZGOV+bHICvF2HCMkbpCDfAu7aE=; b=gs9nAmVAFFDjzCqp3S0IEgv4L+BqJ8rzIKaN4WFU4/ZawhaKlIBu53Nk Yj3GHjXiQ4rWcdCeQvAjmqxqsfzABMCNHXL6/Nq701vjuLPjBNgYphBby ozhXWKoo4QRGcj0HKgeuTpgsJLs0g2LHoECdj3ilzxInxo07BfKt6nafU 8=; X-IronPort-AV: E=Sophos;i="5.37,225,1488844800"; d="scan'208";a="413455288" Received: from rcdn-core-11.cisco.com ([173.37.93.147]) by alln-iport-5.cisco.com with ESMTP/TLS/DHE-RSA-AES256-GCM-SHA384; 20 Apr 2017 18:50:27 +0000 Received: from cisco.com (savbu-usnic-a.cisco.com [10.193.184.48]) by rcdn-core-11.cisco.com (8.14.5/8.14.5) with ESMTP id v3KIoR8P010893; Thu, 20 Apr 2017 18:50:27 GMT Received: by cisco.com (Postfix, from userid 392789) id 0C63D3FAAF20; Thu, 20 Apr 2017 11:50:27 -0700 (PDT) From: John Daley To: john.mcnamara@intel.com Cc: adrien.mazarguil@6wind.com, dev@dpdk.org, John Daley Date: Thu, 20 Apr 2017 11:49:33 -0700 Message-Id: <20170420184933.27450-1-johndale@cisco.com> X-Mailer: git-send-email 2.12.0 In-Reply-To: <20170407002300.14433-1-johndale@cisco.com> References: <20170407002300.14433-1-johndale@cisco.com> Subject: [dpdk-dev] [PATCH v4] doc: fix flow validate comments X-BeenThere: dev@dpdk.org X-Mailman-Version: 2.1.15 Precedence: list List-Id: DPDK patches and discussions List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Thu, 20 Apr 2017 18:50:28 -0000 Change comments for rte_flow_validate() function to indicate that flow rule collision and resource validation is optional for PMDs and therefore the return codes may have different meanings. Fixes: b1a4b4cbc0a8 ("ethdev: introduce generic flow API") Signed-off-by: John Daley --- v2: another crack at the comments v3: fix typos, rewording, put back a sentence omitted in v2 v4: fixes per Adrien Mazarguil- update guide, typo, commit title doc/guides/prog_guide/rte_flow.rst | 17 ++++++++++++----- lib/librte_ether/rte_flow.h | 16 +++++++++++----- 2 files changed, 23 insertions(+), 10 deletions(-) diff --git a/doc/guides/prog_guide/rte_flow.rst b/doc/guides/prog_guide/rte_flow.rst index 5ee045ee8..9f3d3b096 100644 --- a/doc/guides/prog_guide/rte_flow.rst +++ b/doc/guides/prog_guide/rte_flow.rst @@ -1332,9 +1332,11 @@ supported and can be created. const struct rte_flow_action actions[], struct rte_flow_error *error); -While this function has no effect on the target device, the flow rule is -validated against its current configuration state and the returned value -should be considered valid by the caller for that state only. +The flow rule is validated for correctness and whether it could be accepted +by the device given sufficient resources. The rule is checked against the +current device mode and queue configuration. The flow rule may also +optionally be validated against existing flow rules and device resources. +This function has no effect on the target device. The returned value is guaranteed to remain valid only as long as no successful calls to ``rte_flow_create()`` or ``rte_flow_destroy()`` are made @@ -1360,8 +1362,13 @@ Return values: - ``-EINVAL``: unknown or invalid rule specification. - ``-ENOTSUP``: valid but unsupported rule specification (e.g. partial bit-masks are unsupported). -- ``-EEXIST``: collision with an existing rule. -- ``-ENOMEM``: not enough resources. +- ``EEXIST``: collision with an existing rule. Only returned if device + supports flow rule collision checking and there was a flow rule + collision. Not receiving this return code is no guarantee that creating + the rule will not fail due to a collision. +- ``ENOMEM``: not enough memory to execute the function, or if the device + supports resource validation, resource limitation on the device. + - ``-EBUSY``: action cannot be performed due to busy device resources, may succeed if the affected queues or even the entire port are in a stopped state (see ``rte_eth_dev_rx_queue_stop()`` and ``rte_eth_dev_stop()``). diff --git a/lib/librte_ether/rte_flow.h b/lib/librte_ether/rte_flow.h index 8013ecab2..7749491cb 100644 --- a/lib/librte_ether/rte_flow.h +++ b/lib/librte_ether/rte_flow.h @@ -983,9 +983,11 @@ struct rte_flow_error { /** * Check whether a flow rule can be created on a given port. * - * While this function has no effect on the target device, the flow rule is - * validated against its current configuration state and the returned value - * should be considered valid by the caller for that state only. + * The flow rule is validated for correctness and whether it could be accepted + * by the device given sufficient resources. The rule is checked against the + * current device mode and queue configuration. The flow rule may also + * optionally be validated against existing flow rules and device resources. + * This function has no effect on the target device. * * The returned value is guaranteed to remain valid only as long as no * successful calls to rte_flow_create() or rte_flow_destroy() are made in @@ -1016,9 +1018,13 @@ struct rte_flow_error { * -ENOTSUP: valid but unsupported rule specification (e.g. partial * bit-masks are unsupported). * - * -EEXIST: collision with an existing rule. + * -EEXIST: collision with an existing rule. Only returned if device + * supports flow rule collision checking and there was a flow rule + * collision. Not receiving this return code is no guarantee that creating + * the rule will not fail due to a collision. * - * -ENOMEM: not enough resources. + * -ENOMEM: not enough memory to execute the function, or if the device + * supports resource validation, resource limitation on the device. * * -EBUSY: action cannot be performed due to busy device resources, may * succeed if the affected queues or even the entire port are in a stopped -- 2.12.0