[PATCH v2 1/1] dmadev: add domain_id field to access group join API

[Vamsi Krishna <vattunuru@marvell.com>]

From: Vamsi Attunuru <vattunuru@marvell.com>

Add domain_id field to access group join API, which is required
to retrieve handler information associated with the specified domain.
This enhancement ensures that domain-specific context is available
during group join operations, improving flexibility and traceability
in multi-domain environments.

Patch aligns the parameters of access group create and join APIs
for consistency and clarity, also updates the dmadev.rst file with
detailed steps.

Signed-off-by: Vamsi Attunuru <vattunuru@marvell.com>
---
V2 changes:
* Updated domain_id field description.
* Added more detailed steps in dmadev.rst file.

 doc/guides/prog_guide/dmadev.rst | 43 +++++++++++++++++++++-----------
 lib/dmadev/rte_dmadev.c          |  6 ++---
 lib/dmadev/rte_dmadev.h          | 12 +++++----
 lib/dmadev/rte_dmadev_pmd.h      |  4 +--
 lib/dmadev/rte_dmadev_trace.h    |  6 +++--
 5 files changed, 44 insertions(+), 27 deletions(-)

diff --git a/doc/guides/prog_guide/dmadev.rst b/doc/guides/prog_guide/dmadev.rst
index 776a860070..1a2384eea1 100644
--- a/doc/guides/prog_guide/dmadev.rst
+++ b/doc/guides/prog_guide/dmadev.rst
@@ -177,7 +177,7 @@ the :doc:`../howto/telemetry`.
 
 
 Inter-domain DMA Transfers
-~~~~~~~~~~~~~~~~~~~~~~~~~~
+--------------------------
 
 The inter-domain DMA feature enables DMA devices to perform data transfers
 across different processes and OS domains.
@@ -201,32 +201,45 @@ can perform DMA transfers across processes or OS domains.
 Below is the API usage flow
 for setting up the access pair group for DMA between process#1 and process#2.
 
+Each process must generate a unique ``domain_id`` to represent its identity
+(e.g., a process-specific or OS-specific domain identifier).
+
 Process#1 (Group Creator)
-^^^^^^^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+* Generates a unique ``token`` that will be used to secure the access pair group.
+
+* Calls ``rte_dma_access_pair_group_create`` to establish a new access pair group.
 
-Calls ``rte_dma_access_pair_group_create`` to establish a new access pair group,
-then shares the ``group_id``, ``token`` and ``domain_id`` with Process#2 via IPC.
+* Shares the ``group_id``, ``token`` and its ``domain_id`` details with Process#2
+  via IPC or sideband communication channel.
 
 Process#2 (Group Joiner)
-^^^^^^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~~~~~~~
 
-Receives the ``group_id`` and ``token`` from Process#1
-and calls ``rte_dma_access_pair_group_join`` to join the group.
+* Receives the ``group_id``, ``token`` and Process#1's ``domain_id``.
+
+* Passes ``group_id``, ``token`` and its own ``domain_id`` to ``rte_dma_access_pair_group_join``
+  to join the access group.
+
+* Shares its ``domain_id`` details with Process#1 via IPC or sideband communication channel.
 
 Both Processes
-^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~
+
+* Each process retrieves the ``handler`` information associated with its own or the peer's
+  ``domain_id`` using ``rte_dma_access_pair_group_handler_get``.
 
-Use ``rte_dma_access_pair_group_handler_get`` to obtain ``handler`` information
-for domains in the group.
+* Use these ``handler`` details to setup the virtual channel configuration.
 
-Perform inter-domain DMA transfers as required.
+* Perform the inter-domain DMA transfers as required.
 
 Process#2 (when finished)
-^^^^^^^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Calls ``rte_dma_access_pair_group_leave`` to exit the group.
+* Calls ``rte_dma_access_pair_group_leave`` to exit the group.
 
 Process#1 (final cleanup)
-^^^^^^^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Calls ``rte_dma_access_pair_group_destroy`` to destroy the group.
+* Calls ``rte_dma_access_pair_group_destroy`` to destroy the group.
diff --git a/lib/dmadev/rte_dmadev.c b/lib/dmadev/rte_dmadev.c
index c008e829db..b75b4f9bd1 100644
--- a/lib/dmadev/rte_dmadev.c
+++ b/lib/dmadev/rte_dmadev.c
@@ -875,8 +875,8 @@ rte_dma_access_pair_group_destroy(int16_t dev_id, int16_t group_id)
 
 RTE_EXPORT_EXPERIMENTAL_SYMBOL(rte_dma_access_pair_group_join, 25.11)
 int
