Dma-buf's vmap and vunmap callbacks are undocumented and various
exporters currently have slightly different semantics for them. Add
documentation on how to implement and use these interfaces correctly.
v2:
* document vmap semantics in struct dma_buf_ops
* add TODO item for reviewing and maybe fixing dma-buf exporters
Signed-off-by: Thomas Zimmermann <tzimmermann@xxxxxxx>
---
Documentation/gpu/todo.rst | 15 +++++++++++++
include/drm/drm_gem.h | 4 ++++
include/linux/dma-buf.h | 45 ++++++++++++++++++++++++++++++++++++++
3 files changed, 64 insertions(+)
diff --git a/Documentation/gpu/todo.rst b/Documentation/gpu/todo.rst
index 009d8e6c7e3c..32bb797a84fc 100644
--- a/Documentation/gpu/todo.rst
+++ b/Documentation/gpu/todo.rst
@@ -505,6 +505,21 @@ Contact: Thomas Zimmermann <tzimmermann@xxxxxxx>, Christian König, Daniel Vette
Level: Intermediate
+Enforce rules for dma-buf vmap and pin ops
+------------------------------------------
+
+Exporter implementations of vmap and pin in struct dma_buf_ops (and consequently
+struct drm_gem_object_funcs) use a variety of locking semantics. Some rely on
+the caller holding the dma-buf's reservation lock, some do their own locking,
+some don't require any locking. VRAM helpers even used to pin as part of vmap.
+
+We need to review each exporter and enforce the documented rules.
+
+Contact: Christian König, Daniel Vetter, Thomas Zimmermann <tzimmermann@xxxxxxx>
+
+Level: Advanced
+
+
Core refactorings
=================
diff --git a/include/drm/drm_gem.h b/include/drm/drm_gem.h
index 5e6daa1c982f..1864c6a721b1 100644
--- a/include/drm/drm_gem.h
+++ b/include/drm/drm_gem.h
@@ -138,6 +138,8 @@ struct drm_gem_object_funcs {
* drm_gem_dmabuf_vmap() helper.
*
* This callback is optional.
+ *
+ * See also struct dma_buf_ops.vmap
*/
int (*vmap)(struct drm_gem_object *obj, struct dma_buf_map *map);
@@ -148,6 +150,8 @@ struct drm_gem_object_funcs {
* drm_gem_dmabuf_vunmap() helper.
*
* This callback is optional.
+ *
+ * See also struct dma_buf_ops.vunmap
*/
void (*vunmap)(struct drm_gem_object *obj, struct dma_buf_map *map);
diff --git a/include/linux/dma-buf.h b/include/linux/dma-buf.h
index cf72699cb2bc..dc81fdc01dda 100644
--- a/include/linux/dma-buf.h
+++ b/include/linux/dma-buf.h
@@ -267,7 +267,52 @@ struct dma_buf_ops {
*/
int (*mmap)(struct dma_buf *, struct vm_area_struct *vma);
+ /**
+ * @vmap:
+ *
+ * Returns a virtual address for the buffer.
+ *
+ * Notes to callers:
+ *
+ * - Callers must hold the struct dma_buf.resv lock before calling
+ * this interface.
+ *
+ * - Callers must provide means to prevent the mappings from going
+ * stale, such as holding the reservation lock or providing a
+ * move-notify callback to the exporter.
+ *
+ * Notes to implementors:
+ *
+ * - Implementations must expect pairs of @vmap and @vunmap to be
+ * called frequently and should optimize for this case.
+ *
+ * - Implementations should avoid additional operations, such as
+ * pinning.
+ *
+ * - Implementations may expect the caller to hold the dma-buf's
+ * reservation lock to protect against concurrent calls and
+ * relocation.
+ *
+ * - Implementations may provide additional guarantees, such as working
+ * without holding the reservation lock.
+ *
+ * This callback is optional.
+ *
+ * Returns:
+ *
+ * 0 on success or a negative error code on failure.
+ */
int (*vmap)(struct dma_buf *dmabuf, struct dma_buf_map *map);
+
+ /**
+ * @vunmap:
+ *
+ * Releases the address previously returned by @vmap.
+ *
+ * This callback is optional.
+ *
+ * See also @vmap()
+ */
void (*vunmap)(struct dma_buf *dmabuf, struct dma_buf_map *map);
};
--
2.29.2
