[PATCH 15/27] drm/i915: Add gem/i915_gem_context.h to the docs

[Daniel Vetter]

On Mon, May 03, 2021 at 10:57:36AM -0500, Jason Ekstrand wrote:
> 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 at jlekstrand.net>
> ---
>  Documentation/gpu/i915.rst                    |  2 +
>  .../gpu/drm/i915/gem/i915_gem_context_types.h | 43 ++++++++++++++++---
>  2 files changed, 38 insertions(+), 7 deletions(-)
> 
> diff --git a/Documentation/gpu/i915.rst b/Documentation/gpu/i915.rst
> index 486c720f38907..0529e5183982e 100644
> --- 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 df76767f0c41b..5f0673a2129f9 100644
> --- 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;

I got derailed a bit appreciating the lifetime complexity here as
expressed in the callbacks for this. I hope this all simplifies?

Anyway patch looks good, or at least better than what we had.

Reviewed-by: Daniel Vetter <daniel.vetter at ffwll.ch>

> +
> +	/** @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;
>  };
> -- 
> 2.31.1
> 
> _______________________________________________
> dri-devel mailing list
> dri-devel at lists.freedesktop.org
> https://lists.freedesktop.org/mailman/listinfo/dri-devel

-- 
Daniel Vetter
Software Engineer, Intel Corporation
http://blog.ffwll.ch