LP55xx Common Driver

LP55xx 공통 기능과 driver 구조

이 공통 driver는 LP5521, LP5523/LP55231, LP5562, LP8501이 공유하는 I2C register 접근, device 초기화·해제, 다중 output LED class device 생성, userspace device attribute, pattern 실행용 program memory 기능을 제공합니다.

공개 함수는 `lp55xx_init_device()`와 `lp55xx_deinit_device()`, `lp55xx_register_leds()`와 `lp55xx_unregister_leds()`, 원문 표기의 `lp55xx_regsister_sysfs()`와 `lp55xx_unregister_sysfs()`입니다. 오탈자로 보이는 symbol도 원문 보존을 위해 그대로 둡니다.

공통 driver는 두 자료 구조를 사용합니다. `lp55xx_led`는 LED current와 channel index 같은 개별 output 채널을 나타내고, `lp55xx_chip`은 I2C와 platform data 같은 chip 전체 제어 상태를 나타냅니다. LP5521의 chip 하나에는 최대 세 `lp55xx_led`, LP5523/55231에는 아홉 개가 연결됩니다.

Device별 차이는 원문 표기의 `lpxx_device_config`에 둡니다. 최대 채널 수, reset·enable 명령, chip별 초기화, brightness register 접근, output current 설정, pattern program memory 주소, 추가 attribute가 여기에 포함됩니다.

=================================================
LP5521/LP5523/LP55231/LP5562/LP8501 Common Driver
=================================================

Authors: Milo(Woogyom) Kim <[email protected]>

Description
-----------
LP5521, LP5523/55231, LP5562 and LP8501 have common features as below.

  Register access via the I2C
  Device initialization/deinitialization
  Create LED class devices for multiple output channels
  Device attributes for user-space interface
  Program memory for running LED patterns

The LP55xx common driver provides these features using exported functions.

  lp55xx_init_device() / lp55xx_deinit_device()
  lp55xx_register_leds() / lp55xx_unregister_leds()
  lp55xx_regsister_sysfs() / lp55xx_unregister_sysfs()

( Driver Structure Data )

In lp55xx common driver, two different data structure is used.

* lp55xx_led
    control multi output LED channels such as led current, channel index.
* lp55xx_chip
    general chip control such like the I2C and platform data.

For example, LP5521 has maximum 3 LED channels.
LP5523/55231 has 9 output channels::

  lp55xx_chip for LP5521 ... lp55xx_led #1
                             lp55xx_led #2
                             lp55xx_led #3

  lp55xx_chip for LP5523 ... lp55xx_led #1
                             lp55xx_led #2
                                   .
                                   .
                             lp55xx_led #9

( Chip Dependent Code )

To support device specific configurations, special structure
'lpxx_device_config' is used.

  - Maximum number of channels
  - Reset command, chip enable command
  - Chip specific initialization
  - Brightness control register access
  - Setting LED output current
  - Program memory address access for running patterns
  - Additional device specific attributes

공통 firmware interface

LP55xx 계열은 다양한 LED pattern을 실행할 내부 program memory와 세 개의 program engine을 갖습니다. Pattern data는 userspace file로 저장하거나 I2C를 통해 hex byte string으로 memory에 기록할 수 있습니다.

적재와 실행의 공통 순서는 engine 1·2·3 중 하나를 선택하고, mode를 load로 바꾸고, 선택 영역에 pattern data를 쓴 다음, mode를 run으로 바꾸는 것입니다.

공통 interface의 `select_engine`은 실행할 engine을 선택하고, `run_engine`은 firmware interface로 적재한 program을 시작하며, `firmware`는 program data를 적재합니다.

LP5523은 engine별 output을 선택하는 `enginex_leds` 명령이 하나 더 필요합니다. 세부 설명은 원문이 가리키는 `leds-lp5523.txt`에 있습니다.

( Firmware Interface )

LP55xx family devices have the internal program memory for running
various LED patterns.

This pattern data is saved as a file in the user-land or
hex byte string is written into the memory through the I2C.

LP55xx common driver supports the firmware interface.

LP55xx chips have three program engines.

To load and run the pattern, the programming sequence is following.

  (1) Select an engine number (1/2/3)
  (2) Mode change to load
  (3) Write pattern data into selected area
  (4) Mode change to run

The LP55xx common driver provides simple interfaces as below.

select_engine:
        Select which engine is used for running program
