drm/i915/uapi: Add kerneldoc for engine class enum

We'll be adding a new type of engine soon.  Let's document the existing
engine classes first to help make it clear what each type of engine is
used for.

Cc: Andi Shyti <andi.shyti@linux.intel.com>
Signed-off-by: Matt Roper <matthew.d.roper@intel.com>
Reviewed-by: Andi Shyti <andi.shyti@linux.intel.com>
Reviewed-by: Jordan Justen <jordan.l.justen@intel.com>
Link: https://patchwork.freedesktop.org/patch/msgid/20220428041926.1483683-2-matthew.d.roper@intel.com

diff --git a/include/uapi/drm/i915_drm.h b/include/uapi/drm/i915_drm.h
index 35ca528803fd4a5cc106c8319c2bd70ea9502a53..ec000fc6c879aaeb4a5c80bc5ec19d117ea9d943 100644 (file)
--- a/include/uapi/drm/i915_drm.h
+++ b/include/uapi/drm/i915_drm.h
@@ -154,21 +154,62 @@ enum i915_mocs_table_index {
        I915_MOCS_CACHED,
 };
 
-/*
+/**
+ * enum drm_i915_gem_engine_class - uapi engine type enumeration
+ *
  * Different engines serve different roles, and there may be more than one
- * engine serving each role. enum drm_i915_gem_engine_class provides a
- * classification of the role of the engine, which may be used when requesting
- * operations to be performed on a certain subset of engines, or for providing
- * information about that group.
+ * engine serving each role.  This enum provides a classification of the role
+ * of the engine, which may be used when requesting operations to be performed
+ * on a certain subset of engines, or for providing information about that
+ * group.
  */
 enum drm_i915_gem_engine_class {
+       /**
+        * @I915_ENGINE_CLASS_RENDER:
+        *
+        * Render engines support instructions used for 3D, Compute (GPGPU),
+        * and programmable media workloads.  These instructions fetch data and
+        * dispatch individual work items to threads that operate in parallel.
+        * The threads run small programs (called "kernels" or "shaders") on
+        * the GPU's execution units (EUs).
+        */
        I915_ENGINE_CLASS_RENDER        = 0,
+
+       /**
+        * @I915_ENGINE_CLASS_COPY:
+        *
+        * Copy engines (also referred to as "blitters") support instructions
+        * that move blocks of data from one location in memory to another,
+        * or that fill a specified location of memory with fixed data.
+        * Copy engines can perform pre-defined logical or bitwise operations
+        * on the source, destination, or pattern data.
+        */
        I915_ENGINE_CLASS_COPY          = 1,
+
+       /**
+        * @I915_ENGINE_CLASS_VIDEO:
+        *
+        * Video engines (also referred to as "bit stream decode" (BSD) or
+        * "vdbox") support instructions that perform fixed-function media
+        * decode and encode.
+        */
        I915_ENGINE_CLASS_VIDEO         = 2,
+
+       /**
+        * @I915_ENGINE_CLASS_VIDEO_ENHANCE:
+        *
+        * Video enhancement engines (also referred to as "vebox") support
+        * instructions related to image enhancement.
+        */
        I915_ENGINE_CLASS_VIDEO_ENHANCE = 3,
 
-       /* should be kept compact */
+       /* Values in this enum should be kept compact. */
 
+       /**
+        * @I915_ENGINE_CLASS_INVALID:
+        *
+        * Placeholder value to represent an invalid engine class assignment.
+        */
        I915_ENGINE_CLASS_INVALID       = -1
 };