[Intel-gfx] [PATCH v3 3/5] i915: add documentation for a bit on batchbuffer submission backend

[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/intel_ringbuffer.h | 38 +++++++++++++++++++++++++++++++++
 1 file changed, 38 insertions(+)

diff --git a/drivers/gpu/drm/i915/intel_ringbuffer.h b/drivers/gpu/drm/i915/intel_ringbuffer.h
index 62d3a22..2f8908e 100644
--- a/drivers/gpu/drm/i915/intel_ringbuffer.h
+++ b/drivers/gpu/drm/i915/intel_ringbuffer.h
@@ -350,6 +350,44 @@ struct intel_engine_execlists {
  *    the ringbuffer.
  */
 
+/**
+ * DOC: Batchbuffer Submission Backend
+ *
+ * The core logic of submitting a batchbuffer for the GPU to execute
+ * is shared across all engines for all GPU generations. Through the use
+ * of functions pointers, we can customize submission to different GPU
+ * capabilities. The struct ``intel_engine_cs`` has the following member
+ * function pointers for the following purposes in the scope of batchbuffer
+ * submission.
+ *
+ * - context_pin
+ *     pins the context and also returns to what ``intel_ringbuffer``
+ *     to write to submit a batchbuffer.
+ *
+ * - request_alloc
+ *     is used to reserve space in an ``intel_ringbuffer``
+ *     for submitting a batchbuffer to the GPU.
+ *
+ * - emit_flush
+ *     writes a pipeline flush command and/or invalidate caches
+ *     command to the ring buffer.
+ *
+ * - emit_bb_start
+ *     writes the batchbuffer start command to the ringer buffer.
+ *
+ * - emit_breadcrumb
+ *     writes to the ring buffer both the regiser write of the
+ *     request ID (`i915_request::global_seqno`) and the command to
+ *     issue an interrupt.
+ *
+ * - submit_request
+ *     See the comment on this member in ``intel_engine_cs``, declared
+ *     in intel_ringbuffer.h.
+ *
+ * In addition, the struct i915_request is used to track requests'
+ * dependency tree.
+ */
+
 struct intel_engine_cs {
 	struct drm_i915_private *i915;
 	char name[INTEL_ENGINE_CS_MAX_NAME];
-- 
2.7.4