KMS backlight ABI proposition

[Daniel Thompson]

On 20/02/17 12:46, Martin Peres wrote:
> +plasma-devel, as suggested by Martin Gräßlin.

This reply also adds the current drivers/video/backlight maintainers (I 
forwarded the original mail to them separately, so I've been pretty 
brutal with the delete key when quoting the original mail).


> On 17/02/17 14:58, Martin Peres wrote:
>> === 1) Backlight device interoperability ===
>>
>> Since we need to keep backward compatibility of the backlight, we have
>> to keep the current backlight drivers.
>>
>> Here are possible options:
>>
>>  - Exclusive access: Unregister a backlight device when the drm
>> brightness property is requested/used;
>>  - Unidirectional access: When writing to the backlight property, update
>> the backlight device;
>>  - Bi-directional access: Propagate back changes from the backlight
>> device to the property's value.
>>
>> Being bi-directional would be of course the best, but this requires that
>> both drivers have the same number of steps, otherwise, we may write a
>> value to the property, but get another one when reading it right after,
>> due to the non-bijective nature of the transformation.

I don't accept that bi-directional transfer requires the step range to 
be the same. Isn't all that is required is acceptance that both sides 
maintain a copy of the current value in their own number range and that 
if X is written to then Y may change value (i.e. when mapping between 
0..100 and 0..10 then if 0..100 is at 11 and 0..10 gets 1 written then 
0..100 is allowed to change to 10).

I'd note also that the mechanisms inside backlight to support 
sysfs_notify would mean *implementing* bi-directional comms isn't too 
bloated even if the two sides used different number ranges.


>> Uni-directional would work in all cases, with the caveat that mixing
>> calls to the KMS property and the backlight device will not be supported
>> (changes mades through the sysfs interface of the backlight driver will
>> not be reflected in the KMS property). At boot time, we should however
>> initialize the value of the backlight property with a value close to
>> what is currently set in the backlight driver.
>>
>> Giving exclusive access does not sound very good to me, as it would be
>> hard for the userspace to deal with disappearing drivers...

+1  :-)


>> == Current KMS ABI proposal ==
>>
>> The current ABI proposal has mostly been proposed by Jani Nikula, as a
>> result of his experience and our discussions.
>>
>> It takes the following approach:
>>
>>  - Fixed number of steps (I think we should change it to expose the same
>> number of steps)

Fixing a large number of steps over an inflexible (lets say 8 level) 
backlight device creates a new problem. User actions to 
increase/decrease the backlight don't work unless the userspace knows 
the hardware step size...

The 0..100 proposal below will encourage the userspace to implement 
hotkeys that jump by 9 (because 0 is reserved with a special meaning). 
and thus there will be deadspots where the hot key has no effect.


>>  - Uni-directional: KMS -> backlight

See above.


>>  - Do not deal yet with 3) and 4): I have ideas, but I have been
>> procrastinating long-enough to send this email and we already have much
>> to discuss!

Do any of those ideas involve adding *new* API to provide information to 
userspace to help it correct the curves (e.g. somewhat like ALSA)?

It's not that I object to such an approach but I consider it pointless 
to present fixed range brightness levels if the userspace were to end up 
responsible for curve correction.


>>  - Does not expose the current backlight power as we want to let the
>> kernel deal with DPMS on its own
 >>
>> === ABI proposal ===
>>
>> The brightness property MUST have values 0...100 inclusive.

I'm somewhat unconvinced by re-ranging the hardware capability but if 
this is the way we want to go perhaps consider -1..100 as the range. 
There's a risk of bikeshedding here but -1 is a more obvious "special" 
value and it offers more flexibility for natural hotkey strides.


>> The display brightness MUST be a monotonically increasing function of
>> the brightness property.
>>
>> Brightness property value 1 MUST mean the minimum supported visible
>> brightness.
>>
>> Brightness property value 100 MUST mean the maximum supported
>> brightness.
>>
>> Brightness property value 0 SHOULD mean backlight off or equivalent for
>> non-backlight brightness adjustment, typically completely
>> black. Brightness property value 0 MUST NOT switch the display or pipe
>> off [1].
>>
>> If the hardware is not capable of supporting zero brightness, and the
>> driver knows this, value 0 MUST be equal to value 1.
>>
>> If the driver does not know whether the hardware is capable of
>> supporting zero brightness, the driver SHOULD err on the side of 0 not
>> being off rather than 1 meaning off. In this case, value 0 is likely
>> different from value 1, and the minimum brightness can only be reached
>> via property value 0 [2].
>>
>> If the brightness gets changed outside of the property interface,
>> reading the property value MAY be out of sync with the actual brightness
>> [3].

Already discussed above.


Daniel.