| Message ID | 20210503155748.1961781-16-jason@jlekstrand.net (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | drm/i915/gem: ioctl clean-ups (v5) | expand |
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@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@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@lists.freedesktop.org > https://lists.freedesktop.org/mailman/listinfo/dri-devel
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; + + /** @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; };
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> --- Documentation/gpu/i915.rst | 2 + .../gpu/drm/i915/gem/i915_gem_context_types.h | 43 ++++++++++++++++--- 2 files changed, 38 insertions(+), 7 deletions(-)