[RFC PATCH 1/3] ethdev: add set link state on close API

[Ciara Loftus <ciara.loftus@intel.com>]

Allow the user to configure the state a link should be in after
the device has been stopped/closed. Make this configurable
through the new experimental rte_eth_dev_set_link_state_on_close
API. Three states are allowed:
1. down: bring (or keep) the link down
2. up: bring (or keep) the link up
3. initial: restore the link to the state it was in when the device was
started.

Signed-off-by: Ciara Loftus <ciara.loftus@intel.com>
---
 doc/guides/rel_notes/release_25_11.rst |  4 ++++
 lib/ethdev/ethdev_driver.h             | 18 +++++++++++++++
 lib/ethdev/ethdev_trace.h              |  8 +++++++
 lib/ethdev/ethdev_trace_points.c       |  3 +++
 lib/ethdev/rte_ethdev.c                | 19 +++++++++++++++
 lib/ethdev/rte_ethdev.h                | 32 ++++++++++++++++++++++++++
 6 files changed, 84 insertions(+)

diff --git a/doc/guides/rel_notes/release_25_11.rst b/doc/guides/rel_notes/release_25_11.rst
index 32d61691d2..8f9ab31687 100644
--- a/doc/guides/rel_notes/release_25_11.rst
+++ b/doc/guides/rel_notes/release_25_11.rst
@@ -55,6 +55,10 @@ New Features
      Also, make sure to start the actual text at the margin.
      =======================================================
 
+   * ** Added link state on close ethdev API
+
+     * Added a new API to the ethdev library to allow the configuration of link state
+       on device close. It can be configured as down, up or restored to initial state.
 
 Removed Items
 -------------
