world leader in high performance signal processing
This version (18 Feb 2013 16:53) was approved by larsc.The Previously approved version (18 Feb 2013 14:48) is available.Diff

ADP8860 Back-light LED Linux Driver

Supported Devices

Evaluation Boards

Description

Configuration

Software configurable features

Backlight:

Feature ADP8860 ADP8863 ADP8861
Ambient Light Sensor Support (ALS)
Three programmable ambient light sensing
zones for optimal backlight power savings
Configurable Fade On/Off times
Configurable Fade Law functions
Configurable ALS filter settings
Configurable Brightness/Intensity in 128 steps

LED:

Feature ADP8860 ADP8863 ADP8861
Up to 7 LEDs configurable
Configurable Fade On/Off times
LED Blink On/Off times
Configurable Fade Law functions
Configurable Brightness/Intensity in 128 steps from [0..255]

Source Code

Status

Source Mainlined?
git Yes

Files

Instructions / Theory of operation

Backlight control

With the ADP8860 driver installed, you will find sysfs files in the
/sys/class/backlight/adp8860_bl/
directory. You will be able to query and set the current screen
brightness:

brightness
get/set screen brightness (an integer between 0 and 126)
writing 127 will enable the Ambient Light Sensor.
actual_brightness
reading from this file will query the HW to get real brightness value.
max_brightness
the maximum brightness value.
bl_power
Current FB Power mode (0: full on, 1..3: power saving modes; 4: full off).

ADP8860 Specific Backlight controls

The ADP8860 features 3 individually programmable Ambient Light Sensing Zones:

l1_daylight_dim
Ambient Light Zone Daylight: Backlight DIM Intensity (an integer between 0 and 127, typically set to 0).
l1_daylight_max
Ambient Light Zone Daylight: Backlight Intensity (an integer between 0 and 127).
l2_office_dim
Ambient Light Zone Office: Backlight DIM Intensity (an integer between 0 and 127, typically set to 0)
l2_office_max
Ambient Light Zone Office: Backlight Intensity (an integer between 0 and 127)
l3_dark_dim
Ambient Light Zone Dark: Backlight DIM Intensity (an integer between 0 and 127, typically set to 0)
l3_dark_max
Ambient Light Zone Dark: Backlight Intensity (an integer between 0 and 127)
ambient_light_level
Get conversion value of the first 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)
ambient_light_zone
Get/Set current Ambient Light Zone. Reading returns integer between 1..3
(1 = Daylight, 2 = office, 3 = dark). Writing a value between 1..3 forces the Backlight controller
to enter the corresponding Ambient Light Zone. Writing 0 returns to normal operation.

LED handling under Linux

LEDs not assigned to the Backlight are optionally exposed to the Linux LEDs Class.

The LED class allows control of LEDs from userspace. LEDs appear in /sys/class/leds/. The brightness file will set the brightness of the LED (taking a value 0-255). The LEDS class also introduces the optional concept of an LED trigger. A trigger is a kernel based source of led events, such as ide-disk or backlight control.
For more information read linux/Documentaion/leds-class.txt

brightness
get/set LED brightness (an integer between 0 and 255)
max_brightness
the maximum brightness value.

Example platform device initialization

For compile time configuration, it’s common Linux practice to keep board- and application-specific configuration out of the main driver file, instead putting it into the board support file.

For devices on custom boards, as typical of embedded and SoC-(system-on-chip) based hardware, Linux uses platform_data to point to board-specific structures describing devices and how they are connected to the SoC. This can include available ports, chip variants, preferred modes, default initialization, additional pin roles, and so on. This shrinks the board-support packages (BSPs) and minimizes board and application specific #ifdefs in drivers.

21 Oct 2010 16:10 · Michael Hennerich

platform_data: Platform data specific to the ADP8860 device.
Includes what LEDs are available, feature selections and default initialization.

#include <linux/i2c/adp8860.h>

