openkylin
/
linux
mirror of https://gitee.com/openkylin/linux.git
9
0
Fork 0
Code Issues Projects Releases Wiki Activity

LEDS: tca6507 - fix up some comments. 

In particular fix the capitalisation of GPIO and LED and
correct TCA6507_MAKE_CPIO, but also rewrite the comment about
platform-data to include reference to devicetree.

Also re-wrap comments to fit 80 columns.

Reported-by: Bryan Wu <cooloney@gmail.com>
Signed-off-by: NeilBrown <neilb@suse.de>
Signed-off-by: Bryan Wu <cooloney@gmail.com>
This commit is contained in:
NeilBrown 2013-11-12 21:52:43 -08:00 committed by Bryan Wu
parent 10ead6e599
commit 1f431afdb4
1 changed files with 101 additions and 87 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

188
drivers/leds/leds-tca6507.c
View File

@ -4,77 +4,87 @@
* The TCA6507 is a programmable LED controller that can drive 7 * The TCA6507 is a programmable LED controller that can drive 7
* separate lines either by holding them low, or by pulsing them * separate lines either by holding them low, or by pulsing them
* with modulated width. * with modulated width.
* The modulation can be varied in a simple pattern to produce a blink or * The modulation can be varied in a simple pattern to produce a
* double-blink. * blink or double-blink.
* *
* This driver can configure each line either as a 'GPIO' which is out-only * This driver can configure each line either as a 'GPIO' which is
* (no pull-up) or as an LED with variable brightness and hardware-assisted * out-only (pull-up resistor required) or as an LED with variable
* blinking. * brightness and hardware-assisted blinking.
* *
* Apart from OFF and ON there are three programmable brightness levels which * Apart from OFF and ON there are three programmable brightness
* can be programmed from 0 to 15 and indicate how many 500usec intervals in * levels which can be programmed from 0 to 15 and indicate how many
* each 8msec that the led is 'on'. The levels are named MASTER, BANK0 and * 500usec intervals in each 8msec that the led is 'on'. The levels
* BANK1. * are named MASTER, BANK0 and BANK1.
* *
* There are two different blink rates that can be programmed, each with * There are two different blink rates that can be programmed, each
* separate time for rise, on, fall, off and second-off. Thus if 3 or more * with separate time for rise, on, fall, off and second-off. Thus if
* different non-trivial rates are required, software must be used for the extra * 3 or more different non-trivial rates are required, software must
* rates. The two different blink rates must align with the two levels BANK0 and * be used for the extra rates. The two different blink rates must
* BANK1. * align with the two levels BANK0 and BANK1. This driver does not
* This driver does not support double-blink so 'second-off' always matches * support double-blink so 'second-off' always matches 'off'.
* 'off'.
* *
* Only 16 different times can be programmed in a roughly logarithmic scale from * Only 16 different times can be programmed in a roughly logarithmic
* 64ms to 16320ms. To be precise the possible times are: * scale from 64ms to 16320ms. To be precise the possible times are:
* 0, 64, 128, 192, 256, 384, 512, 768, * 0, 64, 128, 192, 256, 384, 512, 768,
* 1024, 1536, 2048, 3072, 4096, 5760, 8128, 16320 * 1024, 1536, 2048, 3072, 4096, 5760, 8128, 16320
* *
* Times that cannot be closely matched with these must be * Times that cannot be closely matched with these must be handled in
* handled in software. This driver allows 12.5% error in matching. * software. This driver allows 12.5% error in matching.
* *
* This driver does not allow rise/fall rates to be set explicitly. When trying * This driver does not allow rise/fall rates to be set explicitly.
* to match a given 'on' or 'off' period, an appropriate pair of 'change' and * When trying to match a given 'on' or 'off' period, an appropriate
* 'hold' times are chosen to get a close match. If the target delay is even, * pair of 'change' and 'hold' times are chosen to get a close match.
* the 'change' number will be the smaller; if odd, the 'hold' number will be * If the target delay is even, the 'change' number will be the
* the smaller. * smaller; if odd, the 'hold' number will be the smaller.
* Choosing pairs of delays with 12.5% errors allows us to match delays in the * Choosing pairs of delays with 12.5% errors allows us to match
* ranges: 56-72, 112-144, 168-216, 224-27504, 28560-36720. * delays in the ranges: 56-72, 112-144, 168-216, 224-27504,
* 26% of the achievable sums can be matched by multiple pairings. For example * 28560-36720.
* 1536 == 1536+0, 1024+512, or 768+768. This driver will always choose the * 26% of the achievable sums can be matched by multiple pairings.
* pairing with the least maximum - 768+768 in this case. Other pairings are * For example 1536 == 1536+0, 1024+512, or 768+768.
* not available. * This driver will always choose the pairing with the least
* maximum - 768+768 in this case. Other pairings are not available.
* *
* Access to the 3 levels and 2 blinks are on a first-come, first-served basis. * Access to the 3 levels and 2 blinks are on a first-come,
* Access can be shared by multiple leds if they have the same level and * first-served basis. Access can be shared by multiple leds if they
* either same blink rates, or some don't blink. * have the same level and either same blink rates, or some don't
* When a led changes, it relinquishes access and tries again, so it might * blink. When a led changes, it relinquishes access and tries again,
* lose access to hardware blink. * so it might lose access to hardware blink.
* If a blink engine cannot be allocated, software blink is used.
* If the desired brightness cannot be allocated, the closest available non-zero
* brightness is used. As 'full' is always available, the worst case would be
* to have two different blink rates at '1', with Max at '2', then other leds
* will have to choose between '2' and '16'. Hopefully this is not likely.
* *
* Each bank (BANK0 and BANK1) has two usage counts - LEDs using the brightness * If a blink engine cannot be allocated, software blink is used. If
* and LEDs using the blink. It can only be reprogrammed when the appropriate * the desired brightness cannot be allocated, the closest available
* counter is zero. The MASTER level has a single usage count. * non-zero brightness is used. As 'full' is always available, the
* worst case would be to have two different blink rates at '1', with
* Max at '2', then other leds will have to choose between '2' and
* '16'. Hopefully this is not likely.
* *
* Each Led has programmable 'on' and 'off' time as milliseconds. With each * Each bank (BANK0 and BANK1) has two usage counts - LEDs using the
* there is a flag saying if it was explicitly requested or defaulted. * brightness and LEDs using the blink. It can only be reprogrammed
* Similarly the banks know if each time was explicit or a default. Defaults * when the appropriate counter is zero. The MASTER level has a
* are permitted to be changed freely - they are not recognised when matching. * single usage count.
*
* Each LED has programmable 'on' and 'off' time as milliseconds.
* With each there is a flag saying if it was explicitly requested or
* defaulted. Similarly the banks know if each time was explicit or a
* default. Defaults are permitted to be changed freely - they are
* not recognised when matching.
* *
* *
* An led-tca6507 device must be provided with platform data. This data * An led-tca6507 device must be provided with platform data or
* lists for each output: the name, default trigger, and whether the signal * configured via devicetree.
* is being used as a GPiO rather than an led. 'struct led_plaform_data'
* is used for this. If 'name' is NULL, the output isn't used. If 'flags'
* is TCA6507_MAKE_CPIO, the output is a GPO.
* The "struct led_platform_data" can be embedded in a
* "struct tca6507_platform_data" which adds a 'gpio_base' for the GPiOs,
* and a 'setup' callback which is called once the GPiOs are available.
* *
* The platform-data lists for each output: the name, default trigger,
* and whether the signal is being used as a GPIO rather than an LED.
* 'struct led_plaform_data' is used for this. If 'name' is NULL, the
* output isn't used. If 'flags' is TCA6507_MAKE_GPIO, the output is
* a GPO. The "struct led_platform_data" can be embedded in a "struct
* tca6507_platform_data" which adds a 'gpio_base' for the GPIOs, and
* a 'setup' callback which is called once the GPIOs are available.
*
* When configured via devicetree there is one child for each output.
* The "reg" determines the output number and "compatible" determines
* whether it is an LED or a GPIO. "linux,default-trigger" can set a
* default trigger.
*/ */
#include <linux/module.h> #include <linux/module.h>
@ -192,17 +202,18 @@ MODULE_DEVICE_TABLE(i2c, tca6507_id);
static int choose_times(int msec, int *c1p, int *c2p) static int choose_times(int msec, int *c1p, int *c2p)
{ {
/* /*
* Choose two timecodes which add to 'msec' as near as possible. * Choose two timecodes which add to 'msec' as near as
* The first returned is the 'on' or 'off' time. The second is to be * possible. The first returned is the 'on' or 'off' time.
* used as a 'fade-on' or 'fade-off' time. If 'msec' is even, * The second is to be used as a 'fade-on' or 'fade-off' time.
* the first will not be smaller than the second. If 'msec' is odd, * If 'msec' is even, the first will not be smaller than the
* the first will not be larger than the second. * second. If 'msec' is odd, the first will not be larger
* If we cannot get a sum within 1/8 of 'msec' fail with -EINVAL, * than the second.
* otherwise return the sum that was achieved, plus 1 if the first is * If we cannot get a sum within 1/8 of 'msec' fail with
* smaller. * -EINVAL, otherwise return the sum that was achieved, plus 1
* If two possibilities are equally good (e.g. 512+0, 256+256), choose * if the first is smaller.
* the first pair so there is more change-time visible (i.e. it is * If two possibilities are equally good (e.g. 512+0,
* softer). * 256+256), choose the first pair so there is more
* change-time visible (i.e. it is softer).
*/ */
int c1, c2; int c1, c2;
int tmax = msec * 9 / 8; int tmax = msec * 9 / 8;
@ -255,8 +266,8 @@ static int choose_times(int msec, int *c1p, int *c2p)
} }
/* /*
* Update the register file with the appropriate 3-bit state for * Update the register file with the appropriate 3-bit state for the
* the given led. * given led.
*/ */
static void set_select(struct tca6507_chip *tca, int led, int val) static void set_select(struct tca6507_chip *tca, int led, int val)
{ {
@ -274,9 +285,9 @@ static void set_select(struct tca6507_chip *tca, int led, int val)
} }
} }
/* Update the register file with the appropriate 4-bit code for /* Update the register file with the appropriate 4-bit code for one
* one bank or other. This can be used for timers, for levels, or * bank or other. This can be used for timers, for levels, or for
* for initialisation. * initialization.
*/ */
static void set_code(struct tca6507_chip *tca, int reg, int bank, int new) static void set_code(struct tca6507_chip *tca, int reg, int bank, int new)
{ {
@ -309,7 +320,7 @@ static void set_level(struct tca6507_chip *tca, int bank, int level)
tca->bank[bank].level = level; tca->bank[bank].level = level;
} }
/* Record all relevant time code for a given bank */ /* Record all relevant time codes for a given bank */
static void set_times(struct tca6507_chip *tca, int bank) static void set_times(struct tca6507_chip *tca, int bank)
{ {
int c1, c2; int c1, c2;
@ -317,7 +328,8 @@ static void set_times(struct tca6507_chip *tca, int bank)
result = choose_times(tca->bank[bank].ontime, &c1, &c2); result = choose_times(tca->bank[bank].ontime, &c1, &c2);
dev_dbg(&tca->client->dev, dev_dbg(&tca->client->dev,
"Chose on times %d(%d) %d(%d) for %dms\n", c1, time_codes[c1], "Chose on times %d(%d) %d(%d) for %dms\n",
c1, time_codes[c1],
c2, time_codes[c2], tca->bank[bank].ontime); c2, time_codes[c2], tca->bank[bank].ontime);
set_code(tca, TCA6507_FADE_ON, bank, c2); set_code(tca, TCA6507_FADE_ON, bank, c2);
set_code(tca, TCA6507_FULL_ON, bank, c1); set_code(tca, TCA6507_FULL_ON, bank, c1);
@ -325,7 +337,8 @@ static void set_times(struct tca6507_chip *tca, int bank)
result = choose_times(tca->bank[bank].offtime, &c1, &c2); result = choose_times(tca->bank[bank].offtime, &c1, &c2);
dev_dbg(&tca->client->dev, dev_dbg(&tca->client->dev,
"Chose off times %d(%d) %d(%d) for %dms\n", c1, time_codes[c1], "Chose off times %d(%d) %d(%d) for %dms\n",
c1, time_codes[c1],
c2, time_codes[c2], tca->bank[bank].offtime); c2, time_codes[c2], tca->bank[bank].offtime);
set_code(tca, TCA6507_FADE_OFF, bank, c2); set_code(tca, TCA6507_FADE_OFF, bank, c2);
set_code(tca, TCA6507_FIRST_OFF, bank, c1); set_code(tca, TCA6507_FIRST_OFF, bank, c1);
@ -373,7 +386,8 @@ static void led_release(struct tca6507_led *led)
static int led_prepare(struct tca6507_led *led) static int led_prepare(struct tca6507_led *led)
{ {
/* Assign this led to a bank, configuring that bank if necessary. */ /* Assign this led to a bank, configuring that bank if
* necessary. */
int level = TO_LEVEL(led->led_cdev.brightness); int level = TO_LEVEL(led->led_cdev.brightness);
struct tca6507_chip *tca = led->chip; struct tca6507_chip *tca = led->chip;
int c1, c2; int c1, c2;
@ -389,10 +403,10 @@ static int led_prepare(struct tca6507_led *led)
if (led->ontime == 0 || led->offtime == 0) { if (led->ontime == 0 || led->offtime == 0) {
/* /*
* Just set the brightness, choosing first usable bank. * Just set the brightness, choosing first usable
* If none perfect, choose best. * bank. If none perfect, choose best. Count
* Count backwards so we check MASTER bank first * backwards so we check MASTER bank first to avoid
* to avoid wasting a timer. * wasting a timer.
*/ */
int best = -1;/* full-on */ int best = -1;/* full-on */
int diff = 15-level; int diff = 15-level;
@ -433,9 +447,9 @@ static int led_prepare(struct tca6507_led *led)
} }
/* /*
* We have on/off time so we need to try to allocate a timing bank. * We have on/off time so we need to try to allocate a timing
* First check if times are compatible with hardware and give up if * bank. First check if times are compatible with hardware
* not. * and give up if not.
*/ */
if (choose_times(led->ontime, &c1, &c2) < 0) if (choose_times(led->ontime, &c1, &c2) < 0)
return -EINVAL; return -EINVAL;
@ -523,8 +537,8 @@ static int led_assign(struct tca6507_led *led)
err = led_prepare(led); err = led_prepare(led);
if (err) { if (err) {
/* /*
* Can only fail on timer setup. In that case we need to * Can only fail on timer setup. In that case we need
* re-establish as steady level. * to re-establish as steady level.
*/ */
led->ontime = 0; led->ontime = 0;
led->offtime = 0; led->offtime = 0;
@ -594,8 +608,8 @@ static void tca6507_gpio_set_value(struct gpio_chip *gc,
spin_lock_irqsave(&tca->lock, flags); spin_lock_irqsave(&tca->lock, flags);
/* /*
* 'OFF' is floating high, and 'ON' is pulled down, so it has the * 'OFF' is floating high, and 'ON' is pulled down, so it has
* inverse sense of 'val'. * the inverse sense of 'val'.
*/ */
set_select(tca, tca->gpio_map[offset], set_select(tca, tca->gpio_map[offset],
val ? TCA6507_LS_LED_OFF : TCA6507_LS_LED_ON); val ? TCA6507_LS_LED_OFF : TCA6507_LS_LED_ON);