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

[Harry Wentland]

On 2025-02-21 11:42, Simon Ser wrote:
> On Friday, February 21st, 2025 at 17:18, Harry Wentland <harry.wentland at amd.com> wrote:
> 
>> 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.
> 
> Isn't the Content Protection property documented here?
> https://dri.freedesktop.org/docs/drm/gpu/drm-kms.html#standard-connector-properties
> 

Yes, but I don't see the actual strings. The doc mentions UNDESIRED,
DESIRED, and ENABLED but the strings are "Undesired", "Desired", and
"Enabled".

> COLOR_RANGE and COLOR_ENCODING are documented here, but indeed they
> are missing docs for enum entries:
> https://dri.freedesktop.org/docs/drm/gpu/drm-kms.html#color-management-properties
> 
> Would be nice to fix.
> 
>> 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"?
> 
> It's an old debate. Some user-space uses enum integer values, some
> user-space uses enum name strings.
> 
> In theory, each KMS object could have a different name-value map for
> a given property. However, this is very theoretical and last time we've
> discussed this we haven't found any case where this would be desirable.
> 
> IMHO, strings make it painful for user-space because it needs to go
> through another level of indirection (to convert names to values right
> before setting a property) for no benefit. Strings are more annoying to
> handle in general (memory management, typos, etc).
> 
> Kernel has a no user-space regression policy anyways, so when user-space
> starts using values, the kernel won't be able to break these users.
> 

Makes sense and thanks for some background on previous discussions on this.

> Other people have argued that strings make it easier for user-space to
> start using a new KMS property without deploying new kernel uAPI headers.
> 

I don't understand this argument. You would either need to define the
strings or the ints in your user-space app. You could do either without
deploying new uAPI headers.

> In the end, it's up to user-space to use their preferred way to set
> properties.

Makes sense.

Harry