How to verify EPD panel functionality

[#1]

Use the EPDC Unit Test to exercise your EPD panel

• Use the EPDC Unit Test to exercise your EPD panel
• 1. Introduction
• 2. Running the EPDC Unit Test
• 3. Individual Test Details
• 3.1 Test 1: Basic Updates
• 3.2 Test 2: Rotation Updates
• 3.3 Test 3: Grayscale Framebuffer Updates
• 3.4 Test 4: Auto-waveform Selection Updates
• 3.5 Test 5: Panning Updates
• 3.6 Test 6: Overlay Updates
• 3.7 Test 7: Auto-Updates
• 3.8 Test 8: Animation Mode Updates
• 3.9 Test 9: Fast Updates
• 3.10 Test 10: Partial to Full Update Transitions
• 3.11 Test 11: Test Pixel Shifting Effect
• 3.12 Test 12: Colormap Updates
• 3.13 Test 13: Collision Test Mode
• 3.14 Test 14: Stress Test
• 4. Customizing
• 5. Something is wrong!

1.  Introduction

The i.MX 6Solo/6DualLite and i.MX 6SoloLite processors contain an Electrophoretic Display Controller (EPDC) designed to drive E-INK(TM) EPD panels supporting a wide variety of TFT backplanes. Detailed information about the EPDC is available in the i.MX 6Solo/6DualLite and i.MX 6SoloLite Reference Manuals. Information about programming the EPDC and integrating support for a particular panel into the Linux BSP is provided in the Linux BSP Reference Manual. Now that you have your panel hardware and software integrated, how can you tell if it is all working? Or perhaps you're using a standard panel that doesn't seem to be working - how can you test it at the lowest level? The answer is the EDPC Unit Test.

2. Running the EPDC Unit Test

Most i.MX processor hardware modules have an associated unit test in the unit_tests directory of the root file system image. The basics of running the EPDC unit test are simple. After logging in as root on the debug console, change to the unit tests directory and execute the test as follows:

$ cd /unit_tests

$ ./mxc_epdc_fb_test.out

Without any arguments, the unit test runs thirteen individual tests and takes about 8 minutes to complete. You will get a lot of output on the panel and it may not be obvious that the images are displaying correctly. Running the unit test with no arguments is a nice automated way to make sure your panel is at least displaying something, and is not causing a crash or hang. But to really verify correctness each test should be run individually and the output carefully reviewed. This can be accomplished by passing a test number option as follows:

$ ./mxc_epdc_fb_test.out -n 1

To show a list of all the available options, as well as a list of the individual test numbers, use the "-h" argument. The helpful output is shown below.

$ ./mxc_epdc_fb_test.out -h

EPDC framebuffer driver test program.

Usage: mxc_epdc_fb_test [-h] [-a] [-p delay] [-u s/q/m] [-n ]

        -h        Print this message

        -a        Enabled animation waveforms for fast updates (tests 8-9)

        -p        Provide a power down delay (in ms) for the EPDC driver

                  0 - Immediate (default)

                  -1 - Never

                   ms - After ms milliseconds

        -u        Select an update scheme

                  s - Snapshot update scheme

                  q - Queue update scheme

                  m - Queue and merge update scheme (default)

        -n        Execute the tests specified in expression

                  Expression is a set of comma-separated numeric ranges

                  If not specified, tests 1-13 are run

Example:

./mxc_epdc_fb_test.out -n 1-3,5,7

EPDC tests:

1 - Basic Updates

2 - Rotation Updates

3 - Grayscale Framebuffer Updates

4 - Auto-waveform Selection Updates

5 - Panning Updates

6 - Overlay Updates

7 - Auto-Updates

8 - Animation Mode Updates

9 - Fast Updates

10 - Partial to Full Update Transitions

11 - Test Pixel Shifting Effect

12 - Colormap Updates

13 - Collision Test Mode

14 - Stress Test

In addition to "-n" to run individual tests, the "-a" and "-u" options are provided to set animation mode and waveform used, respectively. These options make sense only for some of the individual tests, as noted in the next section.

The "-u s" (snapshot) mode purposely does not allow pending updates, so some of the tests will cause the driver to issue the following warning in snapshot mode:

imx_epdc_fb: No free intermediate buffers available.

The "-p" (power down delay) option allows you to specify how soon the device driver automatically powers down the controller after all pending updates have completed. The default is 0 (zero), meaning power down immediately. Use "-1" to disable power down (i.e. never power down).

Sidebar: You can use another unit test, "dump-clocks.sh", to view the state of the EPDC clocks (i.e. the power state of the module). In the example below, a "1" in the third column indicates that the clock is running; a "0" indicates the clock is gated:

$ ./dump-clocks.sh | grep epdc

epdc_pix_clk             pll5_video_main_clk       1   26666667

epdc_axi_clk             pll2_pfd2_400M             1  198000000

3.  Individual Test Details

Important! The notes below assume you are running the version of the unit test binary in the tar file attached to this How-to. Please extract the file mxc_epdc_fb_tests.out from the tar file into your rootfs unit_tests directory before running the test.

Most tests begin with a screen blank operation (all white pixels). Each test works with all three update schemes (snapshot, queue, queue and merge) unless otherwise noted.

3.1 Test 1: Basic Updates

Draws the following patterns:

1. Crosshatch
2. Squares
3. Text
4. Ginger image
5. Colorbar

3.2 Test 2: Rotation Updates

Draws text, squares, crosshatch, and square outlines in all rotation modes:

1. No rotation
2. Clockwise (90 degrees)
3. Upside down (180 degrees)
4. Counterclockwise (270 degrees)

The square outlines are drawn first in RGB format and then in Y8 format.

3.3 Test 3: Grayscale Framebuffer Updates

Draws a top half black screen and then a colorbar, rotated clockwise. First draws in normal Y8 format and then in inverted Y8 format.

3.4 Test 4: Auto-waveform Selection Updates

Draws several small squares using auto-waveform selection. Note: unlike the i.MX508 EPDC driver, the i.MX 6 driver does not report the final waveform selection to user-level applications. This test also verifies that squares at non-8-bit aligned pixels can be drawn.

3.5 Test 5: Panning Updates

1. Draws a colorbar to an off-screen region.
2. Draws the Ginger image to the frame buffer.
3. Sets the focus (pan) to the colorbar, then updates portions of the screen. You should see the colorbar poke through.
4. Slowly pans from Ginger to the entire colorbar.
5. Use pan to flip between black and white buttons.
6. Flashes buttons using pixel inversion.
7. Flashes buttons using panning.

3.6 Test 6: Overlay Updates

Switches between the frame buffer (FB) and the alternate (overlay) frame buffer as follows:

1. Draws Ginger to the FB.
2. Draws the colorbar to the alternate frame buffer.
3. Shows the FB (Ginger).
4. Shows the alternate FB (colorbar).
5. Shows FB again (Ginger).
6. Shows half FB, half alternate FB.
7. Shows cutout region of alternate FB.
8. Shows cutout in upper corner.
9. Shows black screen.
10. Shows clockwise-rotated text overlay in center.

3.7 Test 7: Auto-Updates

Important! The auto-update mechanism must be enabled in the kernel configuration for this test to work. Enable it using the LTIB Kernel configuration menu item "Device Drivers->Graphics support->E-Ink Auto-update Mode Support." Also, please check the Linux BSP Release Notes for any issues with this feature.

3.8 Test 8: Animation Mode Updates

Shows how normal (gray level) and monochrome (black and white) updates compare in appearance and performance.

1. Quickly flashes back and forth between black and white screens.
2. Draws normal squares.
3. Draws black and white squares.
4. Draws Ginger in gray scale and monochrome.
5. Draws colorbar in gray scale and monochrome.
6. Draws normal Y8 colorbar and monochrome colorbar.
7. Draws inverted normal Y8 colorbar and inverted monochrome colorbar.

You can run this test in animation mode using the "-a" command line option. Animation mode only updates monochrome pixels, so you will notice a drawing speed improvement. Also, you will see the implementation of one of the "rules" of using this mode: The screen must be blanked (all white or all black) when switching in and out of animation mode.

3.9 Test 9: Fast Updates

Animates a square across the screen and down one side. This test can also be run in animation mode using "-a". See the animation mode notes in the Test 8 description above.

3.10 Test 10: Partial to Full Update Transitions

Draws small gray squares using separate updates in partial update mode (only pixels that change are updated). Then re-draws the entire screen in one update using full update mode. In full update mode, you will notice the entire screen transition from black to the final grey value.

3.11 Test 11: Test Pixel Shifting Effect

Draws a short, two pixel line and then sends two updates one pixel apart in distance and 5 seconds apart in time. Nothing much to see here; just verifies that a one pixel update shift works.

3.12 Test 12: Colormap Updates

Creates a colormap and uses it to draw full screen blanks and to draw a color bar. In this test, you should follow along with the text printed in the debug console and verify each state:

Screen should be black.

Screen should be white now.

Screen should still be white.

Should be inverted color bar (white to black, left to right).

Colorbar again, with no CMAP (black to white, left to right).

Posterized colorbar.

In the above output, "CMAP" means colormap and "Posterized colorbar" is a colorbar drawn from only black and white components.

3.13 Test 13: Collision Test Mode

Draws two overlapping rectangles. Tests for collision on the first rectangle, which should result in the message:

Collision test result = 0

Then draws the same overlapping rectangles, this time testing for collision on the second rectangle. The result should be:

Collision test result = 1

Note: This test cannot be run using the snapshot scheme. If you try to use "-u s" it will print a message and return.

3.14 Test 14: Stress Test

Draws thousands of random rectangles on the screen in different rotations. Runs for about 8 minutes.

This test must be explicitly specified on the command line; it does not run by default. For example:

$ ./mxc_epdc_fb_test.out -n 14

Note: This test cannot be run using the snapshot scheme. If you try to use "-u s" it will print a message and return.

4. Customizing

A great way to know what's really going on in each test is to look at the source code. You may want to customize the source as well - say to add a new test that exercises some cool feature of your panel. Fortunately, the source is included in the BSP distribution so you can extract, customize, and rebuild it as needed. The magic of LTIB is beyond the scope of this article, but here are some hints:

# Extract the unit test source from the imx-test package:

$ ./ltib -m prep -p imx-test

# Source is now in rpm/BUILD/imx-test-12.08.00/test/mxc_fb_test/mxc_epdc_fb_test.c (your package version number my be different).

# Build from source:

$ ./ltib -m scbuild -p imx-test

# Deploy all unit test binaries to ltib rootfs directory:

$ ./ltib -m scdeploy -p imx-test

# Alternatively you can copy just the epdc unit test binary as follows:

$ sudo cp rpm/BUILD/imx-test-12.08.00/platform/IMX6S/mxc_epdc_fb_test.out rootfs/unit_tests/

As noted in the Individual Test Details section, you should replace the file mxc_epdc_fb_test.c referenced above with the one found in the tar file attached to this How-to.

5. Something is wrong!

Of course there are many things that can go wrong that are beyond the scope of this article, but assuming your hardware is working and the panel options are correctly configured in the BSP (again, beyond our scope), here are some things to check:

1. Is the kernel configured correctly for EPDC support? Check that the following item is enabled in the LTIB Kernel configuration menu: "Device Drivers->Graphics support->E-Ink Panel Framebuffer."
2. Are the U-boot kernel command line arguments set correctly for EPDC? For example, "video=mxcepdcfb:E060SCM consoleblank=0". The "consoleblank=0" command is useful to prevent entering low power suspend mode while you are testing.
3. Does the "Tux" image display correctly on your panel after system boot? If so, the EPDC driver was a least able to perform the initial framebuffer update to your panel. Note: for Tux to display at boot, you need to disable LCDIF support at "Device Drivers->Graphics support->Support MXC ELCDIF framebuffer."
4. Are there any EPDC-related error messages in the kernel log after boot? You can check with "dmesg | grep epdc".