This application note explains how to use the Vybrid on-chip LCD controller in Linux.

All software tests documented below were performed on the Emcraft VF6 SOM TWR Kit, plugged into the Freescale Tower system with the TWR-LCD-RGB module connected to the Tower backplane. The TWR-LCD-RGB module hosts a 4.3" 480 x 272 LCD with a touch panel controlled by an I2C touch controller.

The Linux framebuffer driver for the Vybrid LCD controller resides in linux/drivers/video/mvf_dcu.c. To enable the LCD support in the kernel, you must enable the CONFIG_FB_MVF_DCU build time option in the kernel configuration. To do so, start the kernel configuration GUI (make kmenuconfig from the project directory) and proceed to enable the following items: Device Drivers -> Graphics support -> Support for framebuffer devices -> Faraday DCU framebuffer support:

The platform-specific code that registers a platform device for the Vybrid LCD controller with the framebuffer driver resides in linux/arch/arm/mach-mvf/mvf_fb.c. If you would like to port the framebuffer to a custom LCD, you will need to update that file to provide the framebuffer driver with configuration parameters appropriate for your LCD.

There must be a device node in the target root file system for the framebuffer to allow accessing it using standard Linux interfaces. Add the following line into your <project>.initramfs file to create a device node for the LCD interface:

nod /dev/fb0 0600 0 0 c 29 0

Having updated your project configuration as described above, build the bootable Linux image (<project>.uImage) by running make in the project directory. The procedure described here explains how to install Linux image (<project>.uImage) to the target.

When you boot the newly installed Linux image on the target, there will be the following message in the kernel bootstrap print-out indicating that the framebuffer driver is available and has registered a platform device for the on-chip LCD controller:

...
fb0: Layer0 fb device registered successfully.
...

The next question is what you can do with the framebuffer from Linux userspace code in order to display something on an attached LCD. At a lowest level, the framebuffer exposes a device file /dev/fbN for the LCD interface it is responsible for. Typically, as is the case for the Vybrid, the framebuffer services a single LCD interface so N is 0 and the device file is /dev/fb0. Through that file, userspace applications can perform reads/writes in order to directly access the LCD framebuffer - i.e. the pixel values being displayed on the screen. Additional APIs are available via ioctl calls on that file, that provide functionality to determine parameters of the LCD (width, height, pixel-depth, etc) as well as to perform some other operations.

As an example, this is a demo project (lcdtest.tgz) that illustrates how to display a static test image on the LCD.

Note: This demo project was validated in context of Release 1.14.0. If you are using a different release, some porting changes may be needed.

When you unpack the tarball (lcdtest.tgz) in the projects/ directory, the userspace application that accesses the LCD is projects/lcdtest/app/lcdtest.c. You will see from the sources that the application uses the standard POSIX APIs to open /dev/fd0, then calls appropriate ioctl commands to determine the LCD geometry, then maps the LCD memory buffer into the application address space using mmap and then renders the test image onto the LCD by writing directly into the LCD framebuffer. As mentioned, the application makes use of standard Linux APIs so the same code should work on any Linux system.

To build the project, simply go to projects/lcdtest and run make. The resultant bootable image will be lcdtest.uImage. When you have booted lcdtest.uImage to the target, call the application as follows in order to render the test image on the LCD:

~ # ./lcdtest
480x272, 32bpp
The framebuffer can be accessed at the address 0x2acb3000
~ #

Here is what the image will look like on the LCD:

Of course, in real-life designs developing low-level code that renders graphics directly through the framebuffer is not practical. Typically, developers use off-the-shelf GUI frameworks, such as for instance the Qt GUI framework, to implement a feature-rich GUI.