Rockchip RT-Thread Display Guide: VOP, Panels, Partial Refresh and Color Key

Complete technical content from Chinese RK-KF-YF-105 V1.4.0. Source platform versions are listed below. This is an RT-Thread driver guide, not Linux DRM configuration. Before ArmSoM use, verify the exact SoC, RT-Thread BSP/HAL, VOP, interface, panel model, timing and power supply. No specific board combination has been confirmed: platform reference, not universal board support. No English PDF exists; all four languages use the 16 Chinese-source technical figures, with table/code screenshots additionally transcribed as editable content. Source examples have not been hardware-tested.

Source issues retained: the VOP file table writes dsp/rockchip-common/..., while other paths use bsp. The color-matrix image multiplication order and some fixed-point values (0.0691 to 0x05, 0.0880 to 0x08) do not match the stated multiplication by 0x80; values are not changed. Section 6.4 calls hsync/vsync “porch” while the diagram says “pulse”; MIPI clock units remain Mbps. The section 4 structures do not list every field used in section 7. Initialization arrays in images are excerpts; no missing ending or commands are invented. The original YUVY422 spelling is retained. Verify against the actual HAL, registers and panel specification before using initialization values.

ArmSoM Docs · RT-Thread

1. Overview

The Rockchip RT-Thread display driver registers an LCD driver with the OS using the RT-Thread IO device-driver model and supports GUI applications such as LittlevGL. To exploit the display hardware, extended interfaces add multilayer composition, color-effect adjustment, post-scaling and MIPI switch support.

1.1 Basic concepts

CRTC: display-controller abstraction of the SoC VOP module (also called LCDC in some documents).

Plane: abstraction of a win layer inside VOP/LCDC.

Encoder/Connector: software abstraction of display outputs such as RGB, LVDS, DSI, eDP and HDMI.

Panel: abstraction of LCD, HDMI and other display devices.

1.2 Display pipeline

RK2108

RK2108 display pipeline

For other platforms, see the display-pipeline description in Rockchip_Developer_Guide_DRM_Display_Driver_CN.

2. Software architecture

Display software architecture

2.1 Driver-layer files

2.2 HAL-layer files

3. Common interfaces

RT-Thread GUI applications interact with drivers through control operations, similar to Linux IOCTL. The extended controls include:

4. Key data structures

4.1 struct display_state

The central display-driver structure includes RTT device and graphic_info structures and Rockchip hardware abstractions.

4.2 struct crtc_state

Describes the Rockchip processor VOP module, with the following main fields:

4.3 struct CRTC_WIN_STATE

Describes a WIN layer of the Rockchip VOP module:

4.4 struct VOP_POST_SCALE_INFO

Describes post-scaling in the Rockchip VOP module:

4.5 struct VOP_BCSH_INFO

Describes the VOP post-BCSH stage:

4.6 struct VOP_COLOR_MATRIX_INFO

Describes the VOP post color-matrix stage:

Original color conversion matrix

[csc_out0]   [csc_in0]   [coe00 coe01 coe02]   [offset0]
[csc_out1] = [csc_in1] X [coe10 coe11 coe12] + [offset1]
[csc_out2]   [csc_in2]   [coe20 coe21 coe22]   [offset2]

Example: bt709tobt2020 conversion matrix:

{0.6274, 0.3293, 0.0433},
{0.0691, 0.9195, 0.0114},
{0.0164, 0.0880, 0.8956}

After fixed-point conversion using 0x80 (bit7 is the sign bit):

coe00 = 0.6274 * 0x80  = 0x50
coe01 = 0.3293 * 0x80  = 0x2a
coe02 = 0.0433 * 0x80  = 0x05

Similarly, the source gives:

colorMatrixCoe[3][3] = {
    {0x50, 0x2a, 0x05},
    {0x05, 0x75, 0x02},
    {0x02, 0x08, 0x72}
};

4.7 struct VOP_POST_CLIP_INFO

Describes the VOP post-clip stage:

5. Alignment requirements

5.1 Data alignment

RK2108

RK2108 data alignment

5.2 Panel alignment

Some panels impose alignment requirements. For S6E3HC2 at 1440x3120, the DSC slice is 720x65: partial-refresh position must align to 720x65 and the display-region size to 720x195. At 720x1560, the slice is 360x52: position must align to 360x52 and region size to 360x390.

6. Panel configuration

6.1 Select a supported panel

Select the panel configuration through this menu:

cd bsp/rockchip-pisces
    scons --menuconfig
        RT-Thread rockchip common drivers  --->
            Panel Type (R17 SS mipi panel, resolution is 1080x2340)  --->

6.2 Add a new panel

1. Enter the configuration directory: cd bsp/rockchip-common/drivers/panel_cfg.

2. Copy an existing .h file to new_panel.h and modify its parameters using section 6.4 and the panel specification.

