Understanding PinePhone's Display (MIPI DSI)

📝 2 Oct 2022

UPDATE: Apache NuttX RTOS now supports MIPI DSI! (See this)

How does Pine64 PinePhone control its LCD Display?

Let’s uncover all the secrets about PinePhone’s mysterious LCD Display and its MIPI Display Serial Interface…

• What’s a MIPI Display Serial Interface (DSI)

• What’s inside PinePhone’s LCD Display

• How it’s similar to PineTime’s ST7789 Display Controller

• One lane for Commands, but 4 lanes for Data!

• Implications of a RAM-less Display Controller

• What are PinePhone’s Display Engine (DE) and Timing Controller (TCON)

Why are we doing this?

We’re now porting Apache NuttX RTOS to PinePhone.

But it will look awfully dull until we render something on PinePhone’s LCD Display!

That’s why we’re probing the internals of PinePhone to create a NuttX Display Driver.

We’ll come back to this. Let’s continue the journey from our NuttX Porting Journal…

• lupyuen/pinephone-nuttx

PineTime Smartwatch with ST7789 Display Controller

§1 From PineTime To PinePhone

Why PineTime Smartwatch? Is it really similar to PinePhone’s Display?

Sounds unbelievable, but PineTime’s ST7789 Display Controller has plenty in common with PinePhone’s Display!

(Think of PinePhone as a Super-Sized PineTime)

In this article we shall explain PinePhone’s Display by comparing it with PineTime.

A quick recap of PineTime’s ST7789 Display…

• PineTime talks to its display over SPI (single data lane)…

  “Connect ST7789 Display”

  (We’ll soon see that PinePhone talks to its display over 4 data lanes)

• PineTime uses an extra pin to indicate whether it’s sending Commands or Pixel Data

  “ST7789 Data / Command Pin”

  (PinePhone won’t need this, we’ll learn why)

• At startup, PineTime sends an Initialisation Sequence of Commands to initialise the display…

  “Initialise The Display”

  (PinePhone will send a similar Initialisation Sequence, but much longer)

• PineTime renders a rectangular chunk of the display at a time…

  “Draw A Line”

  (PinePhone will refresh its entire display continously)

If we’re not familiar with PineTime’s ST7789 Display, please read the docs above!

We’ve read the docs, can we move on?

OK great! To understand how PinePhone’s Display differs from PineTime, we begin with the schematic…

LCD Display on PinePhone Schematic (Page 2)

§2 PinePhone Schematic

Let’s turn to Page 2 of the PinePhone Schematic to understand how PinePhone’s Display is connected…

• PinePhone Schematic

From the pic above, we see that the LCD Display is connected to the Allwinner A64 SoC via a MIPI Display Serial Interface (DSI).

(MIPI is the Mobile Industry Processor Interface Alliance)

What’s a MIPI Display Serial Interface?

Think of it as SPI, but supercharged with Multiple Data Lanes!

The (dull) technical details of DSI are covered here…

• “Display Serial Interface (DSI)”

But if we’re seeking a gentler intro to DSI, please follow me to the next section…

MIPI DSI Connector on PinePhone Schematic (Page 11)

§3 Connector for MIPI DSI

How shall we learn about MIPI DSI?

We’ll learn plenty about MIPI DSI (Display Serial Interface)… Just by looking at PinePhone’s Connector for the LCD Display!

Flip to Page 11 of the PinePhone Schematic and we’ll see the MIPI DSI Connector. (Pic above)

The MIPI DSI Connector connects PinePhone’s Allwinner A64 SoC directly to the LCD Display. In the pic above we see these connections…

• CKN and CKP are the DSI Clock Lines

  (Similar to SPI Clock)

• D0N and D0P for DSI Data Lane 0

  (Similar to SPI MISO / MOSI)

• D1N and D1P for DSI Data Lane 1

  (Yep DSI has more data lanes than SPI)

• D2N and D2P for DSI Data Lane 2

• D3N and D3P for DSI Data Lane 3

  (MIPI DSI has 4 data lanes!)

Why the N and P?

Because P=NP… Kidding!

N means Negative, P means Positive.

This means that MIPI DSI uses Differential Signalling for high-speed data transfers. (4.5 Gbps per lane)

(Differential Signalling is also used in HDMI and USB)

Are all 4 DSI Data Lanes identical?

For sending commands to the Display Controller, only DSI Lane 0 is used.

(Lane 0 is Bidirectional, it supports Direction Turnaround)

For sending pixel data, all 4 DSI Lanes will be used. (Unidirectional)

Let’s dig deeper into MIPI DSI…

Xingbangda XBD599 in PinePhone’s Linux Device Tree

§4 Xingbangda XBD599 LCD Panel

What’s connected to this MIPI DSI Connector?

The Linux Device Tree describes everything about PinePhone Hardware in a single text file. Let’s snoop around the Device Tree!

First we follow these steps to dump PinePhone’s Linux Device Tree in text format…

• “PinePhone Device Tree”

Then we search for MIPI DSI in the Device Tree…

• sun50i-a64-pinephone-1.2.dts

From the pic above we see that PinePhone’s MIPI DSI Connector is connected to Xingbangda XBD599.

This is a 5.99-inch 720x1440 MIPI DSI IPS LCD Panel.

But what’s super interesting is that Xingbangda XBD599 has a Sitronix ST7703 LCD Controller inside!

• Sitronix ST7703 LCD Controller Datasheet

Let’s probe deeper…

PineTime (ST7789) vs PinePhone (ST7703)

§5 Sitronix ST7703 LCD Controller

Sitronix ST7703 sounds familiar?

Yep Sitronix makes the LCD Controllers for BOTH PineTime and PinePhone!

In fact they’re from the same family of LCD Controllers. (ST7789 vs ST7703)

Just that PineTime uses an SPI Interface while PinePhone uses a MIPI DSI Interface. (Pic above)