file: arch/blackfin/mach-bf537/boards/stamp.c

scm failed with exit code 1:
file does not exist in git: http://raw.github.com/analogdevicesinc/linux/master/arch/blackfin/mach-bf537/boards/stamp.c

file: arch/blackfin/mach-bf537/boards/stamp.c

static struct adp8860_backlight_platform_data adp8860_pdata = {
	.bl_led_assign = ADP8860_BL_D1 | ADP8860_BL_D2 | ADP8860_BL_D3 |
			 ADP8860_BL_D4 | ADP8860_BL_D5 | ADP8860_BL_D6,	/* 1 = Backlight 0 = Individual LED */
 
	.bl_fade_in = ADP8860_FADE_T_1200ms,		/* Backlight Fade-In Timer */
	.bl_fade_out = ADP8860_FADE_T_1200ms,		/* Backlight Fade-Out Timer */
	.bl_fade_law = ADP8860_FADE_LAW_CUBIC1,		/* fade-on/fade-off transfer characteristic */
 
	.en_ambl_sens = 1,				/* 1 = enable ambient light sensor */
	.abml_filt = ADP8860_BL_AMBL_FILT_320ms,	/* Light sensor filter time */
 
	.l1_daylight_max = ADP8860_BL_CUR_mA(20),	/* use BL_CUR_mA(I) 0 <= I <= 30 mA */
	.l1_daylight_dim = ADP8860_BL_CUR_mA(0),	/* typ = 0, use BL_CUR_mA(I) 0 <= I <= 30 mA */
	.l2_office_max = ADP8860_BL_CUR_mA(6),		/* use BL_CUR_mA(I) 0 <= I <= 30 mA */
	.l2_office_dim = ADP8860_BL_CUR_mA(0),		/* typ = 0, use BL_CUR_mA(I) 0 <= I <= 30 mA */
	.l3_dark_max = ADP8860_BL_CUR_mA(2),		/* use BL_CUR_mA(I) 0 <= I <= 30 mA */
	.l3_dark_dim = ADP8860_BL_CUR_mA(0),		/* typ = 0, use BL_CUR_mA(I) 0 <= I <= 30 mA */
 
	.l2_trip = ADP8860_L2_COMP_CURR_uA(710),	/* use L2_COMP_CURR_uA(I) 0 <= I <= 1106 uA */
	.l2_hyst = ADP8860_L2_COMP_CURR_uA(73),		/* use L2_COMP_CURR_uA(I) 0 <= I <= 1106 uA */
	.l3_trip = ADP8860_L3_COMP_CURR_uA(43),		/* use L3_COMP_CURR_uA(I) 0 <= I <= 138 uA */
	.l3_hyst = ADP8860_L3_COMP_CURR_uA(11),		/* use L3_COMP_CURR_uA(I) 0 <= I <= 138 uA */
 
	.leds = adp8860_leds,
	.num_leds = ARRAY_SIZE(adp8860_leds),
	.led_fade_law = ADP8860_FADE_LAW_SQUARE,	/* fade-on/fade-off transfer characteristic */
	.led_fade_in = ADP8860_FADE_T_600ms,
	.led_fade_out = ADP8860_FADE_T_600ms,
	.led_on_time = ADP8860_LED_ONT_200ms,
};

Declaring I2C devices

Unlike PCI or USB devices, I2C devices are not enumerated at the hardware level. Instead, the software must know which devices are connected on each I2C bus segment, and what address these devices are using. For this reason, the kernel code must instantiate I2C devices explicitly. There are different ways to achieve this, depending on the context and requirements. However the most common method is to declare the I2C devices by bus number.

This method is appropriate when the I2C bus is a system bus, as in many embedded systems, wherein each I2C bus has a number which is known in advance. It is thus possible to pre-declare the I2C devices that inhabit this bus. This is done with an array of struct i2c_board_info, which is registered by calling i2c_register_board_info().

