# 视频输出 - Display

## 模块说明
Display 子系统 是 X5 项目中的视频显示引擎，其主要功能是为显示提供不同分辨率的视频输出。

### 硬件框图
Display 子系统由如下模块组成：
1. `MIPI DSI 控制器`：实现 SoC 和显示设备之间的高速数据传输，兼容 MIPI 协议。
2. `MIPI CSI TX 控制器`： 实现了设备端的 CSI-2 协议。 CSI-2 链路协议规范是 MIPI 联盟标准定义的通信协议的一部分，适用于移动系统的芯片间通信。
3. `MIPI D-PHY`：是 MIPI CSI TX 和 MIPI DSI 的物理层。
4. `BT1120` ：符合 ITU-R BT.1120 标准，可用于驱动外部 HDMI 设备，实现 4K 显示。
5. `DC8000Nano`：是一款高性能、低功耗的显示处理器。

各个模块之间的关系如下图所示：

![ 框图 ](./media/display/display_hardware_framework.png)

上图中， DDR 中图像可以通过 3 条通路输出到外部显示器，如下所示
- 通路 1 ： DDR 中的数据经过 DC8000Nano 、 MIPI DSI、 MIPI-DPHY 输出到 MIPI 显示屏中。
- 通路 2 ： DDR 中的数据经过 DC8000Nano、 BT1120 输出到外部显示器。
- 通路 3 ： DDR 中的数据直接经过 BT1120 输出到外部显示器。

**注意**：
1. DC8000Nano 的输出支持 4 条通路，其中黄色部分目前软件暂不支持。
2. BT1120 的输出可以接入 BT1120 协议的设备或者经过转换芯片连接其他协议的设备，比如 HDMI。
### 规格参数

#### DC8000Nano

1. 支持 4 个硬件图层： Video/Graphic layer， Overlay layer0 ， Overlay layer1 ， Cursor layer。
   - Video/Graphic layer 支持： AR12 AR15 RG16 RG24 AR24 RA12 RA15 RA24 AB12 AB15 BG16 BG24 AB24 BA12 BA15 BA24 YUYV YVYU NV12 NV21 XR24 XB24
   - Overlay layer0 支持 ： AR12 AR15 RG16 AR24 RA12 RA15 RA24 AB12 AB15 BG16 AB24 BA12 BA15 BA24 YUYV NV12 NV21
   - Overlay layer1 支持 ： AR12 AR15 RG16 RG24 AR24 RA12 RA15 RA24 AB12 AB15 BG16 BG24 AB24 BA12 BA15 BA24 YUYV YVYU XR24 XB24
   - Cursor layer 支持 ： AR24
2. 输入格式是 NV12 时， 最高支持分辨率到 3840x2160@30FPS，其余格式最高支持到 2560x1440@60FPS。
3. 支持图像数据从 BT1120/DSI/CSI-TX 输出。
4. 支持颜色重排、 Alpha blending、图层顺序定义、 Gamma 矫正、抖色、关键色。
5. 支持内敛 2DGPU 拓展实现如下功能：支持图层旋转、支持图层镜像翻转、支持八分之一到八倍缩放。

#### BT1120
1. 支持输出的分辨率最高可达 3840x2160@30FPS。
2. 输入和输出支持 8bit YUV422 和 8bit YUV420 。
3. 存储模式：
   - 半平面模式：用于在 Y 和 UV 内存缓冲区中存储 YUV422 和 YUV420 数据。
   - 支持 YUV422 打包模式 存储在内存中。
4. 操作模式：
   - 离线模式（ Offline Mode）：从 DDR 中读取像素数据。
   - 在线模式（ Online Mode）：从显示 IP（如 DC8000Nano）接收数据。
5. 支持两种扫描模式：逐行扫描模式（ Progressive Mode）和隔行扫描模式（ Interleaved Mode）。
1. 输出特性：
   - 输出像素数据宽度为 16 位。
   - 支持像素时钟输出的 DDR 模式（双倍数据速率） 或 SDR 模式（单倍数据速率）。
#### MIPI DSI
1. 最高支持 4 Lanes 输出。
2. 传输能力：
   - 每通道最高支持 2.5 Gbps 数据速率。
   - 支持最多 四个数据通道。
3. 工作模式：支持 非连续模式（ Non-continuous mode） 和 连续模式（ Continuous mode）。

#### MIPI DSI TX
1. 最高支持每 lane 2.5Gbps 速率。
2. 最高支持 4 Lanes 输出。

### 软件描述
X5 显示子系统软件部分接入了 DRM 框架， DRM 框架分为用户空间的 libdrm 以及内核空间的 DRM 驱动。

#### DRM 框架概述
在 DRM 框架里面，主要把显示子系统分成了几个部件： CRTC、 Encoder、 Planes、 Connector、 Framebuffer、 Bridge、 Panel。

|DRM 中的概念 | 含义 | 硬件模块的名称 |
| :----------|:-------|:-------|
|CRTC        | 显示控制器的抽象，负责管理显示设备的核心资源，定义显示内容的输出特性 |DC8000Nano 和 BT1120|
|Encoder     | CRTC 和连接器（ Connector）之间的中间体，负责处理数据格式和信号传输 |DSI Encoder：负责将数据转化为 MIPI DSI 信号 |
|Planes      | 显示数据的基本单位，用于处理多层图像合成（ Overlay） | DC8000Nano 的 4 个硬件图层 |
|Connector   | 显示设备的物理接口抽象 |HDMI 接口、 DSI 接口 |
|Bridge      | 用于扩展 Encoder 功能的模块，用于支持复杂的显示信号处理 | BT1120 转换成 HDMI 协议的转换芯片 |
|Panel       | 实际的显示屏抽象，定义显示设备的属性和行为 | 显示屏（物理面板） |




