[3/3] drm/i915: kerneldoc for fences
diff mbox

Message ID 1437738912-15971-3-git-send-email-daniel.vetter@ffwll.ch
State New
Headers show

Commit Message

Daniel Vetter July 24, 2015, 11:55 a.m. UTC
Signed-off-by: Daniel Vetter <daniel.vetter@intel.com>
---
 Documentation/DocBook/drm.tmpl        |  5 +++
 drivers/gpu/drm/i915/i915_gem_fence.c | 75 +++++++++++++++++++++++++++++++++++
 2 files changed, 80 insertions(+)

Comments

Chris Wilson July 24, 2015, 12:02 p.m. UTC | #1
On Fri, Jul 24, 2015 at 01:55:12PM +0200, Daniel Vetter wrote:
> Signed-off-by: Daniel Vetter <daniel.vetter@intel.com>
> ---
>  Documentation/DocBook/drm.tmpl        |  5 +++
>  drivers/gpu/drm/i915/i915_gem_fence.c | 75 +++++++++++++++++++++++++++++++++++
>  2 files changed, 80 insertions(+)
> 
> diff --git a/Documentation/DocBook/drm.tmpl b/Documentation/DocBook/drm.tmpl
> index 458772e6ce08..86c9c453b218 100644
> --- a/Documentation/DocBook/drm.tmpl
> +++ b/Documentation/DocBook/drm.tmpl
> @@ -4137,6 +4137,11 @@ int num_ioctls;</synopsis>
>  !Idrivers/gpu/drm/i915/i915_gem_gtt.c
>        </sect2>
>        <sect2>
> +        <title>Global GTT Fence Handling</title>
> +!Pdrivers/gpu/drm/i915/i915_gem_fence.c fence handling
> +!Idrivers/gpu/drm/i915/i915_gem_fence.c
> +      </sect2>
> +      <sect2>
>          <title>Buffer Object Eviction</title>
>  	<para>
>  	  This section documents the interface functions for evicting buffer
> diff --git a/drivers/gpu/drm/i915/i915_gem_fence.c b/drivers/gpu/drm/i915/i915_gem_fence.c
> index d3284ee04794..63d8d0d8a9cb 100644
> --- a/drivers/gpu/drm/i915/i915_gem_fence.c
> +++ b/drivers/gpu/drm/i915/i915_gem_fence.c
> @@ -25,6 +25,36 @@
>  #include <drm/i915_drm.h>
>  #include "i915_drv.h"
>  
> +/**
> + * DOC: fence handling

DOC: fence register handling

Might as well aim not to be ambiguous when you start out by pointing out
the confusion between the GTT detiling registers and dma-fence.

> + *
> + * Important to avoid confusions: "fences" in the i915 driver are not execution
> + * fences used to track command completion but hardware detiler objects which
> + * wrap a given range of the global GTT. Each platform has only a fairly limited
> + * set of these objects.

Hmm, good point. Maybe i915_gem_tiling was the better name after all!
Otoh, i915_gem_fence is better as it prevents us from wondering whether
this is suitable for Yf etc.

We really should emphasize that again in the set-tiling documentation -
that is not about declaring the tiling for the buffer per-se, but about
fence allocation.

> + *
> + * Fences are used to detile GTT memory mappings. They're also connected to the
> + * hardware frontbuffer render tracking and hence interract with frontbuffer
> + * conmpression. Furthermore on older platforms fences are required for tiled
> + * objects used by the display engine. They can also be used by the render
> + * engine - they're required for blitter commands and are optional for render
> + * commands. But on gen4+ both display (with the exception of fbc) and rendering
> + * have their own tiling state bits and don't need fences.
> + *
> + * Also note that fences only support X and Y tiling and hence can't be used for
> + * the fancier new tiling formats like W, Ys and Yf.
> + *
> + * Finally note that because fences are such a restricted resource they're
> + * dynamically associated with objects. Furthermore fence state is committed to
> + * the hardware lazily to avoid unecessary stalls on gen2/3. Therefore code must
> + * explictly call i915_gem_object_get_fence() to synchronize fencing status
> + * for cpu access. Also note that some code wants an unfenced view, for those
> + * cases the fence can be removed forcefully with i915_gem_object_put_fence().
> + *
> + * Internally these functions will synchronize with userspace access by removing
> + * ptes as needed.

Revoking CPU ptes into GTT mmaps.

Important when discussing PTEs to be clear when we don't mean the GTT
PTEs (which I think is the default for the driver).
-Chris
Shuang He July 24, 2015, 5:07 p.m. UTC | #2
Tested-By: Intel Graphics QA PRTS (Patch Regression Test System Contact: shuang.he@intel.com)
Task id: 6855
-------------------------------------Summary-------------------------------------
Platform          Delta          drm-intel-nightly          Series Applied
ILK                                  295/295              295/295
SNB                                  315/315              315/315
IVB                                  342/342              342/342
BYT                 -2              285/285              283/285
HSW                                  378/378              378/378
-------------------------------------Detailed-------------------------------------
Platform  Test                                drm-intel-nightly          Series Applied
*BYT  igt@gem_partial_pwrite_pread@reads      PASS(1)      FAIL(1)
*BYT  igt@gem_partial_pwrite_pread@reads-display      PASS(1)      FAIL(1)
Note: You need to pay more attention to line start with '*'

Patch
diff mbox

diff --git a/Documentation/DocBook/drm.tmpl b/Documentation/DocBook/drm.tmpl
index 458772e6ce08..86c9c453b218 100644
--- a/Documentation/DocBook/drm.tmpl
+++ b/Documentation/DocBook/drm.tmpl
@@ -4137,6 +4137,11 @@  int num_ioctls;</synopsis>
 !Idrivers/gpu/drm/i915/i915_gem_gtt.c
       </sect2>
       <sect2>
+        <title>Global GTT Fence Handling</title>
+!Pdrivers/gpu/drm/i915/i915_gem_fence.c fence handling
+!Idrivers/gpu/drm/i915/i915_gem_fence.c
+      </sect2>
+      <sect2>
         <title>Buffer Object Eviction</title>
 	<para>
 	  This section documents the interface functions for evicting buffer
diff --git a/drivers/gpu/drm/i915/i915_gem_fence.c b/drivers/gpu/drm/i915/i915_gem_fence.c
index d3284ee04794..63d8d0d8a9cb 100644
--- a/drivers/gpu/drm/i915/i915_gem_fence.c
+++ b/drivers/gpu/drm/i915/i915_gem_fence.c
@@ -25,6 +25,36 @@ 
 #include <drm/i915_drm.h>
 #include "i915_drv.h"
 
+/**
+ * DOC: fence handling
+ *
+ * Important to avoid confusions: "fences" in the i915 driver are not execution
+ * fences used to track command completion but hardware detiler objects which
+ * wrap a given range of the global GTT. Each platform has only a fairly limited
+ * set of these objects.
+ *
+ * Fences are used to detile GTT memory mappings. They're also connected to the
+ * hardware frontbuffer render tracking and hence interract with frontbuffer
+ * conmpression. Furthermore on older platforms fences are required for tiled
+ * objects used by the display engine. They can also be used by the render
+ * engine - they're required for blitter commands and are optional for render
+ * commands. But on gen4+ both display (with the exception of fbc) and rendering
+ * have their own tiling state bits and don't need fences.
+ *
+ * Also note that fences only support X and Y tiling and hence can't be used for
+ * the fancier new tiling formats like W, Ys and Yf.
+ *
+ * Finally note that because fences are such a restricted resource they're
+ * dynamically associated with objects. Furthermore fence state is committed to
+ * the hardware lazily to avoid unecessary stalls on gen2/3. Therefore code must
+ * explictly call i915_gem_object_get_fence() to synchronize fencing status
+ * for cpu access. Also note that some code wants an unfenced view, for those
+ * cases the fence can be removed forcefully with i915_gem_object_put_fence().
+ *
+ * Internally these functions will synchronize with userspace access by removing
+ * ptes as needed.
+ */
+
 static void i965_write_fence_reg(struct drm_device *dev, int reg,
 				 struct drm_i915_gem_object *obj)
 {
@@ -247,6 +277,17 @@  i915_gem_object_wait_fence(struct drm_i915_gem_object *obj)
 	return 0;
 }
 
