[dpdk-dev] Guidelines for moving PMDs to new ethdev offloads API

[Stephen Hemminger]

On Sun, 10 Dec 2017 05:35:45 +0000
Shahaf Shuler <shahafs at mellanox.com> wrote:

> In 17.11 the ethdev offloads API has changed:
> 
>                 commit cba7f53b717d ("ethdev: introduce Tx queue offloads API")
> 
>                 commit ce17eddefc20 ("ethdev: introduce Rx queue offloads API") The new API is documented in the programmer's guide:
> 
>                 https://emea01.safelinks.protection.outlook.com/?url=http%3A%2F%2Fdpdk.org%2Fdoc%2Fguides%2Fprog_guide%2Fpoll_mode_drv.html%23hardware-offload&data=02%7C01%7Cshahafs%40mellanox.com%7Cc365451c3f934b73db5e08d53f6fe6fd%7Ca652971c7d2e4d9ba6a4d149256f461b%7C0%7C0%7C636484672216209911&sdata=l0OkZ8m78BMsw%2F0d7bA8m80gVqlSL%2Bpcs9UplVSmlOA%3D&reserved=0
> 
> 
> 
> As announced in the deprecation notice, the old API is planned to be removed in 18.05:
> 
>                 https://emea01.safelinks.protection.outlook.com/?url=http%3A%2F%2Fdpdk.org%2Fdoc%2Fguides%2Frel_notes%2Fdeprecation.html&data=02%7C01%7Cshahafs%40mellanox.com%7Cc365451c3f934b73db5e08d53f6fe6fd%7Ca652971c7d2e4d9ba6a4d149256f461b%7C0%7C0%7C636484672216209911&sdata=85wB%2BoU3um%2BXegYiLAJIDYWIkvpb9WQtPSgA73zsLHI%3D&reserved=0
> 
> As agreed, all the PMDs must be converted to the new API by their maintainers.
> 
> This email will better explain the transition process.
> 
> 
> 
> The main concepts in the new API are:
> 
>                 - All offloads are disabled by default
> 
>                 - Distinction between per port and per queue offloads.
> 
>                 Per port offloads needs to be set also for each queue of the port.
> 
> 
> 
> The transition period is using an API translation in rte_ethdev.c:
> 
>                 - The old API is translated to allow using converted PMDs
> 
>                 - The new API is translated to allow using not converted PMDs
> 
>                 - The use of the new API is flagged to trigger the right translation
> 
> 
> 
> * Device capabilities - rte_eth_dev_info_get()
> 
>                 - Not changing: use DEV_RX/TX_OFFLOAD_* flags
> 
>                 - Old API: per-port fields rte_eth_dev_info.rx/tx_offload_capa
> 
>                 - New API: added per-queue rte_eth_dev_info.rx/tx_queue_offload_capa
> 
> 
> 
> * Rx offloads
> 
>                 - Not changing: offload disabled by default
> 
>                 - Old API: per-port rte_eth_conf.rxmode.[bit-fields]
> 
>                 - New API: per-port rte_eth_conf.rxmode.offloads and per queue rte_eth_rxconf.offloads  using DEV_RX_OFFLOAD_*
> 
>                 - Transition: rte_eth_conf.rxmode.ignore_offload_bitfield must be set
> 
>                               when using the new API (Done by application)
> 
>                 - To be removed: rte_eth_conf.rxmode.[
> 
>                                 header_split, hw_ip_checksum, hw_vlan_filter, hw_vlan_strip,
> 
>                                 hw_vlan_extend, jumbo_frame, hw_strip_crc, enable_scatter,
> 
>                                 enable_lro, hw_timestamp, security]
> 
> 
> 
> * Tx offloads
> 
>                 - Old API: enabled by default
> 
>                            per-queue rte_eth_txconf.txq_flags using ETH_TXQ_FLAGS_NO*
> 
>                 - New API: disabled by default
> 
>                            per-port rte_eth_conf.txmode.offloads and per queue rte_eth_txconf.offloads  using DEV_TX_OFFLOAD_*
> 
>                 - Transition: ETH_TXQ_FLAGS_IGNORE must be set when using the new API (Done by application)
> 
>                               PMD should ignore port offloads not set on the device configuration when using old API
> 
>                 - To be removed: rte_eth_txconf.txq_flags and ETH_TXQ_FLAGS_NO*
> 
> 
> --Shahaf
> 

I agree with this change. but how can it be done with out breaking ABI?