[PATCH v1 8/8] vfio: deprecate group-based API

[Anatoly Burakov <anatoly.burakov@intel.com>]

Aside from "get group number" which is a read-only API, deprecate all VFIO
group-based API's, and steer the users towards container device assignment
model.

Signed-off-by: Anatoly Burakov <anatoly.burakov@intel.com>
---
 lib/eal/include/rte_vfio.h | 31 ++++++++++++++++++++++++++-----
 1 file changed, 26 insertions(+), 5 deletions(-)

diff --git a/lib/eal/include/rte_vfio.h b/lib/eal/include/rte_vfio.h
index 735e67a54c..c57067f054 100644
--- a/lib/eal/include/rte_vfio.h
+++ b/lib/eal/include/rte_vfio.h
@@ -151,20 +151,28 @@ enum rte_vfio_mode
 rte_vfio_get_mode(void);
 
 /**
+ * @deprecated
  * Check if VFIO NOIOMMU mode is enabled.
  *
+ * This function is deprecated and its use is discouraged.
+ * Use `rte_vfio_get_mode()` instead to query NOIOMMU status.
+ *
  * This function is only relevant on Linux in group mode.
  *
  * @return
  *   1 if enabled.
  *   0 if not enabled or not supported.
  */
-int
+int __rte_deprecated
 rte_vfio_noiommu_is_enabled(void);
 
 /**
+ * @deprecated
  * Remove group fd from internal VFIO tracking.
  *
+ * This function is deprecated and its use is discouraged.
+ * Use `rte_vfio_release_device()` instead, which will release the device and its resources.
+ *
  * This function is only relevant on Linux in group mode.
  *
  * @param vfio_group_fd
@@ -179,7 +187,7 @@ rte_vfio_noiommu_is_enabled(void);
  * - ENXIO   - VFIO support not initialized.
  * - ENOTSUP - Operation not supported.
  */
-int
+int __rte_deprecated
 rte_vfio_clear_group(int vfio_group_fd);
 
 /**
@@ -276,8 +284,12 @@ int
 rte_vfio_get_container_fd(void);
 
 /**
+ * @deprecated
  * Return file descriptor for an open VFIO group.
  *
+ * This function is deprecated and its use is discouraged.
+ * Use `rte_vfio_setup_device()` instead, which handles group management automatically.
+ *
  * This function is only relevant on Linux in group mode.
  *
  * @param iommu_group_num
@@ -292,7 +304,7 @@ rte_vfio_get_container_fd(void);
  * - ENXIO   - VFIO support not initialized.
  * - ENOTSUP - Operation not supported.
  */
-int
+int __rte_deprecated
 rte_vfio_get_group_fd(int iommu_group_num);
 
 /**
@@ -379,8 +391,12 @@ rte_vfio_container_assign_device(int vfio_container_fd,
 		const char *sysfs_base, const char *dev_addr);
 
 /**
+ * @deprecated
  * Bind an IOMMU group to a container.
  *
+ * This function is deprecated and its use is discouraged.
+ * Use `rte_vfio_container_assign_device()` instead to assign devices to a non-default container.
+ *
  * This function is only relevant on Linux in group mode.
  *
  * @param container_fd
@@ -399,12 +415,17 @@ rte_vfio_container_assign_device(int vfio_container_fd,
  * - ENXIO   - VFIO support not initialized.
  * - ENOTSUP - Operation not supported.
  */
-int
+int __rte_deprecated
 rte_vfio_container_group_bind(int container_fd, int iommu_group_num);
 
 /**
+ * @deprecated
  * Unbind an IOMMU group from a container.
  *
+ * This function is deprecated and its use is discouraged.
+ * Use `rte_vfio_release_device()` instead to release devices, which handles group cleanup
+ * automatically.
+ *
  * This function is only relevant on Linux in group mode.
  *
  * @param container_fd
@@ -423,7 +444,7 @@ rte_vfio_container_group_bind(int container_fd, int iommu_group_num);
  * - ENXIO   - VFIO support not initialized.
  * - ENOTSUP - Operation not supported.
  */
-int
+int __rte_deprecated
 rte_vfio_container_group_unbind(int container_fd, int iommu_group_num);
 
 /**
-- 
2.47.3