Re: [PATCH] docs: dmaengine: document ownership of the descriptor flags field

[Frank Li]

On Sat, Aug 22, 2026 at 03:15:30AM +0300, Bogdan Mahomet wrote:
> The flags field of struct dma_async_tx_descriptor has carried a TODO
> since the provider documentation was added in 2014, asking whether a
> driver may modify the field itself or whether it must always hold the
> flags passed in the arguments.
>
> The field belongs to the client. dma_async_tx_descriptor_init() does
> not touch it, so the provider has to set it, and providers store the
> flags they were given verbatim; vchan_tx_prep() does this for every
> driver built on top of virt-dma. Afterwards providers only read the
> field: the DMA_PREP_* bits are consumed while the descriptor is being
> prepared, and DMA_CTRL_ACK and DMA_CTRL_REUSE are tested with
> async_tx_test_ack() and dmaengine_desc_test_reuse() before a
> descriptor is recycled or freed.
>
> Once a descriptor has been prepared, nothing in the tree changes the
> field except the client helpers in include/linux/dmaengine.h:
> async_tx_ack(), async_tx_clear_ack(), dmaengine_desc_set_reuse() and
> dmaengine_desc_clear_reuse().
>
> Document that rule in place of the TODO.
>
> Signed-off-by: Bogdan Mahomet <bogdan.mahomet.dev@xxxxxxxxx>
> ---

Reviewed-by: Frank Li <Frank.Li@xxxxxxx>

>  Documentation/driver-api/dmaengine/provider.rst | 8 +++++---
>  1 file changed, 5 insertions(+), 3 deletions(-)
>
> diff --git a/Documentation/driver-api/dmaengine/provider.rst b/Documentation/driver-api/dmaengine/provider.rst
> index f4ed98f701c9..c10d8ab8fdbd 100644
> --- a/Documentation/driver-api/dmaengine/provider.rst
> +++ b/Documentation/driver-api/dmaengine/provider.rst
> @@ -413,9 +413,11 @@ supported.
>
>    - You'll also need to set following fields in this structure:
>
> -    - flags:
> -      TODO: Can it be modified by the driver itself, or
> -      should it be always the flags passed in the arguments
> +    - flags: this field belongs to the client. The driver stores the
> +      flags passed in the arguments and must not modify them. It reads
> +      the DMA_PREP_* bits while preparing the descriptor, and must only
> +      test DMA_CTRL_ACK and DMA_CTRL_REUSE, which the client may change
> +      after the descriptor has been prepared.
>
>      - tx_submit: A pointer to a function you have to implement,
>        that is supposed to push the current transaction descriptor to a
> --
> 2.55.0
>