[PATCH 3/3] ethdev: document special cases of port start and stop

[Dariusz Sosnowski <dsosnowski@nvidia.com>]

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(-)

diff --git a/app/test-pmd/testpmd.c b/app/test-pmd/testpmd.c
index 7381dfd9e5..c9252031e8 100644
--- a/app/test-pmd/testpmd.c
+++ b/app/test-pmd/testpmd.c
@@ -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;
diff --git a/lib/ethdev/rte_ethdev.h b/lib/ethdev/rte_ethdev.h
index 13fe73d5a3..abf5a24f92 100644
--- a/lib/ethdev/rte_ethdev.h
+++ b/lib/ethdev/rte_ethdev.h
@@ -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);
-- 
2.25.1