Use the EPDC Unit Test to exercise your EPD panel 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: Crosshatch Squares Text Ginger image Colorbar 3.2 Test 2: Rotation Updates Draws text, squares, crosshatch, and square outlines in all rotation modes: No rotation Clockwise (90 degrees) Upside down (180 degrees) 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 Draws a colorbar to an off-screen region. Draws the Ginger image to the frame buffer. Sets the focus (pan) to the colorbar, then updates portions of the screen. You should see the colorbar poke through. Slowly pans from Ginger to the entire colorbar. Use pan to flip between black and white buttons. Flashes buttons using pixel inversion. Flashes buttons using panning. 3.6 Test 6: Overlay Updates Switches between the frame buffer (FB) and the alternate (overlay) frame buffer as follows: Draws Ginger to the FB. Draws the colorbar to the alternate frame buffer. Shows the FB (Ginger). Shows the alternate FB (colorbar). Shows FB again (Ginger). Shows half FB, half alternate FB. Shows cutout region of alternate FB. Shows cutout in upper corner. Shows black screen. 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. Quickly flashes back and forth between black and white screens. Draws normal squares. Draws black and white squares. Draws Ginger in gray scale and monochrome. Draws colorbar in gray scale and monochrome. Draws normal Y8 colorbar and monochrome colorbar. 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: 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." 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. 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." Are there any EPDC-related error messages in the kernel log after boot? You can check with "dmesg | grep epdc".
View full article
