Commit bd6e8441 authored by Mauro Carvalho Chehab's avatar Mauro Carvalho Chehab Committed by Greg Kroah-Hartman
Browse files

docs: ABI: sysfs-class-backlight: unify ABI documentation

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.

Acked-by: default avatarJonathan Corbet <corbet@lwn.net>
Signed-off-by: default avatarMauro Carvalho Chehab <mchehab+huawei@kernel.org>
Link: https://lore.kernel.org/r/342195ad5a819d9bcfcebc133c77ab69b4211672.1604042072.git.mchehab+huawei@kernel.org


Signed-off-by: default avatarGreg Kroah-Hartman <gregkh@linuxfoundation.org>
parent 1b3023ef
Loading
Loading
Loading
Loading
+60 −0
Original line number Diff line number Diff line
@@ -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.
+2 −19
Original line number Diff line number Diff line
@@ -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
+3 −27
Original line number Diff line number Diff line
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.