The resolutions are different too. PinePhone has a huge display with more colours…

(Source)

Which means that PinePhone’s LCD Controller is RAM-less…

It doesn’t have any RAM inside to remember the pixels. (Unlike PineTime)

What’s the implication of a RAM-less display?

Because PinePhone’s LCD Controller doesn’t have any RAM inside to remember the pixels drawn…

PinePhone’s A64 SoC will pump a constant stream of pixels to refresh the display.

(Just like an old CRT TV!)

This pixel pumping is done by A64’s Display Engine (DE) and Timing Controller (TCON0). We’ll come back to this.

§6 Initialise LCD Controller

What happens inside PinePhone’s ST7703 LCD Controller?

Let’s figure out by looking at the initialisation of PinePhone’s ST7703 LCD Controller.

Xingbangda has provided an Initialisation Sequence of (magical) ST7703 Commands that we should send to the LCD Controller at startup…

The above commands are (mostly) documented in the ST7703 Datasheet…

• Sitronix ST7703 LCD Controller Datasheet

How to send the Init Sequence to ST7703?

We’ll send the above commands to ST7703 via a MIPI DSI Display Command: DCS Long Write.

Which we’ll explain next…

MIPI DSI Display Command Set from A31 User Manual (Page 837)

§7 Display Command Set for MIPI DSI

MIPI Display Serial Interface (DSI) defines a standard list of commands for controlling the display: DSI Display Command Set (DCS). (Pic above)

To send the Initialisation Sequence to ST7703, we shall transmit the DCS Long Write command. (Data Type 0x39)

Which is described in the ST7703 Datasheet (page 19)…

Display Command Set (DCS) Long Write is always using a Long Packet from the HOST to the driver IC.

The content can include Command (No Parameters) or Command with 1 or more parameters.

(More about “Long Packet” in a while)

And we shall transmit the DCS Long Write command in DSI Video Mode.

Let’s talk about DSI Video Mode…

(Note: We might need to use DCS Short Write No Parameters 0x05 for single-byte ST7703 Commands, DCS Short Write 1 Parameter 0x15 for 2-byte ST7703 Commands. See the Appendix for details)

DSI Video Mode from A31 User Manual (Page 841)

§8 Video Mode Only for MIPI DSI

What’s MIPI DSI Video Mode?

MIPI Display Serial Interface (DSI) supports 2 modes of operation (pic above)…

• DSI Command Mode: For sending DCS Commands to the display

  (DCS is the Display Command Set)

• DSI Video Mode: For blasting pixels to the display

But the ST7703 Datasheet (page 19) says that DSI Command Mode is NOT supported…

ST7703 only support Video mode. Video Mode refers to operation in which transfers from the host processor to the peripheral take the form of a real-time pixel stream.

And while we’re in DSI Video Mode, PinePhone needs to pump pixels continuously to ST7703 (or the display goes blank)…

In normal operation, the driver IC relies on the host processor to provide image data at sufficient bandwidth to avoid flicker or other visible artifacts in the displayed image. Video information should only be transmitted using High Speed Mode.

So we’ll transmit our DCS Commands in DSI Video Mode? Even though it’s meant for blasting pixels?

Yeah earlier we talked about sending the DCS Long Write command for initialising PinePhone’s ST7703 LCD Controller…

• “Initialise LCD Controller”

We’ll have to transmit the command in DSI Video Mode. (Instead of DSI Command Mode)

It sounds odd, but that’s how ST7703 works!

Wait we’re mixing DCS Commands and Pixel Data in the same mode? Won’t ST7703 LCD Controller get confused?

If we flip back to the Display Command Set…

• “Display Command Set for MIPI DSI”

  (Also in the ST7703 Datasheet, page 34)

We see that the DCS Long Write command has a different Data Type (0x39) from the other Pixel Stream commands.

(Like “Packed Pixel Stream, 24-bit RGB, 8-8-8 Format”, Data Type 0x3E)

That’s why PinePhone’s Display doesn’t need a Data / Command Pin like PineTime.

MIPI DSI Registers from A31 User Manual (Page 842)

§9 A64 Registers for MIPI DSI

How shall we send a DCS Long Write command to PinePhone’s Display?

To send a DCS Long Write command, we’ll set some Hardware Registers in A64’s MIPI DSI Controller.

The MIPI DSI Registers are missing from the A64 docs!

Yep it’s totally odd, but the A64 MIPI DSI Registers are actually documented in the Allwinner A31 SoC, which is a 32-bit SoC!

• Allwinner A31 User Manual (Page 842)

(A64 is actually an Allwinner H3 upgraded with 64-bit Arm Cores)

A64’s MIPI DSI Hardware is identical to A31 because both SoCs use the same MIPI DSI Driver…

