Am 31.08.22 um 17:37 schrieb Dmitry Osipenko:
Add documentation for the dynamic locking convention. The documentation tells dma-buf API users when they should take the reservation lock and when not.
Signed-off-by: Dmitry Osipenko dmitry.osipenko@collabora.com
Reviewed-by: Christian König christian.koenig@amd.com
Documentation/driver-api/dma-buf.rst | 6 +++ drivers/dma-buf/dma-buf.c | 64 ++++++++++++++++++++++++++++ 2 files changed, 70 insertions(+)
diff --git a/Documentation/driver-api/dma-buf.rst b/Documentation/driver-api/dma-buf.rst index 36a76cbe9095..622b8156d212 100644 --- a/Documentation/driver-api/dma-buf.rst +++ b/Documentation/driver-api/dma-buf.rst @@ -119,6 +119,12 @@ DMA Buffer ioctls .. kernel-doc:: include/uapi/linux/dma-buf.h +DMA-BUF locking convention +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.. kernel-doc:: drivers/dma-buf/dma-buf.c
- :doc: locking convention
- Kernel Functions and Structures Reference
diff --git a/drivers/dma-buf/dma-buf.c b/drivers/dma-buf/dma-buf.c index d9130486cb8f..97ce884fad76 100644 --- a/drivers/dma-buf/dma-buf.c +++ b/drivers/dma-buf/dma-buf.c @@ -794,6 +794,70 @@ static struct sg_table * __map_dma_buf(struct dma_buf_attachment *attach, return sg_table; } +/**
- DOC: locking convention
- In order to avoid deadlock situations between dma-buf exports and importers,
- all dma-buf API users must follow the common dma-buf locking convention.
- Convention for importers
- Importers must hold the dma-buf reservation lock when calling these
- functions:
- dma_buf_pin()
- dma_buf_unpin()
- dma_buf_map_attachment()
- dma_buf_unmap_attachment()
- dma_buf_vmap()
- dma_buf_vunmap()
- Importers must not hold the dma-buf reservation lock when calling these
- functions:
- dma_buf_attach()
- dma_buf_dynamic_attach()
- dma_buf_detach()
- dma_buf_export(
- dma_buf_fd()
- dma_buf_get()
- dma_buf_put()
- dma_buf_mmap()
- dma_buf_begin_cpu_access()
- dma_buf_end_cpu_access()
- dma_buf_map_attachment_unlocked()
- dma_buf_unmap_attachment_unlocked()
- dma_buf_vmap_unlocked()
- dma_buf_vunmap_unlocked()
- Convention for exporters
- These &dma_buf_ops callbacks are invoked with unlocked dma-buf
- reservation and exporter can take the lock:
- &dma_buf_ops.attach()
- &dma_buf_ops.detach()
- &dma_buf_ops.release()
- &dma_buf_ops.begin_cpu_access()
- &dma_buf_ops.end_cpu_access()
- These &dma_buf_ops callbacks are invoked with locked dma-buf
- reservation and exporter can't take the lock:
- &dma_buf_ops.pin()
- &dma_buf_ops.unpin()
- &dma_buf_ops.map_dma_buf()
- &dma_buf_ops.unmap_dma_buf()
- &dma_buf_ops.mmap()
- &dma_buf_ops.vmap()
- &dma_buf_ops.vunmap()
- Exporters must hold the dma-buf reservation lock when calling these
- functions:
- dma_buf_move_notify()- */
- /**
- dma_buf_dynamic_attach - Add the device to dma_buf's attachments list
- @dmabuf: [in] buffer to attach device to.