Quectel SC668S Series Display Driver Development Guide
Smart Module Series
Version: 1.0
Date: 2023-04-23
Version: Released
About the Document
Revision History
Version | Date | Author | Description |
- | 2022-04-18 | Hbingo HUANG | Creation of the Document |
1.0 | 2023-04-23 | Hbingo HUANG/ Aivin XU | First official release |
Contents
1. Introduction
This document introduces how to use the Display Serial Interface (DSI) to bring up the LCD display panel of Quectel SC668S series module on Android platform, including important parameters of panel configuration files and the configuration steps in Kernel and UEFI.
NOTE:
- In this document, LCD HX8394F on the EVB corresponding to the module is used as an example to outline the development flow of LCD display driver.
- This document only describes important user configurations during LCD display driver development.
- This document is applicable to multiple Android versions, and the kernel path can be divided into two paths:
kernel\msm-4.14
(For Android 10 and Android 11) andUM.x.xx\kernel\msm-4.14
(For Android 12 or above). You need to select the corresponding path according to the specific Android version.
2. Panel Configuration File Modification
This chapter describes the panel configuration files introduced:
dsi-panel-hx8394f-720p-video.dtsi
(Chapter 2.1 to 2.6)trinket-sde-display.dtsi
(Chapter 2.7)
The two files are located in the kernel\msm-4.14\arch\arm64\boot\dts\qcom\
directory. You can configure the required LCD by copying the default panel configuration files of the module and then modifying the corresponding MIPI parameters.
NOTE: This chapter only introduces important parameters that may be modified by users. Parameters not mentioned herein usually do not need to be modified.
2.1. Configure Panel Information
You can configure the panel information as required. Here is an example:
&mdss_mdp {
dsi_hx8394f_720p_video: qcom,mdss_dsi_hx8394f_720p_video {
qcom,mdss-dsi-panel-name = "hx8394f video mode dsi panel without DSC";
qcom,mdss-dsi-panel-type = "dsi_video_mode";
qcom,mdss-dsi-virtual-channel-id = <0>;
qcom,mdss-dsi-stream = <0>;
qcom,mdss-dsi-h-left-border = <0>;
qcom,mdss-dsi-h-right-border = <0>;
qcom,mdss-dsi-v-top-border = <0>;
qcom,mdss-dsi-v-bottom-border = <0>;
qcom,mdss-dsi-bpp = <24>;
qcom,mdss-dsi-color-order = "rgb_swap_rgb";
qcom,mdss-dsi-underflow-color = <0xff>;
qcom,mdss-dsi-border-color = <0>;
};
}
Parameter | Description | Value | |
mdss-dsi-panel-name |
Panel name | Panel name/configuration file value | |
mdss-dsi-panel-type |
Panel type | "dsi_video_mode" "dsi_cmd_mode" |
Video mode Command mode |
2.2. Configure Panel Resolution
You can configure panel resolution as required. Here is an example:
qcom,mdss-dsi-display-timings {
timing@0{
qcom,mdss-dsi-panel-width = <720>;
qcom,mdss-dsi-panel-height = <1280>;
qcom,mdss-dsi-h-front-porch = <50>;
qcom,mdss-dsi-h-back-porch = <50>;
qcom,mdss-dsi-h-pulse-width = <50>;
qcom,mdss-dsi-h-sync-skew = <0>;
qcom,mdss-dsi-v-back-porch = <4>;
qcom,mdss-dsi-v-front-porch = <10>;
qcom,mdss-dsi-v-pulse-width = <4>;
qcom,mdss-dsi-panel-framerate = <60>;
qcom,mdss-dsi-on-command = [
];
}
Parameter | Description |
mdss-dsi-panel-width |
Panel width (pixel) |
mdss-dsi-panel-height |
Panel height (pixel) |
mdss-dsi-h-front-porch |
Horizontal front porch value |
mdss-dsi-h-back-porch |
Horizontal back porch value |
mdss-dsi-h-pulse-width |
Horizontal pulse width |
mdss-dsi-h-sync-skew |
Horizontal sync skew value |
mdss-dsi-v-back-porch |
Vertical back porch value |
mdss-dsi-v-front-porch |
Vertical front porch value |
mdss-dsi-v-pulse-width |
Vertical pulse width |
mdss-dsi-panel-framerate |
Panel framerate, which is the number of frames refreshed on panel per second |
2.3. Configure Panel Color Information
You can configure panel color information as required. Here is an example:
qcom,mdss-dsi-bpp = <24>;
qcom,mdss-dsi-color-order = "rgb_swap_rgb";
qcom,mdss-dsi-underflow-color = <0xff>;
qcom,mdss-dsi-border-color = <0>;
Parameter | Description | Value |
mdss-dsi-bpp |
Defines the number of bits per pixel | 24 888_RGB |
18 666_RGB | ||
16 565_RGB | ||
12 444_RGB | ||
8 332_RGB | ||
3 111_RGB | ||
mdss-dsi-color-order |
Specifies the R, G, B channel order | "rgb_swap_rgb" "rgb_swap_rbg" "rgb_swap_brg" "rgb_swap_grb" "rgb_swap_gbr" |
2.4. Configure Panel Command Information
You can configure panel command information (for LCD initialization) as required. The information is provided by LCD module manufacturer. Here is an example:
qcom,mdss-dsi-on-command = [
29 01 00 00 00 00 04 B9 FF 83 94
29 01 00 00 00 00 07 BA 63 03 68 6b b2 c0
29 01 00 00 00 00 0B B1 50 12 72 09 33 54 B1 31 6B 2F
29 01 00 00 00 00 07 B2 00 80 64 0e 0d 2f
29 01 00 00 00 00 16 B4 73 74 73 74 73 74 01 OC 86 75 00 3F 73 74 73 74 73 74 01 OC 86
29 01 00 00 00 00 22 D3 00 00 07 07 40 07 10 00 08 10 08 00 08 54 15 0e 05 0e 02 15 06 05 06 47 44 0a 0a 4b 10 07 07
29 01 00 00 00 00 2D D5 1a 1a 1b 1b 00 01 02 03 04 05 06 07 08 09 0a 0b 24 25 18 18 26 27 18 18 18 18 18 18 18 18 18
29 01 00 00 00 00 2D D6 1a 1a 1b 1b 0b 0a 09 08 07 06 05 04 03 02 01 00 21 20 18 18 27 26 18 18 18 18 18 18 18 18 18
29 01 00 00 00 00 3B E0 00 OD 1B 22 25 2A 2F 2C 5A 6B 7A 77 7E 8E 92 95 9F 9E 99 a1 b0 57 55 5c 5F 5F 67 6F 7f 00 OD
29 01 00 00 00 00 03 C0 1f 31
29 01 00 00 00 00 02 CC OB
29 01 00 00 00 00 03 B6 78 78
29 01 00 00 00 00 02 D4 02
29 01 00 00 00 00 02 BD 02
29 01 00 00 00 00 0D D8 FF FF FF FF FF FF FF FF FF FF FF FF
29 01 00 00 00 00 02 BD 00
29 01 00 00 00 00 02 BD 01
29 01 00 00 00 00 02 B1 00
29 01 00 00 00 00 02 BD 00
29 01 00 00 00 00 08 BF 40 81 50 00 1A FC 01
05 01 00 00 78 00 02 11 00
05 01 00 00 05 00 02 29 00
];
qcom,mdss-dsi-off-command = [
05 01 00 00 14 00 02 28 00
05 01 00 00 78 00 02 10 00
];
Parameter | Description |
mdss-dsi-on-command |
Array of variable length that lists the initialization commands of the panel |
mdss-dsi-off-command |
Array of variable length that lists the de-initialization commands of the panel |
2.4.1. Command Format
Usually, only PayloadSize and Payload in the command need to be modified, but sometimes Wait also needs to be modified. See the requirements of initialization commands provided by the LCD module manufacturer for details. The parameter information is described as below:
qcom,mdss-dsi-on-command = [
29 01 00 00 00 00 04 B9 FF 83 94
29 01 00 00 00 00 07 BA 63 03 68 6b b2 c0
29 01 00 00 00 00 0B B1 50 12 72 09 33 54 B1 31 6B 2F
29 01 00 00 00 00 07 B2 00 80 64 0e 0d 2f
29 01 00 00 00 00 16 B4 73 74 73 74 73 74 01 OC 86 75 00 3F 73 74 73 74 73 74 01 OC 86
29 01 00 00 00 00 22 D3 00 00 07 07 40 07 10 00 08 10 08 00 08 54 15 0e 05 0e 02 15 06 05 06 47 44 0a 0a 4b 10 07 07
29 01 00 00 00 00 2D D5 1a 1a 1b 1b 00 01 02 03 04 05 06 07 08 09 0a 0b 24 25 18 18 26 27 18 18 18 18 18 18 18 18 18
29 01 00 00 00 00 2D D6 1a 1a 1b 1b 0b 0a 09 08 07 06 05 04 03 02 01 00 21 20 18 18 27 26 18 18 18 18 18 18 18 18 18
29 01 00 00 00 00 3B E0 00 OD 1B 22 25 2A 2F 2C 5A 6B 7A 77 7E 8E 92 95 9F 9E 99 a1 b0 57 55 5c 5F 5F 67 6F 7f 00 OD
29 01 00 00 00 00 03 C0 1f 31
29 01 00 00 00 00 02 CC OB
29 01 00 00 00 00 03 B6 78 78
29 01 00 00 00 00 02 D4 02
29 01 00 00 00 00 02 BD 02
29 01 00 00 00 00 0D D8 FF FF FF FF FF FF FF FF FF FF FF FF
29 01 00 00 00 00 02 BD 00
29 01 00 00 00 00 02 BD 01
29 01 00 00 00 00 02 B1 00
29 01 00 00 00 00 02 BD 00
29 01 00 00 00 00 08 BF 40 81 50 00 1A FC 01
05 01 00 00 78 00 02 11 00
05 01 00 00 05 00 02 29 00
];
qcom,mdss-dsi-off-command = [
05 01 00 00 14 00 02 28 00
05 01 00 00 78 00 02 10 00
];
qcom,mdss-dsi-on-command-state = "dsi_lp_mode";
qcom,mdss-dsi-off-command-state = "dsi_hs_mode";
Parameter | Description | Length |
CommandType | Data type of command | 1 |
Last | Specifies whether this command packet is an individual command | 1 |
VC | Virtual channel used to send this command | 1 |
Ack | Indicates whether acknowledgement from the panel is needed | 1 |
Wait | Waiting time in milliseconds before sending next command | 1 |
PayloadSize | Payload size | 2 |
Payload | Payload | Based on PayloadSize |
Payload is generally provided by the LCD module manufacturer.
Payload provided by LCD module manufacturer in the following format are preferable:
CMD(Hex),Number(Hex),DATA(Hex),DATA(Hex),...
When Payload is provided in the above format, mdss-dsi-on-command
will be in the following format:
Register = 29 01 00 00 (A collection of CommandType, Last, VC and Ack)
Wait (Unit: ms. The value is provided by LCD module manufacturer)
PayloadSize = Number+1
Payload = CMD DATA DATA
For example, if Payload provided by LCD module manufacturer is:
B9,3,FF,83,94
BA,6,63,3,68,6B,B2,C0
mdss-dsi-on-command
will be configured as:
29 01 00 00 00 00 04 B9 FF 83 94
29 01 00 00 00 00 07 BA 63 03 68 6B B2 CO
Usually, the last two commands of mdss-dsi-on-command
are given as below, where 11
means LCD exiting sleep (sleep out) and 29
means turning on LCD (display on).
05 01 00 00 78 00 02 11 00
05 01 00 00 05 00 02 29 00
NOTE: You can delete the above two commands if they are not needed for the LCD module used. For specific usage conditions of the commands, see LCD module hardware design or contact the corresponding LCD module manufacturer.
2.5. Configure Video Mode Panel
Usually, parameters for video mode panel do not need to be modified, except for mdss-dsi-traffic-mode
since it may vary with LCD chip. Here is an example:
qcom,mdss-dsi-traffic-mode = "non_burst_sync_event";
Parameter | Description | Value |
mdss-dsi-traffic-mode |
MIPI transmission mode | "non_burst_sync_pulse" Non-burst with synchronization pulse |
"non_burst_sync_event" Non-burst with synchronization start event |
||
"burst_mode" Burst mode |
2.6. Configure Data Lane
You can configure data lane as required. The following is a configuration example when 4 data lanes are enabled. If one of the data lanes is disabled, then you do not need to configure the corresponding lane number. Please see the corresponding LCD module hardware design for details.
qcom,mdss-dsi-lane-0-state;
qcom,mdss-dsi-lane-1-state;
qcom,mdss-dsi-lane-2-state;
qcom,mdss-dsi-lane-3-state;
Parameter | Description |
mdss-dsi-lane-0-state |
Enable lane 0 |
mdss-dsi-lane-1-state |
Enable lane 1 |
mdss-dsi-lane-2-state |
Enable lane 2 |
mdss-dsi-lane-3-state |
Enable lane 3 |
2.7. Configure DSI Timings
You can configure DSI timing sequence of the panel according to your needs. Here is an example:
&dsi_hx8394f_720p_video {
qcom,mdss-dsi-t-clk-post = <0x0a>;
qcom,mdss-dsi-t-clk-pre = <0x1c>;
qcom, dsi-supported-dfps-list = <60 55 53 43>;
qcom,mdss-dsi-pan-enable-dynamic-fps;
qcom,mdss-dsi-pan-fps-update =
"dfps_immediate_porch_mode_vfp";
// qcom,esd-check-enabled;
// qcom,mdss-dsi-panel-status-check-mode = "reg_read";
// qcom,mdss-dsi-panel-status-command = [06 01 00 01 00 00 01 0a];
// qcom,mdss-dsi-panel-status-command-state = "dsi_hs_mode";
// qcom,mdss-dsi-panel-status-value = <0x9d 0x9d 0x9d 0x9d>;
// qcom,mdss-dsi-panel-on-check-value = <0x9d 0x9d 0x9d 0x9d>;
// qcom,mdss-dsi-panel-status-read-length = <4>;
qcom,mdss-dsi-display-timings {
timing@0{
qcom,mdss-dsi-panel-phy-timings =
[1E 1B 04 05 02 02 04 a0
1E 1B 04 05 02 02 04 a0
1E 1B 04 05 02 02 04 a0
1E 1B 04 05 02 02 04 a0
1E 0D 03 05 02 02 04 a0];
qcom, display-topology = <1 0 1>;
qcom, default-topology-index = <0>;
}
}
Parameter | Description |
mdss-dsi-t-clk-pre |
Pre-value of DSI timing control clock (generated according to the steps in Chapter 2.7.1) |
mdss-dsi-t-clk-post |
Post value of DSI timing control clock (generated according to the steps in Chapter 2.7.1) |
mdss-dsi-panel-phy-timings |
An array with a length of 40 bytes that specifies the physical timing settings (generated according to the steps in Chapter 2.7.1) |
2.7.1. Generate DSI Timings
80-nh713-1_yb_dsi timing parameters user interactive spreadsheet.xlsm
in 80-NH713-1_DSI.zip
can be used to calculate the DSI timings values automatically. The detailed steps are as below:
NOTE:
- Please contact Quectel Technical Supports for obtaining
80-NH713-1_DSI.zip
. - Please use Microsoft Excel (Microsoft Excel 2016 is recommended) to open
80-nh713-1_yb_dsi timing parameters user interactive spreadsheet.xlsm
. The use of other tools such as WPS is not supported.
Step 1: Open 80-nh713-1_yb_dsi timing parameters user interactive spreadsheet.xlsm
and click "Enable Content", as shown in the figure below:
Step 2: Open DSI and MDP Registers sheet. Input the values of frame rate, lane config, pixel format BPP, Active Width, Active Height, Porch and Chip to be configured to the specified area, as shown in the figure below:
NOTE: If the LCD module manufacturer requires to change the Porch to be 4 or a multiple of 4. Please change it accordingly and also update the panel Porch node.
Step 3: Open DSI PHY Timing Setting sheet and press Ctrl + J at the same time to clear the previous timings data. Then press Ctrl + K simultaneously to regenerate timings data. After the operation is completed, the field Check for T_CLK_ZERO will be displayed as VALID, as shown below.
Step 4: Open DSI PHY 2.0.0 Timing Setting sheet to check the calculated timings values.
Step 5: Update trinket-sde-display.dtsi
of the corresponding LCD configuration node in the file kernel\msm-4.14\arch\arm64\boot\dts\qcom\
using the values generated in the sheet. For example, the module currently uses dsi_hx8394f_720p_video
panel, so you should update mdss-dsi-panel-phy-timings
of dsi_hx8394f_720p_video
node with the values. The corresponding relationship is shown as below:
Step 6: Copy the value of T_CLK_POST and T_CLK_PRE generated in the sheet to replace the value of mdss-dsi-t-clk-post
and mdss-dsi-t-clk-pre
in file trinket-sde-display.dtsi
. The value in the sheet is in decimal format. Before you updating the two parameters, please make sure that these two values are in hexadecimal format. Here is an example:
qcom,mdss-dsi-t-clk-post = <0x0a>;
qcom,mdss-dsi-t-clk-pre = <0x1c>;
3. Kernel and UEFI Configuration
This chapter takes LCD HX8394F as an example to introduce how to configure Kernel and UEFI to add a new panel.
NOTE: LCD parameters should be configured in both UEFI and Kernel.
- After the module is booted, LCD will be driven using configuration parameters in UEFI before the module enters sleep mode for the first time.
- After the module sleeps and then wakes up, LCD will be driven using configuration parameters in Kernel.
3.1. Configure Kernel
3.1.1. Configure Device Tree File
Step 1: Modify the configuration file of the used panel. For example, the default panel configuration file of the module is dsi-panel-hx8394f-720p-video.dtsi
. You can rename dsi-panel-xxx-xxx-video.dtsi
according to the actually used LCD, such as dsi-panel-hx8394f-720p-video.dtsi
. Then copy the file to the directory kernel\msm-4.14\arch\arm64\boot\dts\qcom\
.
Step 2: Modify dsi_hx8394f_720p_video
in dsi-panel-xxx-xxx-video.dtsi
into the name of the panel actually used. Other parameters can be modified referring to Chapter 2.1 to 2.6 as required.
/*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
*/
&mdss_mdp {
dsi_hx8394f_720p_video: qcom,mdss_dsi_hx8394f_720p_video {
qcom,mdss-dsi-panel-name = "hx8394f video mode dsi panel without DSC";
qcom,mdss-dsi-panel-type = "dsi_video_mode";
qcom,mdss-dsi-virtual-channel-id = <0>;
qcom,mdss-dsi-stream = <0>;
qcom,mdss-dsi-h-left-border = <0>;
qcom,mdss-dsi-h-right-border = <0>;
qcom,mdss-dsi-v-top-border = <0>;
qcom,mdss-dsi-v-bottom-border = <0>;
qcom,mdss-dsi-bpp = <24>;
NOTE: You should configure dsi_xxx_xxx_video: qcom,mdss_dsi_xxx_xxx_video
and make sure that dsi_xxx_xxx_video
is consistent with the node name corresponding to trinket-sde-display.dtsi and trinket-idp.dtsi.
Step 3: Add panel configuration file actually used dsi-panel-xxx-xxx-video.dtsi
to trinket-sde-display.dtsi
in the kernel\msm-4.14\arch\arm64\boot\dts\qcom\
directory. The format is #include "dsi-panel-xxx-xxx-video.dtsi"
. Take the default panel configuration file dsi-panel-hx8394f-720p-video.dtsi
as an example, as shown in the figure below:
#include "dsi-panel-nt36672-truly-fhd-video.dtsi"
#include "dsi-panel-hx8394f-720p-video.dtsi"
#include "dsi-panel-ili9881c-720p-video.dtsi"
#include "dsi-panel-ili9881d-720p-video.dtsi"
Step 4: Add qcom,dsi-display
related configurations of the current panel in trinket-sde-display.dtsi
. You can copy and modify the default panel configuration dsi_hx8394f_720p_video
, as shown in the figure below:
dsi_hx8394f_720p_video display: qcom,dsi-display@5 {
label = "dsi_hx8394f_720p_video_display";
qcom,display-type = "primary";
qcom,dsi-ctrl-num = <0>;
qcom,dsi-phy-num = <0>;
qcom,dsi-select-clocks = "mux_byte_clk0", "mux_pixel_clk0";
qcom,dsi-panel = <&dsi_hx8394f_720p_video>;
};
In the figure:
dsi_hx8394f_720p_video_display
: Panel name. You can modify it as required. Usually, you can refer to the panel node name in the panel configuration filedsi-panel-xxx-xxx-video.dtsi
, and add_display after dsi_xxx_xxx_video to name it. For example, the default panel configuration file of the module isdsi-panel-hx8394f-720p-video.dtsi
, and the node name of the panel isdsi_hx8394f_720p_video
. Then the panel name can be configured asdsi_hx8394f_720p_video_display
.label
: Generally, it should be consistent with the panel name.qcom,dsi-display@5
: The number followed by @ is the serial number of the panel. The module is configured with multiple panels by default, which are numbered in sequence, and the number cannot be repeated.qcom,display-type = "primary"
: primary indicates main panel.qcom,dsi-panel
: The name of panel node indsi-panel-xxx-xxx-video.dtsi
. The format isqcom,dsi-panel = <&dsi_xxx_xxx_video>;
. For example,qcom,dsi-panel = <&dsi_hx8394f_720p_video>;
.
NOTE: If you modify the configuration of label
, please inform Quectel, and Quectel will configure the name in UEFI to keep it consistent with the configuration of label
.
Step 5: Add the configured dsi_xxx_xxx_video_display
to dsi-display-list
. For example, add dsi_hx8394f_720p_video_display
to dsi-display-list
, as shown in the figure below:
sde_dsi: qcom,dsi-display {
compatible = "qcom,dsi-display";
qcom,dsi-ctrl = <&mdss_dsi0>;
qcom,dsi-phy = <&mdss_dsi_phy0>;
clocks
= <&mdss_dsi0_pll_BYTE0_MUX_CLK>,
<&mdss_dsi0_pll_PIXO_MUX_CLK>,
<&mdss_dsi0_pll_BYTE0_SRC_CLK>,
<&mdss_dsi0_pll_PIXO_SRC_CLK>,
<&mdss_dsi0_pll_SHADOW_BYTE0_SRC_CLK>,
<&mdss_dsi0_pll_SHADOW_PIXO_SRC_CLK>;
clock-names = "mux_byte_clk0", "mux_pixel_clk0",
"src_byte_clk0", "src_pixel_clk0",
"shadow_byte_clk0", "shadow_pixel_clk0";
pinctrl-names = "panel_active", "panel_suspend";
pinctrl-0 = <&sde_dsi_active &sde_te_active>;
pinctrl-1 = <&sde_dsi_suspend &sde_te_suspend>;
qcom,platform-te-gpio = <&tlmm 89 0>;
vddio-supply = <&L12A>;
// vdd-supply = <&L5P>;
lab-supply = <&lcdb_ldo_vreg>;
ibb-supply = <&lcdb_ncp_vreg>;
qcom,dsi-display-list =
<dsi_td4330_truly_vid_display>
<dsi_td4330_truly_cmd_display>
<dsi_sim_vid_display>
<dsi_hx83112a_truly_vid_display>
<dci_nt36672_truly_vid_display>
<dsi_hx8394f_720p_video_display>
<dsi_ili9881c_720p_video_display>
<dsi_ili9881d_720p_video_display>;
};
3.1.2. Update Kernel
Execute the following commands in sequence to compile and generate images.
source build/envsetup.sh
lunch trinket-userdebug
make bootimage
make dtboimage
Execute the following commands in sequence to burn the generated images to update the kernel.
adb reboot bootloader
fastboot flash boot boot.img
fastboot flash dtbo dtbo.img
fastboot reboot
3.2. Configure UEFI
The bootloader of SC668S series module is replaced by UEFI, and thus there is no need to debug LCD. You can send the configuration parameters debugged in Kernel to Quectel. Then Quectel will bring up the LCD in UEFI and send the updated image xbl.elf
to you.
4. Appendix References
Abbreviation | Description |
BPP | Bits Per Pixel |
DSI | Display Serial Interface |
EVB | Evaluation Board |
LCD | Liquid Crystal Display |
MDP | Mobile Display Processor |
MIPI | Mobile Industry Processor Interface |
PHY | Physical |
PWM | Pulse Width Modulation |
UEFI | Unified Extensible Firmware Interface |