Documentation/leds/leds-lp55xx.txt

   1 LP5521/LP5523/LP55231 Common Driver
   2 ===================================
   3
   4 Authors: Milo(Woogyom) Kim <milo.kim@ti.com>
   5
   6 Description
   7 -----------
   8 LP5521, LP5523/55231 and LP5562 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 ( 'run_engine' and 'firmware_cb' )
 113 The sequence of running the program data is common.
 114 But each device has own specific register addresses for commands.
 115 To support this, 'run_engine' and 'firmware_cb' are configurable in each driver.
 116 run_engine  : Control the selected engine
 117 firmware_cb : The callback function after loading the firmware is done.
 118               Chip specific commands for loading and updating program memory.
 119
 120 ( Predefined pattern data )
 121
 122 Without the firmware interface, LP55xx driver provides another method for
 123 loading a LED pattern. That is 'predefined' pattern.
 124 A predefined pattern is defined in the platform data and load it(or them)
 125 via the sysfs if needed.
 126 To use the predefined pattern concept, 'patterns' and 'num_patterns' should be
 127 configured.
 128
 129   Example of predefined pattern data:
 130
 131   /* mode_1: blinking data */
 132   static const u8 mode_1[] = {
 133                 0x40, 0x00, 0x60, 0x00, 0x40, 0xFF, 0x60, 0x00,
 134                 };
 135
 136   /* mode_2: always on */
 137   static const u8 mode_2[] = { 0x40, 0xFF, };
 138
 139   struct lp55xx_predef_pattern board_led_patterns[] = {
 140         {
 141                 .r = mode_1,
 142                 .size_r = ARRAY_SIZE(mode_1),
 143         },
 144         {
 145                 .b = mode_2,
 146                 .size_b = ARRAY_SIZE(mode_2),
 147         },
 148   }
 149
 150   struct lp55xx_platform_data lp5562_pdata = {
 151   ...
 152         .patterns      = board_led_patterns,
 153         .num_patterns  = ARRAY_SIZE(board_led_patterns),
 154   };
 155
 156 Then, mode_1 and mode_2 can be run via through the sysfs.
 157
 158   echo 1 > /sys/bus/i2c/devices/xxxx/led_pattern    # red blinking LED pattern
 159   echo 2 > /sys/bus/i2c/devices/xxxx/led_pattern    # blue LED always on
 160
 161 To stop running pattern,
 162   echo 0 > /sys/bus/i2c/devices/xxxx/led_pattern