# Display 驱动

基于 lisa_device 框架的显示设备驱动，为 ARCS 平台提供统一的 LCD 显示屏控制接口。

## 功能特性

- **总线支持**: 支持 SPI 4-Wire、SPI 3-Wire、QSPI、RGB 并行等多种总线接口
- **面板支持**: 支持 ST7789P3、AXS15231B 等多款显示控制器
- **背光控制**: 支持 PWM 调光和单线调光两种背光控制方式
- **显示方向**: 支持 0°/90°/180°/270° 四种显示方向，可选 CPDMA 硬件加速旋转
- **像素格式**: 支持 RGB565、RGB888、BGR565、ARGB8888、单色等多种像素格式
- **TE 同步**: 支持撕裂效应（Tearing Effect）同步，防止画面撕裂
- **线程安全**: 内部使用互斥锁保护，支持多线程环境使用

## 配置选项

在 `prj.conf` 中启用驱动：

```kconfig
# 启用 Display 驱动
CONFIG_LISA_DISPLAY_DEVICE=y

# 选择面板驱动（二选一）
CONFIG_LISA_DISPLAY_PANEL_ST7789P3=y    # ST7789P3 面板
# CONFIG_LISA_DISPLAY_PANEL_AXS15231B=y # AXS15231B 面板

# 选择总线类型（四选一）
CONFIG_LISA_DISPLAY_BUS_SPI_4WIRE=y     # 4线 SPI
# CONFIG_LISA_DISPLAY_BUS_SPI_3WIRE=y   # 3线 SPI
# CONFIG_LISA_DISPLAY_BUS_QSPI=y        # QSPI
# CONFIG_LISA_DISPLAY_BUS_RGB=y         # RGB 并行

# 可选功能
CONFIG_LISA_DISPLAY_TE_SYNC=y           # 启用 TE 同步
CONFIG_LISA_DISPLAY_CPDMA_ROTATE=y      # 启用 CPDMA 硬件旋转
CONFIG_LISA_DISPLAY_CPDMA_CH=2          # CPDMA 通道号
CONFIG_LISA_DISPLAY_COLOR_INVERT=y      # 启用颜色反转
```

## API 接口

### 总线配置接口

```c
int lisa_display_attach_bus(lisa_device_t *dev, const lisa_display_config_t *config);
```

**重要**: 必须先调用 `lisa_display_attach_bus()` 配置总线后，才能使用其他显示功能 API。

### 显示控制接口

```c
int lisa_display_get_capabilities(lisa_device_t *dev, lisa_display_capabilities_t *caps);
int lisa_display_blanking_on(lisa_device_t *dev);
int lisa_display_blanking_off(lisa_device_t *dev);
int lisa_display_set_brightness(lisa_device_t *dev, uint8_t brightness);
int lisa_display_set_orientation(lisa_device_t *dev, lisa_display_orientation_t orientation);
```

### 数据写入接口

```c
int lisa_display_write(lisa_device_t *dev, uint16_t x, uint16_t y,
                       const lisa_display_buffer_desc_t *desc, const void *buf);
```

## 使用示例

### 基础显示（SPI 4-Wire）