So, to enable such a driver one need only edit the board support file by adding an appropriate entry to i2c_board_info.

For more information see: Documentation/i2c/instantiating-devices

21 Oct 2010 16:10 · Michael Hennerich
static struct i2c_board_info __initdata bfin_i2c_board_info[] = {
#if defined(CONFIG_BACKLIGHT_ADP8860) || defined(CONFIG_BACKLIGHT_ADP8860_MODULE)
	{
		I2C_BOARD_INFO("adp8860", 0x2A),
		.platform_data = (void *)&adp8860_pdata,
	},
#endif
}

Adding Linux driver support

Configure kernel with “make menuconfig” (alternatively use “make xconfig” or “make qconfig”)

The ADP8860 Backlight driver depends on I2C. It therefore requires selected I2C support to show up during kernel configuration.

Device Drivers  --->
	Graphics support  --->
		[*] Backlight & LCD device support  ---

ADP8860 Back-light LED Linux Driver

Supported Devices

Evaluation Boards

Description

Configuration

Software configurable features

Backlight:

Feature ADP8860 ADP8863 ADP8861
Ambient Light Sensor Support (ALS)
Three programmable ambient light sensing
zones for optimal backlight power savings
Configurable Fade On/Off times
Configurable Fade Law functions
Configurable ALS filter settings
Configurable Brightness/Intensity in 128 steps

LED:

Feature ADP8860 ADP8863 ADP8861
Up to 7 LEDs configurable
Configurable Fade On/Off times
LED Blink On/Off times
Configurable Fade Law functions
Configurable Brightness/Intensity in 128 steps from [0..255]

Source Code

Status

Source Mainlined?
git Yes

Files

Instructions / Theory of operation

Backlight control

With the ADP8860 driver installed, you will find sysfs files in the
/sys/class/backlight/adp8860_bl/
directory. You will be able to query and set the current screen
brightness:

brightness
get/set screen brightness (an integer between 0 and 126)
writing 127 will enable the Ambient Light Sensor.
actual_brightness
reading from this file will query the HW to get real brightness value.
max_brightness
the maximum brightness value.
bl_power
Current FB Power mode (0: full on, 1..3: power saving modes; 4: full off).

ADP8860 Specific Backlight controls

The ADP8860 features 3 individually programmable Ambient Light Sensing Zones:

l1_daylight_dim
Ambient Light Zone Daylight: Backlight DIM Intensity (an integer between 0 and 127, typically set to 0).
l1_daylight_max
Ambient Light Zone Daylight: Backlight Intensity (an integer between 0 and 127).
l2_office_dim
Ambient Light Zone Office: Backlight DIM Intensity (an integer between 0 and 127, typically set to 0)
l2_office_max
Ambient Light Zone Office: Backlight Intensity (an integer between 0 and 127)
l3_dark_dim
Ambient Light Zone Dark: Backlight DIM Intensity (an integer between 0 and 127, typically set to 0)
l3_dark_max
Ambient Light Zone Dark: Backlight Intensity (an integer between 0 and 127)
ambient_light_level
Get conversion value of the first 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)
ambient_light_zone
Get/Set current Ambient Light Zone. Reading returns integer between 1..3
(1 = Daylight, 2 = office, 3 = dark). Writing a value between 1..3 forces the Backlight controller
to enter the corresponding Ambient Light Zone. Writing 0 returns to normal operation.

LED handling under Linux

LEDs not assigned to the Backlight are optionally exposed to the Linux LEDs Class.

The LED class allows control of LEDs from userspace. LEDs appear in /sys/class/leds/. The brightness file will set the brightness of the LED (taking a value 0-255). The LEDS class also introduces the optional concept of an LED trigger. A trigger is a kernel based source of led events, such as ide-disk or backlight control.
For more information read linux/Documentaion/leds-class.txt

brightness
get/set LED brightness (an integer between 0 and 255)
max_brightness
the maximum brightness value.

