Documentation/leds/leds-lp55xx.txt

   1 LP5521/LP5523/LP55231/LP5562/LP8501 Common Driver
   2 =================================================
   3
   4 Authors: Milo(Woogyom) Kim <milo.kim@ti.com>
   5
   6 Description
   7 -----------
   8 LP5521, LP5523/55231, LP5562 and LP8501 have common features as below.
   9
  10   Register access via the I2C
  11   Device initialization/deinitialization
  12   Create LED class devices for multiple output channels
  13   Device attributes for user-space interface
  14   Program memory for running LED patterns
  15
  16 The LP55xx common driver provides these features using exported functions.
  17   lp55xx_init_device() / lp55xx_deinit_device()
  18   lp55xx_register_leds() / lp55xx_unregister_leds()
  19   lp55xx_regsister_sysfs() / lp55xx_unregister_sysfs()
  20
  21 ( Driver Structure Data )
  22
  23 In lp55xx common driver, two different data structure is used.
  24
  25 o lp55xx_led
  26   control multi output LED channels such as led current, channel index.
  27 o lp55xx_chip
  28   general chip control such like the I2C and platform data.
  29
  30 For example, LP5521 has maximum 3 LED channels.
  31 LP5523/55231 has 9 output channels.
  32
  33 lp55xx_chip for LP5521 ... lp55xx_led #1
  34                            lp55xx_led #2
  35                            lp55xx_led #3
  36
  37 lp55xx_chip for LP5523 ... lp55xx_led #1
  38                            lp55xx_led #2
  39                                  .
  40                                  .
  41                            lp55xx_led #9
  42
  43 ( Chip Dependent Code )
  44
  45 To support device specific configurations, special structure
  46 'lpxx_device_config' is used.
  47
  48   Maximum number of channels
  49   Reset command, chip enable command
  50   Chip specific initialization
  51   Brightness control register access
  52   Setting LED output current
  53   Program memory address access for running patterns
  54   Additional device specific attributes
  55
  56 ( Firmware Interface )
  57
  58 LP55xx family devices have the internal program memory for running
  59 various LED patterns.
  60 This pattern data is saved as a file in the user-land or
  61 hex byte string is written into the memory through the I2C.
  62 LP55xx common driver supports the firmware interface.
  63
  64 LP55xx chips have three program engines.
  65 To load and run the pattern, the programming sequence is following.
  66   (1) Select an engine number (1/2/3)
  67   (2) Mode change to load
  68   (3) Write pattern data into selected area
  69   (4) Mode change to run
  70
  71 The LP55xx common driver provides simple interfaces as below.
  72 select_engine : Select which engine is used for running program
  73 run_engine    : Start program which is loaded via the firmware interface
  74 firmware      : Load program data
  75
  76 In case of LP5523, one more command is required, 'enginex_leds'.
  77 It is used for selecting LED output(s) at each engine number.
  78 In more details, please refer to 'leds-lp5523.txt'.
  79
  80 For example, run blinking pattern in engine #1 of LP5521
  81 echo 1 > /sys/bus/i2c/devices/xxxx/select_engine
  82 echo 1 > /sys/class/firmware/lp5521/loading
  83 echo "4000600040FF6000" > /sys/class/firmware/lp5521/data
  84 echo 0 > /sys/class/firmware/lp5521/loading
  85 echo 1 > /sys/bus/i2c/devices/xxxx/run_engine
  86
  87 For example, run blinking pattern in engine #3 of LP55231
  88 Two LEDs are configured as pattern output channels.
  89 echo 3 > /sys/bus/i2c/devices/xxxx/select_engine
  90 echo 1 > /sys/class/firmware/lp55231/loading
  91 echo "9d0740ff7e0040007e00a0010000" > /sys/class/firmware/lp55231/data
  92 echo 0 > /sys/class/firmware/lp55231/loading
  93 echo "000001100" > /sys/bus/i2c/devices/xxxx/engine3_leds
  94 echo 1 > /sys/bus/i2c/devices/xxxx/run_engine
  95
  96 To start blinking patterns in engine #2 and #3 simultaneously,
  97 for idx in 2 3
  98 do
  99   echo $idx > /sys/class/leds/red/device/select_engine
 100   sleep 0.1
 101   echo 1 > /sys/class/firmware/lp5521/loading
 102   echo "4000600040FF6000" > /sys/class/firmware/lp5521/data
 103   echo 0 > /sys/class/firmware/lp5521/loading
 104 done
 105 echo 1 > /sys/class/leds/red/device/run_engine
 106
 107 Here is another example for LP5523.
 108 Full LED strings are selected by 'engine2_leds'.
 109 echo 2 > /sys/bus/i2c/devices/xxxx/select_engine
 110 echo 1 > /sys/class/firmware/lp5523/loading
 111 echo "9d80400004ff05ff437f0000" > /sys/class/firmware/lp5523/data
 112 echo 0 > /sys/class/firmware/lp5523/loading
 113 echo "111111111" > /sys/bus/i2c/devices/xxxx/engine2_leds
 114 echo 1 > /sys/bus/i2c/devices/xxxx/run_engine
 115
 116 As soon as 'loading' is set to 0, registered callback is called.
 117 Inside the callback, the selected engine is loaded and memory is updated.
 118 To run programmed pattern, 'run_engine' attribute should be enabled.
 119
 120 The pattern sequence of LP8501 is similar to LP5523.
 121 However pattern data is specific.
 122 Ex 1) Engine 1 is used
 123 echo 1 > /sys/bus/i2c/devices/xxxx/select_engine
 124 echo 1 > /sys/class/firmware/lp8501/loading
 125 echo "9d0140ff7e0040007e00a001c000" > /sys/class/firmware/lp8501/data
 126 echo 0 > /sys/class/firmware/lp8501/loading
 127 echo 1 > /sys/bus/i2c/devices/xxxx/run_engine
 128
 129 Ex 2) Engine 2 and 3 are used at the same time
 130 echo 2 > /sys/bus/i2c/devices/xxxx/select_engine
 131 sleep 1
 132 echo 1 > /sys/class/firmware/lp8501/loading
 133 echo "9d0140ff7e0040007e00a001c000" > /sys/class/firmware/lp8501/data
 134 echo 0 > /sys/class/firmware/lp8501/loading
 135 sleep 1
 136 echo 3 > /sys/bus/i2c/devices/xxxx/select_engine
 137 sleep 1
 138 echo 1 > /sys/class/firmware/lp8501/loading
 139 echo "9d0340ff7e0040007e00a001c000" > /sys/class/firmware/lp8501/data
 140 echo 0 > /sys/class/firmware/lp8501/loading
 141 sleep 1
 142 echo 1 > /sys/class/leds/d1/device/run_engine
 143
 144 ( 'run_engine' and 'firmware_cb' )
 145 The sequence of running the program data is common.
 146 But each device has own specific register addresses for commands.
 147 To support this, 'run_engine' and 'firmware_cb' are configurable in each driver.
 148 run_engine  : Control the selected engine
 149 firmware_cb : The callback function after loading the firmware is done.
 150               Chip specific commands for loading and updating program memory.
 151
 152 ( Predefined pattern data )
 153
 154 Without the firmware interface, LP55xx driver provides another method for
 155 loading a LED pattern. That is 'predefined' pattern.
 156 A predefined pattern is defined in the platform data and load it(or them)
 157 via the sysfs if needed.
 158 To use the predefined pattern concept, 'patterns' and 'num_patterns' should be
 159 configured.
 160
 161   Example of predefined pattern data:
 162
 163   /* mode_1: blinking data */
 164   static const u8 mode_1[] = {
 165                 0x40, 0x00, 0x60, 0x00, 0x40, 0xFF, 0x60, 0x00,
 166                 };
 167
 168   /* mode_2: always on */
 169   static const u8 mode_2[] = { 0x40, 0xFF, };
 170
 171   struct lp55xx_predef_pattern board_led_patterns[] = {
 172         {
 173                 .r = mode_1,
 174                 .size_r = ARRAY_SIZE(mode_1),
 175         },
 176         {
 177                 .b = mode_2,
 178                 .size_b = ARRAY_SIZE(mode_2),
 179         },
 180   }
 181
 182   struct lp55xx_platform_data lp5562_pdata = {
 183   ...
 184         .patterns      = board_led_patterns,
 185         .num_patterns  = ARRAY_SIZE(board_led_patterns),
 186   };
 187
 188 Then, mode_1 and mode_2 can be run via through the sysfs.
 189
 190   echo 1 > /sys/bus/i2c/devices/xxxx/led_pattern    # red blinking LED pattern
 191   echo 2 > /sys/bus/i2c/devices/xxxx/led_pattern    # blue LED always on
 192
 193 To stop running pattern,
 194   echo 0 > /sys/bus/i2c/devices/xxxx/led_pattern