@@ -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];