Example platform device initialization

For compile time configuration, it’s common Linux practice to keep board- and application-specific configuration out of the main driver file, instead putting it into the board support file.

For devices on custom boards, as typical of embedded and SoC-(system-on-chip) based hardware, Linux uses platform_data to point to board-specific structures describing devices and how they are connected to the SoC. This can include available ports, chip variants, preferred modes, default initialization, additional pin roles, and so on. This shrinks the board-support packages (BSPs) and minimizes board and application specific #ifdefs in drivers.

21 Oct 2010 16:10 · Michael Hennerich

platform_data: Platform data specific to the ADP8860 device.
Includes what LEDs are available, feature selections and default initialization.

#include <linux/i2c/adp8860.h>

file: arch/blackfin/mach-bf537/boards/stamp.c

static struct led_info adp8860_leds[] = {
	{
		.name = "adp8860-led7",
		.default_trigger = "none",
		.flags = ADP8860_LED_D7 | ADP8860_LED_OFFT_600ms,
	},
};

file: arch/blackfin/mach-bf537/boards/stamp.c

static struct adp8860_backlight_platform_data adp8860_pdata = {
	.bl_led_assign = ADP8860_BL_D1 | ADP8860_BL_D2 | ADP8860_BL_D3 |
			 ADP8860_BL_D4 | ADP8860_BL_D5 | ADP8860_BL_D6,	/* 1 = Backlight 0 = Individual LED */
 
	.bl_fade_in = ADP8860_FADE_T_1200ms,		/* Backlight Fade-In Timer */
	.bl_fade_out = ADP8860_FADE_T_1200ms,		/* Backlight Fade-Out Timer */
	.bl_fade_law = ADP8860_FADE_LAW_CUBIC1,		/* fade-on/fade-off transfer characteristic */
 
	.en_ambl_sens = 1,				/* 1 = enable ambient light sensor */
	.abml_filt = ADP8860_BL_AMBL_FILT_320ms,	/* Light sensor filter time */
 
	.l1_daylight_max = ADP8860_BL_CUR_mA(20),	/* use BL_CUR_mA(I) 0 <= I <= 30 mA */
	.l1_daylight_dim = ADP8860_BL_CUR_mA(0),	/* typ = 0, use BL_CUR_mA(I) 0 <= I <= 30 mA */
	.l2_office_max = ADP8860_BL_CUR_mA(6),		/* use BL_CUR_mA(I) 0 <= I <= 30 mA */
	.l2_office_dim = ADP8860_BL_CUR_mA(0),		/* typ = 0, use BL_CUR_mA(I) 0 <= I <= 30 mA */
	.l3_dark_max = ADP8860_BL_CUR_mA(2),		/* use BL_CUR_mA(I) 0 <= I <= 30 mA */
	.l3_dark_dim = ADP8860_BL_CUR_mA(0),		/* typ = 0, use BL_CUR_mA(I) 0 <= I <= 30 mA */
 
	.l2_trip = ADP8860_L2_COMP_CURR_uA(710),	/* use L2_COMP_CURR_uA(I) 0 <= I <= 1106 uA */
	.l2_hyst = ADP8860_L2_COMP_CURR_uA(73),		/* use L2_COMP_CURR_uA(I) 0 <= I <= 1106 uA */
	.l3_trip = ADP8860_L3_COMP_CURR_uA(43),		/* use L3_COMP_CURR_uA(I) 0 <= I <= 138 uA */
	.l3_hyst = ADP8860_L3_COMP_CURR_uA(11),		/* use L3_COMP_CURR_uA(I) 0 <= I <= 138 uA */
 
	.leds = adp8860_leds,
	.num_leds = ARRAY_SIZE(adp8860_leds),
	.led_fade_law = ADP8860_FADE_LAW_SQUARE,	/* fade-on/fade-off transfer characteristic */
	.led_fade_in = ADP8860_FADE_T_600ms,
	.led_fade_out = ADP8860_FADE_T_600ms,
	.led_on_time = ADP8860_LED_ONT_200ms,
};

