KMS backlight ABI proposition

[Jani Nikula]

On Mon, 20 Feb 2017, Thierry Reding <thierry.reding at gmail.com> wrote:
>>  - The luminance curve of the backlight drivers is not specified, which
>> can lead to a bad user experience: Little changes in the highest levels
>> but drastic changes in the low levels.
>
> I think this is something that the backlight framework should specify.
> It's fairly unlikely that you could get this right every time in the
> display driver. I suppose for something like x86 this might actually
> work, but I don't think it'll work on something like ARM where you'd
> have to encode this based on what backlight driver was actually being
> used.

I outlined one idea elsewhere in the thread [1].

[1] http://lkml.kernel.org/r/87mvdei7ug.fsf@intel.com

>> 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 think this is the only reasonable choice. As has been discussed
> elsewhere trying to map different ranges always has drawbacks. Also its
> really the backlight driver's job to expose the number of brightness
> levels that make sense given the specific hardware.

I outlined some of the problems with bi-directional access elsewhere in
the thread [1]. This is also related to scaling (or re-ranging) between
API and hardware.

>> It was brought up that we could simply not allow the backlight to be
>> turned off, and just request DPMS to reach this state. However, I do not
>> think it is a good idea as some panels (like the one from the OLPC)
>> switch to e-paper mode when the backlight is set to 0 and are perfectly
>> readable.
>
> I think this is something that the backlight API should be stricter
> about. Some drivers seem to equate brightness 0 with backlight off,
> while others don't. That's really confusing in my opinion. Since we
> already have separate properties for both (and reflected in sysfs),
> I think the most sensible thing to do would be to formalize this in
> the backlight subsystem.

Yes, we should be clear in the specification, but also provide
recommendation for cases where 1) the driver does not know whether the
lowest value is off or not, 2) the driver can't switch the backlight
off.

(Reasons for the latter might be that you just can't switch the PWM
generator off alone, or it must be done in sequence with other hardware
that really needs a full DPMS, and the PWM or board design does not
allow 0 duty cycle with the PWM on. This is not theoretical.)

> If we expose all values that the backlight driver exposes, then there
> should be no reason not to trust that when we set a value within the
> given range, it will be the value that's actually going to be
> programmed.

See [1].

>>  - Uni-directional: KMS -> backlight
>
> I don't think that'll work very well. At the very least we'll need to
> read back the initial brightness. And then there's the issue of these
> brightness values going out of sync. Both of which are likely going to
> result in very annoying user interface behaviour. Bidirectional sounds
> like the best to me, and I don't think it would be very difficult to
> implement, either.

See [1]. (Sorry for these types of annoying references, but I already
replied there and don't want to split the discussion about the same
thing further.)

>>  - 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!
>
> I think we should push 3) into backlight drivers where this knowledge
> should exist. I suspect there could be edge cases where the driver does
> not expose a sensible range (think 0-65535, with no obvious relation to
> brightness at all). In those cases I think we could possible overlay a
> backlight driver that makes something useful out of those values,
> possibly using device-specific knowledge.
>
>>  - Does not expose the current backlight power as we want to let the
>> kernel deal with DPMS on its own
>
> I think DPMS and backlight power are separate things. As was mentioned
> elsewhere there are cases where it makes sense to disable the backlight
> but keep the display pipeline running. It's probably okay to not support
> these right away, but I think we need to be careful to design an
> interface that will allow them to be supported later on.

Should we encourage a backlight on/off interface when we can't be sure
whether the backlight can be switched off? The OLPC case is a valid one,
but I don't want to encourage backlight off as a "light DPMS".

(Side note, we should really remember that all brightness is not
backlight either.)

>> === ABI proposal ===
>> 
>> The brightness property MUST have values 0...100 inclusive.
>> 
>> 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].
>
> Why special case 0? Couldn't we simply add a second property for the
> power? We could for example have a boolean "backlight" property that
> userspace can turn "On" or "Off" and a "brightness" property which
> controls the backlight brightness.

Very few of the backlight class implementations support the bl_power
attribute to switch off the backlight. Even if they can be switched off
using 0 brightness. Unless we're looking at changing all backlight
drivers, the property implementation can only try to use value 0 for
backlight off. But we don't know if it's off or minimum or what. Also
see below.

>> 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].
>
> Yeah, this definition is really complicated. I've been reading it three
> times and I'm not sure I fully understand it. =)
>
> For my understanding, with those e-paper displays, what would be the
> difference between brightness 0 and backlight off? Would backlight off
> actually turn off the display? So that no "ink" would even be visible?
> For panels we typically have enabled and disabled states, where the
> disabled state, among other things, also turns off the backlight. So
> for panels we do have one more level of abstraction. For e-paper-able
> displays we could simply have a full range of brightness values, with
> 0 meaning e-paper mode and panel off meaning, well, panel off.
>
> Alternatively, e-paper mode could be the same as backlight off, since
> obviously there is no backlight anymore, in which case there wouldn't be
> a need to differentiate the special case for 0.

The main goal was to allow for cases where you can't switch off the
backlight, or you don't know whether the lowest value is pitch black. As
I wrote in [1], we can change the meaning of 0, but we need to take into
account it really might mean "off" for some, and "minimum visible" for
others.

The old sysfs ABI handled this by deferring it all to drivers, and we
know the result... this really is an unholy mess.

BR,
Jani.

-- 
Jani Nikula, Intel Open Source Technology Center