doc: update API deprecation for device reset
PATCH v2 1/1 doc: update API deprecation for device reset
Device reset may have the dependency, for example, a VF reset expects PF ready, or a NIC function as a part of a SOC need to wait for other parts of the system be ready, these are time-consuming tasks and will block current thread.
So we rename rte_eth_dev_reset to rte_eth_dev_reset_async as an async API, that makes things easy for an application that what to reset the device from the interrupt thread since typically a RTE_ETH_EVENT_INTR_RESET handler is invoked in interrupt thread.
RFC patch:
http://patchwork.dpdk.org/patch/44989/
---
v2:
- rename rte_eth_dev_reset to rte_eth_dev_reset_async
doc/guides/rel_notes/deprecation.rst | 6 ++++++ 1 file changed, 6 insertions(+)
doc/guides/rel_notes/deprecation.rst +6 -0
@@ -95,3 +95,9 @@ Deprecation Notices - ``rte_pdump_set_socket_dir`` will be removed; - The parameter, ``path``, of ``rte_pdump_init`` will be removed; - The enum ``rte_pdump_socktype`` will be removed. + +* ethdev: In v19.02 ``rte_eth_dev_reset`` is renamed to + ``rte_eth_dev_reset_async``. As the name, it is an async API. + Application should not assume device reset is finished after + ``rte_eth_dev_reset_async`` return, it should always wait for a + RTE_ETH_EVENT_RESET_COMPLETE event and check the reset result.
Signature · 1 line
2.13.6
Hi,
I don't remember why this deprecation notice did not get any feedback in the 18.11 cycle. It looks to be outdated now.
In case you still plan some changes, I give my opinion below.
20/09/2018 06:59, Qi Zhang:
Quoted 10 lines
Device reset may have the dependency, for example, a VF reset expects PF ready, or a NIC function as a part of a SOC need to wait for other parts of the system be ready, these are time-consuming tasks and will block current thread.
So we rename
rte_eth_dev_resettorte_eth_dev_reset_asyncas an async API, that makes things easy for an application that what to reset the device from the interrupt thread since typically aRTE_ETH_EVENT_INTR_RESEThandler is invoked in interrupt thread.
Quoted 4 lines
RFC patch:
http://patchwork.dpdk.org/patch/44989/Signed-off-by Qi Zhang <[email protected]>
I remmember I did not like this function when it was introduced. I think the cases addressed by rte_eth_dev_reset() should be handled with hotplug mechanism.
doc/guides/rel_notes/deprecation.rst Deprecation Notices · line 99
Quoted 3 lines
doc/guides/rel_notes/deprecation.rst +1
-0+* ethdev: In v19.02 ``rte_eth_dev_reset`` is renamed to
Is it still planned for 19.05?
Quoted 1 line
+ ``rte_eth_dev_reset_async``. As the name, it is an async API.
Why removing the old function?
We could avoid breaking applications by adding an async flavor of the function.
doc/guides/rel_notes/deprecation.rst Deprecation Notices · line 103
Quoted 3 lines
doc/guides/rel_notes/deprecation.rst +3
-0+ Application should not assume device reset is finished after + ``rte_eth_dev_reset_async`` return, it should always wait for a + RTE_ETH_EVENT_RESET_COMPLETE event and check the reset result.
This could be done in the synchronous flavor with sleeps in a loop.