3. Return with cd ../ to bsp/rockchip-common/drivers/.

4. Open Kconfig, find “Panel Type” and define RT_USING_PANEL_NEW_PANEL following the existing config RT_USING_PANEL entries.

Kconfig new-panel example

--- a/bsp/rockchip-common/drivers/Kconfig
+++ b/bsp/rockchip-common/drivers/Kconfig
@@ -58,6 +58,9 @@ choice

     config RT_USING_PANEL_S6E3HC2_X4
        bool "S6E3HC2_X4 mipi panel, resolution is 720x1560"
+
+    config RT_USING_PANEL_NEW_PANEL
+       bool "It's a new panel demo, resolution is wxh"
 endchoice

6.3 Typical scan timing

Display scan timing

6.4 Panel configuration parameters

6.5 Panel initialization commands

1. MIPI DSI CMD example:

Initialization command screenshot excerpt

struct rockchip_cmd cmd_on[] =
{
    /* sleep out */
    {0x05, 0x05, 0x01, {0x11}},
    /* FD Setting */
    {0x29, 0x00, 0x03, {0xf0, 0x5a, 0x5a}},
    {0x23, 0x00, 0x02, {0xb0, 0x01}},
    {0x23, 0x00, 0x02, {0xcd, 0x01}},
    {0x29, 0x14, 0x03, {0xf0, 0xa5, 0xa5}},
    /* 4. Common Setting */
    /* 4.1 TE(Vync) ON/OFF */
    {0x29, 0x00, 0x03, {0x9f, 0xa5, 0xa5}},
    {0x15, 0x00, 0x02, {0x35, 0x00}},
    {0x29, 0x00, 0x03, {0x9f, 0x5a, 0x5a}},

The first three hexadecimal bytes are Data Type, Delay and Payload Length. From the fourth byte, the actual payload contains Payload Length bytes.

1. First-command decoding:

First initialization command

/* sleep out */
{0x05, 0x05, 0x01, {0x11}},

Data Type: 0x05 (DCS Short Write)

Delay: 0x05 (5 ms)

Payload Length: 0x01 (1 byte)

Payload: 0x11

1. Second-command decoding:

Second initialization command

/* FD Setting */
{0x29, 0x00, 0x03, {0xf0, 0x5a, 0x5a}},

Data Type: 0x29 (Generic Long Write)

Delay: 0x00 (0 ms)

Payload Length: 0x03 (3 bytes)

Payload: 0xf0 0x5a 0x5a

1. Data Type definitions

Processor-sourced packet types

Packet types continued

1. DCS Write

DCS Write types

A DCS packet contains one DCS-command byte and n parameter bytes. For n < 2, use a Short Packet: n=0 sends only the command with Data Type 0x05; n=1 sends one parameter with Data Type 0x15. For n >= 2, use a Long Packet containing the command and n parameters, Data Type 0x39.

1. Generic Write

Generic Write types

A Generic Packet contains n parameter bytes. For n < 3, use a Short Packet: n=0 has no parameters, Data Type 0x03; n=1 has one parameter, 0x13; n=2 has two parameters, 0x23. For n >= 3, use a Long Packet with n parameters, Data Type 0x29.

1. Delay specifies the wait in ms after sending the current packet and before the next command.

2. Payload Length is the packet payload length.

3. Payload is the packet’s actual data, of length Payload Length.

4. Example

Dimming settings and commands

/* 5.1 Dimming Setting */
{0x29, 0x00, 0x03, {0xf0, 0x5a, 0x5a}},
{0x23, 0x00, 0x02, {0xb0, 0x07}},
{0x23, 0x00, 0x02, {0xb7, 0x01}},
{0x29, 0x00, 0x03, {0xf0, 0xa5, 0xa5}},
{0x15, 0x00, 0x02, {0x53, 0x28}},
{0x39, 0x00, 0x03, {0x51, 0x03, 0xff}},

7. display_test tool

display_test applies only to RK2108. Other platforms must use modetest, described below, to test display functions.

7.1 Supported test cases

Command:

display_test cmd
dsc; winloop; winmove; winalpha; scale; coe;  bcsh; gamma; clip; mipi_switch;
ebook; color_bar

7.2 Demo walkthrough

1. Find the LCD device.

g_display_dev = rt_device_find("lcd");
RT_ASSERT(g_display_dev != RT_NULL);

1. Open the LCD device.

ret = rt_device_open(g_display_dev, RT_DEVICE_FLAG_RDWR);
RT_ASSERT(ret == RT_EOK);

1. Enable the LCD device.

ret = rt_device_control(g_display_dev, RK_DISPLAY_CTRL_ENABLE, NULL);
RT_ASSERT(ret == RT_EOK);

1. Obtain panel information.

ret = rt_device_control(g_display_dev, RTGRAPHIC_CTRL_GET_INFO, (void *)graphic_info);
RT_ASSERT(ret == RT_EOK);

1. Initialize win_config and post_scale. Initialize win_config as follows:

static void display_win_init(struct CRTC_WIN_STATE *win_config)
{
    win_config->winEn = true;
    win_config->winId = 0;
    win_config->zpos  = 0;
    win_config->format   = SRC_DATA_FMT;
    win_config->yrgbAddr = (uint32_t)rtt_framebuffer_test;
    win_config->cbcrAddr = (uint32_t)rtt_framebuffer_uv;
    win_config->yrgbLength = 0;
    win_config->cbcrLength = 0;
    win_config->xVir = SRC_DATA_W;
    win_config->srcX = 0;
    win_config->srcY = 0;
    win_config->srcW = SRC_DATA_W;
    win_config->srcH = SRC_DATA_H;
    win_config->crtcX = 0;
    win_config->crtcY = 0;
    win_config->crtcW = SRC_DATA_W;
    win_config->crtcH = SRC_DATA_H;
    win_config->xLoopOffset = 0;
    win_config->yLoopOffset = 0;
}

Initialize post_scale for fullscreen display without scaling:

static void display_post_init(struct CRTC_WIN_STATE *win_config,
                              struct VOP_POST_SCALE_INFO *post_scale,
                              struct rt_device_graphic_info *graphic_info)
{
    post_scale->srcW = graphic_info->width;
    post_scale->srcH = graphic_info->height;
    post_scale->dstX = 0;
    post_scale->dstY = 0;
    post_scale->dstW = graphic_info->width;
    post_scale->dstH = graphic_info->height;
}

Initialize post_scale for partial refresh with 2x horizontal and vertical scaling:

static void display_post_init(struct CRTC_WIN_STATE *win_config,
                              struct VOP_POST_SCALE_INFO *post_scale,
                              struct rt_device_graphic_info *graphic_info)
{
    post_scale->srcW = graphic_info->width / 2;
    post_scale->srcH = win_config->srcH;
    post_scale->dstX = 0;
    post_scale->dstY = 0;
    post_scale->dstW = graphic_info->width;
    post_scale->dstH = win_config->srcH * 2;
}

1. Load the LUT palette for bpp images; skip this step for other formats.

ret = rt_device_control(g_display_dev, RK_DISPLAY_CTRL_LOAD_LUT, &lut_state);
RT_ASSERT(ret == RT_EOK);

1. Configure post_scale with the data dimensions before scaling and displayed dimensions afterward.

ret = rt_device_control(g_display_dev, RK_DISPLAY_CTRL_SET_SCALE, post_scale);
RT_ASSERT(ret == RT_EOK);

1. Configure win_config layer information.

ret = rt_device_control(g_display_dev, RK_DISPLAY_CTRL_SET_PLANE, win_config);
RT_ASSERT(ret == RT_EOK);

1. Commit the display.

ret = rt_device_control(g_display_dev, RK_DISPLAY_CTRL_COMMIT, NULL);
RT_ASSERT(ret == RT_EOK);

Display one frame using steps 1–9. For multiple frames, modify win_config and post_scale, then repeat steps 7, 8 and 9.

7.3 Partial-refresh coordinates

1. Demo for panels supporting partial refresh in both X and Y.

XY partial-refresh coordinates

The red region is win0 at (X0,Y0), size (W0,H0). Configure:

win_config->winId = 0;
win_config->winEn = 1;
……
win_config->srcX = X0;
win_config->srcY = Y0;
win_config->srcW = W0;
win_config->srcH = H0;

The green region is win1 at (X1,Y1), size (W1,H1). Configure:

win_config->winId = 1;
win_config->winEn = 1;
……
win_config->srcX = X1;
win_config->srcY = Y1;
win_config->srcW = W1;
win_config->srcH = H1;

Post-scaling configuration:

post_scale->srcW = W1;
post_scale->srcH = H2;
post_scale->dstX = X1;
post_scale->dstY = Y0;
post_scale->dstW = W1;
post_scale->dstH = H2;

In the actual display code, configure post-scaling first:

ret = rt_device_control(g_display_dev, RK_DISPLAY_CTRL_SET_SCALE, post_scale);
RT_ASSERT(ret == RT_EOK);

Then configure WIN0 and WIN1:

ret = rt_device_control(g_display_dev, RK_DISPLAY_CTRL_SET_PLANE, win_config);
RT_ASSERT(ret == RT_EOK);

Finally commit the display:

ret = rt_device_control(g_display_dev, RK_DISPLAY_CTRL_COMMIT, NULL);
RT_ASSERT(ret == RT_EOK);

1. Demo for Y-only partial refresh, without X support.

Y-only partial-refresh coordinates

The red region is win0 at (X0,Y0), size (W0,H0). Configure:

win_config->winId = 0;
win_config->winEn = 1;
……
win_config->srcX = X0;
win_config->srcY = Y0;
win_config->srcW = W0;
win_config->srcH = H0;

The green region is win1 at (X1,Y1), size (W1,H1). Configure:

win_config->winId = 1;
win_config->winEn = 1;
……
win_config->srcX = X1;
win_config->srcY = Y1;
win_config->srcW = W1;
win_config->srcH = H1;

Post-scaling configuration:

post_scale->srcW = Xres;
post_scale->srcH = H2;
post_scale->dstX = 0;
post_scale->dstY = Y0;
post_scale->dstW = Xres;
post_scale->dstH = H2;

Without X partial refresh, unlike case 1, the post-scale source width and dstW are the actual panel width Xres, and dstX is 0. Other steps match case 1. Configure post-scaling first:

ret = rt_device_control(g_display_dev, RK_DISPLAY_CTRL_SET_SCALE, post_scale);
RT_ASSERT(ret == RT_EOK);

Then configure WIN0 and WIN1:

ret = rt_device_control(g_display_dev, RK_DISPLAY_CTRL_SET_PLANE, win_config);
RT_ASSERT(ret == RT_EOK);

Finally commit the display:

ret = rt_device_control(g_display_dev, RK_DISPLAY_CTRL_COMMIT, NULL);
RT_ASSERT(ret == RT_EOK);

8. modetest tool

8.1 Supported test cases

modetest [-afgp]