run_engine:
        Start program which is loaded via the firmware interface
firmware:
        Load program data

In case of LP5523, one more command is required, 'enginex_leds'.
It is used for selecting LED output(s) at each engine number.
In more details, please refer to 'leds-lp5523.txt'.

LP5521·LP55231·LP5523 적재 예제

LP5521 engine 1 blink 예제는 `select_engine = 1`, firmware `loading = 1`, data `4000600040FF6000`, `loading = 0`, `run_engine = 1` 순서입니다.

LP55231 engine 3 예제는 `9d0740ff7e0040007e00a0010000`을 적재한 뒤 `engine3_leds`에 `000001100`을 써서 두 LED를 output channel로 선택합니다.

LP5521의 engine 2와 3을 동시에 준비하는 shell loop는 각 engine을 차례로 선택하고 0.1초 기다린 뒤 같은 blink data를 적재합니다. 두 engine의 적재가 끝나면 `run_engine`을 한 번 활성화합니다.

LP5523 예제는 engine 2를 선택하고 `9d80400004ff05ff437f0000`을 적재한 뒤 `engine2_leds`에 `111111111`을 써서 아홉 LED 전체를 선택합니다.

Firmware `loading`을 `0`으로 바꾸는 즉시 등록된 callback이 호출되어 선택 engine과 program memory를 갱신합니다. 실제 pattern을 시작하려면 이어서 `run_engine` attribute를 활성화해야 합니다.

For example, run blinking pattern in engine #1 of LP5521::

        echo 1 > /sys/bus/i2c/devices/xxxx/select_engine
        echo 1 > /sys/class/firmware/lp5521/loading
        echo "4000600040FF6000" > /sys/class/firmware/lp5521/data
        echo 0 > /sys/class/firmware/lp5521/loading
        echo 1 > /sys/bus/i2c/devices/xxxx/run_engine

For example, run blinking pattern in engine #3 of LP55231

Two LEDs are configured as pattern output channels::

        echo 3 > /sys/bus/i2c/devices/xxxx/select_engine
        echo 1 > /sys/class/firmware/lp55231/loading
        echo "9d0740ff7e0040007e00a0010000" > /sys/class/firmware/lp55231/data
        echo 0 > /sys/class/firmware/lp55231/loading
        echo "000001100" > /sys/bus/i2c/devices/xxxx/engine3_leds
        echo 1 > /sys/bus/i2c/devices/xxxx/run_engine

To start blinking patterns in engine #2 and #3 simultaneously::

        for idx in 2 3
        do
        echo $idx > /sys/class/leds/red/device/select_engine
        sleep 0.1
        echo 1 > /sys/class/firmware/lp5521/loading
        echo "4000600040FF6000" > /sys/class/firmware/lp5521/data
        echo 0 > /sys/class/firmware/lp5521/loading
        done
        echo 1 > /sys/class/leds/red/device/run_engine

Here is another example for LP5523.

Full LED strings are selected by 'engine2_leds'::

        echo 2 > /sys/bus/i2c/devices/xxxx/select_engine
        echo 1 > /sys/class/firmware/lp5523/loading
        echo "9d80400004ff05ff437f0000" > /sys/class/firmware/lp5523/data
        echo 0 > /sys/class/firmware/lp5523/loading
        echo "111111111" > /sys/bus/i2c/devices/xxxx/engine2_leds
        echo 1 > /sys/bus/i2c/devices/xxxx/run_engine

As soon as 'loading' is set to 0, registered callback is called.
Inside the callback, the selected engine is loaded and memory is updated.
To run programmed pattern, 'run_engine' attribute should be enabled.

LP8501 예제와 device별 callback

LP8501의 pattern sequence는 LP5523과 비슷하지만 program data는 device별입니다. Engine 1 예제는 `9d0140ff7e0040007e00a001c000`을 적재합니다.

Engine 2와 3을 함께 사용할 때는 engine 2에 `9d0140ff7e0040007e00a001c000`, engine 3에 `9d0340ff7e0040007e00a001c000`을 각각 적재하며 단계 사이에 1초씩 기다립니다. 마지막에는 `/sys/class/leds/d1/device/run_engine`을 활성화합니다.

Program 실행 순서는 공통이지만 명령 register 주소는 device마다 다릅니다. 이를 지원하기 위해 각 driver가 `run_engine`과 `firmware_cb`를 구성합니다.

