[v4,19/21] dma-buf: Document dynamic locking convention

Commit Message

Dmitry Osipenko Aug. 31, 2022, 3:37 p.m. UTC

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 <[e-mail]>
---
 Documentation/driver-api/dma-buf.rst |  6 +++
 drivers/dma-buf/dma-buf.c            | 64 ++++++++++++++++++++++++++++
 2 files changed, 70 insertions(+)

Comments

Christian König Sept. 1, 2022, 7:16 a.m. UTC | #1

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 <[e-mail]>

Reviewed-by: Christian König <[e-mail]>

> ---
>   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
> + *
> + * 1. 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()
> + *
> + * 2. 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
> + *
> + * 1. 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()
> + *
> + * 2. 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()
> + *
> + * 3. 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.

Patch

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
+ *
+ * 1. 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()
+ *
+ * 2. 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
+ *
+ * 1. 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()
+ *
+ * 2. 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()
+ *
+ * 3. 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.