```c
#include "lisa_display.h"
#include "lisa_gpio.h"

// 1. 获取设备
lisa_device_t *display = lisa_device_get("display");
lisa_device_t *gpioa = lisa_device_get("gpioa");
lisa_device_t *gpiob = lisa_device_get("gpiob");
lisa_device_t *spi = lisa_device_get("spi1");
lisa_device_t *pwm = lisa_device_get("pwm0");

if (!display || !gpioa || !gpiob || !spi || !pwm) {
    return -1;
}

// 2. 配置总线
lisa_display_config_t config = {
    .bus_type = LISA_DISPLAY_BUS_SPI_4WIRE,
    .bus_config.spi_4wire = {
        .spi_dev = spi,
        .cs_gpio = gpiob,
        .cs_pin = 1,
        .dc_gpio = gpiob,
        .dc_pin = 0,
        .spi_freq = 50000000,  // 50MHz
    },
    .backlight = {
        .type = LISA_DISPLAY_BACKLIGHT_TYPE_PWM,
        .config.pwm = {
            .dev = pwm,
            .channel = 0,
            .freq = 2000,
        },
    },
    .rst_gpio = gpioa,
    .rst_pin = 1,
};
lisa_display_attach_bus(display, &config);

// 3. 获取显示能力
lisa_display_capabilities_t caps;
lisa_display_get_capabilities(display, &caps);

// 4. 分配帧缓冲区
size_t buf_size = caps.width * caps.height * sizeof(uint16_t);
uint16_t *buffer = lisa_mem_alloc(buf_size);

// 5. 开启显示
lisa_display_blanking_off(display);
lisa_display_set_brightness(display, 80);  // 80% 亮度

// 6. 写入显示数据
lisa_display_buffer_desc_t desc = {
    .width = caps.width,
    .height = caps.height,
    .buf_size = buf_size,
};

// 填充红色
for (int i = 0; i < caps.width * caps.height; i++) {
    buffer[i] = LISA_DISPLAY_COLOR_RED;
}
lisa_display_write(display, 0, 0, &desc, buffer);
```

### 设置显示方向

```c
#include "lisa_display.h"

lisa_device_t *display = lisa_device_get("display");

// 设置为 90 度旋转
int ret = lisa_display_set_orientation(display, LISA_DISPLAY_ORIENTATION_90);
if (ret != LISA_DEVICE_OK) {
    // 错误处理
}
```

### 使用 QSPI 总线

```c
#include "lisa_display.h"

lisa_device_t *display = lisa_device_get("display");
lisa_device_t *qspi = lisa_device_get("qspilcd0");
lisa_device_t *gpio = lisa_device_get("gpioa");

lisa_display_config_t config = {
    .bus_type = LISA_DISPLAY_BUS_QSPI,
    .bus_config.qspi = {
        .qspi_dev = qspi,
        .qspi_freq = 50000000,
        .cs_gpio = gpio,
        .cs_pin = 19,
    },
    .rst_gpio = gpio,
    .rst_pin = 1,
};
lisa_display_attach_bus(display, &config);
```

## 硬件配置

### 引脚复用配置

Display 驱动依赖底层总线驱动（SPI、QSPI、GPIO、PWM）的引脚配置。需要在板型目录中配置相应的 pinmux 函数。

**配置位置**:
- **定义**: `boards/<板型名>/pinmux.c` 中实现各驱动的 pinmux 函数
- **声明**: `boards/<板型名>/pinmux.h` 中声明函数
- **调用时机**: 各底层设备初始化时自动调用

**示例** (参考 `boards/arcs_evb/pinmux.c`):

```c
// SPI1 引脚配置（用于 Display 数据传输）
void lisa_spi1_pinmux()
{
    IOMuxManager_PinConfigure(CSK_IOMUX_PAD_B, 5, 6);  // SPI1 CLK
    IOMuxManager_PinConfigure(CSK_IOMUX_PAD_B, 3, 6);  // SPI1 MOSI
    IOMuxManager_PinConfigure(CSK_IOMUX_PAD_B, 1, 6);  // SPI1 CS/MISO
}

// GPIO 引脚配置（用于 RST、DC、CS 控制）
void lisa_gpioa_pinmux()
{
    IOMuxManager_PinConfigure(CSK_IOMUX_PAD_A, 1, 1);  // LCD RST
}

void lisa_gpiob_pinmux()
{
    IOMuxManager_PinConfigure(CSK_IOMUX_PAD_B, 0, 0);  // LCD DC
    IOMuxManager_PinConfigure(CSK_IOMUX_PAD_B, 8, 0);  // LCD TE
}

// PWM 引脚配置（用于背光控制）
void lisa_pwm_pinmux()
{
    IOMuxManager_PinConfigure(CSK_IOMUX_PAD_A, 0, 12); // LCD 背光 PWM
}
```

**注意**:
- 功能码需根据芯片手册确定
- 不同板型的引脚配置可能不同
- 只需配置实际使用的引脚