+/**
+ * i915_gem_object_put_fence - force-remove fence for an object
+ * @obj: object to map through a fence reg
+ *
+ * This function force-removes any fence from the given object, which is useful
+ * if the kernel wants to do untiled GTT access.
+ *
+ * Returns:
+ *
+ * 0 on success, negative error code on failure.
+ */
 int
 i915_gem_object_put_fence(struct drm_i915_gem_object *obj)
 {
@@ -322,6 +363,10 @@  deadlock:
  * and tiling format.
  *
  * For an untiled surface, this removes any existing fence.
+ *
+ * Returns:
+ *
+ * 0 on success, negative error code on failure.
  */
 int
 i915_gem_object_get_fence(struct drm_i915_gem_object *obj)
@@ -374,6 +419,21 @@  i915_gem_object_get_fence(struct drm_i915_gem_object *obj)
 	return 0;
 }
 
+/**
+ * i915_gem_object_pin_fence - pin fencing state
+ * @obj: object to pin fencing for
+ *
+ * This pins the fencing state (whether tiled or untiled) to make sure the
+ * object is ready to be used as a scanout target. Fencing status must be
+ * synchronize first by calling i915_gem_object_get_fence():
+ *
+ * The resulting fence pin reference must be released again with
+ * i915_gem_object_unpin_fence().
+ *
+ * Returns:
+ *
+ * True if the object has a fence, false otherwise.
+ */
 bool
 i915_gem_object_pin_fence(struct drm_i915_gem_object *obj)
 {
@@ -390,6 +450,14 @@  i915_gem_object_pin_fence(struct drm_i915_gem_object *obj)
 		return false;
 }
 
+/**
+ * i915_gem_object_unpin_fence - unpin fencing state
+ * @obj: object to unpin fencing for
+ *
+ * This releases the fence pin reference acquired through
+ * i915_gem_object_pin_fence. It will handle both objects with and without an
+ * attached fence correctly, callers do not need to distinguish this.
+ */
 void
 i915_gem_object_unpin_fence(struct drm_i915_gem_object *obj)
 {
@@ -400,6 +468,13 @@  i915_gem_object_unpin_fence(struct drm_i915_gem_object *obj)
 	}
 }
 
+/**
+ * i915_gem_restore_fences - restore fence state
+ * @dev: DRM device
+ *
+ * Restore the hw fence state to match the software tracking again, to be called
+ * after a gpu reset and on resume.
+ */
 void i915_gem_restore_fences(struct drm_device *dev)
 {
 	struct drm_i915_private *dev_priv = dev->dev_private;