-rte_dma_access_pair_group_join(int16_t dev_id, int16_t group_id, rte_uuid_t token,
-			       rte_dma_access_pair_group_event_cb_t cb)
+rte_dma_access_pair_group_join(int16_t dev_id, rte_uuid_t domain_id, rte_uuid_t token,
+			       int16_t group_id, rte_dma_access_pair_group_event_cb_t cb)
 {
 	struct rte_dma_info dev_info;
 	struct rte_dma_dev *dev;
@@ -899,7 +899,7 @@ rte_dma_access_pair_group_join(int16_t dev_id, int16_t group_id, rte_uuid_t toke
 
 	if (*dev->dev_ops->access_pair_group_join == NULL)
 		return -ENOTSUP;
-	return (*dev->dev_ops->access_pair_group_join)(dev, group_id, token, cb);
+	return (*dev->dev_ops->access_pair_group_join)(dev, domain_id, token, group_id, cb);
 }
 
 RTE_EXPORT_EXPERIMENTAL_SYMBOL(rte_dma_access_pair_group_leave, 25.11)
diff --git a/lib/dmadev/rte_dmadev.h b/lib/dmadev/rte_dmadev.h
index 0f4f10ec12..c554c4289c 100644
--- a/lib/dmadev/rte_dmadev.h
+++ b/lib/dmadev/rte_dmadev.h
@@ -867,7 +867,7 @@ typedef void (*rte_dma_access_pair_group_event_cb_t)(int16_t dev_id,
  * @param dev_id
  *   Identifier of the DMA device initiating the group.
  * @param domain_id
- *   Unique identifier representing the process or OS domain.
+ *   Unique identifier representing the current process or OS domain.
  * @param token
  *   Authentication token used to establish the access group.
  * @param[out] group_id
@@ -912,10 +912,12 @@ int rte_dma_access_pair_group_destroy(int16_t dev_id, int16_t group_id);
  *
  * @param dev_id
  *   Identifier of the DMA device attempting to join the group.
- * @param group_id
- *   ID of the access group to join.
+ * @param domain_id
+ *   Unique identifier representing the current process or OS domain.
  * @param token
  *   Authentication token used to validate group membership.
+ * @param group_id
+ *   ID of the access group to join.
  * @param cb
  *   Callback function to be invoked when the device leaves the group
  *   or when the group is destroyed due to some exception or failure.
@@ -925,8 +927,8 @@ int rte_dma_access_pair_group_destroy(int16_t dev_id, int16_t group_id);
  *   negative value on failure indicating the error code.
  */
 __rte_experimental
-int rte_dma_access_pair_group_join(int16_t dev_id, int16_t group_id, rte_uuid_t token,
-				   rte_dma_access_pair_group_event_cb_t cb);
+int rte_dma_access_pair_group_join(int16_t dev_id, rte_uuid_t domain_id, rte_uuid_t token,
+				   int16_t group_id, rte_dma_access_pair_group_event_cb_t cb);
 
 /**
  * Leave an access group, removing the device's entry from the group table
diff --git a/lib/dmadev/rte_dmadev_pmd.h b/lib/dmadev/rte_dmadev_pmd.h
index 16fd625c2d..8a6b0a9c98 100644
--- a/lib/dmadev/rte_dmadev_pmd.h
+++ b/lib/dmadev/rte_dmadev_pmd.h
@@ -75,8 +75,8 @@ typedef int (*rte_dma_access_pair_group_destroy_t)(const struct rte_dma_dev *dev
 						   int16_t group_id);
 
 /** @internal Used to join an access pair group for inter-process or inter-OS DMA transfers. */
-typedef int (*rte_dma_access_pair_group_join_t)(const struct rte_dma_dev *dev, int16_t group_id,
-						rte_uuid_t token,
+typedef int (*rte_dma_access_pair_group_join_t)(const struct rte_dma_dev *dev, rte_uuid_t domain_id,
+						rte_uuid_t token, int16_t group_id,
 						rte_dma_access_pair_group_event_cb_t cb);
 
 /** @internal Used to leave an access pair group, removing the device from the group. */
diff --git a/lib/dmadev/rte_dmadev_trace.h b/lib/dmadev/rte_dmadev_trace.h
index da80a8cb50..7ad00b5bfa 100644
--- a/lib/dmadev/rte_dmadev_trace.h
+++ b/lib/dmadev/rte_dmadev_trace.h
@@ -120,10 +120,12 @@ RTE_TRACE_POINT(
 
 RTE_TRACE_POINT(
 	rte_dma_trace_access_pair_group_join,
-	RTE_TRACE_POINT_ARGS(int16_t dev_id, int16_t group_id, rte_uuid_t token),
+	RTE_TRACE_POINT_ARGS(int16_t dev_id, rte_uuid_t domain_id, rte_uuid_t token,
+			     int16_t group_id),
 	rte_trace_point_emit_i16(dev_id);
-	rte_trace_point_emit_i16(group_id);
+	rte_trace_point_emit_u8_ptr(&domain_id[0]);
 	rte_trace_point_emit_u8_ptr(&token[0]);
+	rte_trace_point_emit_i16(group_id);
 )
 
 RTE_TRACE_POINT(
-- 
2.34.1