docs: dmaengine: document ownership of the descriptor flags field
Subsystems (2)
PATCH 1/1 docs: dmaengine: document ownership of the descriptor flags field
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.
--- Documentation/driver-api/dmaengine/provider.rst | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-)
Documentation/driver-api/dmaengine/provider.rst +5 -3
@@ -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
Signature · 1 line
2.55.0
Quoted 19 lines · Bogdan Mahomet
The flags field of struct
dma_async_tx_descriptorhas 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, andDMA_CTRL_ACKandDMA_CTRL_REUSEare tested withasync_tx_test_ack()anddmaengine_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()anddmaengine_desc_clear_reuse().
Quoted 4 lines
Document that rule in place of the TODO.
Signed-off-by Bogdan Mahomet <[email protected]>---
Quoted 25 lines
Documentation/driver-api/dmaengine/provider.rst | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-)Documentation/driver-api/dmaengine/provider.rst +5
-4@@ -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
Quoted 14 lines · Bogdan Mahomet
The flags field of struct
dma_async_tx_descriptorhas 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, andDMA_CTRL_ACKandDMA_CTRL_REUSEare tested withasync_tx_test_ack()anddmaengine_desc_test_reuse()before a descriptor is recycled or freed.
Quoted 1 line
[...]
Applied, thanks!
[1/1] docs: dmaengine: document ownership of the descriptor flags field
commit: ef399305a5bf64231059c63a53f3384eb59c2458
Best regards,
Signature · 1 line
~Vinod