From: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
To: Linux Doc Mailing List <linux-doc@vger.kernel.org>
Cc: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>,
"Jonathan Corbet" <corbet@lwn.net>,
Daniel Thompson <daniel.thompson@linaro.org>,
Jingoo Han <jingoohan1@gmail.com>,
Lee Jones <lee.jones@linaro.org>,
dri-devel@lists.freedesktop.org, linux-kernel@vger.kernel.org
Subject: [PATCH v2 37/39] docs: ABI: sysfs-class-backlight: unify ABI documentation
Date: Fri, 30 Oct 2020 08:40:56 +0100 [thread overview]
Message-ID: <342195ad5a819d9bcfcebc133c77ab69b4211672.1604042072.git.mchehab+huawei@kernel.org> (raw)
In-Reply-To: <cover.1604042072.git.mchehab+huawei@kernel.org>
Both adp8860 and adp8870 define some extensions to the
backlight class. This causes warnings:
Warning: /sys/class/backlight/<backlight>/ambient_light_level is defined 2 times: /sys/class/backlight/<backlight>/ambient_light_level:8 /sys/class/backlight/<backlight>/ambient_light_level:30
Warning: /sys/class/backlight/<backlight>/ambient_light_zone is defined 2 times: /sys/class/backlight/<backlight>/ambient_light_zone:18 /sys/class/backlight/<backlight>/ambient_light_zone:40
As ABI definitions shouldn't be duplicated.
Unfortunately, the ABI is dependent on the specific device
features. As such, ambient_light_level range is somewhat
different among the supported devices.
The ambient_light_zone is even worse: the meanings of each
preset are different, and there's no ABI to retrieve
the supported types nor their meanins. Unfortunately,
it is too late to fix it without causing regressions,
as this has been used since Kernel v2.6.35.
Rewrite those ABI documentation using the current documentation
as a reference, and double-checking at the datasheets:
https://www.analog.com/media/en/technical-documentation/data-sheets/ADP8870.pdf
https://www.analog.com/media/en/technical-documentation/data-sheets/ADP8860.pdf
in order to properly document the differences between those two
drivers.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
.../ABI/testing/sysfs-class-backlight | 60 +++++++++++++++++++
.../ABI/testing/sysfs-class-backlight-adp8860 | 21 +------
.../sysfs-class-backlight-driver-adp8870 | 30 +---------
3 files changed, 65 insertions(+), 46 deletions(-)
diff --git a/Documentation/ABI/testing/sysfs-class-backlight b/Documentation/ABI/testing/sysfs-class-backlight
index 3ab175a3f5cb..1fc86401bf95 100644
--- a/Documentation/ABI/testing/sysfs-class-backlight
+++ b/Documentation/ABI/testing/sysfs-class-backlight
@@ -24,3 +24,63 @@ Description:
non-linear
The brightness changes non-linearly with each step. Brightness
controls should use a linear mapping for a linear perception.
+
+What: /sys/class/backlight/<backlight>/ambient_light_level
+Date: Apr, 2010
+KernelVersion: v2.6.35
+Contact: Michael Hennerich <michael.hennerich@analog.com>
+Description:
+ (RO) Get conversion value of the light sensor.
+
+ The value is automatically updated every 80 ms when the
+ light sensor is enabled.
+
+ The value range is device-driver specific:
+
+ For ADP8870:
+
+ It returns integer between 0 (dark) and 8000 (max ambient
+ brightness).
+
+ For ADP8860:
+
+ It returns a 13-bits integer.
+
+What: /sys/class/backlight/<backlight>/ambient_light_zone
+Date: Apr, 2010
+KernelVersion: v2.6.35
+Contact: Michael Hennerich <michael.hennerich@analog.com>,
+ device-drivers-devel@blackfin.uclinux.org
+
+Description:
+ (RW) Read or write the specific brightness level at which the
+ backlight operates.
+
+ The value meaning is device-driver specific:
+
+ For ADP8860:
+
+ == ==========================
+ 0 Off: Backlight set to 0 mA
+ 1 Level 1: daylight
+ 2 Level 2: bright
+ 3 Level 3: dark
+ == ==========================
+
+ For ADP8870:
+
+ == ==========================
+ 0 Off: Backlight set to 0 mA
+ 1 Level 1: daylight
+ 2 Level 2: bright
+ 3 Level 3: office
+ 4 Level 4: indoor
+ 5 Level 5: dark
+ == ==========================
+
+ Writing 0 returns to normal/automatic ambient light level
+ operation.
+
+ It can be enabled by writing the value stored in
+ /sys/class/backlight/<backlight>/max_brightness to
+ /sys/class/backlight/<backlight>/brightness.
diff --git a/Documentation/ABI/testing/sysfs-class-backlight-adp8860 b/Documentation/ABI/testing/sysfs-class-backlight-adp8860
index 54d61c788b1b..6610ac73f9ba 100644
--- a/Documentation/ABI/testing/sysfs-class-backlight-adp8860
+++ b/Documentation/ABI/testing/sysfs-class-backlight-adp8860
@@ -6,25 +6,8 @@ adp8860, adp8861 and adp8863 devices: daylight (level 1), office (level 2) and
dark (level 3). By default the brightness operates at the daylight brightness
level.
-What: /sys/class/backlight/<backlight>/ambient_light_level
-Date: Apr, 2010
-KernelVersion: v2.6.35
-Contact: Michael Hennerich <michael.hennerich@analog.com>
-Description:
- (RO) 13-bit conversion value for the first light sensor—high
- byte (Bit 12 to Bit 8). The value is updated every 80 ms (when
- the light sensor is enabled).
-
-
-What: /sys/class/backlight/<backlight>/ambient_light_zone
-Date: Apr, 2010
-KernelVersion: v2.6.35
-Contact: Michael Hennerich <michael.hennerich@analog.com>
-Description:
- (RW) Read or write the specific level at which the backlight
- operates. Value "0" enables automatic ambient light sensing, and
- values "1", "2" or "3" set the control to daylight, office or
- dark respectively.
+See also /sys/class/backlight/<backlight>/ambient_light_level and
+/sys/class/backlight/<backlight>/ambient_light_zone.
What: /sys/class/backlight/<backlight>/l1_daylight_max
diff --git a/Documentation/ABI/testing/sysfs-class-backlight-driver-adp8870 b/Documentation/ABI/testing/sysfs-class-backlight-driver-adp8870
index 33e648808117..b08ca912cad4 100644
--- a/Documentation/ABI/testing/sysfs-class-backlight-driver-adp8870
+++ b/Documentation/ABI/testing/sysfs-class-backlight-driver-adp8870
@@ -1,3 +1,6 @@
+See also /sys/class/backlight/<backlight>/ambient_light_level and
+/sys/class/backlight/<backlight>/ambient_light_zone.
+
What: /sys/class/backlight/<backlight>/<ambient light zone>_max
What: /sys/class/backlight/<backlight>/l1_daylight_max
What: /sys/class/backlight/<backlight>/l2_bright_max
@@ -27,30 +30,3 @@ Description:
set to 0. Full off when the backlight is disabled.
This file will also show the dim brightness level stored for
this <ambient light zone>.
-
-What: /sys/class/backlight/<backlight>/ambient_light_level
-Date: May 2011
-KernelVersion: 3.0
-Contact: device-drivers-devel@blackfin.uclinux.org
-Description:
- Get conversion value of the light sensor.
- This value is updated every 80 ms (when the light sensor
- is enabled). Returns integer between 0 (dark) and
- 8000 (max ambient brightness)
-
-What: /sys/class/backlight/<backlight>/ambient_light_zone
-Date: May 2011
-KernelVersion: 3.0
-Contact: device-drivers-devel@blackfin.uclinux.org
-Description:
- Get/Set current ambient light zone. Reading returns
- integer between 1..5 (1 = daylight, 2 = bright, ..., 5 = dark).
- Writing a value between 1..5 forces the backlight controller
- to enter the corresponding ambient light zone.
- Writing 0 returns to normal/automatic ambient light level
- operation. The ambient light sensing feature on these devices
- is an extension to the API documented in
- Documentation/ABI/stable/sysfs-class-backlight.
- It can be enabled by writing the value stored in
- /sys/class/backlight/<backlight>/max_brightness to
- /sys/class/backlight/<backlight>/brightness.
--
2.26.2
next prev parent reply other threads:[~2020-10-30 7:42 UTC|newest]
Thread overview: 62+ messages / expand[flat|nested] mbox.gz Atom feed top
2020-10-30 7:40 [PATCH v2 00/39] ABI: add it to the documentation build system Mauro Carvalho Chehab
2020-10-30 7:40 ` [PATCH v2 01/39] scripts: get_abi.pl: change script to allow parsing in ReST mode Mauro Carvalho Chehab
2020-10-30 7:40 ` [PATCH v2 02/39] scripts: get_abi.pl: fix parsing on " Mauro Carvalho Chehab
2020-10-30 7:40 ` [PATCH v2 03/39] scripts: get_abi.pl: Allow optionally record from where a line came from Mauro Carvalho Chehab
2020-10-30 7:40 ` [PATCH v2 04/39] scripts: get_abi.pl: improve its parser to better catch up indentation Mauro Carvalho Chehab
2020-10-30 7:40 ` [PATCH v2 05/39] scripts: get_abi.pl: cleanup ABI cross-reference logic Mauro Carvalho Chehab
2020-10-30 7:40 ` [PATCH v2 06/39] scripts: get_abi.pl: detect duplicated ABI definitions Mauro Carvalho Chehab
2020-10-30 7:40 ` [PATCH v2 07/39] scripts: get_abi.pl: output users in ReST format Mauro Carvalho Chehab
2020-10-30 7:40 ` [PATCH v2 08/39] scripts: get_abi.pl: prevent duplicated file names Mauro Carvalho Chehab
2020-10-30 7:40 ` [PATCH v2 09/39] scripts: get_abi.pl: use bold font for ABI definitions Mauro Carvalho Chehab
2020-10-30 7:40 ` [PATCH v2 10/39] scripts: get_abi.pl: auto-generate cross references Mauro Carvalho Chehab
2020-10-30 7:40 ` [PATCH v2 11/39] docs: kernellog.py: add support for info() Mauro Carvalho Chehab
2020-10-30 7:40 ` [PATCH v2 12/39] docs: kernel_abi.py: add a script to parse ABI documentation Mauro Carvalho Chehab
2020-10-30 7:40 ` [PATCH v2 13/39] docs: kernel_abi.py: fix UTF-8 support Mauro Carvalho Chehab
2020-10-30 7:40 ` [PATCH v2 14/39] docs: kernel_abi.py: make it compatible with Sphinx 1.7+ Mauro Carvalho Chehab
2020-10-30 7:40 ` [PATCH v2 15/39] docs: kernel_abi.py: use --enable-lineno for get_abi.pl Mauro Carvalho Chehab
2020-10-30 7:40 ` [PATCH v2 16/39] docs: kernel_abi.py: Handle with a lazy Sphinx parser Mauro Carvalho Chehab
2020-10-30 7:40 ` [PATCH v2 17/39] docs: add ABI documentation to the admin-guide book Mauro Carvalho Chehab
2020-10-30 7:40 ` [PATCH v2 18/39] docs: ABI: README: specify that files should be ReST compatible Mauro Carvalho Chehab
2020-10-30 7:40 ` [PATCH v2 19/39] docs: ABI: stable: make files " Mauro Carvalho Chehab
2020-10-30 10:04 ` Srinivas Kandagatla
2020-10-30 7:40 ` [PATCH v2 20/39] docs: ABI: testing: make the files compatible with ReST output Mauro Carvalho Chehab
2020-10-30 9:19 ` Fabrice Gasnier
2020-10-30 10:09 ` Mauro Carvalho Chehab
2020-11-02 11:04 ` Fabrice Gasnier
2020-11-02 12:46 ` Greg Kroah-Hartman
2020-11-02 14:42 ` Mauro Carvalho Chehab
2020-11-08 16:56 ` Jonathan Cameron
2020-11-10 7:26 ` Duplicated ABI entries - Was: " Mauro Carvalho Chehab
2020-11-10 18:18 ` Randy Dunlap
2020-11-14 15:27 ` Jonathan Cameron
2020-10-30 17:26 ` Frederic Barrat
2020-10-30 7:40 ` [PATCH v2 21/39] docs: ABI: sysfs-uevent: make it " Mauro Carvalho Chehab
2020-10-30 7:40 ` [PATCH v2 22/39] docs: ABI: make it parse ABI/stable as ReST-compatible files Mauro Carvalho Chehab
2020-10-30 7:40 ` [PATCH v2 23/39] docs: ABI: create a 2-depth index for ABI Mauro Carvalho Chehab
2020-10-30 7:40 ` [PATCH v2 24/39] docs: ABI: don't escape ReST-incompatible chars from obsolete and removed Mauro Carvalho Chehab
2020-10-30 7:40 ` [PATCH v2 25/39] docs: abi-testing.rst: enable --rst-sources when building docs Mauro Carvalho Chehab
2020-10-30 7:40 ` [PATCH v2 26/39] docs: Kconfig/Makefile: add a check for broken ABI files Mauro Carvalho Chehab
2020-10-30 16:49 ` Randy Dunlap
2020-10-30 7:40 ` [PATCH v2 27/39] docs: ABI: convert testing/configfs-acpi to ReST Mauro Carvalho Chehab
2020-10-30 14:33 ` Rafael J. Wysocki
2020-10-30 7:40 ` [PATCH v2 28/39] docs: ABI: fix syntax to be parsed using ReST notation Mauro Carvalho Chehab
2020-10-30 14:39 ` Rafael J. Wysocki
2020-11-02 5:50 ` Jinpu Wang
2020-11-02 18:39 ` Joseph, Jithu
2020-10-30 7:40 ` [PATCH v2 29/39] docs: ABI: vdso: use the right format for ABI Mauro Carvalho Chehab
2020-10-30 7:40 ` [PATCH v2 30/39] docs: ABI: sysfs-bus-nvdimm: " Mauro Carvalho Chehab
2020-10-30 7:40 ` [PATCH v2 31/39] docs: ABI: cleanup several ABI documents Mauro Carvalho Chehab
2020-10-30 8:27 ` Rojewski, Cezary
2020-10-30 9:49 ` Suzuki K Poulose
2020-10-30 11:11 ` Ilya Dryomov
2020-10-30 16:42 ` Mathieu Poirier
2020-10-30 23:23 ` Peter Chen
2020-11-01 3:43 ` Dmitry Torokhov
2020-10-30 7:40 ` [PATCH v2 32/39] docs: ABI: change read/write attributes Mauro Carvalho Chehab
2020-10-30 7:40 ` [PATCH v2 33/39] docs: ABI: stable: remove a duplicated documentation Mauro Carvalho Chehab
2020-10-30 7:40 ` [PATCH v2 34/39] docs: ABI: unify /sys/class/leds/<led>/brightness documentation Mauro Carvalho Chehab
2020-10-30 7:40 ` [PATCH v2 35/39] docs: ABI: sysfs-class-power: unify duplicated properties Mauro Carvalho Chehab
2020-10-30 7:40 ` [PATCH v2 36/39] docs: ABI: sysfs-c2port: remove a duplicated entry Mauro Carvalho Chehab
2020-10-30 7:40 ` Mauro Carvalho Chehab [this message]
2020-10-30 7:40 ` [PATCH v2 38/39] docs: ABI: sysfs-class-led-trigger-pattern: remove hw_pattern duplication Mauro Carvalho Chehab
2020-10-30 7:40 ` [PATCH v2 39/39] scripts: get_abi.pl: assume ReST format by default Mauro Carvalho Chehab
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=342195ad5a819d9bcfcebc133c77ab69b4211672.1604042072.git.mchehab+huawei@kernel.org \
--to=mchehab+huawei@kernel.org \
--cc=corbet@lwn.net \
--cc=daniel.thompson@linaro.org \
--cc=dri-devel@lists.freedesktop.org \
--cc=jingoohan1@gmail.com \
--cc=lee.jones@linaro.org \
--cc=linux-doc@vger.kernel.org \
--cc=linux-kernel@vger.kernel.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).