[Intel-gfx] [PATCH v3 4/5] i915: add doc for synchronization

[kevin.rogovin at intel.com]

From: Kevin Rogovin <kevin.rogovin at intel.com>

Signed-off-by: Kevin Rogovin <kevin.rogovin at intel.com>
---
 drivers/gpu/drm/i915/i915_request.h | 28 ++++++++++++++++++++++++++++
 1 file changed, 28 insertions(+)

diff --git a/drivers/gpu/drm/i915/i915_request.h b/drivers/gpu/drm/i915/i915_request.h
index 7d6eb82..093b9d7 100644
--- a/drivers/gpu/drm/i915/i915_request.h
+++ b/drivers/gpu/drm/i915/i915_request.h
@@ -57,6 +57,34 @@ struct i915_dependency {
 #define I915_DEPENDENCY_ALLOC BIT(0)
 };
 
+/**
+ * DOC: Synchronization
+ *
+ * The i915 kernel driver needs to also synchronize the ordering in which
+ * to submit batchbuffers in following cases.
+ *
+ * 1. When a fixed file descriptor is used to submit work to different
+ *    engines of the GPU; the issue is that the different engines run
+ *    independently to each other but the kernel interface guarantees
+ *    that the memory writes of previously issued commands within a
+ *    fixed file descriptor will be seen by the next command.
+ *
+ * 2. When an ioctl to submit a batchbuffer has an in-fence that represents
+ *    an action that needs to be completed or submitted before before the
+ *    given command is submitted.
+ *
+ * Rather than waiting, the i915 kernel driver builds a data structure tree
+ * (represented by ``i915_priotree``) to store dependencies of different
+ * batchbuffer execute requests, the requests themselves are tracked via
+ * ``i915_request`` structs. The critical point that action of processing
+ * a user request does NOT wait for the dependencies to finish or even be
+ * submitted to the GPU. Instead, an ``i915_request`` structure is created
+ * and it is added to the dependency tree; when its dependencies are
+ * satisfied, then the call back updates the tail pointer of the ring buffer
+ * where the command was placed. This way, execute batchbuffer requests
+ * return from the kernel almost immediately.
+ */
+
 /*
  * "People assume that time is a strict progression of cause to effect, but
  * actually, from a nonlinear, non-subjective viewpoint, it's more like a big
-- 
2.7.4