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 For example, run blinking pattern in engine #1 of LP5521
  77 echo 1 > /sys/bus/i2c/devices/xxxx/select_engine
  78 echo 1 > /sys/class/firmware/lp5521/loading
  79 echo "4000600040FF6000" > /sys/class/firmware/lp5521/data
  80 echo 0 > /sys/class/firmware/lp5521/loading
  81 echo 1 > /sys/bus/i2c/devices/xxxx/run_engine
  82
  83 For example, run blinking pattern in engine #3 of LP55231
  84 echo 3 > /sys/bus/i2c/devices/xxxx/select_engine
  85 echo 1 > /sys/class/firmware/lp55231/loading
  86 echo "9d0740ff7e0040007e00a0010000" > /sys/class/firmware/lp55231/data
  87 echo 0 > /sys/class/firmware/lp55231/loading
  88 echo 1 > /sys/bus/i2c/devices/xxxx/run_engine
  89
  90 To start blinking patterns in engine #2 and #3 simultaneously,
  91 for idx in 2 3
  92 do
  93   echo $idx > /sys/class/leds/red/device/select_engine
  94   sleep 0.1
  95   echo 1 > /sys/class/firmware/lp5521/loading
  96   echo "4000600040FF6000" > /sys/class/firmware/lp5521/data
  97   echo 0 > /sys/class/firmware/lp5521/loading
  98 done
  99 echo 1 > /sys/class/leds/red/device/run_engine
 100
 101 Here is another example for LP5523.
 102 echo 2 > /sys/bus/i2c/devices/xxxx/select_engine
 103 echo 1 > /sys/class/firmware/lp5523/loading
 104 echo "9d80400004ff05ff437f0000" > /sys/class/firmware/lp5523/data
 105 echo 0 > /sys/class/firmware/lp5523/loading
 106 echo 1 > /sys/bus/i2c/devices/xxxx/run_engine
 107
 108 As soon as 'loading' is set to 0, registered callback is called.
 109 Inside the callback, the selected engine is loaded and memory is updated.
 110 To run programmed pattern, 'run_engine' attribute should be enabled.
 111
 112 The pattern sqeuence of LP8501 is same as LP5523.
 113 However pattern data is specific.
 114 Ex 1) Engine 1 is used
 115 echo 1 > /sys/bus/i2c/devices/xxxx/select_engine
 116 echo 1 > /sys/class/firmware/lp8501/loading
 117 echo "9d0140ff7e0040007e00a001c000" > /sys/class/firmware/lp8501/data
 118 echo 0 > /sys/class/firmware/lp8501/loading
 119 echo 1 > /sys/bus/i2c/devices/xxxx/run_engine
 120
 121 Ex 2) Engine 2 and 3 are used at the same time
 122 echo 2 > /sys/bus/i2c/devices/xxxx/select_engine
 123 sleep 1
 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 sleep 1
 128 echo 3 > /sys/bus/i2c/devices/xxxx/select_engine
 129 sleep 1
 130 echo 1 > /sys/class/firmware/lp8501/loading
 131 echo "9d0340ff7e0040007e00a001c000" > /sys/class/firmware/lp8501/data
 132 echo 0 > /sys/class/firmware/lp8501/loading
 133 sleep 1
 134 echo 1 > /sys/class/leds/d1/device/run_engine
 135
 136 ( 'run_engine' and 'firmware_cb' )
 137 The sequence of running the program data is common.
 138 But each device has own specific register addresses for commands.
 139 To support this, 'run_engine' and 'firmware_cb' are configurable in each driver.
 140 run_engine  : Control the selected engine
 141 firmware_cb : The callback function after loading the firmware is done.
 142               Chip specific commands for loading and updating program memory.
 143
 144 ( Predefined pattern data )
 145
 146 Without the firmware interface, LP55xx driver provides another method for
 147 loading a LED pattern. That is 'predefined' pattern.
 148 A predefined pattern is defined in the platform data and load it(or them)
 149 via the sysfs if needed.
 150 To use the predefined pattern concept, 'patterns' and 'num_patterns' should be
 151 configured.
 152
 153   Example of predefined pattern data:
 154
 155   /* mode_1: blinking data */
 156   static const u8 mode_1[] = {
 157                 0x40, 0x00, 0x60, 0x00, 0x40, 0xFF, 0x60, 0x00,
 158                 };
 159
 160   /* mode_2: always on */
 161   static const u8 mode_2[] = { 0x40, 0xFF, };
 162
 163   struct lp55xx_predef_pattern board_led_patterns[] = {
 164         {
 165                 .r = mode_1,
 166                 .size_r = ARRAY_SIZE(mode_1),
 167         },
 168         {
 169                 .b = mode_2,
 170                 .size_b = ARRAY_SIZE(mode_2),
 171         },
 172   }
 173
 174   struct lp55xx_platform_data lp5562_pdata = {
 175   ...
 176         .patterns      = board_led_patterns,
 177         .num_patterns  = ARRAY_SIZE(board_led_patterns),
 178   };
 179
 180 Then, mode_1 and mode_2 can be run via through the sysfs.
 181
 182   echo 1 > /sys/bus/i2c/devices/xxxx/led_pattern    # red blinking LED pattern
 183   echo 2 > /sys/bus/i2c/devices/xxxx/led_pattern    # blue LED always on
 184
 185 To stop running pattern,
 186   echo 0 > /sys/bus/i2c/devices/xxxx/led_pattern