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

[Matt Roper]

On Tue, Dec 05, 2023 at 12:07:55PM -0600, Lucas De Marchi wrote:
> On Tue, Dec 05, 2023 at 09:28:03AM -0800, Matt Roper wrote:
> > 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
> 
> It shows "Access: Masked(R/W)" for me. Same thing on bspec 45921 for the
> same register, different platform.

Ah, they put it up at the top of the page rather on the fields
themselves as they do on a lot of the other registers.

> 
> IMO if any register doesn't have the tag, it needs to be raised as a
> bspec bug.

Yeah, agreed.


I was mainly wonder if we should say the registers are "usually" annoted
this way (since across thousands of registers there's almost always
human error for things like this in the docs on one or two), but I don't
have any specific examples at the moment of it missing, so just
indicating it's always the case is probably fine.

Reviewed-by: Matt Roper <matthew.d.roper at intel.com>

> 
> Lucas De Marchi

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