[Intel-gfx] [PATCH] drm/i915/gt: Fix sphinx warnings for workarounds documentation

[Mauro Carvalho Chehab]

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 at intel.com>
>> Signed-off-by: Gustavo Sousa <gustavo.sousa at intel.com>
> Cc: Mauro Carvalho Chehab <mchehab at 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 at 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
>>