## 参数说明

### 总线类型

| 枚举值 | 说明 |
|-------|------|
| `LISA_DISPLAY_BUS_SPI_3WIRE` | 3线 SPI（SCLK, MOSI, CS） |
| `LISA_DISPLAY_BUS_SPI_4WIRE` | 4线 SPI（SCLK, MOSI, CS, D/C） |
| `LISA_DISPLAY_BUS_QSPI` | QSPI 接口 |
| `LISA_DISPLAY_BUS_RGB` | RGB 并行接口 |

### 像素格式

| 枚举值 | 说明 |
|-------|------|
| `LISA_DISPLAY_PIXEL_FORMAT_RGB_565` | RGB565，每像素 2 字节 |
| `LISA_DISPLAY_PIXEL_FORMAT_RGB_888` | RGB888，每像素 3 字节 |
| `LISA_DISPLAY_PIXEL_FORMAT_BGR_565` | BGR565，每像素 2 字节 |
| `LISA_DISPLAY_PIXEL_FORMAT_ARGB_8888` | ARGB8888，每像素 4 字节 |
| `LISA_DISPLAY_PIXEL_FORMAT_MONO_1` | 单色，每像素 1 位 |

### 显示方向

| 枚举值 | 说明 |
|-------|------|
| `LISA_DISPLAY_ORIENTATION_0` | 0° 正常方向 |
| `LISA_DISPLAY_ORIENTATION_90` | 90° 顺时针旋转 |
| `LISA_DISPLAY_ORIENTATION_180` | 180° 旋转 |
| `LISA_DISPLAY_ORIENTATION_270` | 270° 顺时针旋转 |

### 常用颜色宏（RGB565）

| 宏定义 | 值 | 说明 |
|-------|-----|------|
| `LISA_DISPLAY_COLOR_BLACK` | `0x0000` | 黑色 |
| `LISA_DISPLAY_COLOR_WHITE` | `0xFFFF` | 白色 |
| `LISA_DISPLAY_COLOR_RED` | `0xF800` | 红色 |
| `LISA_DISPLAY_COLOR_GREEN` | `0x07E0` | 绿色 |
| `LISA_DISPLAY_COLOR_BLUE` | `0x001F` | 蓝色 |

## 返回值说明

| 返回值 | 说明 |
|-------|------|
| `LISA_DEVICE_OK (0)` | 操作成功 |
| `LISA_DEVICE_ERR_INVALID` | 参数无效 |
| `LISA_DEVICE_ERR_NOT_SUPPORT` | 不支持该操作 |
| `LISA_DEVICE_ERR_NOT_READY` | 设备未就绪 |
| `LISA_DEVICE_ERR_IO` | IO 错误 |

## 注意事项

1. **配置顺序**: 必须先调用 `lisa_display_attach_bus()` 配置总线，才能使用其他显示 API
2. **帧缓冲区**: 建议从 PSRAM 分配帧缓冲区，确保 `CONFIG_PSRAM_HEAP_SIZE` 足够大
3. **亮度范围**: `lisa_display_set_brightness()` 参数范围为 0-100，表示百分比
4. **TE 同步**: 启用 `CONFIG_LISA_DISPLAY_TE_SYNC` 可防止画面撕裂，但需要连接 TE 引脚
5. **旋转性能**: 启用 `CONFIG_LISA_DISPLAY_CPDMA_ROTATE` 可使用硬件加速旋转，提升性能
6. **SPI 频率**: 实际 SPI 频率需根据屏幕规格和 PCB 走线质量调整
7. **线程安全**: 驱动内部使用互斥锁保护，可在多线程环境中安全使用
8. **依赖设备**: 使用前需确保底层设备（GPIO、SPI/QSPI、PWM）已正确初始化

## 架构说明

LISA Display 驱动采用分层架构设计，将应用接口、Panel 通用逻辑、Panel 专用驱动和总线专用驱动分离开来，以提供灵活性和可移植性。

