KMS backlight ABI proposition

Wed Feb 22 19:07:46 UTC 2017

On Fri, Feb 17, 2017 at 4:58 AM, Martin Peres
<martin.peres at linux.intel.com> wrote:
> Hey everyone,
>
> We have been working towards exposing the backlight as a KMS property
> instead of relying on the backlight drivers. We have CC:ed the people we
> have found to be the more likely to be interested in the discussion but
> please add everyone you think would have some experience with this issue.
>
> == Introduction ==
>
> We are trying to bring the same level of support for the backlight on both
> the xf86-video-intel and -modesetting DDX.
>
> Looking into the situation of the backlight, we identified these problems
> which are almost show-stoppers for -modesetting and wayland compositors:
>
>  - There is no mapping between the backlight driver and DRM-connectors. This
> means that, in case there are multiple backlight drivers, the userspace has
> to have knowledge of the machine to know which driver should be used. See
> the priority list for the intel driver [0].
>
>  - 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.
>
>  - Writing to the backlight driver still requires root rights. Given that
> the xserver and wayland compositors are now running root-less, this means we
> would need a complex dance involving a setuid helper [1].
>
> Hans de Goede has already given a presentation about these issues at
> XDC2014. The slides are a good read[2].
>
> [0]
> https://cgit.freedesktop.org/xorg/driver/xf86-video-intel/tree/src/backlight.c#n259
>
> [1]
> https://cgit.freedesktop.org/xorg/driver/xf86-video-intel/tree/src/backlight.c#n348
>
> [2]
> https://www.x.org/wiki/Events/XDC2014/XDC2014GoedeBacklight/backlight.pdf
>
> == Proposal ==
>
> Since David Hermann already worked on this and proposed what I consider
> being greats foundations for building towards a solution addressing the
> issues above, I will just ask you to read his original words:
>
> https://lists.freedesktop.org/archives/dri-devel/2014-September/067984.html
>
> == Open issues ==
>
> Here are the open issues we have identified with the solution proposed by
> David:
>
>   1) Backlight device interoperability: How far should we support
>      mixing the backlight device and brightness property? Should it be
>      unidirectional or bi-directional? What about the start-up value
>      exposed by the brightness property?
>
>   2) How many steps should be exposed: fixed or driver-dependent?
>
>   3) Expected output curve: power? luminance? Simply monotonically
>      increasing?
>
>   4) Should the userspace be able to turn off the backlight? If so, how
>      should it do it? What can we do to let the userspace distinguish
>      between backlight off or on?
>
>   5) Should we expose to the userspace what is the current backlight
>      power?
>
> Here is our current point of view on the matter:
>
> === 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.
>
> 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...
>
> === 2) How many steps should be exposed ===
>
> If the KMS property exposes the same number of steps as the backlight
> driver, it allows us to get a bijective function between the two interfaces,
> and allow a bi-directional communication. The downside of this is that it
> forces the userspace to deal with a variable number of steps which can range
> from 4 to 1k+. Also, the userspace would be able to handle the case where
> there are less steps than it would like to expose.
>
> If the KMS property exposes a fixed number of steps (say 100), it becomes
> easy for the userspace to express the wanted brightness. However, on drivers
> exposing less than these 100 steps, we cannot guarantee that any change in
> the value will produce any change. If there is only one possible value (on
> or off), the user may be trying the change the brightness, a GUI would show
> what is the expected backlight state, but no change in the luminance would
> be seen, which is pretty bad.

Yes, I don't think we want to normalize anything here. It would
essentially be hiding functionality from user space, which then can't
expose it in the user interface. As you say, if the backlight slider
moves, but the backlight level didn't change, that's weird. On the
other hand if user space knows the number of levels it can give you a
consistent slider, and normalizing in user space is not that hard
(that's how things currently work after all, so people should be used
to it).

>
> === 3) and 4) ===
>
> These issues are not handled at all by the backlight device sysfs interface.
>
> But since David already had to add an in-kernel interface to access the
> backlight devices [0], we could add capabilities to the drivers while
> keeping the backward compatibility.
>
> From the in-kernel interface, it is already possible to turn on and off the
> backlight for sure (when supported, but this is also reported properly).
> However, what is not supported is to know what the value 0 means (lowest
> setting possible but not turned off, or no power at all).
>
> 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 would suggest we design an interface that will allow good drivers to
> expose as many features as possible, but yet gracefully degrade if
> information is not present.

Yes the ability to turn off the backlight is important. Some
backlights are not stable at low levels, so they don't expose these
low levels and effectively level 0 is not off (it is the lowest level
which works). So I guess the question is how should that non-linearity
be exposed versus the ability to turn it off completely.

>
> Over time, drivers will improve to expose information about the platform,
> and the user experience will improve as a result.
>
> [0]
> https://lists.freedesktop.org/archives/dri-devel/2014-September/067987.html
>
> ===  5) Exposing the current backlight power?  ===
>
> The backlight_current interface in the backlight devices is meant to expose
> the currently-used backlight value, regardless of the wanted value that
> should be used when the backlight is not off.
>
> My current stance on this is that this should not be needed. The userspace
> should describe the intent of the user (wanted backlight level) and trust
> the KMS property to turn off the backlight when entering DPMS.

Are we saying that we are putting the kernel in charge of  display vs
backlight sequencing? Currently on some ARM boards with separate pwm
backlight drivers that's not the case. Don't get me wrong, I think the
kernel should be in charge of enforcing sequencing because otherwise
user space can damage hardware, I'm just pointing out that right now
it isn't the case.

Stéphane

>
> == 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)
>  - Uni-directional: KMS -> backlight
>  - 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!
>  - 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.
>
> 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].
>
> [1] Must be able to support displays which are visible even with the
> backlight switched off.
>
> [2] The main downside corner case with this is that if the driver
> doesn't know whether it can switch off the backlight, 0 might end up
> meaning the minimum visible, and 1 is the second lowest visible, and
> with a userspace that avoids black display, the user can't use the
> lowest brightness setting.
>
> [3] This is not unlike the "brightness" property in the backlight class
> sysfs interface. The intention is that the drm interface does not have
> an equivalent of "actual_brightness".
> _______________________________________________
> dri-devel mailing list
> dri-devel at lists.freedesktop.org
> https://lists.freedesktop.org/mailman/listinfo/dri-devel