`run_engine` callback은 선택 engine을 제어합니다. `firmware_cb`는 firmware loading 완료 뒤 호출되어 chip별 명령으로 program memory를 적재하고 갱신합니다.

The pattern sequence of LP8501 is similar to LP5523.

However pattern data is specific.

Ex 1) Engine 1 is used::

        echo 1 > /sys/bus/i2c/devices/xxxx/select_engine
        echo 1 > /sys/class/firmware/lp8501/loading
        echo "9d0140ff7e0040007e00a001c000" > /sys/class/firmware/lp8501/data
        echo 0 > /sys/class/firmware/lp8501/loading
        echo 1 > /sys/bus/i2c/devices/xxxx/run_engine

Ex 2) Engine 2 and 3 are used at the same time::

        echo 2 > /sys/bus/i2c/devices/xxxx/select_engine
        sleep 1
        echo 1 > /sys/class/firmware/lp8501/loading
        echo "9d0140ff7e0040007e00a001c000" > /sys/class/firmware/lp8501/data
        echo 0 > /sys/class/firmware/lp8501/loading
        sleep 1
        echo 3 > /sys/bus/i2c/devices/xxxx/select_engine
        sleep 1
        echo 1 > /sys/class/firmware/lp8501/loading
        echo "9d0340ff7e0040007e00a001c000" > /sys/class/firmware/lp8501/data
        echo 0 > /sys/class/firmware/lp8501/loading
        sleep 1
        echo 1 > /sys/class/leds/d1/device/run_engine

( 'run_engine' and 'firmware_cb' )

The sequence of running the program data is common.

But each device has own specific register addresses for commands.

To support this, 'run_engine' and 'firmware_cb' are configurable in each driver.

run_engine:
        Control the selected engine
firmware_cb:
        The callback function after loading the firmware is done.

        Chip specific commands for loading and updating program memory.

Platform data의 predefined pattern

Firmware interface 외에도 LP55xx driver는 platform data에 미리 정의한 LED pattern을 sysfs에서 선택해 적재하는 `predefined` 방식을 제공합니다.

이 방식을 사용하려면 platform data의 `patterns`와 `num_patterns`를 구성해야 합니다. 예제의 `mode_1`은 `0x40, 0x00, 0x60, 0x00, 0x40, 0xFF, 0x60, 0x00` blink data이고, `mode_2`는 `0x40, 0xFF` always-on data입니다.

`lp55xx_predef_pattern` 배열 첫 항목은 `mode_1`을 red program과 크기에 연결하고, 둘째 항목은 `mode_2`를 blue program과 크기에 연결합니다. `lp5562_pdata`는 이 배열과 `ARRAY_SIZE(board_led_patterns)`를 보관합니다.

Sysfs `led_pattern`에 `1`을 쓰면 red blink인 mode 1, `2`를 쓰면 blue always-on인 mode 2가 실행됩니다. 실행 중인 pattern을 중지하려면 `0`을 씁니다.

( Predefined pattern data )

Without the firmware interface, LP55xx driver provides another method for
loading a LED pattern. That is 'predefined' pattern.

A predefined pattern is defined in the platform data and load it(or them)
via the sysfs if needed.

To use the predefined pattern concept, 'patterns' and 'num_patterns' should be
configured.

Example of predefined pattern data::

  /* mode_1: blinking data */
  static const u8 mode_1[] = {
                0x40, 0x00, 0x60, 0x00, 0x40, 0xFF, 0x60, 0x00,
                };

  /* mode_2: always on */
  static const u8 mode_2[] = { 0x40, 0xFF, };

  struct lp55xx_predef_pattern board_led_patterns[] = {
        {
                .r = mode_1,
                .size_r = ARRAY_SIZE(mode_1),
        },
        {
                .b = mode_2,
                .size_b = ARRAY_SIZE(mode_2),
        },
  }

  struct lp55xx_platform_data lp5562_pdata = {
  ...
        .patterns      = board_led_patterns,
        .num_patterns  = ARRAY_SIZE(board_led_patterns),
  };

Then, mode_1 and mode_2 can be run via through the sysfs::

  echo 1 > /sys/bus/i2c/devices/xxxx/led_pattern    # red blinking LED pattern
  echo 2 > /sys/bus/i2c/devices/xxxx/led_pattern    # blue LED always on

To stop running pattern::

  echo 0 > /sys/bus/i2c/devices/xxxx/led_pattern