[PATCH v1] drm/prime: Clarify DMA-BUF/GEM Object lifetime

[Daniel Vetter]

On Fri, Jan 27, 2017 at 09:04:25AM +0200, Oleksandr Andrushchenko wrote:
> From: Oleksandr Andrushchenko <oleksandr_andrushchenko at epam.com>
> 
> From the description of the "DMA-BUF/GEM Object references
> and lifetime overview" it is not clear when exactly
> dma_buf gets destroyed and memory freed: only driver
> .release function mentioned which makes confusion on the
> real buffer's lifetime.
> 
> Add more description so all the paths are covered.
> 
> Cc: Rob Clark <robdclark at gmail.com>
> Cc: Dave Airlie <airlied at linux.ie>
> Cc: Daniel Vetter <daniel.vetter at ffwll.ch>
> Signed-off-by: Oleksandr Andrushchenko <oleksandr_andrushchenko at epam.com>
> ---
>  drivers/gpu/drm/drm_prime.c | 16 ++++++++++++++--
>  1 file changed, 14 insertions(+), 2 deletions(-)
> 
> diff --git a/drivers/gpu/drm/drm_prime.c b/drivers/gpu/drm/drm_prime.c
> index 8d77b2462594..893a1a6311f0 100644
> --- a/drivers/gpu/drm/drm_prime.c
> +++ b/drivers/gpu/drm/drm_prime.c
> @@ -40,8 +40,11 @@
>   * On the export the dma_buf holds a reference to the exporting GEM
>   * object. It takes this reference in handle_to_fd_ioctl, when it
>   * first calls .prime_export and stores the exporting GEM object in
> - * the dma_buf priv. This reference is released when the dma_buf
> - * object goes away in the driver .release function.
> + * the dma_buf priv. This refernce needs to be released when the

s/refernce/reference/

> + * final reference to the &dma_buf itself is dropped and its
> + * &dma_buf_ops.release function is called. For GEM-based drivers,
> + * the dma_buf should be exported using drm_gem_dmabuf_export() and
> + * then released by drm_gem_dmabuf_release().
>   *
>   * On the import the importing GEM object holds a reference to the
>   * dma_buf (which in turn holds a ref to the exporting GEM object).
> @@ -51,6 +54,15 @@
>   * when the imported object is destroyed, we remove the attachment
>   * and drop the reference to the dma_buf.
>   *
> + * When all the references to the dma_buf are dropped, e.g. when
> + * userspace closes both handles to the imported (fd_to_handle_ioctl)
> + * and exported (handle_to_fd_ioctl) dma_buf and closes the corresponding

Usualla we call ioctls with uppercase, e.g. HANDLE_TO_FD IOCTL.

> + * file descriptor (handle_to_fd), then dma_buf gets destroyed.
> + * This can also happen as a part of the clean up procedure in the
> + * driver .release function if userspace fails to properly clean up.

Extended the references here to full file_ops one.

Since this is all tiny, I've done this while applying, thanks a lot for
your patch.
-Daniel

> + * Note that both the kernel and userspace (by keeeping the PRIME file
> + * descriptors open) can hold references onto a &dma_buf.
> + *
>   * Thus the chain of references always flows in one direction
>   * (avoiding loops): importing_gem -> dmabuf -> exporting_gem
>   *
> -- 
> 2.7.4
> 

-- 
Daniel Vetter
Software Engineer, Intel Corporation
http://blog.ffwll.ch