Commit ae2e7f28 authored by Dmitry Osipenko's avatar Dmitry Osipenko
Browse files

dma-buf: Document dynamic locking convention 



Add documentation for the dynamic locking convention. The documentation
tells dma-buf API users when they should take the reservation lock and
when not.

Acked-by: default avatarSumit Semwal <sumit.semwal@linaro.org>
Reviewed-by: default avatarChristian König <christian.koenig@amd.com>
Signed-off-by: default avatarDmitry Osipenko <dmitry.osipenko@collabora.com>
Link: https://patchwork.freedesktop.org/patch/msgid/20221017172229.42269-20-dmitry.osipenko@collabora.com
parent d078fd9b

Documentation/driver-api/dma-buf.rst

+6 −0
Original line number Diff line number Diff line
@@ -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

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

drivers/dma-buf/dma-buf.c

+64 −0
Original line number Diff line number Diff line
@@ -795,6 +795,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.