        -p <plane_id>:<w>x<h>:<crtc_w>x<crtc_h>[+<x>+<y>][#<zpos>][@<format>]  set plane
        -f <pattern>    specify fill pattern
        -a      test alpha
        -g      test gamma

Example command:

modetest -p 0:720x1280:720x1280@AR24 -a -g

9. Color Key

VOP can make a selected color in a layer fully transparent, exposing the next layer or background. The driver uses win_config.colorKey: bits [23,0] contain the RGB key components, and bit24 enables/disables the function. The RGB888 and RGB565 examples below use R_VAL, G_VAL and B_VAL for the component values to make transparent.

#define COLOR_KEY_EN    BIT(24)

9.1 RGB888 Color Key configuration

1. Make red fully transparent:

win_config->colorKey = 0xFF0000 | COLOR_KEY_EN;

1. Make green fully transparent:

win_config->colorKey = 0x00FF00 | COLOR_KEY_EN;

1. Make blue fully transparent:

win_config->colorKey = 0x0000FF | COLOR_KEY_EN;

That is:

win_config->colorKey = (R_VAL << 16) | (G_VAL << 8) | (B_VAL) | COLOR_KEY_EN;

9.2 RGB565 Color Key configuration

1. Make red fully transparent:

win_config->colorKey = 0xF80000 | COLOR_KEY_EN;

1. Make green fully transparent:

win_config->colorKey = 0x00FC00 | COLOR_KEY_EN;

1. Make blue fully transparent:

win_config->colorKey = 0x0000F8 | COLOR_KEY_EN;

That is:

R_VAL_CONFIG = R_VAL << 3;  //R[4,0] -> R[7,0]

G_VAL_CONFIG = G_VAL << 2;  //G[5,0] -> G[7,0]

B_VAL_CONFIG = B_VAL << 3;  //B[4,0] -> B[7,0]

win_config->colorKey = (R_VAL_CONFIG  << 16) | (G_VAL_CONFIG << 8) | B_VAL_CONFIG | COLOR_KEY_EN;

9.3 Disable Color Key

win_config->colorKey = 0;

10. Updating the LUT

Using a layer LUT requires lut_en. Once enabled, the LUT is protected and its registers cannot be read or written. Changing lut_en takes effect on a frame boundary. To update the LUT when switching scenarios, follow these steps:

1. Disable the LUT. (1) Set a non-bpp layer format, excluding:

RTGRAPHIC_PIXEL_FORMAT_GRAY1
RTGRAPHIC_PIXEL_FORMAT_GRAY4,
RTGRAPHIC_PIXEL_FORMAT_GRAY16,
RTGRAPHIC_PIXEL_FORMAT_GRAY256,
RTGRAPHIC_PIXEL_FORMAT_RGB332,

(2) Disable all layers and refresh a 32x32 image where no content is displayed. 32x32 is not mandatory: the purpose is an ineffective frame that applies lut_en disable without affecting the current screen content.

1. Update the LUT array and call RK_DISPLAY_CTRL_LOAD_LUT.

2. Configure a new frame: set the win format to the corresponding bpp format and refresh one frame. The new LUT then takes effect.

11. References

1. Rockchip DRM Display Driver Development Guide

2. Rockchip_DRM_Panel_Porting_Guide.pdf