Re: [dpdk-dev] [PATCH v10] ethdev: new Rx/Tx offloads API

[Ferruh Yigit <ferruh.yigit@intel.com>]

On 5/10/2018 1:56 AM, Wei Dai wrote:
> This patch check if a input requested offloading is valid or not.
> Any reuqested offloading must be supported in the device capabilities.
> Any offloading is disabled by default if it is not set in the parameter
> dev_conf->[rt]xmode.offloads to rte_eth_dev_configure( ) and
> [rt]x_conf->offloads to rte_eth_[rt]x_queue_setup( ).
> If any offloading is enabled in rte_eth_dev_configure( ) by application,
> it is enabled on all queues no matter whether it is per-queue or
> per-port type and no matter whether it is set or cleared in
> [rt]x_conf->offloads to rte_eth_[rt]x_queue_setup( ).
> If a per-queue offloading hasn't be enabled in rte_eth_dev_configure( ),
> it can be enabled or disabled for individual queue in
> ret_eth_[rt]x_queue_setup( ).
> A new added offloading is the one which hasn't been enabled in
> rte_eth_dev_configure( ) and is reuqested to be enabled in
> rte_eth_[rt]x_queue_setup( ), it must be per-queue type,
> otherwise triger an error log.
> The underlying PMD must be aware that the requested offloadings
> to PMD specific queue_setup( ) function only carries those
> new added offloadings of per-queue type.
> 
> This patch can make above such checking in a common way in rte_ethdev
> layer to avoid same checking in underlying PMD.
> 
> This patch assumes that all PMDs in 18.05-rc2 have already
> converted to offload API defined in 17.11 . It also assumes
> that all PMDs can return correct offloading capabilities
> in rte_eth_dev_infos_get( ).
> 
> In the beginning of [rt]x_queue_setup( ) of underlying PMD,
> add offloads = [rt]xconf->offloads |
> dev->data->dev_conf.[rt]xmode.offloads; to keep same as offload API
> defined in 17.11 to avoid upper application broken due to offload
> API change.
> PMD can use the info that input [rt]xconf->offloads only carry
> the new added per-queue offloads to do some optimization or some
> code change on base of this patch.
> 
> Signed-off-by: Wei Dai <wei.dai@intel.com>
> Signed-off-by: Ferruh Yigit <ferruh.yigit@intel.com>
> Signed-off-by: Qi Zhang <qi.z.zhang@intel.com>
> 
> ---
> v10:
> sorry, miss the code change, fix the buidling error
> 
> v9:
> replace RTE_PMD_DEBUG_TRACE with ethdev_log(ERR, in ethdev
> to avoid failure of application which hasn't been completely
> converted to new offload API.
> 
> v8:
> Revise PMD codes to comply with offload API in v7
> update document
> 
> v7:
> Give the maximum freedom for upper application,
> only minimal checking is performed in ethdev layer.
> Only requested specific pure per-queue offloadings are input
> to underlying PMD.
> 
> v6:
> No need enable an offload in queue_setup( ) if it has already
> been enabled in dev_configure( )
> 
> v5:
> keep offload settings sent to PMD same as those from application
> 
> v4:
> fix a wrong description in git log message.
> 
> v3:
> rework according to dicision of offloading API in community
> 
> v2:
> add offloads checking in rte_eth_dev_configure( ).
> check if a requested offloading is supported.
> ---
>  doc/guides/prog_guide/poll_mode_drv.rst |  26 +++--

Following are the documentation update suggestions by John [1], since the new
version is sent I will apply applicable ones into that new commit before merge.

[1]
diff --git a/doc/guides/prog_guide/poll_mode_drv.rst
b/doc/guides/prog_guide/poll_mode_drv.rst
index bbb85f0..bd66e64 100644
--- a/doc/guides/prog_guide/poll_mode_drv.rst
+++ b/doc/guides/prog_guide/poll_mode_drv.rst
@@ -296,33 +296,37 @@ described in the mbuf API documentation and in the in
:ref:`Mbuf Library
 Per-Port and Per-Queue Offloads
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

-In the DPDK offload API, offloads are divided into per-port and per-queue offloads.
-A per-queue offloading can be enabled on a queue and disabled on another queue
at the same time.
-A pure per-port offload is the one supported by device but not per-queue type.
-A pure per-port offloading can't be enabled on a queue and disabled on another
queue at the same time.
-A pure per-port offloading must be enabled or disabled on all queues at the
same time.
-Any offloading is per-queue or pure per-port type, but can't be both types at
same devices.
-A per-port offloading can be enabled or disabled on all queues at the same time.
-It is certain that both per-queue and pure per-port offloading are per-port type.
+In the DPDK offload API, offloads are divided into per-port and per-queue
offloads as follows:
+
+* A per-queue offloading can be enabled on a queue and disabled on another
queue at the same time.
+* A pure per-port offload is the one supported by device but not per-queue type.
+* A pure per-port offloading can't be enabled on a queue and disabled on
another queue at the same time.
+* A pure per-port offloading must be enabled or disabled on all queues at the
same time.
+* Any offloading is per-queue or pure per-port type, but can't be both types at
same devices.
+* A per-port offloading can be enabled or disabled on all queues at the same time.
+* It is certain that both per-queue and pure per-port offloading are per-port type.
+
 The different offloads capabilities can be queried using
``rte_eth_dev_info_get()``.
-The dev_info->[rt]x_queue_offload_capa returned from ``rte_eth_dev_info_get()``
includes all per-queue offloading capabilities.
-The dev_info->[rt]x_offload_capa returned from ``rte_eth_dev_info_get()``
includes all per-port and per-queue offloading capabilities.
+The ``dev_info->[rt]x_queue_offload_capa`` returned from
``rte_eth_dev_info_get()`` includes all per-queue offloading capabilities.
+The ``dev_info->[rt]x_offload_capa returned`` from ``rte_eth_dev_info_get()``
includes all per-port and per-queue offloading capabilities.
 Supported offloads can be either per-port or per-queue.

 Offloads are enabled using the existing ``DEV_TX_OFFLOAD_*`` or
``DEV_RX_OFFLOAD_*`` flags.
-Any requested offloading by application must be within the device capabilities.
+Any requested offloading by an application must be within the device capabilities.
 Any offloading is disabled by default if it is not set in the parameter
-dev_conf->[rt]xmode.offloads to ``rte_eth_dev_configure()`` and
-[rt]x_conf->offloads to ``rte_eth_[rt]x_queue_setup()``.
-If any offloading is enabled in ``rte_eth_dev_configure()`` by application,
+``dev_conf->[rt]xmode.offloads`` to ``rte_eth_dev_configure()`` and
+``[rt]x_conf->offloads`` to ``rte_eth_[rt]x_queue_setup()``.
+
+If any offloading is enabled in ``rte_eth_dev_configure()`` by an application,
 it is enabled on all queues no matter whether it is per-queue or
 per-port type and no matter whether it is set or cleared in
-[rt]x_conf->offloads to ``rte_eth_[rt]x_queue_setup()``.
+``[rt]x_conf->offloads`` to ``rte_eth_[rt]x_queue_setup()``.
+
 If a per-queue offloading hasn't been enabled in ``rte_eth_dev_configure()``,
 it can be enabled or disabled in ``rte_eth_[rt]x_queue_setup()`` for individual
queue.
-A new added offloads in [rt]x_conf->offloads to ``rte_eth_[rt]x_queue_setup()``
input by application
+A newly added offload in ``[rt]x_conf->offloads`` to
``rte_eth_[rt]x_queue_setup()`` input by an application
 is the one which hasn't been enabled in ``rte_eth_dev_configure()`` and is
requested to be enabled
-in ``rte_eth_[rt]x_queue_setup()``, it must be per-queue type, otherwise
trigger an error log.
+in ``rte_eth_[rt]x_queue_setup()``. It must be per-queue type, otherwise
trigger an error log.

 For an application to use the Tx offloads API it should set the
``ETH_TXQ_FLAGS_IGNORE`` flag in the ``txq_flags`` field located in
``rte_eth_txconf`` struct.
 In such cases it is not required to set other flags in ``txq_flags``.
diff --git a/doc/guides/prog_guide/poll_mode_drv.rst
b/doc/guides/prog_guide/poll_mode_drv.rst
index bbb85f0..bd66e64 100644
--- a/doc/guides/prog_guide/poll_mode_drv.rst
+++ b/doc/guides/prog_guide/poll_mode_drv.rst
@@ -296,33 +296,37 @@ described in the mbuf API documentation and in the in
:ref:`Mbuf Library
 Per-Port and Per-Queue Offloads
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

-In the DPDK offload API, offloads are divided into per-port and per-queue offloads.
-A per-queue offloading can be enabled on a queue and disabled on another queue
at the same time.
-A pure per-port offload is the one supported by device but not per-queue type.
-A pure per-port offloading can't be enabled on a queue and disabled on another
queue at the same time.
-A pure per-port offloading must be enabled or disabled on all queues at the
same time.
-Any offloading is per-queue or pure per-port type, but can't be both types at
same devices.
-A per-port offloading can be enabled or disabled on all queues at the same time.
-It is certain that both per-queue and pure per-port offloading are per-port type.
+In the DPDK offload API, offloads are divided into per-port and per-queue
offloads as follows:
+
+* A per-queue offloading can be enabled on a queue and disabled on another
queue at the same time.
+* A pure per-port offload is the one supported by device but not per-queue type.
+* A pure per-port offloading can't be enabled on a queue and disabled on
another queue at the same time.
+* A pure per-port offloading must be enabled or disabled on all queues at the
same time.
+* Any offloading is per-queue or pure per-port type, but can't be both types at
same devices.
+* A per-port offloading can be enabled or disabled on all queues at the same time.
+* It is certain that both per-queue and pure per-port offloading are per-port type.
+
 The different offloads capabilities can be queried using
``rte_eth_dev_info_get()``.
-The dev_info->[rt]x_queue_offload_capa returned from ``rte_eth_dev_info_get()``
includes all per-queue offloading capabilities.
-The dev_info->[rt]x_offload_capa returned from ``rte_eth_dev_info_get()``
includes all per-port and per-queue offloading capabilities.
+The ``dev_info->[rt]x_queue_offload_capa`` returned from
``rte_eth_dev_info_get()`` includes all per-queue offloading capabilities.
+The ``dev_info->[rt]x_offload_capa returned`` from ``rte_eth_dev_info_get()``
includes all per-port and per-queue offloading capabilities.
 Supported offloads can be either per-port or per-queue.

 Offloads are enabled using the existing ``DEV_TX_OFFLOAD_*`` or
``DEV_RX_OFFLOAD_*`` flags.
-Any requested offloading by application must be within the device capabilities.
+Any requested offloading by an application must be within the device capabilities.
 Any offloading is disabled by default if it is not set in the parameter
-dev_conf->[rt]xmode.offloads to ``rte_eth_dev_configure()`` and
-[rt]x_conf->offloads to ``rte_eth_[rt]x_queue_setup()``.
-If any offloading is enabled in ``rte_eth_dev_configure()`` by application,
+``dev_conf->[rt]xmode.offloads`` to ``rte_eth_dev_configure()`` and
+``[rt]x_conf->offloads`` to ``rte_eth_[rt]x_queue_setup()``.
+
+If any offloading is enabled in ``rte_eth_dev_configure()`` by an application,
 it is enabled on all queues no matter whether it is per-queue or
 per-port type and no matter whether it is set or cleared in
-[rt]x_conf->offloads to ``rte_eth_[rt]x_queue_setup()``.
+``[rt]x_conf->offloads`` to ``rte_eth_[rt]x_queue_setup()``.
+
 If a per-queue offloading hasn't been enabled in ``rte_eth_dev_configure()``,
 it can be enabled or disabled in ``rte_eth_[rt]x_queue_setup()`` for individual
queue.
-A new added offloads in [rt]x_conf->offloads to ``rte_eth_[rt]x_queue_setup()``
input by application
+A newly added offload in ``[rt]x_conf->offloads`` to
``rte_eth_[rt]x_queue_setup()`` input by an application
 is the one which hasn't been enabled in ``rte_eth_dev_configure()`` and is
requested to be enabled
-in ``rte_eth_[rt]x_queue_setup()``, it must be per-queue type, otherwise
trigger an error log.
+in ``rte_eth_[rt]x_queue_setup()``. It must be per-queue type, otherwise
trigger an error log.

 For an application to use the Tx offloads API it should set the
``ETH_TXQ_FLAGS_IGNORE`` flag in the ``txq_flags`` field located in
``rte_eth_txconf`` struct.
 In such cases it is not required to set other flags in ``txq_flags``.