Patchwork [v2] drm/fences: add DOC: for explicit fencing

login
register
mail settings
Submitter Gustavo F. Padovan
Date Nov. 22, 2016, 12:11 a.m.
Message ID <1479773488-15048-1-git-send-email-gustavo@padovan.org>
Download mbox | patch
Permalink /patch/9440299/
State New
Headers show

Comments

Gustavo F. Padovan - Nov. 22, 2016, 12:11 a.m.
From: Gustavo Padovan <gustavo.padovan@collabora.co.uk>

Document IN_FENCE_FD and OUT_FENCE_PTR properties.

v2: incorporate comments from Daniel Vetter

Signed-off-by: Gustavo Padovan <gustavo.padovan@collabora.co.uk>
---
 Documentation/gpu/drm-kms.rst |  6 +++++
 drivers/gpu/drm/drm_atomic.c  | 52 +++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 58 insertions(+)
Daniel Vetter - Nov. 22, 2016, 7:07 a.m.
On Tue, Nov 22, 2016 at 09:11:28AM +0900, Gustavo Padovan wrote:
> From: Gustavo Padovan <gustavo.padovan@collabora.co.uk>
> 
> Document IN_FENCE_FD and OUT_FENCE_PTR properties.
> 
> v2: incorporate comments from Daniel Vetter
> 
> Signed-off-by: Gustavo Padovan <gustavo.padovan@collabora.co.uk>
> ---
>  Documentation/gpu/drm-kms.rst |  6 +++++
>  drivers/gpu/drm/drm_atomic.c  | 52 +++++++++++++++++++++++++++++++++++++++++++
>  2 files changed, 58 insertions(+)
> 
> diff --git a/Documentation/gpu/drm-kms.rst b/Documentation/gpu/drm-kms.rst
> index 568f3c2..cdc9539 100644
> --- a/Documentation/gpu/drm-kms.rst
> +++ b/Documentation/gpu/drm-kms.rst
> @@ -287,6 +287,12 @@ Tile Group Property
>  .. kernel-doc:: drivers/gpu/drm/drm_connector.c
>     :doc: Tile group
>  
> +Explicit Fencing Properties
> +---------------------------
> +
> +.. kernel-doc:: drivers/gpu/drm/drm_atomic.c
> +   :doc: explicit fencing properties
> +
>  Existing KMS Properties
>  -----------------------
>  
> diff --git a/drivers/gpu/drm/drm_atomic.c b/drivers/gpu/drm/drm_atomic.c
> index b476ec5..f548e68 100644
> --- a/drivers/gpu/drm/drm_atomic.c
> +++ b/drivers/gpu/drm/drm_atomic.c
> @@ -1809,6 +1809,58 @@ void drm_atomic_clean_old_fb(struct drm_device *dev,
>  }
>  EXPORT_SYMBOL(drm_atomic_clean_old_fb);
>  
> +/**
> + * DOC: explicit fencing properties
> + *
> + * Explicit fencing allows userspace to control the buffer synchronization
> + * between devices. A Fence or a group of fences are transfered to/from
> + * userspace using Sync File fds and there are two DRM properties for that.
> + * IN_FENCE_FD on each DRM Plane to send fences to the kernel and
> + * OUT_FENCE_PTR on each DRM CRTC to receive fences from the kernel.
> + *
> + * As a contrast, with implicit fencing the kernel keeps track of any
> + * ongoing rendering, and automatically ensures that the atomic update waits
> + * for any pending rendering to complete. For shared buffers represented with
> + * a struct &dma_buf this is tracked in &reservation_object structures.
> + * Implicit syncing is how Linux traditionally worked (e.g. DRI2/3 on X.org),
> + * whereas explicit fencing is what Android wants.
> + *
> + * "IN_FENCE_FD”:
> + *	Use this property to pass a fence that DRM should wait on before
> + *	proceeding with the Atomic Commit request and show the framebuffer for
> + *	the plane on the screen. The fence can be either a normal fence or a
> + *	merged one, the sync_file framework will handle both cases and use a
> + *	fence_array if a merged fence is received. Passing -1 here means no
> + *	fences to wait on.
> + *
> + *	If the Atomic Commit request has the DRM_MODE_ATOMIC_TEST_ONLY flag
> + *	it will only check if the Sync File is a valid one.
> + *
> + *	On the driver side the fence is stored on the @fence parameter of
> + *	struct &drm_plane_state. Drivers which also support implicit fencing
> + *	should set the implicit fence using drm_atomic_set_fence_for_plane(),
> + *	to make sure there's consistent behaviour between drivers in precedence
> + *	of implicit vs. explicit fencing.
> + *
> + * "OUT_FENCE_PTR”:
> + *	Use this property to pass a file descriptor pointer to DRM. Once the
> + *	Atomic Commit request call returns OUT_FENCE_PTR will be filled with
> + *	the file descriptor number of a Sync File. This Sync File contains the
> + *	CRTC fence that will be signaled when all framebuffers present on the
> + *	Atomic Commit * request for that given CRTC are scanned out on the
> + *	screen.
> + *
> + *	The Atomic Commit request fails if a invalid pointer is passed. If the
> + *	Atomic Commit request fails for any other reason the out fence fd
> + *	returned will be -1. On a Atomic Commit with the
> + *	DRM_MODE_ATOMIC_TEST_ONLY flag the out fence will also be set to -1.
> + *
> + *	Note that out-fences don't have a special interface to drivers and are
> + *	internally represented by a struct &drm_pending_vblank_event in struct
> + *	&drm_crtc_state, which is also used by the async atomic commit helpers

I've done an s/async/nonblocking/ here for consistency, since async commit
== tearing commit (but it might still block), and applied the patch to
drm-misc.

Thanks a lot for typing this!
-Daniel

> + *	and for the DRM event handling for existing userspace.
> + */
> +
>  static struct dma_fence *get_crtc_fence(struct drm_crtc *crtc)
>  {
>  	struct dma_fence *fence;
> -- 
> 2.5.5
> 
> _______________________________________________
> dri-devel mailing list
> dri-devel@lists.freedesktop.org
> https://lists.freedesktop.org/mailman/listinfo/dri-devel

Patch

diff --git a/Documentation/gpu/drm-kms.rst b/Documentation/gpu/drm-kms.rst
index 568f3c2..cdc9539 100644
--- a/Documentation/gpu/drm-kms.rst
+++ b/Documentation/gpu/drm-kms.rst
@@ -287,6 +287,12 @@  Tile Group Property
 .. kernel-doc:: drivers/gpu/drm/drm_connector.c
    :doc: Tile group
 
+Explicit Fencing Properties
+---------------------------
+
+.. kernel-doc:: drivers/gpu/drm/drm_atomic.c
+   :doc: explicit fencing properties
+
 Existing KMS Properties
 -----------------------
 
diff --git a/drivers/gpu/drm/drm_atomic.c b/drivers/gpu/drm/drm_atomic.c
index b476ec5..f548e68 100644
--- a/drivers/gpu/drm/drm_atomic.c
+++ b/drivers/gpu/drm/drm_atomic.c
@@ -1809,6 +1809,58 @@  void drm_atomic_clean_old_fb(struct drm_device *dev,
 }
 EXPORT_SYMBOL(drm_atomic_clean_old_fb);
 
+/**
+ * DOC: explicit fencing properties
+ *
+ * Explicit fencing allows userspace to control the buffer synchronization
+ * between devices. A Fence or a group of fences are transfered to/from
+ * userspace using Sync File fds and there are two DRM properties for that.
+ * IN_FENCE_FD on each DRM Plane to send fences to the kernel and
+ * OUT_FENCE_PTR on each DRM CRTC to receive fences from the kernel.
+ *
+ * As a contrast, with implicit fencing the kernel keeps track of any
+ * ongoing rendering, and automatically ensures that the atomic update waits
+ * for any pending rendering to complete. For shared buffers represented with
+ * a struct &dma_buf this is tracked in &reservation_object structures.
+ * Implicit syncing is how Linux traditionally worked (e.g. DRI2/3 on X.org),
+ * whereas explicit fencing is what Android wants.
+ *
+ * "IN_FENCE_FD”:
+ *	Use this property to pass a fence that DRM should wait on before
+ *	proceeding with the Atomic Commit request and show the framebuffer for
+ *	the plane on the screen. The fence can be either a normal fence or a
+ *	merged one, the sync_file framework will handle both cases and use a
+ *	fence_array if a merged fence is received. Passing -1 here means no
+ *	fences to wait on.
+ *
+ *	If the Atomic Commit request has the DRM_MODE_ATOMIC_TEST_ONLY flag
+ *	it will only check if the Sync File is a valid one.
+ *
+ *	On the driver side the fence is stored on the @fence parameter of
+ *	struct &drm_plane_state. Drivers which also support implicit fencing
+ *	should set the implicit fence using drm_atomic_set_fence_for_plane(),
+ *	to make sure there's consistent behaviour between drivers in precedence
+ *	of implicit vs. explicit fencing.
+ *
+ * "OUT_FENCE_PTR”:
+ *	Use this property to pass a file descriptor pointer to DRM. Once the
+ *	Atomic Commit request call returns OUT_FENCE_PTR will be filled with
+ *	the file descriptor number of a Sync File. This Sync File contains the
+ *	CRTC fence that will be signaled when all framebuffers present on the
+ *	Atomic Commit * request for that given CRTC are scanned out on the
+ *	screen.
+ *
+ *	The Atomic Commit request fails if a invalid pointer is passed. If the
+ *	Atomic Commit request fails for any other reason the out fence fd
+ *	returned will be -1. On a Atomic Commit with the
+ *	DRM_MODE_ATOMIC_TEST_ONLY flag the out fence will also be set to -1.
+ *
+ *	Note that out-fences don't have a special interface to drivers and are
+ *	internally represented by a struct &drm_pending_vblank_event in struct
+ *	&drm_crtc_state, which is also used by the async atomic commit helpers
+ *	and for the DRM event handling for existing userspace.
+ */
+
 static struct dma_fence *get_crtc_fence(struct drm_crtc *crtc)
 {
 	struct dma_fence *fence;