From 6a5ece12aac0f079dff3aaf00b2ec5c420b9b1f8 Mon Sep 17 00:00:00 2001
From: Eric Anholt <eric@anholt.net>
Date: Mon, 21 Jul 2014 11:26:24 -0700
Subject: [PATCH] vc4: Add docs for the drm interface

---
 src/gallium/drivers/vc4/vc4_drm.h | 70 +++++++++++++++++++++++++++----
 1 file changed, 61 insertions(+), 9 deletions(-)

diff --git a/src/gallium/drivers/vc4/vc4_drm.h b/src/gallium/drivers/vc4/vc4_drm.h
index 430d7cc1314..b958f1d03d0 100644
--- a/src/gallium/drivers/vc4/vc4_drm.h
+++ b/src/gallium/drivers/vc4/vc4_drm.h
@@ -30,16 +30,68 @@
 
 #define DRM_IOCTL_VC4_SUBMIT_CL           DRM_IOWR( DRM_COMMAND_BASE + DRM_VC4_SUBMIT_CL, struct drm_vc4_submit_cl)
 
+/**
+ * struct drm_vc4_submit_cl - ioctl argument for submitting commands to the 3D
+ * engine.
+ *
+ * Drivers typically use GPU BOs to store batchbuffers / command lists and
+ * their associated state.  However, because the VC4 lacks an MMU, we have to
+ * do validation of memory accesses by the GPU commands.  If we were to store
+ * our commands in BOs, we'd need to do uncached readback from them to do the
+ * validation process, which is too expensive.  Instead, userspace accumulates
+ * commands and associated state in plain memory, then the kernel copies the
+ * data to its own address space, and then validates and stores it in a GPU
+ * BO.
+ */
 struct drm_vc4_submit_cl {
-        void __user *bin_cl;
-        void __user *render_cl;
-        void __user *shader_records;
-        void __user *bo_handles;
-        uint32_t bin_cl_len;
-        uint32_t render_cl_len;
-        uint32_t shader_record_len;
-        uint32_t shader_record_count;
-        uint32_t bo_handle_count;
+	/* Pointer to the binner command list.
+	 *
+	 * This is the first set of commands executed, which runs the
+	 * coordinate shader to determine where primitives land on the screen,
+	 * then writes out the state updates and draw calls necessary per tile
+	 * to the tile allocation BO.
+	 */
+	void __user *bin_cl;
+
+	/* Pointer to the render command list.
+	 *
+	 * The render command list contains a set of packets to load the
+	 * current tile's state (reading from memory, or just clearing it)
+	 * into the GPU, then call into the tile allocation BO to run the
+	 * stored rendering for that tile, then store the tile's state back to
+	 * memory.
+	 */
+	void __user *render_cl;
+
+	/* Pointer to the shader records.
+	 *
+	 * Shader records are the structures read by the hardware that contain
+	 * pointers to uniforms, shaders, and vertex attributes.  The
+	 * reference to the shader record has enough information to determine
+	 * how many pointers are necessary (fixed number for shaders/uniforms,
+	 * and an attribute count), so those BO indices into bo_handles are
+	 * just stored as uint32_ts before each shader record passed in.
+	 */
+	void __user *shader_records;
+
+	void __user *bo_handles;
+
+	/* Size in bytes of the binner command list. */
+	uint32_t bin_cl_len;
+	/* Size in bytes of the render command list */
+	uint32_t render_cl_len;
+	/* Size in bytes of the list of shader records. */
+	uint32_t shader_record_len;
+	/* Number of shader records.
+	 *
+	 * This could just be computed from the contents of shader_records,
+	 * but it keeps the kernel from having to resize various allocations
+	 * it makes.
+	 */
+	uint32_t shader_record_count;
+
+	/* Number of BO handles passed in (size is that times 4). */
+	uint32_t bo_handle_count;
 };
 
 #endif /* _UAPI_VC4_DRM_H_ */
-- 
2.30.2