static const struct of_device_id sun6i_dsi_of_table[] = {
  { .compatible = "allwinner,sun6i-a31-mipi-dsi" },
  { .compatible = "allwinner,sun50i-a64-mipi-dsi" },

(Source)

The Base Address of A64’s MIPI DSI Controller is 0x01CA 0000. (Pic above)

Also in the pic above is list of MIPI DSI Registers for A64 SoC.

For today we shall study 2 of the above registers…

• DSI_BASIC_CTL1_REG (Offset 0x14)

  DSI Configuration Register 1

• DSI_CMD_TX_REG (Offset 0x300 to 0x3FC):

  DSI Low Power Transmit Package Register

Though eventually we shall use these too…

• DSI_CTL_REG (Offset 0x00)

  DSI Control Register

• DSI_BASIC_CTL0_REG (Offset 0x10)

  DSI Configuration Register 0

• DSI_CMD_CTL_REG (Offset 0x200)

  DSI Low Power Control Register

• DSI_CMD_RX_REG (Offset 0x240 to 0x25C)

  DSI Low Power Receive Package Register

MIPI DSI Configuration Register 1 from A31 User Manual (Page 846)

§10 Initialise MIPI DSI

We said earlier that PinePhone’s ST7789 LCD Controller needs to run in DSI Video Mode (instead of DSI Command Mode)…

• “Video Mode Only for MIPI DSI”

At startup, our PinePhone Display Driver shall set DSI_Mode to 1. (Pic above)

That’s Bit 0 of DSI_BASIC_CTL1_REG (DSI Configuration Register 1) at Offset 0x14.

Our driver shall also set Video_Precision_Mode_Align to 1, Video_Frame_Start to 1 and Video_Start_Delay. (What’s the delay value?)

(Here’s how we set DSI_BASIC_CTL1_REG)

Anything else we should init at startup?

Actually we should turn on the MIPI DSI Controller BEFORE setting the Video Mode. At startup our driver shall set these registers…

• DSI_CTL_REG (Offset 0x00):

  Enable MIPI DSI (Bit 0)

• DSI_BASIC_CTL0_REG (Offset 0x10):

  Enable Error Correction Code (Bit 16)

  Enable Cyclic Redundancy Check (Bit 17)

• DSI_TRANS_START_REG (Offset 0x60, undocumented):

  Set to 10 (Why?)

• DSI_TRANS_ZERO_REG (Offset 0x78, undocumented):

  Set to 0 (Why?)

• DSI_DEBUG_DATA_REG (Offset 0x2f8, undocumented):

  Set to 0xFF (Why?)

(Here’s how we set the registers)

Is that all?

There’s something else that needs to be initialised: MIPI DPHY, the Display Physical Layer for MIPI DSI.

Sadly A64’s MIPI DPHY doesn’t seem to be documented, so we might need to do Reverse Engineering. See this…

• “Enable MIPI Display Physical Layer (DPHY)”

Don’t forget to switch on the Display Backlight!

• “PinePhone Backlight”

Now that we have initialised A64 MIPI DSI, we’re ready to send our DCS Command…

MIPI DSI Long Packet (Page 203)

§11 Long Packet for MIPI DSI

Earlier we talked about transmitting a DCS Long Write command (Data Type 0x39) to ST7703 LCD Controller…

• “Display Command Set for MIPI DSI”

Page 32 of the ST7703 Datasheet says that we need to transmit a Long Packet in this format…

Packet Header (4 bytes):

• Data Identifier (DI) (1 byte):

  Virtual Channel Identifier (Bits 6 to 7)

  Data Type (Bits 0 to 5)

  (Virtual Channel should be 0, I think)

• Word Count (WC) (2 bytes)：

  Number of bytes in the Packet Payload

• Error Correction Code (ECC) (1 byte):

  Allow single-bit errors to be corrected and 2-bit errors to be detected in the Packet Header

  (See “12.3.6.12: Error Correction Code”, Page 208)

  (How we compose the Packet Header)

Packet Payload:

• Data (0 to 65,541 bytes):

  Number of data bytes should match the Word Count (WC)

Packet Footer:

• Checksum (CS) (2 bytes):

  16-bit Cyclic Redundancy Check (CRC)

  (See “12.3.6.13: Packet Footer”, Page 210)

  (How we compute the CRC)

We have implemented MIPI DSI Long Packets in Apache NuttX Kernel…

• “Send MIPI DSI Packet”

Let’s program A64 to send this Long Packet.

(Page 32 of the ST7703 Datasheet also defines a Short Packet format, which is explained in the Appendix)

MIPI DSI Low Power Transmit Package Register from A31 User Manual (Page 856)

§12 Transmit Packet over MIPI DSI

We’re finally ready to transmit the DCS Long Write command to ST7703 LCD Controller!

We begin by setting the following bits to 1 in DSI_CMD_CTL_REG (DSI Low Power Control Register) at Offset 0x200…

• RX_Overflow (Bit 26): Clear flag for “Receive overflow”

• RX_Flag (Bit 25): Clear flag for “Receive has started”

• TX_Flag (Bit 9): Clear flag for “Transmit has started”

All other bits must be set to 0. (Like this)

We compose a Long Packet (or Short Packet) containing the DCS Long Write (or DCS Short Write) command…

• “Long Packet for MIPI DSI”

• “Short Packet for MIPI DSI”

The packet contains…

• Packet Header

• Packet Payload (only for Long Packet)

• Packet Footer (only for Long Packet)

Now we write the packet to DSI_CMD_TX_REG (DSI Low Power Transmit Package Register) at Offset 0x300 to 0x3FC. (Pic above)

What’s N in the table above?

We may rewrite the table without N like so…

Thus DSI_CMD_TX_REG works like a Packet Buffer that will contain the data to be transmitted over MIPI DSI.

Then we set Packet Length - 1 in Bits 0 to 7 (TX_Size) of DSI_CMD_CTL_REG (DSI Low Power Control Register) at Offset 0x200.

Finally we set DSI_INST_JUMP_SEL_REG (Offset 0x48, undocumented) to begin the Low Power Transmission.

(How we write the packet to DSI_CMD_TX_REG)

We also need to…

• Disable DSI Processing:

  Set Instru_En to 0 (Like this)

• Then Enable DSI Processing:

  Set Instru_En to 1 (Like this)

Instru_En is Bit 0 of DSI_BASIC_CTL0_REG (DSI Configuration Register 0) at Offset 0x10.

How will we know when the transmission is complete?

To check whether the transmission is complete, we poll on Instru_En.

(Like this)

Wow this looks super complicated!

Yeah. The complete steps to initialise the ST7703 LCD Controller will look like this…

• “Initialise ST7703 LCD Controller”

We have implemented the sending of MIPI DSI Packets in Apache NuttX Kernel…

• “Send MIPI DSI Packet”

Display Engine (DE) and Timing Controller (TCON0) from A64 User Manual (Page 498)

§13 Render Display

OK we have initialised the ST7703 display…

What about rendering the display?

Remember we said that the ST7703 LCD Controller is RAM-less? And thus we need to pump a constant stream of pixels to the display?

To do this, we program two controllers in Allwinner A64…

• Display Engine (DE): Execute the Rendering Pipeline to generate the pixels for display

  (Handles image buffering, scaling, mixing, …)

• Timing Controller (TCON0): Pump the generated pixels at the right clock frequency to the MIPI DSI display

  (Pic above)

Is there a specific sequence of steps for calling the Display Serial Interface, Display Engine and Timing Controller?

To render graphics on PinePhone’s LCD Display, our Display Driver needs to follow these steps…

• “Sequence of Steps for PinePhone Display Driver”

We’ll explain all these in the next article!

• “Rendering PinePhone’s Display (DE and TCON0)”

u/immibis on Reddit has shared some helpful tips…

“To actually display pixels on the screen you also need to program DE and TCON. I saw something somewhere about a test pattern that might be able to bypass this, and a framebuffer mode that bypasses the mixing IIRC.”

And we might hit some undocumented A64 Registers…

“several important registers used by the driver aren’t documented (the command registers) but the basic format is shown in the driver source code”

“…the module is running a little instruction set and the manual conspicuously omits any description of the instructions or even the registers where you put the instructions.”

We’ll find out soon in the next article!

Apache NuttX RTOS booting on PinePhone

§14 NuttX Display Driver for PinePhone

Once again, why are we doing all this?

We’re now porting Apache NuttX RTOS to PinePhone.

But it will look awfully dull until we render something on PinePhone’s LCD Display!

That’s why we’re probing the internals of PinePhone to create a NuttX Display Driver.

How shall we build the NuttX Driver for PinePhone’s Display?

Our NuttX Display Driver for PinePhone shall implement these functions (pic below)…

• “Complete Display Driver for PinePhone”

We have completed the Zig Implementation of the NuttX Driver…

• “NuttX RTOS for PinePhone: Display Driver in Zig”

• “NuttX RTOS for PinePhone: Render Graphics in Zig”

We’re porting the Zig Driver to C and adding to NuttX Kernel…

• “Upcoming NuttX Drivers”

Stay Tuned for Updates!

Inside our Complete Display Driver for PinePhone

§15 What’s Next

I hope we learnt lots about PinePhone’s Display…

• What’s a MIPI Display Serial Interface (DSI)

• What’s inside PinePhone’s LCD Display

• How it’s similar to PineTime’s Display Controller

• Implications of a RAM-less Display Controller

• What are PinePhone’s Display Engine (DE) and Timing Controller (TCON)

Please join me in the next article when we’ll build a PinePhone Display Driver in Zig!

• “NuttX RTOS for PinePhone: Display Driver in Zig”

• “NuttX RTOS for PinePhone: Render Graphics in Zig”

Please check out the other articles on NuttX for PinePhone…

• “Apache NuttX RTOS for PinePhone”

Many Thanks to my GitHub Sponsors for supporting my work! This article wouldn’t have been possible without your support.

• Sponsor me a coffee

• Discuss this article on Reddit

• My Current Project: “Apache NuttX RTOS for Ox64 BL808”

• My Other Project: “NuttX for Star64 JH7110”

• Older Project: “NuttX for PinePhone”

• Check out my articles

• RSS Feed

Got a question, comment or suggestion? Create an Issue or submit a Pull Request here…

lupyuen.github.io/src/dsi.md

§16 Notes

1. All writes to MIPI DSI Hardware Registers must use Data Memory Barrier (DMB)

   (According to this)

2. How did we find the Reference Code for the MIPI DSI Driver? We used GitHub Code Search…

   “Searching online for the driver”

3. This doc explains MIPI DSI rather well…

   “BL808 Reference Manual”

   (Page 181, Chapter 12: “DSI”)

4. ST7703 always runs in DSI Video Mode (instead of Command Mode).

   Does this mean that all DCS Commands are sent over all 4 DSI Data Lanes? (Instead of DSI Lane 0 only)

5. Can we receive data from ST7703?

   (See this)

Inside our Complete Display Driver for PinePhone

§17 Appendix: Sequence of Steps for PinePhone Display Driver

Is there a specific sequence of steps for calling the Display Serial Interface, Display Engine and Timing Controller?

To render graphics on PinePhone’s LCD Display, our Display Driver needs to follow these steps: render.zig

1. Turn on Display Backlight

   (Explained here)

   (Implemented here)

2. Initialise Timing Controller (TCON0)

   (Explained here)

   (Implemented here)

3. Initialise Power Management Integrated Circuit (PMIC) and wait 15 milliseconds

   (Explained here)

   (Implemented here)

4. Enable MIPI DSI Block

   (Explained here)

   (Implemented here)

5. Enable MIPI Display Physical Layer (DPHY)

   (Explained here)

   (Implemented here)

6. Reset LCD Panel and wait 15 milliseconds

   (Explained here)

   (Implemented here)

7. Initialise LCD Controller (ST7703)

   (Explained here)

   (Implemented here)

8. Start MIPI DSI HSC and HSD

   (High Speed Clock Mode and High Speed Data Transmission)

   (Explained here)

   (Implemented here)

9. Initialise Display Engine (DE)

   (Explained here)

   (Implemented here)

10. Wait 160 milliseconds

11. Render Graphics with Display Engine (DE)

    (Explained here)

    (Implemented here)

§18 Appendix: Enable MIPI DSI Block

Earlier we talked about the sequence of steps that our Display Driver needs to follow…

• “Sequence of Steps for PinePhone Display Driver”

This section explains how we enable the Allwinner A64 MIPI DSI Block, before calling it to transmit MIPI DSI Commands to the ST7703 LCD Controller.

We captured the log from p-boot dsi_init…

• Log from dsi_init

By decoding the captured addresses and values, we decipher the following steps to enable the Allwinner A64 MIPI DSI Block…

1. Enable MIPI DSI Bus

   BUS_CLK_GATING_REG0: CCU Offset 0x60 (A64 Page 100)

   • Set MIPIDSI_GATING (Bit 1) to 1 (Pass Gating Clock for MIPI DSI)

   BUS_SOFT_RST_REG0: CCU Offset 0x2C0 (A64 Page 138)

   • Set MIPI_DSI_RST (Bit 1) to 1 (Deassert MIPI DSI Reset)

   CCU Base Address: 0x01C2 0000 (A64 Page 82)

   mipi dsi bus enable
   setbits 0x1c20060, 0x2 (DMB)
   setbits 0x1c202c0, 0x2 (DMB)
   

2. Enable DSI Block

   DSI_CTL_REG: DSI Offset 0x0 (A31 Page 843)

   • Set DSI_En (Bit 0) to 1 (Enable DSI)

   DSI_BASIC_CTL0_REG: DSI Offset 0x10 (A31 Page 845)

   • Set CRC_En (Bit 17) to 1 (Enable CRC)
   • Set ECC_En (Bit 16) to 1 (Enable ECC)

   DSI_TRANS_START_REG: DSI Offset 0x60 (Undocumented)

   • Set to 10

   DSI_TRANS_ZERO_REG: DSI Offset 0x78 (Undocumented)

   • Set to 0

   DSI Base Address: 0x01CA 0000 (A31 Page 842)

   Enable the DSI block
   0x1ca0000 = 0x1 (DMB)
   0x1ca0010 = 0x30000 (DMB)
   0x1ca0060 = 0xa (DMB)
   0x1ca0078 = 0x0 (DMB)
   

3. Set Instructions (Undocumented)

   DSI_INST_FUNC_REG(0): DSI Offset 0x20

   • Set to 0x1f
   • Index 0 is DSI_INST_ID_LP11

   DSI_INST_FUNC_REG(1): DSI Offset 0x24

   • Set to 0x1000 0001
   • Index 1 is DSI_INST_ID_TBA

   DSI_INST_FUNC_REG(2): DSI Offset 0x28

   • Set to 0x2000 0010
   • Index 2 is DSI_INST_ID_HSC

   DSI_INST_FUNC_REG(3): DSI Offset 0x2c

   • Set to 0x2000 000f
   • Index 3 is DSI_INST_ID_HSD

   DSI_INST_FUNC_REG(4): DSI Offset 0x30

   • Set to 0x3010 0001
   • Index 4 is DSI_INST_ID_LPDT

   DSI_INST_FUNC_REG(5): DSI Offset 0x34

   • Set to 0x4000 0010
   • Index 5 is DSI_INST_ID_HSCEXIT

   DSI_INST_FUNC_REG(6): DSI Offset 0x38

   • Set to 0xf
   • Index 6 is DSI_INST_ID_NOP

   DSI_INST_FUNC_REG(7): DSI Offset 0x3c

   • Set to 0x5000 001f
   • Index 7 is DSI_INST_ID_DLY

   (DSI_INST_FUNC_REG(n) is (0x020 + (n) * 0x04))

   inst_init
   0x1ca0020 = 0x1f (DMB)
   0x1ca0024 = 0x10000001 (DMB)
   0x1ca0028 = 0x20000010 (DMB)
   0x1ca002c = 0x2000000f (DMB)
   0x1ca0030 = 0x30100001 (DMB)
   0x1ca0034 = 0x40000010 (DMB)
   0x1ca0038 = 0xf (DMB)
   0x1ca003c = 0x5000001f (DMB)
   

4. Configure Jump Instructions (Undocumented)

   DSI_INST_JUMP_CFG_REG(0): DSI Offset 0x4c

   • Set to 0x56 0001
   • Index 0 is DSI_INST_JUMP_CFG

   (DSI_INST_JUMP_CFG_REG(n) is (0x04c + (n) * 0x04))

   DSI_DEBUG_DATA_REG: DSI Offset 0x2f8

   • Set to 0xff

   0x1ca004c = 0x560001 (DMB)
   0x1ca02f8 = 0xff (DMB)
   

5. Set Video Start Delay

   DSI_BASIC_CTL1_REG: DSI Offset 0x14 (A31 Page 846)

   • Set Video_Start_Delay (Bits 4 to 16) to 1468 (Line Delay)
   • Set Video_Precision_Mode_Align (Bit 2) to 1 (Fill Mode)
   • Set Video_Frame_Start (Bit 1) to 1 (Precision Mode)
   • Set DSI_Mode (Bit 0) to 1 (Video Mode)

   Note: Video_Start_Delay is actually 13 bits, not 8 bits as stated in the A31 User Manual

   get_video_start_delay
   0x1ca0014 = 0x5bc7 (DMB)
   

6. Set Burst (Undocumented)

   DSI_TCON_DRQ_REG: DSI Offset 0x7c

   • Set to 0x1000 0007

   setup_burst
   0x1ca007c = 0x10000007 (DMB)
   

7. Set Instruction Loop (Undocumented)

   DSI_INST_LOOP_SEL_REG: DSI Offset 0x40

   • Set to 0x3000 0002

   DSI_INST_LOOP_NUM_REG(0): DSI Offset 0x44

   • Set to 0x31 0031

   DSI_INST_LOOP_NUM_REG(1): DSI Offset 0x54

   • Set to 0x31 0031

   (DSI_INST_LOOP_NUM_REG(n) is (0x044 + (n) * 0x10))

   setup_inst_loop
   0x1ca0040 = 0x30000002 (DMB)
   0x1ca0044 = 0x310031 (DMB)
   0x1ca0054 = 0x310031 (DMB)
   

8. Set Pixel Format

   DSI_PIXEL_PH_REG: DSI Offset 0x90 (A31 Page 848)

   • Set ECC (Bits 24 to 31) to 19
   • Set WC (Bits 8 to 23) to 2160 (Byte Numbers of PD in a Pixel Packet)
   • Set VC (Bits 6 to 7) to 0 (Virtual Channel)
   • Set DT (Bits 0 to 5) to 0x3E (24-bit Video Mode)

   DSI_PIXEL_PF0_REG: DSI Offset 0x98 (A31 Page 849)

   • Set CRC_Force (Bits 0 to 15) to 0xffff (Force CRC to this value)

   DSI_PIXEL_PF1_REG: DSI Offset 0x9c (A31 Page 849)

   • Set CRC_Init_LineN (Bits 16 to 31) to 0xffff (CRC initial to this value in transmitions except 1st one)
   • Set CRC_Init_Line0 (Bits 0 to 15) to 0xffff (CRC initial to this value in 1st transmition every frame)

   DSI_PIXEL_CTL0_REG: DSI Offset 0x80 (A31 Page 847)

   • Set PD_Plug_Dis (Bit 16) to 1 (Disable PD plug before pixel bytes)
   • Set Pixel_Endian (Bit 4) to 0 (LSB first)
   • Set Pixel_Format (Bits 0 to 3) to 8 (24-bit RGB888)

   setup_format
   0x1ca0090 = 0x1308703e (DMB)
   0x1ca0098 = 0xffff (DMB)
   0x1ca009c = 0xffffffff (DMB)
   0x1ca0080 = 0x10008 (DMB)
   

9. Set Sync Timings

   DSI_BASIC_CTL_REG: DSI Offset 0x0c (Undocumented)

   • Set to 0

   DSI_SYNC_HSS_REG: DSI Offset 0xb0 (A31 Page 850)

   • Set ECC (Bits 24 to 31) to 0x12
   • Set D1 (Bits 16 to 23) to 0
   • Set D0 (Bits 8 to 15) to 0
   • Set VC (Bits 6 to 7) to 0 (Virtual Channel)
   • Set DT (Bits 0 to 5) to 0x21 (HSS)

   DSI_SYNC_HSE_REG: DSI Offset 0xb4 (A31 Page 850)

   • Set ECC (Bits 24 to 31) to 1
   • Set D1 (Bits 16 to 23) to 0
   • Set D0 (Bits 8 to 15) to 0
   • Set VC (Bits 6 to 7) to 0 (Virtual Channel)
   • Set DT (Bits 0 to 5) to 0x31 (HSE)

   DSI_SYNC_VSS_REG: DSI Offset 0xb8 (A31 Page 851)

   • Set ECC (Bits 24 to 31) to 7
   • Set D1 (Bits 16 to 23) to 0
   • Set D0 (Bits 8 to 15) to 0
   • Set VC (Bits 6 to 7) to 0 (Virtual Channel)
   • Set DT (Bits 0 to 5) to 1 (VSS)

   DSI_SYNC_VSE_REG: DSI Offset 0xbc (A31 Page 851)

   • Set ECC (Bits 24 to 31) to 0x14
   • Set D1 (Bits 16 to 23) to 0
   • Set D0 (Bits 8 to 15) to 0
   • Set VC (Bits 6 to 7) to 0 (Virtual Channel)
   • Set DT (Bits 0 to 5) to 0x11 (VSE)

   setup_timings
   0x1ca000c = 0x0 (DMB)
   0x1ca00b0 = 0x12000021 (DMB)
   0x1ca00b4 = 0x1000031 (DMB)
   0x1ca00b8 = 0x7000001 (DMB)
   0x1ca00bc = 0x14000011 (DMB)
   

10. Set Basic Size (Undocumented)

    DSI_BASIC_SIZE0_REG: DSI Offset 0x18

    • Set Video_VBP (Bits 16 to 27) to 17
    • Set Video_VSA (Bits 0 to 11) to 10

    DSI_BASIC_SIZE1_REG: DSI Offset 0x1c

    • Set Video_VT (Bits 16 to 28) to 1485
    • Set Video_VACT (Bits 0 to 11) to 1440

    0x1ca0018 = 0x11000a (DMB)
    0x1ca001c = 0x5cd05a0 (DMB)
    

11. Set Horizontal Blanking

    DSI_BLK_HSA0_REG: DSI Offset 0xc0 (A31 Page 852)

    • Set HSA_PH (Bits 0 to 31) to 0x900 4a19

    DSI_BLK_HSA1_REG: DSI Offset 0xc4 (A31 Page 852)

    • Set HSA_PF (Bits 16 to 31) to 0x50b4
    • Set HSA_PD (Bits 0 to 7) to 0

    DSI_BLK_HBP0_REG: DSI Offset 0xc8 (A31 Page 852)

    • Set HBP_PH (Bits 0 to 31) to 0x3500 5419

    DSI_BLK_HBP1_REG: DSI Offset 0xcc (A31 Page 852)

    • Set HBP_PF (Bits 16 to 31) to 0x757a
    • Set HBP_PD (Bits 0 to 7) to 0

    DSI_BLK_HFP0_REG: DSI Offset 0xd0 (A31 Page 852)

    • Set HFP_PH (Bits 0 to 31) to 0x900 4a19

    DSI_BLK_HFP1_REG: DSI Offset 0xd4 (A31 Page 853)

    • Set HFP_PF (Bits 16 to 31) to 0x50b4
    • Set HFP_PD (Bits 0 to 7) to 0

    DSI_BLK_HBLK0_REG: DSI Offset 0xe0 (A31 Page 853)

    • Set HBLK_PH (Bits 0 to 31) to 0xc09 1a19

    DSI_BLK_HBLK1_REG: DSI Offset 0xe4 (A31 Page 853)

    • Set HBLK_PF (Bits 16 to 31) to 0x72bd
    • Set HBLK_PD (Bits 0 to 7) to 0

    0x1ca00c0 = 0x9004a19 (DMB)
    0x1ca00c4 = 0x50b40000 (DMB)
    0x1ca00c8 = 0x35005419 (DMB)
    0x1ca00cc = 0x757a0000 (DMB)
    0x1ca00d0 = 0x9004a19 (DMB)
    0x1ca00d4 = 0x50b40000 (DMB)
    0x1ca00e0 = 0xc091a19 (DMB)
    0x1ca00e4 = 0x72bd0000 (DMB)
    

12. Set Vertical Blanking

    DSI_BLK_VBLK0_REG: DSI Offset 0xe8 (A31 Page 854)

    • Set VBLK_PH (Bits 0 to 31) to 0x1a00 0019

    DSI_BLK_VBLK1_REG: DSI Offset 0xec (A31 Page 854)

    • Set VBLK_PF (Bits 16 to 31) to 0xffff
    • Set VBLK_PD (Bits 0 to 7) to 0

    0x1ca00e8 = 0x1a000019 (DMB)
    0x1ca00ec = 0xffff0000 (DMB)
    

Based on the above steps, we have implemented in Zig the PinePhone Driver that enables the Allwinner A64 MIPI DSI Block…

• pinephone-nuttx/display.zig

• Output Log for display.zig

We have implemented the driver in Apache NuttX Kernel…

• “Enable MIPI DSI and D-PHY”

§19 Appendix: Start MIPI DSI HSC and HSD

Earlier we talked about the sequence of steps that our Display Driver needs to follow…

• “Sequence of Steps for PinePhone Display Driver”

This section explains how we start Allwinner A64 MIPI DSI in HSC and HSD Modes, before calling it to transmit MIPI DSI Commands to the ST7703 LCD Controller.

(High Speed Clock Mode and High Speed Data Transmission)

We captured the log from p-boot dsi_init…

• Log from dsi_init

By decoding the captured addresses and values, we decipher the following steps to start Allwinner A64 MIPI DSI in HSC and HSD Modes…

1. Start HSC (Undocumented)

   DSI_INST_JUMP_SEL_REG: DSI Offset 0x48

   • Set to 0xf02

   DSI Base Address: 0x01CA 0000 (A31 Page 842)

   dsi_start DSI_START_HSC
   0x1ca0048 = 0xf02 (DMB)
   

2. Commit

   DSI_BASIC_CTL0_REG: DSI Offset 0x10 (A31 Page 845)

   • Set Instru_En (Bit 0) to 1 (Enable DSI Processing from Instruction 0)

   dsi_update_bits: 0x01ca0010 : 00030000 -> (00000001) 00000001 (DMB)
   addr=0x1ca0010, mask=0x1, val=0x1 (DMB)
   

3. Instruction Function Lane (Undocumented)

   DSI_INST_FUNC_REG(0): DSI Offset 0x20

   • Set DSI_INST_FUNC_LANE_CEN (Bit 4) to 0
   • Index 0 is DSI_INST_ID_LP11

   (DSI_INST_FUNC_REG(n) is (0x020 + (n) * 0x04))

   dsi_update_bits: 0x01ca0020 : 0000001f -> (00000010) 00000000 (DMB)
   addr=0x1ca0020, mask=0x10, val=0x0 (DMB)
   

4. Wait 1,000 microseconds

   udelay 1000
   

5. Start HSD (Undocumented)

   DSI_INST_JUMP_SEL_REG: DSI Offset 0x48

   • Set to 0x63f0 7006

   dsi_start DSI_START_HSD
   0x1ca0048 = 0x63f07006 (DMB)
   

6. Commit

   DSI_BASIC_CTL0_REG: DSI Offset 0x10 (A31 Page 845)

   • Set Instru_En (Bit 0) to 1 (Enable DSI Processing from Instruction 0)

   dsi_update_bits: 0x01ca0010 : 00030000 -> (00000001) 00000001 (DMB)
   addr=0x1ca0010, mask=0x1, val=0x1 (DMB)
   

Based on the above steps, we have implemented in Zig the PinePhone Driver that starts Allwinner A64 MIPI DSI (in HSC and HSD Modes)…

• pinephone-nuttx/display.zig

• Output Log for display.zig

We have implemented the driver in Apache NuttX Kernel…

• “Enable MIPI DSI and D-PHY”

MIPI DSI Protocol Layers (Page 183)

§20 Appendix: Enable MIPI Display Physical Layer (DPHY)

Earlier we talked about initialising the MIPI DSI Controller…

• “Initialise MIPI DSI”

There’s something else that needs to be initialised: MIPI DPHY, the Display Physical Layer for MIPI DSI…

• “A64 MIPI DPHY”

MIPI DPHY is the “Physical Layer” in the pic above.

(MIPI DSI runs in the layers above MIPI DPHY)

Sadly Allwinner A64’s MIPI DPHY doesn’t seem to be documented, so we might need to do Reverse Engineering.

How do we implement MIPI DPHY if it’s undocumented?

We captured the log from p-boot dphy_enable…

• Log from dphy_enable

By decoding the captured addresses and values, we decipher the following steps to enable the Allwinner A64 MIPI Display Physical Layer (DPHY)…

1. Set DSI Clock to 150 MHz (600 MHz / 4)

   MIPI_DSI_CLK_REG: CCU Offset 0x168 (A64 Page 122)

   • Set DSI_DPHY_GATING (Bit 15) to 1 (DSI DPHY Clock is On)
   • Set DSI_DPHY_SRC_SEL (Bits 8 to 9) to 0b10 (DSI DPHY Clock Source is PLL_PERIPH0(1X))
   • Set DPHY_CLK_DIV_M (Bits 0 to 3) to 3 (DSI DPHY Clock divide ratio - 1)

   CCU Base Address: 0x01C2 0000 (A64 Page 82)

   150MHz (600 / 4)
   0x1c20168 = 0x8203 (DMB)
   

2. Power on DPHY Tx (Undocumented)

   DPHY_TX_CTL_REG: DPHY Offset 0x04

   • Set to 0x1000 0000

   DPHY_TX_TIME0_REG: DPHY Offset 0x10

   • Set to 0xa06 000e

   DPHY_TX_TIME1_REG: DPHY Offset 0x14

   • Set to 0xa03 3207

   DPHY_TX_TIME2_REG: DPHY Offset 0x18

   • Set to 0x1e

   DPHY_TX_TIME3_REG: DPHY Offset 0x1c

   • Set to 0x0

   DPHY_TX_TIME4_REG: DPHY Offset 0x20

   • Set to 0x303

   DPHY Base Address: 0x01ca 1000

   0x1ca1004 = 0x10000000 (DMB)
   0x1ca1010 = 0xa06000e (DMB)
   0x1ca1014 = 0xa033207 (DMB)
   0x1ca1018 = 0x1e (DMB)
   0x1ca101c = 0x0 (DMB)
   0x1ca1020 = 0x303 (DMB)
   

3. Enable DPHY (Undocumented)

   DPHY_GCTL_REG: DPHY Offset 0x00 (Enable DPHY)

   • Set to 0x31

   DPHY_ANA0_REG: DPHY Offset 0x4c (PWS)

   • Set to 0x9f00 7f00

   DPHY_ANA1_REG: DPHY Offset 0x50 (CSMPS)

   • Set to 0x1700 0000

   DPHY_ANA4_REG: DPHY Offset 0x5c (CKDV)

   • Set to 0x1f0 1555

   DPHY_ANA2_REG: DPHY Offset 0x54 (ENIB)

   • Set to 0x2

   Wait 5 microseconds

   0x1ca1000 = 0x31 (DMB)
   0x1ca104c = 0x9f007f00 (DMB)
   0x1ca1050 = 0x17000000 (DMB)
   0x1ca105c = 0x1f01555 (DMB)
   0x1ca1054 = 0x2 (DMB)
   udelay 5
   

4. Enable LDOR, LDOC, LDOD (Undocumented)

   DPHY_ANA3_REG: DPHY Offset 0x58 (Enable LDOR, LDOC, LDOD)

   • Set to 0x304 0000

   Wait 1 microsecond

   DPHY_ANA3_REG: DPHY Offset 0x58 (Enable VTTC, VTTD)

   • Set bits 0xf800 0000

   Wait 1 microsecond

   DPHY_ANA3_REG: DPHY Offset 0x58 (Enable DIV)

   • Set bits 0x400 0000

   Wait 1 microsecond

   DPHY_ANA2_REG: DPHY Offset 0x54 (Enable CK_CPU)

   • Set bits 0x10

   Wait 1 microsecond

   DPHY_ANA1_REG: DPHY Offset 0x50 (VTT Mode)

   • Set bits 0x8000 0000

   DPHY_ANA2_REG: DPHY Offset 0x54 (Enable P2S CPU)

   • Set bits 0xf00 0000

   0x1ca1058 = 0x3040000 (DMB)
   udelay 1
   update_bits addr=0x1ca1058, mask=0xf8000000, val=0xf8000000 (DMB)
   udelay 1
   update_bits addr=0x1ca1058, mask=0x4000000, val=0x4000000 (DMB)
   udelay 1
   update_bits addr=0x1ca1054, mask=0x10, val=0x10 (DMB)
   udelay 1
   update_bits addr=0x1ca1050, mask=0x80000000, val=0x80000000 (DMB)
   update_bits addr=0x1ca1054, mask=0xf000000, val=0xf000000 (DMB)
   

Based on the above steps, we have implemented in Zig the PinePhone Driver that enables the Allwinner A64 MIPI Display Physical Layer (DPHY)…

• pinephone-nuttx/dphy.zig

• Output Log for dphy.zig

We have implemented the driver in Apache NuttX Kernel…

• “Enable MIPI DSI and D-PHY”

MIPI DSI Short Packet (Page 201)

§21 Appendix: Short Packet for MIPI DSI

According to BL808 Reference Manual (Page 201, pic above)…

A Short Packet consists of 8-bit data identification (DI), two bytes of commands or data, and 8-bit ECC.

The length of a short packet is 4 bytes including ECC.

Thus a MIPI DSI Short Packet (compared with Long Packet)…

• Doesn’t have Packet Payload and Packet Footer (CRC)

• Instead of Word Count (WC), the Packet Header now has 2 bytes of data

• DCS Command (Data Type) is…

  DCS Short Write Without Parameter (0x05) for sending 1 byte of data

  DCS Short Write With Parameter (0x15) for sending 2 bytes of data

Everything else is the same.

We have implemented MIPI DSI Short Packets in Apache NuttX Kernel…

• “Send MIPI DSI Packet”

§22 Appendix: Initialise LCD Controller

Earlier we talked about the sequence of steps that our Display Driver needs to follow…

• “Sequence of Steps for PinePhone Display Driver”

Xingbangda has provided an Initialisation Sequence of (magical) ST7703 Commands that we should send to the LCD Controller at startup.

The commands below are (mostly) documented in the ST7703 Datasheet…

• Sitronix ST7703 LCD Controller Datasheet

The Initialisation Sequence consists of the following 20 DCS Commands that we should send via DCS Short Write or DCS Long Write…

The above commands were originally specified here (partially annotated)…

• Initialisation Sequence

We added the last 2 commands (SLPOUT and Display On) to be consistent with the p-boot Version, which was tested OK on NuttX…

• p-boot Initialisation Sequence