Declaring I2C devices

Unlike PCI or USB devices, I2C devices are not enumerated at the hardware level. Instead, the software must know which devices are connected on each I2C bus segment, and what address these devices are using. For this reason, the kernel code must instantiate I2C devices explicitly. There are different ways to achieve this, depending on the context and requirements. However the most common method is to declare the I2C devices by bus number.

This method is appropriate when the I2C bus is a system bus, as in many embedded systems, wherein each I2C bus has a number which is known in advance. It is thus possible to pre-declare the I2C devices that inhabit this bus. This is done with an array of struct i2c_board_info, which is registered by calling i2c_register_board_info().

So, to enable such a driver one need only edit the board support file by adding an appropriate entry to i2c_board_info.

For more information see: Documentation/i2c/instantiating-devices

21 Oct 2010 16:10 · Michael Hennerich
static struct i2c_board_info __initdata bfin_i2c_board_info[] = {
#if defined(CONFIG_BACKLIGHT_ADP8860) || defined(CONFIG_BACKLIGHT_ADP8860_MODULE)
	{
		I2C_BOARD_INFO("adp8860", 0x2A),
		.platform_data = (void *)&adp8860_pdata,
	},
#endif
}

Adding Linux driver support

Configure kernel with “make menuconfig” (alternatively use “make xconfig” or “make qconfig”)

The ADP8860 Backlight driver depends on I2C. It therefore requires selected I2C support to show up during kernel configuration.

Device Drivers  --->
	Graphics support  --->
		[*] Backlight & LCD device support  --->
			<*>   Lowlevel Backlight controls
			<M>   Backlight Driver for ADP8860 using WLED

Hardware configuration

During test and driver development we used the ADP8860 Evaluation Mother/Daughter Board.

It can be easily wired to the Blackfin STAMP TWI/I2C header.

BF537-STAMP (P10) TWI/I2C header ADP886x Adaptor Board (J30)
PIN Function PIN/Function
5 SCL SCL
6 SDA SDA
20 GND GND

Leave J31 and J32 open (these jumpers connect the SCL and SDA to the cypress chip used as USB bridge). Then apply your own SCL, SDA, and GND to the big J30 connector on the left edge of the board.

The ADP8860 chip still needs Vin (to power the chip), Vddio (to pull nRST and nINT high), and Vboard (to power the ALS sensor on the daughter card). These are provided through the USB port and then get regulated down (Vin becomes 3.6V, Vddio is 2.7V, and Vboard is around 4 V). So even though you won't be using the USB to program the part, it would still be easiest to plug the board into a USB port just to power Vin, Vddio, and Vboard. Of course, if you want, you can power these supplies from a lab bench power supply. In that case, move LK1, 2, and 3 to the “EXT” position and apply the signals to J29.

Driver testing

Driver compiled as a module

ADP8860 driver is build as a module

root:/> modprobe adp8860_bl
adp8860_bl 0-002a: Rev.7 Backlight
Registered led device: adp8860-led7
root:/>

Example Backlight usage

