[Intel-gfx] [PATCH v3 2/5] i915: add documentation of what happens at the bottom of submitting a batchbuffer

[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 | 33 +++++++++++++++++++++++++++++++++
 1 file changed, 33 insertions(+)

diff --git a/drivers/gpu/drm/i915/intel_ringbuffer.h b/drivers/gpu/drm/i915/intel_ringbuffer.h
index 1f50727..62d3a22 100644
--- a/drivers/gpu/drm/i915/intel_ringbuffer.h
+++ b/drivers/gpu/drm/i915/intel_ringbuffer.h
@@ -317,6 +317,39 @@ struct intel_engine_execlists {
 
 #define INTEL_ENGINE_CS_MAX_NAME 8
 
+/**
+ * DOC: Ringbuffers to submit batchbuffers
+ *
+ * At the lowest level, submitting work to a GPU engine is to add commands to
+ * a ringbuffer. A ringbuffer in the kernel driver is essentially a location
+ * from which the GPU reads its next command. To avoid copying the contents
+ * of a batchbuffer in order to submit it, the GPU has native hardware support
+ * to perform commands specified in another buffer; the command to do so is
+ * a batchbuffer start and the i915 kernel driver uses this to avoid copying
+ * batchbuffers to the ringbuffer. At the very bottom of the stack, the i915
+ * does the following to submit a batchbuffer to the GPU.
+ *
+ * 1. Add a command to invalidate caches to the ringbuffer
+ *
+ * 2. Add a batchbuffer start command to the ringbuffer. The start command is
+ *    essentially a token together with the GPU address of the batchbuffer to
+ *    be executed.
+ *
+ * 3. Add a pipeline flush to the the ringbuffer.
+ *
+ * 4. Add a register write command to the ring buffer.  This register write
+ *    writes the the request ID, ``i915_request::global_seqno``; the i915
+ *    kernel driver uses the value in the register to know what requests are
+ *    completed.
+ *
+ * 5. Add a user interrupt command to the ringbuffer. This command instructs
+ *    the GPU to issue an interrupt when the command (and pipeline flush) are
+ *    completed.
+ *
+ * 6. Inform the hardware of the additional commands added to
+ *    the ringbuffer.
+ */
+
 struct intel_engine_cs {
 	struct drm_i915_private *i915;
 	char name[INTEL_ENGINE_CS_MAX_NAME];
-- 
2.7.4