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

[Simon Ser]

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

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.

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.

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