```
+-------------------------------------------------------------------------+
|                                应用层                                   |
|                    +---------------------------+                        |
|                    |   应用程序 (e.g. main.c)  |                        |
|                    +---------------------------+                        |
+--------------------------------|----------------------------------------+
                                 | (调用)
                                 v
+--------------------------------+----------------------------------------+
|                      LISA Display 驱动框架                              |
|                                                                         |
|   +-------------------------------------------------------------------+ |
|   | lisa_display_api_t (lisa_display.h)                               | |
|   +--------------------------------|----------------------------------+ |
|                                    | (由...实现)                        |
|                                    v                                    |
|   +-------------------------------------------------------------------+ |
|   | Display 设备层 (lisa_display_arcs.c)                              | |
|   | (设备注册, 互斥锁, TE同步)                                        | |
|   +--------------------------------|----------------------------------+ |
|                                    | (通过Kconfig选择并转发至)          |
|                                    v                                    |
|   +-------------------------------------------------------------------+ |
|   | Panel 驱动 (e.g. panel_st7789p3.c)                                | |
|   | (IC专用初始化和命令)                                              | |
|   +--------------------------------|----------------------------------+ |
|                                    | (实现)                             |
|                                    v                                    |
|   +-------------------------------------------------------------------+ |
|   | Panel 抽象层 (lisa_display_panel.c)                               | |
|   | (Panel通用逻辑, 旋转算法)                                         | |
|   +--------------------------------|----------------------------------+ |
|                                    | (调用)                             |
|                                    v                                    |
|   +-------------------------------------------------------------------+ |
|   | 总线抽象层 (lisa_display_bus.h)                                   | |
|   | (定义标准总线API)                                                 | |
|   +--------------------------------|----------------------------------+ |
|                                    | (由...实现)                        |
|                                    v                                    |
|   +-------------------------------------------------------------------+ |
|   | 总线驱动 (e.g. bus_spi_4wire.c)                                   | |
|   | (实现总线专用数据传输)                                            | |
|   +-------------------------------------------------------------------+ |
|                                                                         |
+--------------------------------|----------------------------------------+
                                 | (通过...访问硬件)
                                 v
+--------------------------------+----------------------------------------+
|                      硬件抽象层 (HAL)                                   |
|   +-------------------------------------------------------------------+ |
|   | LISA 设备驱动 (SPI, GPIO, PWM, DMA)                               | |
|   +-------------------------------------------------------------------+ |
+-------------------------------------------------------------------------+
```

### 各层描述

- **Display 设备层 (`lisa_display_arcs.c`)**: 实现 `lisa_display_api_t`，处理设备注册、互斥锁保护、TE 同步，通过 Kconfig 链接到特定 Panel 驱动
- **Panel 驱动层 (`panel_*.c`)**: 针对特定显示控制器（如 ST7789P3）的初始化序列和专用命令
- **Panel 抽象层 (`lisa_display_panel.c`)**: 提供独立于显示控制器的通用逻辑，如旋转算法、辅助函数
- **总线抽象层 (`lisa_display_bus.h`)**: 定义用于不同硬件总线通信的标准 `lisa_display_bus_api_t` 接口
- **总线驱动层 (`bus_*.c`)**: 实现特定总线协议（如 4 线 SPI、QSPI）的数据传输

```{toctree}
:maxdepth: 1
:hidden:

panels/README.md
```

## Panel 移植适配

如需添加新的显示面板驱动，请参考 [Panel 移植适配指南](panels/README.md)。

## 文件说明

- `lisa_display.h` - 驱动头文件，包含所有 API 和类型定义
- `lisa_display_arcs.c` - ARCS 平台 Display 设备实现
- `lisa_display_panel.c` - Panel 抽象层实现
- `lisa_display_panel.h` - Panel 驱动接口定义
- `lisa_display_bus.h` - 总线抽象层接口定义
- `mipi_dcs.h` - MIPI DCS 命令定义
- `bus/` - 总线驱动实现目录
- `panels/` - Panel 驱动实现目录
- `Kconfig` - 配置选项
- `CMakeLists.txt` - 构建配置