[3/3] ethdev: document special cases of port start and stop
Checks
Commit Message
This patch clarifies the handling of following cases
in the ethdev API docs:
- If rte_eth_dev_start() returns (-EAGAIN) for some port,
it cannot be started until other port is started.
- If rte_eth_dev_stop() returns (-EBUSY) for some port,
it cannot be stopped until other port is stopped.
When stopping the port in testpmd fails due to (-EBUSY),
port's state is switched back to STARTED
to allow users to manually retry stopping the port.
No additional changes in testpmd are required to handle
failure to start port with (-EAGAIN).
If rte_eth_dev_start() fails, port's state is switched to STOPPED
and users are allowed to retry the operation.
Signed-off-by: Dariusz Sosnowski <dsosnowski@nvidia.com>
---
app/test-pmd/testpmd.c | 10 +++++++++-
lib/ethdev/rte_ethdev.h | 9 +++++++++
2 files changed, 18 insertions(+), 1 deletion(-)
@@ -3158,6 +3158,7 @@ stop_port(portid_t pid)
int need_check_link_status = 0;
portid_t peer_pl[RTE_MAX_ETHPORTS];
int peer_pi;
+ int ret;
if (port_id_is_invalid(pid, ENABLED_WARN))
return;
@@ -3207,9 +3208,16 @@ stop_port(portid_t pid)
if (port->flow_list)
port_flow_flush(pi);
- if (eth_dev_stop_mp(pi) != 0)
+ ret = eth_dev_stop_mp(pi);
+ if (ret != 0) {
RTE_LOG(ERR, EAL, "rte_eth_dev_stop failed for port %u\n",
pi);
+ if (ret == -EBUSY) {
+ /* Allow to retry stopping the port. */
+ port->port_status = RTE_PORT_STARTED;
+ continue;
+ }
+ }
if (port->port_status == RTE_PORT_HANDLING)
port->port_status = RTE_PORT_STOPPED;
@@ -2701,10 +2701,14 @@ int rte_eth_dev_tx_queue_stop(uint16_t port_id, uint16_t tx_queue_id);
* On success, all basic functions exported by the Ethernet API (link status,
* receive/transmit, and so on) can be invoked.
*
+ * If the port depends on another one being started,
+ * PMDs might return (-EAGAIN) to notify about such requirement.
+ *
* @param port_id
* The port identifier of the Ethernet device.
* @return
* - 0: Success, Ethernet device started.
+ * - -EAGAIN: If it depends on another port to be started first.
* - <0: Error code of the driver device start function.
*/
int rte_eth_dev_start(uint16_t port_id);
@@ -2713,10 +2717,15 @@ int rte_eth_dev_start(uint16_t port_id);
* Stop an Ethernet device. The device can be restarted with a call to
* rte_eth_dev_start()
*
+ * If the port provides some resources for other ports
+ * and it cannot be stopped before them,
+ * PMDs might return (-EBUSY) to notify about such requirement.
+ *
* @param port_id
* The port identifier of the Ethernet device.
* @return
* - 0: Success, Ethernet device stopped.
+ * - -EBUSY: If it depends on another port to be stopped first.
* - <0: Error code of the driver device stop function.
*/
int rte_eth_dev_stop(uint16_t port_id);