[V7 08/45] Documentation/gpu: document drm_colorop

[Harry Wentland]

On 2025-02-15 09:40, Simon Ser wrote:
> On Monday, February 10th, 2025 at 23:03, Harry Wentland <harry.wentland at amd.com> wrote:
> 
>>>> + * DOC: overview
>>>> + *
>>>> + * A colorop represents a single color operation. Colorops are chained
>>>> + * via the NEXT property and make up color pipelines. Color pipelines
>>>> + * are advertised and selected via the COLOR_PIPELINE &drm_plane
>>>> + * property.
>>>> + *
>>>> + * A colorop will be of a certain type, advertised by the read-only TYPE
>>>> + * property. Each type of colorop will advertise a different set of
>>>> + * properties and is programmed in a different manner. Types can be
>>>> + * enumerated 1D curves, 1D LUTs, 3D LUTs, matrices, etc. See the
>>>> + * &drm_colorop_type documentation for information on each type.
>>>
>>> It's not super nice to refer to internal kernel docs here, because AFAIU
>>> this section is mostly written towards user-space developers. User-space
>>> developers have no idea how internal kernel structs work.
>>>
>>> It would be nicer to have a list of colorop types here, without referring
>>> to kernel internals. For instance, we have a list of
>>
>> I'm not sure I follow. This is linking to the drm_colorop_type
>> (from drm_mode.h) enum documentation in drm-uapi.html.
>>
>> Duplicating it here would mean that sooner or later the two
>> docs will get out of sync.
> 
> Oh, I thought this was an internal kernel enum. I guess the only missing
> thing is the string exposed to user-space for each enum entry then?
> 

Good point. We'll add that to the enum drm_colorop_type docs.

I did a brief survey of other enum properties and noticed
that this isn't well documented for others, such as the Content
Protection connector property, or the COLOR_RANGE and COLOR_ENCODING
plane properties.

On the IGT front, some tests set enum properties via enum strings,
and other set and get enum properties based on the prop uint64_t
prop_values[i] entry from the drmModeObjectPropertiesPtr.

Do you know if there's a best practice for enum usage or is it mostly
a case of "use what works for you"?

Harry

> In any case, sounds good to me.
> 
>> I agree with the rest and we'll reflect that in v8.
> 
> Sweet!