drm/i915: Add gem/i915_gem_context.h to the docs

In order to prevent kernel doc warnings, also fill out docs for any
missing fields and fix those that forgot the "@".

Signed-off-by: Jason Ekstrand <jason@jlekstrand.net>
Reviewed-by: Daniel Vetter <daniel.vetter@ffwll.ch>
Signed-off-by: Daniel Vetter <daniel.vetter@ffwll.ch>
Link: https://patchwork.freedesktop.org/patch/msgid/20210708154835.528166-16-jason@jlekstrand.net

diff --git a/Documentation/gpu/i915.rst b/Documentation/gpu/i915.rst
index e6fd960..204ebda 100644 (file)
--- a/Documentation/gpu/i915.rst
+++ b/Documentation/gpu/i915.rst
@@ -422,6 +422,8 @@ Batchbuffer Parsing
 User Batchbuffer Execution
 --------------------------
 
+.. kernel-doc:: drivers/gpu/drm/i915/gem/i915_gem_context_types.h
+
 .. kernel-doc:: drivers/gpu/drm/i915/gem/i915_gem_execbuffer.c
    :doc: User command execution
 

diff --git a/drivers/gpu/drm/i915/gem/i915_gem_context_types.h b/drivers/gpu/drm/i915/gem/i915_gem_context_types.h
index df76767..5f0673a 100644 (file)
--- a/drivers/gpu/drm/i915/gem/i915_gem_context_types.h
+++ b/drivers/gpu/drm/i915/gem/i915_gem_context_types.h
@@ -30,19 +30,39 @@ struct i915_address_space;
 struct intel_timeline;
 struct intel_ring;
 
+/**
+ * struct i915_gem_engines - A set of engines
+ */
 struct i915_gem_engines {
        union {
+               /** @link: Link in i915_gem_context::stale::engines */
                struct list_head link;
+
+               /** @rcu: RCU to use when freeing */
                struct rcu_head rcu;
        };
+
+       /** @fence: Fence used for delayed destruction of engines */
        struct i915_sw_fence fence;
+
+       /** @ctx: i915_gem_context backpointer */
        struct i915_gem_context *ctx;
+
+       /** @num_engines: Number of engines in this set */
        unsigned int num_engines;
+
+       /** @engines: Array of engines */
        struct intel_context *engines[];
 };
 
+/**
+ * struct i915_gem_engines_iter - Iterator for an i915_gem_engines set
+ */
 struct i915_gem_engines_iter {
+       /** @idx: Index into i915_gem_engines::engines */
        unsigned int idx;
+
+       /** @engines: Engine set being iterated */
        const struct i915_gem_engines *engines;
 };
 
@@ -53,10 +73,10 @@ struct i915_gem_engines_iter {
  * logical hardware state for a particular client.
  */
 struct i915_gem_context {
-       /** i915: i915 device backpointer */
+       /** @i915: i915 device backpointer */
        struct drm_i915_private *i915;
 
-       /** file_priv: owning file descriptor */
+       /** @file_priv: owning file descriptor */
        struct drm_i915_file_private *file_priv;
 
        /**
@@ -81,7 +101,9 @@ struct i915_gem_context {
         * CONTEXT_USER_ENGINES flag is set).
         */
        struct i915_gem_engines __rcu *engines;
-       struct mutex engines_mutex; /* guards writes to engines */
+
+       /** @engines_mutex: guards writes to engines */
+       struct mutex engines_mutex;
 
        /**
         * @syncobj: Shared timeline syncobj
@@ -118,7 +140,7 @@ struct i915_gem_context {
         */
        struct pid *pid;
 
-       /** link: place with &drm_i915_private.context_list */
+       /** @link: place with &drm_i915_private.context_list */
        struct list_head link;
 
        /**
@@ -153,11 +175,13 @@ struct i915_gem_context {
 #define CONTEXT_CLOSED                 0
 #define CONTEXT_USER_ENGINES           1
 
+       /** @mutex: guards everything that isn't engines or handles_vma */
        struct mutex mutex;
 
+       /** @sched: scheduler parameters */
        struct i915_sched_attr sched;
 
-       /** guilty_count: How many times this context has caused a GPU hang. */
+       /** @guilty_count: How many times this context has caused a GPU hang. */
        atomic_t guilty_count;
        /**
         * @active_count: How many times this context was active during a GPU
@@ -171,15 +195,17 @@ struct i915_gem_context {
        unsigned long hang_timestamp[2];
 #define CONTEXT_FAST_HANG_JIFFIES (120 * HZ) /* 3 hangs within 120s? Banned! */
 
-       /** remap_slice: Bitmask of cache lines that need remapping */
+       /** @remap_slice: Bitmask of cache lines that need remapping */
        u8 remap_slice;
 
        /**
-        * handles_vma: rbtree to look up our context specific obj/vma for
+        * @handles_vma: rbtree to look up our context specific obj/vma for
         * the user handle. (user handles are per fd, but the binding is
         * per vm, which may be one per context or shared with the global GTT)
         */
        struct radix_tree_root handles_vma;
+
+       /** @lut_mutex: Locks handles_vma */
        struct mutex lut_mutex;
 
        /**
@@ -191,8 +217,11 @@ struct i915_gem_context {
         */
        char name[TASK_COMM_LEN + 8];
 
+       /** @stale: tracks stale engines to be destroyed */
        struct {
+               /** @lock: guards engines */
                spinlock_t lock;
+               /** @engines: list of stale engines */
                struct list_head engines;
        } stale;
 };