root:/> cd sys/class/backlight/adp8860_bl/
root:/sys/devices/platform/i2c-bfin-twi.0/i2c-adapter/i2c-0/0-002a/backlight/adp8860_bl> ls -l
-r--r--r--    1 root     root         4096 Jan  1 03:29 actual_brightness
-r--r--r--    1 root     root         4096 Jan  1 03:29 ambient_light_level
-rw-rw-r--    1 root     root         4096 Jan  1 03:29 ambient_light_zone
-rw-r--r--    1 root     root         4096 Jan  1 03:31 bl_power
-rw-r--r--    1 root     root         4096 Jan  1 04:55 brightness
lrwxrwxrwx    1 root     root            0 Jan  1 03:29 device -> ../../../0-002a
-rw-rw-r--    1 root     root         4096 Jan  1 03:29 l1_daylight_dim
-rw-rw-r--    1 root     root         4096 Jan  1 03:29 l1_daylight_max
-rw-rw-r--    1 root     root         4096 Jan  1 03:30 l2_office_dim
-rw-rw-r--    1 root     root         4096 Jan  1 03:29 l2_office_max
-rw-rw-r--    1 root     root         4096 Jan  1 03:31 l3_dark_dim
-rw-rw-r--    1 root     root         4096 Jan  1 03:29 l3_dark_max
-r--r--r--    1 root     root         4096 Jan  1 03:29 max_brightness
drwxr-xr-x    2 root     root            0 Jan  1 03:29 power
lrwxrwxrwx    1 root     root            0 Jan  1 03:29 subsystem -> ../../../../../../../../class/backlight
-rw-r--r--    1 root     root         4096 Jan  1 03:29 uevent
root:/sys/devices/platform/i2c-bfin-twi.0/i2c-adapter/i2c-0/0-002a/backlight/adp8860_bl>

Set Backlight Intensity

root:/sys/devices/platform/i2c-bfin-twi.0/i2c-adapter/i2c-0/0-002a/backlight/adp8860_bl> echo 42 > brightness

Query Backlight Intensity

root:/sys/devices/platform/i2c-bfin-twi.0/i2c-adapter/i2c-0/0-002a/backlight/adp8860_bl> cat brightness
42

Enable Ambient Light Sensing Feature

root:/sys/devices/platform/i2c-bfin-twi.0/i2c-adapter/i2c-0/0-002a/backlight/adp8860_bl> echo 127 > brightness

Query Ambient Light Level

root:/sys/devices/platform/i2c-bfin-twi.0/i2c-adapter/i2c-0/0-002a/backlight/adp8860_bl> cat ambient_light_level
1276

Query Ambient Light Zone

root:/sys/devices/platform/i2c-bfin-twi.0/i2c-adapter/i2c-0/0-002a/backlight/adp8860_bl> cat ambient_light_zone
2

Adjust Intensity for Ambient Light Zone 2 (office)

root:/sys/devices/platform/i2c-bfin-twi.0/i2c-adapter/i2c-0/0-002a/backlight/adp8860_bl> echo 22 > l2_office_max
22

root:/sys/devices/platform/i2c-bfin-twi.0/i2c-adapter/i2c-0/0-002a/backlight/adp8860_bl> cat l2_office_max
22

Example LED usage

root:/> cd /sys/class/leds/adp8860-led7/
root:/sys/devices/platform/i2c-bfin-twi.0/i2c-adapter/i2c-0/0-002a/leds/adp8860-led7> ls -l
-rw-r--r--    1 root     root         4096 Jan  1 03:29 brightness
lrwxrwxrwx    1 root     root            0 Jan  1 03:29 device -> ../../../0-002a
-r--r--r--    1 root     root         4096 Jan  1 03:29 max_brightness
drwxr-xr-x    2 root     root            0 Jan  1 03:29 power
lrwxrwxrwx    1 root     root            0 Jan  1 03:29 subsystem -> ../../../../../../../../class/leds

Set Intensity

root:/sys/devices/platform/i2c-bfin-twi.0/i2c-adapter/i2c-0/0-002a/leds/adp8860-led7>echo 99 > brightness

Turn LED OFF

root:/sys/devices/platform/i2c-bfin-twi.0/i2c-adapter/i2c-0/0-002a/leds/adp8860-led7> echo 0 > brightness

Query Max Brightness

root:/sys/devices/platform/i2c-bfin-twi.0/i2c-adapter/i2c-0/0-002a/leds/adp8860-led7> cat max_brightness
255
root:/sys/devices/platform/i2c-bfin-twi.0/i2c-adapter/i2c-0/0-002a/leds/adp8860-led7>

More Information