#### DRM 调试信息与硬件的对应关系

DRM 使用过程中，主要关注 Planes、 CRTC、 Connector 三种部件。系统启动后 , 可以使用 modetest 命令查看这些资源。

##### modetest 运行

**注意**：
1. modetest 打印的信息在不同版本上会有不一样体现。
2. modetest 命令运行前要保证如下命令已经执行。
```bash
modprobe panel-jc-050hd134
modprobe galcore
modprobe vio_n2d
modprobe lontium_lt8618
modprobe vs-x5-syscon-bridge
modprobe vs_drm
```

```bash
root@buildroot:/userdata/bin# modetest -M vs-drm -a
Encoders:
id      crtc    type    possible crtcs  possible clones
57      0       Virtual 0x00000001      0x00000001
69      0       Virtual 0x00000003      0x00000002
72      0       DSI     0x00000001      0x00000004
74      0       TMDS    0x00000003      0x00000008

Connectors:
id      encoder status          name            size (mm)       modes   encoders
73      0       connected       DSI-1           62x110          1       72
  modes:
        index name refresh (Hz) hdisp hss hse htot vdisp vss vse vtot
  #0 720x1280 61.99 720 752 772 792 1280 1300 1304 1324 65000 flags: nhsync, nvsync; type: preferred, driver
  props:
   	[...]
75      0       connected       HDMI-A-1        600x340         40      74
  modes:
        index name refresh (Hz) hdisp hss hse htot vdisp vss vse vtot
  #0 1920x1080 60.00 1920 2008 2052 2200 1080 1084 1089 1125 148500 flags: phsync, pvsync; type: preferred, driver
  #1 1920x1080 60.00 1920 2008 2052 2200 1080 1084 1089 1125 148500 flags: phsync, pvsync; type: driver
 	[...]
  props:
	[...]

CRTCs:
id      fb      pos     size
31      0       (0,0)   (0x0)
  #0  nan 0 0 0 0 0 0 0 0 0 flags: ; type:
  props:
	[...]
63      0       (0,0)   (0x0)
  #0  nan 0 0 0 0 0 0 0 0 0 flags: ; type:
  props:
	[...]

Planes:
id      crtc    fb      CRTC x,y        x,y     gamma size      possible crtcs
33      0       0       0,0             0,0     0               0x00000001
  formats: AR12 AR15 RG16 AR24 RA12 RA15 RA24 AB12 AB15 BG16 AB24 BA12 BA15 BA24 YUYV NV12 NV21 XR24 XB24
  props:
	[...]
41      0       0       0,0             0,0     0               0x00000001
  formats: AR12 AR15 RG16 RG24 AR24 RA12 RA15 RA24 AB12 AB15 BG16 BG24 AB24 BA12 BA15 BA24 YUYV YVYU NV12 NV21 XR24 XB24
  props:
	[...]
48      0       0       0,0             0,0     0               0x00000001
  formats: AR12 AR15 RG16 RG24 AR24 RA12 RA15 RA24 AB12 AB15 BG16 BG24 AB24 BA12 BA15 BA24 YUYV YVYU NV12 NV21 XR24 XB24
  props:
	[...]
53      0       0       0,0             0,0     0               0x00000001
  formats: AR24
  props:
	[...]
64      0       0       0,0             0,0     0               0x00000002
  formats: NV16 NV61 NV12 NV21 YUYV YVYU UYVY VYUY
  props:
        8 type:
                flags: immutable enum
                enums: Overlay=0 Primary=1 Cursor=2
                value: 1
	[...]

Frame buffers:
id      size    pitch
```

##### modetest 信息分析

DRM 调试信息与硬件的对应关系如下描述：
1. CRTC:
   - 31 -> DC8000Nano
   - 63 -> BT1120
2. Connectors:
   - 73 -> MIPI-DSI
   - 75 -> HDMI （ EVB 上接入了一颗 BT1120 转 HDMI 的芯片，型号是 LT8618SXB）
3. Planes:
   - 33 -> Primary Plane
   - 41 -> Overlay0 （内联 2D GPU 实现旋转、缩放功能）
   - 48 -> Overlay1
   - 53 -> Cursor
   - 64 -> BT1120 Primary Plane

**注意**：
1. ID 为 64 图层只能在 CRTC 为 63 （ BT1120 ）的时候使用。



#### DRM 快速体验


根据 `modetest` 获取到的信息，我们可以执行下面命令进行 HDMI 功能测试，执行之前请接入支持 1080P@60Hz 模式的显示器：

```bash
modetest -M vs-drm -a -s 75@31:1920x1080 -P 33@31:1920x1080@NV12
```

命令执行完成之后，显示屏上应该会出现 **SMPTE** 的测试彩条 **ECR-1-1978**：

![](./media/display_subsystem_smpte_patten.png)

## 参考示例
- Display 部分示例代码可以参考 [sample_vot](../samples/sample_vot.html)  章节

## API 参考

参考 [ 开源代码： drm lib](https://gitlab.freedesktop.org/mesa/drm/-/blob/main/xf86drmMode.h)
## 接口说明
参考 [ 开源代码： drm lib ](https://gitlab.freedesktop.org/mesa/drm/-/blob/main/xf86drmMode.h)
## 数据结构
参考 [ 开源代码： drm lib ](https://gitlab.freedesktop.org/mesa/drm/-/blob/main/xf86drmMode.h)
## 返回值说明
参考 [ 开源代码： drm lib ](https://gitlab.freedesktop.org/mesa/drm/-/blob/main/xf86drmMode.h)
