| Message ID | 20230121190853.18722-1-gustavo.sousa@intel.com (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | drm/i915/gt: Fix sphinx warnings for workarounds documentation | expand |
On Sat, Jan 21, 2023 at 04:08:53PM -0300, Gustavo Sousa wrote: > The wildchar ("*") used in the function name patterns in the > documentation was taken as a start of an "emphasis" inline markup. Wrap > the patterns with the inline literal markup and, for consistency, do the > same for the other function names mentioned. > > Fixes: 0c3064cf33fb ("drm/i915/doc: Document where to implement register workarounds") > Reported-by: kernel test robot <lkp@intel.com> > Signed-off-by: Gustavo Sousa <gustavo.sousa@intel.com> Cc: Mauro Carvalho Chehab <mchehab@kernel.org> just in case he sees some better alternative for the escaping the '*' My fear is that this ``*_fn_name()`` could create invalid links in the doc... > --- > drivers/gpu/drm/i915/gt/intel_workarounds.c | 20 ++++++++++---------- > 1 file changed, 10 insertions(+), 10 deletions(-) > > diff --git a/drivers/gpu/drm/i915/gt/intel_workarounds.c b/drivers/gpu/drm/i915/gt/intel_workarounds.c > index 918a271447e2..e849035d8dc5 100644 > --- a/drivers/gpu/drm/i915/gt/intel_workarounds.c > +++ b/drivers/gpu/drm/i915/gt/intel_workarounds.c > @@ -30,8 +30,8 @@ > * creation to have a "primed golden context", i.e. a context image that > * already contains the changes needed to all the registers. > * > - * Context workarounds should be implemented in the *_ctx_workarounds_init() > - * variants respective to the targeted platforms. > + * Context workarounds should be implemented in the > + * ``*_ctx_workarounds_init()`` variants respective to the targeted platforms. > * > * - Engine workarounds: the list of these WAs is applied whenever the specific > * engine is reset. It's also possible that a set of engine classes share a > @@ -46,16 +46,16 @@ > * ``drivers/gpu/drm/i915/gt/uc/intel_guc_ads.c`` for reference. > * > * Workarounds for registers specific to RCS and CCS should be implemented in > - * rcs_engine_wa_init() and ccs_engine_wa_init(), respectively; those for > - * registers belonging to BCS, VCS or VECS should be implemented in > - * xcs_engine_wa_init(). Workarounds for registers not belonging to a specific > - * engine's MMIO range but that are part of of the common RCS/CCS reset domain > - * should be implemented in general_render_compute_wa_init(). > + * ``rcs_engine_wa_init()`` and ``ccs_engine_wa_init()``, respectively; those > + * for registers belonging to BCS, VCS or VECS should be implemented in > + * ``xcs_engine_wa_init()``. Workarounds for registers not belonging to a > + * specific engine's MMIO range but that are part of of the common RCS/CCS > + * reset domain should be implemented in ``general_render_compute_wa_init()``. > * > * - GT workarounds: the list of these WAs is applied whenever these registers > * revert to their default values: on GPU reset, suspend/resume [1]_, etc. > * > - * GT workarounds should be implemented in the *_gt_workarounds_init() > + * GT workarounds should be implemented in the ``*_gt_workarounds_init()`` > * variants respective to the targeted platforms. > * > * - Register whitelist: some workarounds need to be implemented in userspace, > @@ -64,8 +64,8 @@ > * this is just a special case of a MMIO workaround (as we write the list of > * these to/be-whitelisted registers to some special HW registers). > * > - * Register whitelisting should be done in the *_whitelist_build() variants > - * respective to the targeted platforms. > + * Register whitelisting should be done in the ``*_whitelist_build()`` > + * variants respective to the targeted platforms. > * > * - Workaround batchbuffers: buffers that get executed automatically by the > * hardware on every HW context restore. These buffers are created and > -- > 2.39.0 >
On 1/24/23 20:39, Rodrigo Vivi wrote: > On Sat, Jan 21, 2023 at 04:08:53PM -0300, Gustavo Sousa wrote: >> The wildchar ("*") used in the function name patterns in the >> documentation was taken as a start of an "emphasis" inline markup. Wrap >> the patterns with the inline literal markup and, for consistency, do the >> same for the other function names mentioned. >> >> Fixes: 0c3064cf33fb ("drm/i915/doc: Document where to implement register workarounds") >> Reported-by: kernel test robot <lkp@intel.com> >> Signed-off-by: Gustavo Sousa <gustavo.sousa@intel.com> > Cc: Mauro Carvalho Chehab <mchehab@kernel.org> > > just in case he sees some better alternative for the escaping the '*' > > My fear is that this ``*_fn_name()`` could create invalid links in the doc... Seems OK to me. ``foo`` is literal inline. It won't try to generate cross-references. Reviewed-by: Mauro Carvalho Chehab <mchehab@kernel.org> > > >> --- >> drivers/gpu/drm/i915/gt/intel_workarounds.c | 20 ++++++++++---------- >> 1 file changed, 10 insertions(+), 10 deletions(-) >> >> diff --git a/drivers/gpu/drm/i915/gt/intel_workarounds.c b/drivers/gpu/drm/i915/gt/intel_workarounds.c >> index 918a271447e2..e849035d8dc5 100644 >> --- a/drivers/gpu/drm/i915/gt/intel_workarounds.c >> +++ b/drivers/gpu/drm/i915/gt/intel_workarounds.c >> @@ -30,8 +30,8 @@ >> * creation to have a "primed golden context", i.e. a context image that >> * already contains the changes needed to all the registers. >> * >> - * Context workarounds should be implemented in the *_ctx_workarounds_init() >> - * variants respective to the targeted platforms. >> + * Context workarounds should be implemented in the >> + * ``*_ctx_workarounds_init()`` variants respective to the targeted platforms. >> * >> * - Engine workarounds: the list of these WAs is applied whenever the specific >> * engine is reset. It's also possible that a set of engine classes share a >> @@ -46,16 +46,16 @@ >> * ``drivers/gpu/drm/i915/gt/uc/intel_guc_ads.c`` for reference. >> * >> * Workarounds for registers specific to RCS and CCS should be implemented in >> - * rcs_engine_wa_init() and ccs_engine_wa_init(), respectively; those for >> - * registers belonging to BCS, VCS or VECS should be implemented in >> - * xcs_engine_wa_init(). Workarounds for registers not belonging to a specific >> - * engine's MMIO range but that are part of of the common RCS/CCS reset domain >> - * should be implemented in general_render_compute_wa_init(). >> + * ``rcs_engine_wa_init()`` and ``ccs_engine_wa_init()``, respectively; those >> + * for registers belonging to BCS, VCS or VECS should be implemented in >> + * ``xcs_engine_wa_init()``. Workarounds for registers not belonging to a >> + * specific engine's MMIO range but that are part of of the common RCS/CCS >> + * reset domain should be implemented in ``general_render_compute_wa_init()``. >> * >> * - GT workarounds: the list of these WAs is applied whenever these registers >> * revert to their default values: on GPU reset, suspend/resume [1]_, etc. >> * >> - * GT workarounds should be implemented in the *_gt_workarounds_init() >> + * GT workarounds should be implemented in the ``*_gt_workarounds_init()`` >> * variants respective to the targeted platforms. >> * >> * - Register whitelist: some workarounds need to be implemented in userspace, >> @@ -64,8 +64,8 @@ >> * this is just a special case of a MMIO workaround (as we write the list of >> * these to/be-whitelisted registers to some special HW registers). >> * >> - * Register whitelisting should be done in the *_whitelist_build() variants >> - * respective to the targeted platforms. >> + * Register whitelisting should be done in the ``*_whitelist_build()`` >> + * variants respective to the targeted platforms. >> * >> * - Workaround batchbuffers: buffers that get executed automatically by the >> * hardware on every HW context restore. These buffers are created and >> -- >> 2.39.0 >>
On Tue, Jan 31, 2023 at 02:03:01PM +0100, Mauro Carvalho Chehab wrote: > > On 1/24/23 20:39, Rodrigo Vivi wrote: > > On Sat, Jan 21, 2023 at 04:08:53PM -0300, Gustavo Sousa wrote: > > > The wildchar ("*") used in the function name patterns in the > > > documentation was taken as a start of an "emphasis" inline markup. Wrap > > > the patterns with the inline literal markup and, for consistency, do the > > > same for the other function names mentioned. > > > > > > Fixes: 0c3064cf33fb ("drm/i915/doc: Document where to implement register workarounds") > > > Reported-by: kernel test robot <lkp@intel.com> > > > Signed-off-by: Gustavo Sousa <gustavo.sousa@intel.com> > > Cc: Mauro Carvalho Chehab <mchehab@kernel.org> > > > > just in case he sees some better alternative for the escaping the '*' > > > > My fear is that this ``*_fn_name()`` could create invalid links in the doc... > > > Seems OK to me. ``foo`` is literal inline. It won't try to generate > cross-references. > > > Reviewed-by: Mauro Carvalho Chehab <mchehab@kernel.org> Gustavo and Mauro, please accept my apologies here. I ended up pushing the patch from Bagas that had a escape \* instead of the `` wrapper. For some unexcused reason I had missed Mauro's response here and forgot about this. I'm really sorry. And the escape sounded more natural so I just pushed it immediately. > > > > > > > > > --- > > > drivers/gpu/drm/i915/gt/intel_workarounds.c | 20 ++++++++++---------- > > > 1 file changed, 10 insertions(+), 10 deletions(-) > > > > > > diff --git a/drivers/gpu/drm/i915/gt/intel_workarounds.c b/drivers/gpu/drm/i915/gt/intel_workarounds.c > > > index 918a271447e2..e849035d8dc5 100644 > > > --- a/drivers/gpu/drm/i915/gt/intel_workarounds.c > > > +++ b/drivers/gpu/drm/i915/gt/intel_workarounds.c > > > @@ -30,8 +30,8 @@ > > > * creation to have a "primed golden context", i.e. a context image that > > > * already contains the changes needed to all the registers. > > > * > > > - * Context workarounds should be implemented in the *_ctx_workarounds_init() > > > - * variants respective to the targeted platforms. > > > + * Context workarounds should be implemented in the > > > + * ``*_ctx_workarounds_init()`` variants respective to the targeted platforms. > > > * > > > * - Engine workarounds: the list of these WAs is applied whenever the specific > > > * engine is reset. It's also possible that a set of engine classes share a > > > @@ -46,16 +46,16 @@ > > > * ``drivers/gpu/drm/i915/gt/uc/intel_guc_ads.c`` for reference. > > > * > > > * Workarounds for registers specific to RCS and CCS should be implemented in > > > - * rcs_engine_wa_init() and ccs_engine_wa_init(), respectively; those for > > > - * registers belonging to BCS, VCS or VECS should be implemented in > > > - * xcs_engine_wa_init(). Workarounds for registers not belonging to a specific > > > - * engine's MMIO range but that are part of of the common RCS/CCS reset domain > > > - * should be implemented in general_render_compute_wa_init(). > > > + * ``rcs_engine_wa_init()`` and ``ccs_engine_wa_init()``, respectively; those > > > + * for registers belonging to BCS, VCS or VECS should be implemented in > > > + * ``xcs_engine_wa_init()``. Workarounds for registers not belonging to a > > > + * specific engine's MMIO range but that are part of of the common RCS/CCS > > > + * reset domain should be implemented in ``general_render_compute_wa_init()``. > > > * > > > * - GT workarounds: the list of these WAs is applied whenever these registers > > > * revert to their default values: on GPU reset, suspend/resume [1]_, etc. > > > * > > > - * GT workarounds should be implemented in the *_gt_workarounds_init() > > > + * GT workarounds should be implemented in the ``*_gt_workarounds_init()`` > > > * variants respective to the targeted platforms. > > > * > > > * - Register whitelist: some workarounds need to be implemented in userspace, > > > @@ -64,8 +64,8 @@ > > > * this is just a special case of a MMIO workaround (as we write the list of > > > * these to/be-whitelisted registers to some special HW registers). > > > * > > > - * Register whitelisting should be done in the *_whitelist_build() variants > > > - * respective to the targeted platforms. > > > + * Register whitelisting should be done in the ``*_whitelist_build()`` > > > + * variants respective to the targeted platforms. > > > * > > > * - Workaround batchbuffers: buffers that get executed automatically by the > > > * hardware on every HW context restore. These buffers are created and > > > -- > > > 2.39.0 > > >
On Mon, Feb 06, 2023 at 12:00:01PM -0500, Rodrigo Vivi wrote: > On Tue, Jan 31, 2023 at 02:03:01PM +0100, Mauro Carvalho Chehab wrote: > > > > On 1/24/23 20:39, Rodrigo Vivi wrote: > > > On Sat, Jan 21, 2023 at 04:08:53PM -0300, Gustavo Sousa wrote: > > > > The wildchar ("*") used in the function name patterns in the > > > > documentation was taken as a start of an "emphasis" inline markup. Wrap > > > > the patterns with the inline literal markup and, for consistency, do the > > > > same for the other function names mentioned. > > > > > > > > Fixes: 0c3064cf33fb ("drm/i915/doc: Document where to implement register workarounds") > > > > Reported-by: kernel test robot <lkp@intel.com> > > > > Signed-off-by: Gustavo Sousa <gustavo.sousa@intel.com> > > > Cc: Mauro Carvalho Chehab <mchehab@kernel.org> > > > > > > just in case he sees some better alternative for the escaping the '*' > > > > > > My fear is that this ``*_fn_name()`` could create invalid links in the doc... > > > > > > Seems OK to me. ``foo`` is literal inline. It won't try to generate > > cross-references. > > > > > > Reviewed-by: Mauro Carvalho Chehab <mchehab@kernel.org> > > Gustavo and Mauro, please accept my apologies here. > I ended up pushing the patch from Bagas that had a escape \* > instead of the `` wrapper. > > For some unexcused reason I had missed Mauro's response here > and forgot about this. I'm really sorry. > > And the escape sounded more natural so I just pushed it immediately. No worries! I'm glad the issue that I caused is fixed :-) -- Gustavo Sousa > > > > > > > > > > > > > > > --- > > > > drivers/gpu/drm/i915/gt/intel_workarounds.c | 20 ++++++++++---------- > > > > 1 file changed, 10 insertions(+), 10 deletions(-) > > > > > > > > diff --git a/drivers/gpu/drm/i915/gt/intel_workarounds.c b/drivers/gpu/drm/i915/gt/intel_workarounds.c > > > > index 918a271447e2..e849035d8dc5 100644 > > > > --- a/drivers/gpu/drm/i915/gt/intel_workarounds.c > > > > +++ b/drivers/gpu/drm/i915/gt/intel_workarounds.c > > > > @@ -30,8 +30,8 @@ > > > > * creation to have a "primed golden context", i.e. a context image that > > > > * already contains the changes needed to all the registers. > > > > * > > > > - * Context workarounds should be implemented in the *_ctx_workarounds_init() > > > > - * variants respective to the targeted platforms. > > > > + * Context workarounds should be implemented in the > > > > + * ``*_ctx_workarounds_init()`` variants respective to the targeted platforms. > > > > * > > > > * - Engine workarounds: the list of these WAs is applied whenever the specific > > > > * engine is reset. It's also possible that a set of engine classes share a > > > > @@ -46,16 +46,16 @@ > > > > * ``drivers/gpu/drm/i915/gt/uc/intel_guc_ads.c`` for reference. > > > > * > > > > * Workarounds for registers specific to RCS and CCS should be implemented in > > > > - * rcs_engine_wa_init() and ccs_engine_wa_init(), respectively; those for > > > > - * registers belonging to BCS, VCS or VECS should be implemented in > > > > - * xcs_engine_wa_init(). Workarounds for registers not belonging to a specific > > > > - * engine's MMIO range but that are part of of the common RCS/CCS reset domain > > > > - * should be implemented in general_render_compute_wa_init(). > > > > + * ``rcs_engine_wa_init()`` and ``ccs_engine_wa_init()``, respectively; those > > > > + * for registers belonging to BCS, VCS or VECS should be implemented in > > > > + * ``xcs_engine_wa_init()``. Workarounds for registers not belonging to a > > > > + * specific engine's MMIO range but that are part of of the common RCS/CCS > > > > + * reset domain should be implemented in ``general_render_compute_wa_init()``. > > > > * > > > > * - GT workarounds: the list of these WAs is applied whenever these registers > > > > * revert to their default values: on GPU reset, suspend/resume [1]_, etc. > > > > * > > > > - * GT workarounds should be implemented in the *_gt_workarounds_init() > > > > + * GT workarounds should be implemented in the ``*_gt_workarounds_init()`` > > > > * variants respective to the targeted platforms. > > > > * > > > > * - Register whitelist: some workarounds need to be implemented in userspace, > > > > @@ -64,8 +64,8 @@ > > > > * this is just a special case of a MMIO workaround (as we write the list of > > > > * these to/be-whitelisted registers to some special HW registers). > > > > * > > > > - * Register whitelisting should be done in the *_whitelist_build() variants > > > > - * respective to the targeted platforms. > > > > + * Register whitelisting should be done in the ``*_whitelist_build()`` > > > > + * variants respective to the targeted platforms. > > > > * > > > > * - Workaround batchbuffers: buffers that get executed automatically by the > > > > * hardware on every HW context restore. These buffers are created and > > > > -- > > > > 2.39.0 > > > >
On 2/6/23 18:00, Rodrigo Vivi wrote: > On Tue, Jan 31, 2023 at 02:03:01PM +0100, Mauro Carvalho Chehab wrote: >> On 1/24/23 20:39, Rodrigo Vivi wrote: >>> On Sat, Jan 21, 2023 at 04:08:53PM -0300, Gustavo Sousa wrote: >>>> The wildchar ("*") used in the function name patterns in the >>>> documentation was taken as a start of an "emphasis" inline markup. Wrap >>>> the patterns with the inline literal markup and, for consistency, do the >>>> same for the other function names mentioned. >>>> >>>> Fixes: 0c3064cf33fb ("drm/i915/doc: Document where to implement register workarounds") >>>> Reported-by: kernel test robot <lkp@intel.com> >>>> Signed-off-by: Gustavo Sousa <gustavo.sousa@intel.com> >>> Cc: Mauro Carvalho Chehab <mchehab@kernel.org> >>> >>> just in case he sees some better alternative for the escaping the '*' >>> >>> My fear is that this ``*_fn_name()`` could create invalid links in the doc... >> >> Seems OK to me. ``foo`` is literal inline. It won't try to generate >> cross-references. >> >> >> Reviewed-by: Mauro Carvalho Chehab <mchehab@kernel.org> > Gustavo and Mauro, please accept my apologies here. > I ended up pushing the patch from Bagas that had a escape \* > instead of the `` wrapper. > > For some unexcused reason I had missed Mauro's response here > and forgot about this. I'm really sorry. > > And the escape sounded more natural so I just pushed it immediately. No worries. An escape \* works. Regards, Mauro
diff --git a/drivers/gpu/drm/i915/gt/intel_workarounds.c b/drivers/gpu/drm/i915/gt/intel_workarounds.c index 918a271447e2..e849035d8dc5 100644 --- a/drivers/gpu/drm/i915/gt/intel_workarounds.c +++ b/drivers/gpu/drm/i915/gt/intel_workarounds.c @@ -30,8 +30,8 @@ * creation to have a "primed golden context", i.e. a context image that * already contains the changes needed to all the registers. * - * Context workarounds should be implemented in the *_ctx_workarounds_init() - * variants respective to the targeted platforms. + * Context workarounds should be implemented in the + * ``*_ctx_workarounds_init()`` variants respective to the targeted platforms. * * - Engine workarounds: the list of these WAs is applied whenever the specific * engine is reset. It's also possible that a set of engine classes share a @@ -46,16 +46,16 @@ * ``drivers/gpu/drm/i915/gt/uc/intel_guc_ads.c`` for reference. * * Workarounds for registers specific to RCS and CCS should be implemented in - * rcs_engine_wa_init() and ccs_engine_wa_init(), respectively; those for - * registers belonging to BCS, VCS or VECS should be implemented in - * xcs_engine_wa_init(). Workarounds for registers not belonging to a specific - * engine's MMIO range but that are part of of the common RCS/CCS reset domain - * should be implemented in general_render_compute_wa_init(). + * ``rcs_engine_wa_init()`` and ``ccs_engine_wa_init()``, respectively; those + * for registers belonging to BCS, VCS or VECS should be implemented in + * ``xcs_engine_wa_init()``. Workarounds for registers not belonging to a + * specific engine's MMIO range but that are part of of the common RCS/CCS + * reset domain should be implemented in ``general_render_compute_wa_init()``. * * - GT workarounds: the list of these WAs is applied whenever these registers * revert to their default values: on GPU reset, suspend/resume [1]_, etc. * - * GT workarounds should be implemented in the *_gt_workarounds_init() + * GT workarounds should be implemented in the ``*_gt_workarounds_init()`` * variants respective to the targeted platforms. * * - Register whitelist: some workarounds need to be implemented in userspace, @@ -64,8 +64,8 @@ * this is just a special case of a MMIO workaround (as we write the list of * these to/be-whitelisted registers to some special HW registers). * - * Register whitelisting should be done in the *_whitelist_build() variants - * respective to the targeted platforms. + * Register whitelisting should be done in the ``*_whitelist_build()`` + * variants respective to the targeted platforms. * * - Workaround batchbuffers: buffers that get executed automatically by the * hardware on every HW context restore. These buffers are created and
The wildchar ("*") used in the function name patterns in the documentation was taken as a start of an "emphasis" inline markup. Wrap the patterns with the inline literal markup and, for consistency, do the same for the other function names mentioned. Fixes: 0c3064cf33fb ("drm/i915/doc: Document where to implement register workarounds") Reported-by: kernel test robot <lkp@intel.com> Signed-off-by: Gustavo Sousa <gustavo.sousa@intel.com> --- drivers/gpu/drm/i915/gt/intel_workarounds.c | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-)