From: Vamsi Attunuru <[email protected]> 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 <[email protected]> --- 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
