Documentation/leds/leds-lp55xx.rst

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