diff --git a/lib/ethdev/ethdev_driver.h b/lib/ethdev/ethdev_driver.h
index 2b4d2ae9c3..f82c67ce36 100644
--- a/lib/ethdev/ethdev_driver.h
+++ b/lib/ethdev/ethdev_driver.h
@@ -1199,6 +1199,21 @@ typedef int (*eth_ip_reassembly_conf_set_t)(struct rte_eth_dev *dev,
 typedef const uint32_t *(*eth_buffer_split_supported_hdr_ptypes_get_t)(struct rte_eth_dev *dev,
 								       size_t *no_of_elements);
 
+/**
+ * @internal
+ * Set the state the link should be configured to be on device closure.
+ *
+ * @param dev
+ *   Ethdev handle of port.
+ * @param state
+ *   Either down, up or initial.
+ *
+ * @return
+ *   Negative errno value on error, zero otherwise.
+ */
+typedef int (*eth_link_state_on_close_set_t)(struct rte_eth_dev *dev,
+						enum rte_eth_link_state_on_close state);
+
 /**
  * @internal
  * Dump private info from device to a file.
@@ -1599,6 +1614,9 @@ struct eth_dev_ops {
 	/** Get supported header ptypes to split */
 	eth_buffer_split_supported_hdr_ptypes_get_t buffer_split_supported_hdr_ptypes_get;
 
+	/** Set link state on close */
+	eth_link_state_on_close_set_t link_state_on_close_set;
+
 	/** Dump private info from device */
 	eth_dev_priv_dump_t eth_dev_priv_dump;
 
diff --git a/lib/ethdev/ethdev_trace.h b/lib/ethdev/ethdev_trace.h
index 482befc209..6554d176b8 100644
--- a/lib/ethdev/ethdev_trace.h
+++ b/lib/ethdev/ethdev_trace.h
@@ -1298,6 +1298,14 @@ RTE_TRACE_POINT(
 	rte_trace_point_emit_u32(ptypes);
 )
 
+RTE_TRACE_POINT(
+	rte_eth_trace_link_state_on_close_set,
+	RTE_TRACE_POINT_ARGS(uint16_t port_id, enum rte_eth_link_state_on_close state, int ret),
+	rte_trace_point_emit_u16(port_id);
+	rte_trace_point_emit_int(state);
+	rte_trace_point_emit_int(ret);
+)
+
 RTE_TRACE_POINT(
 	rte_eth_trace_cman_info_get,
 	RTE_TRACE_POINT_ARGS(uint16_t port_id,
diff --git a/lib/ethdev/ethdev_trace_points.c b/lib/ethdev/ethdev_trace_points.c
index 071c508327..e515efacc7 100644
--- a/lib/ethdev/ethdev_trace_points.c
+++ b/lib/ethdev/ethdev_trace_points.c
@@ -482,6 +482,9 @@ RTE_TRACE_POINT_REGISTER(rte_eth_trace_ip_reassembly_conf_set,
 RTE_TRACE_POINT_REGISTER(rte_eth_trace_buffer_split_get_supported_hdr_ptypes,
 	lib.ethdev.buffer_split_get_supported_hdr_ptypes)
 
+RTE_TRACE_POINT_REGISTER(rte_eth_trace_link_state_on_close_set,
+	lib.ethdev.link_state_on_close_set)
+
 RTE_TRACE_POINT_REGISTER(rte_eth_trace_cman_info_get,
 	lib.ethdev.cman_info_get)
 
diff --git a/lib/ethdev/rte_ethdev.c b/lib/ethdev/rte_ethdev.c
index dd7c00bc94..4847a89440 100644
--- a/lib/ethdev/rte_ethdev.c
+++ b/lib/ethdev/rte_ethdev.c
@@ -7344,6 +7344,25 @@ rte_eth_buffer_split_get_supported_hdr_ptypes(uint16_t port_id, uint32_t *ptypes
 	return j;
 }
 
+RTE_EXPORT_EXPERIMENTAL_SYMBOL(rte_eth_dev_set_link_state_on_close, 25.11)
+int
+rte_eth_dev_set_link_state_on_close(uint16_t port_id, enum rte_eth_link_state_on_close state)
+{
+	struct rte_eth_dev *dev;
+	int ret;
+
+	RTE_ETH_VALID_PORTID_OR_ERR_RET(port_id, -ENODEV);
+	dev = &rte_eth_devices[port_id];
+
+	if (dev->dev_ops->link_state_on_close_set == NULL)
+		return -ENOTSUP;
+	ret = eth_err(port_id, dev->dev_ops->link_state_on_close_set(dev, state));
+
+	rte_eth_trace_link_state_on_close_set(port_id, state, ret);
+
+	return ret;
+}
+
 RTE_EXPORT_EXPERIMENTAL_SYMBOL(rte_eth_dev_count_aggr_ports, 23.03)
 int rte_eth_dev_count_aggr_ports(uint16_t port_id)
 {
diff --git a/lib/ethdev/rte_ethdev.h b/lib/ethdev/rte_ethdev.h
index f9fb6ae549..3312f1e95c 100644
--- a/lib/ethdev/rte_ethdev.h
+++ b/lib/ethdev/rte_ethdev.h
@@ -514,6 +514,12 @@ struct rte_eth_rss_conf {
 	enum rte_eth_hash_function algorithm;	/**< Hash algorithm. */
 };
 
+enum rte_eth_link_state_on_close {
+	RTE_ETH_LINK_STATE_ON_CLOSE_DOWN = 1,
+	RTE_ETH_LINK_STATE_ON_CLOSE_UP = 2,
+	RTE_ETH_LINK_STATE_ON_CLOSE_INITIAL = 3
+};
+
 /*
  * A packet can be identified by hardware as different flow types. Different
  * NIC hardware may support different flow types.
@@ -7065,6 +7071,32 @@ __rte_experimental
 int rte_eth_buffer_split_get_supported_hdr_ptypes(uint16_t port_id, uint32_t *ptypes, int num)
 	__rte_warn_unused_result;
 
+/**
+ * @warning
+ * @b EXPERIMENTAL: this API may change without prior notice
+ *
+ * Configure the state of the physical link when the device is closed.
+ *
+ * This function allows the configuration of the physical link state
+ * when the device is closed. The link can be set to either down, up or
+ * remain configured as the device default, depending on the value of the
+ * 'state' parameter.
+ *
+ * @param port_id
+ *   The port identifier of the device.
+ * @param state
+ *  - RTE_ETH_LINK_STATE_ON_CLOSE_DOWN - Bring (or keep) the link down.
+ *  - RTE_ETH_LINK_STATE_ON_CLOSE_UP   - Bring (or keep) the link up.
+ *  - RTE_ETH_LINK_STATE_ON_CLOSE_INITIAL - Restore the link to the state it
+ *    was in when the device was started.
+ * @return
+ *   - (0) on success
+ *   - (-ENOTSUP) if the device does not support this function.
+ */
+__rte_experimental
+int rte_eth_dev_set_link_state_on_close(uint16_t port_id, enum rte_eth_link_state_on_close state)
+	__rte_warn_unused_result;
+
 /**
  * @warning
  * @b EXPERIMENTAL: this API may change, or be removed, without prior notice.
-- 
2.34.1