[systemd-devel] [PATCH v2] backlight: let the administrator override clamping

[Topi Miettinen]

On my computer, the minimum brightness enforced by clamping in
backlight is too bright.

Add a new option to override clamping in unit file. While at it, describe
the clamping in documentation.
---
 man/systemd-backlight at .service.xml | 27 +++++++++++++++++++++++++--
 src/backlight/backlight.c          | 11 ++++++-----
 2 files changed, 31 insertions(+), 7 deletions(-)

diff --git a/man/systemd-backlight at .service.xml b/man/systemd-backlight at .service.xml
index 453afbf..0d30957 100644
--- a/man/systemd-backlight at .service.xml
+++ b/man/systemd-backlight at .service.xml
@@ -48,7 +48,17 @@
 
         <refsynopsisdiv>
                 <para><filename>systemd-backlight at .service</filename></para>
-                <para><filename>/usr/lib/systemd/systemd-backlight</filename></para>
+                <cmdsynopsis>
+                        <command>systemd-backlight</command>
+                        <arg choice="plain">save</arg>
+                        <arg choice="opt"><replaceable>PATH</replaceable></arg>
+                </cmdsynopsis>
+                <cmdsynopsis>
+                        <command>systemd-backlight</command>
+                        <arg choice="plain">load</arg>
+                        <arg choice="opt"><replaceable>PATH</replaceable></arg>
+                        <arg choice="opt"><replaceable>--allow-any-brightness</replaceable></arg>
+                </cmdsynopsis>
         </refsynopsisdiv>
 
         <refsect1>
@@ -58,7 +68,20 @@
                 is a service that restores the display backlight
                 brightness at early boot and saves it at shutdown. On
                 disk, the backlight brightness is stored in
-                <filename>/var/lib/systemd/backlight/</filename>.</para>
+                <filename>/var/lib/systemd/backlight/</filename>. During
+                loading, unless option
+                <replaceable>--allow-any-brightness</replaceable> is
+                specified, the brightness is clamped to at least value
+                <literal>1</literal> or 5% of maximum brightness. This
+                is to avoid an unpowered display due to poor API
+                design in kernel (unfixed as of 2015-01-18) that does
+                not allow user space to know the difference between
+                lowest brightness and powering off the
+                backlight.</para>
+
+                <para><replaceable>PATH</replaceable> identifies the
+                display brightness control device. It is resolved by
+                udev.</para>
         </refsect1>
 
         <refsect1>
diff --git a/src/backlight/backlight.c b/src/backlight/backlight.c
index 1271a66..96a25d8 100644
--- a/src/backlight/backlight.c
+++ b/src/backlight/backlight.c
@@ -255,7 +255,7 @@ static void clamp_brightness(struct udev_device *device, char **value, unsigned
                         return;
                 }
 
-                log_info("Saved brightness %s %s to %s.", old_value,
+                log_info("Saved brightness %s %s to %s (use --allow-any-brightness to override).", old_value,
                          new_brightness > brightness ?
                          "too low; increasing" : "too high; decreasing",
                          *value);
@@ -272,8 +272,8 @@ int main(int argc, char *argv[]) {
         unsigned max_brightness;
         int r;
 
-        if (argc != 3) {
-                log_error("This program requires two arguments.");
+        if (argc < 3 || argc > 4) {
+                log_error("This program requires two or three arguments.");
                 return EXIT_FAILURE;
         }
 
@@ -389,8 +389,9 @@ int main(int argc, char *argv[]) {
                         log_error_errno(r, "Failed to read %s: %m", saved);
                         return EXIT_FAILURE;
                 }
-
-                clamp_brightness(device, &value, max_brightness);
+                /* Don't clamp brightness if asked */
+                if (!(argc == 4 && streq(argv[3], "--allow-any-brightness")))
+                        clamp_brightness(device, &value, max_brightness);
 
                 r = udev_device_set_sysattr_value(device, "brightness", value);
                 if (r < 0) {
-- 
2.1.4