[Intel-xe] [PATCH] drm/xe: Expand XE_REG_OPTION_MASKED documentation

[Matt Roper]

On Tue, Dec 05, 2023 at 07:58:20AM -0800, Lucas De Marchi wrote:
> Expand documentation and add an example to make clear this isn't about
> generic masks in registers. Also, fix the doc regarding read operations:
> the mask part has no effect on them.
> 
> Signed-off-by: Lucas De Marchi <lucas.demarchi at intel.com>
> ---
>  drivers/gpu/drm/xe/regs/xe_reg_defs.h | 11 ++++++++++-
>  1 file changed, 10 insertions(+), 1 deletion(-)
> 
> diff --git a/drivers/gpu/drm/xe/regs/xe_reg_defs.h b/drivers/gpu/drm/xe/regs/xe_reg_defs.h
> index 6e20fc2de9ff..c50e7650c09a 100644
> --- a/drivers/gpu/drm/xe/regs/xe_reg_defs.h
> +++ b/drivers/gpu/drm/xe/regs/xe_reg_defs.h
> @@ -60,7 +60,16 @@ struct xe_reg_mcr {
>  
>  /**
>   * XE_REG_OPTION_MASKED - Register is "masked", with upper 16 bits marking the
> - * read/written bits on the lower 16 bits.
> + * written bits on the lower 16 bits.
> + *
> + * It only applies to registers explicitly marked in bspec with
> + * "Access: Masked". Registers with this option can have write operations to

Unfortunately, this notation isn't always consistently applied in the
bspec.  E.g., FF_SLICE_CS_CHICKEN1 (0x20e0), documented on bspec 55934
lacks the "Access: Masked" notation, but is indeed a masked register.


Matt

> + * specific lower bits by setting the corresponding upper bits. Other bits will
> + * not be affected. This allows register writes without needing a RMW cycle and
> + * without caching in software the register value.
> + *
> + * Example: a write with value 0x00010001 will set bit 0 and all other bits
> + * retain their previous values.
>   *
>   * To be used with XE_REG(). XE_REG_MCR() and XE_REG_INITIALIZER()
>   */
> -- 
> 2.40.1
> 

-- 
Matt Roper
Graphics Software Engineer
Linux GPU Platform Enablement
Intel Corporation