第4章：显示驱动——DBI 与 SPI 墨水屏

屏幕不识字，它只认电压——把"字"变成"帧"，是艺术与工程的合奏。

4.1 两种接口：DBI 与 SPI 墨水屏

电子墨水屏和主控之间靠什么"说话"？本项目给出了两种答案，对应第 3 章里的两套板级配置。第一种叫 DBI（Display Bus Interface，显示总线接口）：一种把数据通过多根并行信号线同时送出的接口；这里用的是 8-bit DBI，一次并行送出 8 位数据，速度快、吞吐高，适合 1032×758、1448×1072 这种大分辨率墨水屏。第二种叫 SPI（Serial Peripheral Interface，串行外设接口）：一种用一根数据线按位逐位传的通用串行接口，引脚少（SDA / SCK / DC / CS / RES / BUSY），但速度低，适合 240×416 这种小屏。

这两种接口在代码里用一"行"字就能区分——LCDC_InitTypeDef 里的 .lcd_itf 字段。8-bit 并行屏写 LCDC_INTF_DBI_8BIT_B（B 代表 8 位总线），SPI 屏写 LCDC_INTF_SPI_DCX_1DATA（DCX 表示数据/命令由 DC 引脚区分、1 根数据线）。剩下的差距全在驱动里：并行屏要把像素数据打包成"每帧的 8-bit 波形查找表"喂给 EPIC 图像加速引擎；SPI 屏则把数据通过寄存器写进屏幕自带的波形引擎。先记下这个总纲，后面两节分别展开。

对比项	DBI（8-bit 并行）	SPI（串行）
数据线	8 根（D0-D7）	1 根（SDA）
其它信号	CLK / LE / OE / SPH / STV / CPV / GMODE	SCK / DC / CS / RES / BUSY
接口宏	LCDC_INTF_DBI_8BIT_B	LCDC_INTF_SPI_DCX_1DATA
典型时钟	sclk_freq=24MHz（并行一次 8bit）	freq=5000000（5MHz 串行）
驱动目录	src/boards/display_dbi/	src/boards/display_spi/
适用屏	YZC085 / R7D005	OPM037A3 240×416

// src/boards/display_dbi/epd_display.c —— 8-bit 并行 DBI 接口
static LCDC_InitTypeDef lcdc_int_cfg =
{
    .lcd_itf = LCDC_INTF_DBI_8BIT_B,
    .freq = 0, /* 由 epd_get_timing_config 返回的 sclk_freq 覆盖 */
    .color_mode = LCDC_PIXEL_FORMAT_RGB332,
};

// src/boards/display_spi/epd_display.c —— SPI 串行接口
static LCDC_InitTypeDef lcdc_int_cfg = {
    .lcd_itf = LCDC_INTF_SPI_DCX_1DATA,
    .freq = 5000000,
    .color_mode = LCDC_PIXEL_FORMAT_RGB332,
};

4.2 波形与帧：全刷 32 帧、局刷 12 帧

先把 波形（waveform）说人话：它是电子墨水"翻面"的完整剧本——屏幕上每一个点，从"旧颜色"变到"新颜色"，需要按一定顺序施加一串电压，这串"每帧给哪个点加什么电压"的序列就叫波形。墨水屏不是像 LCD 那样一亮即显，而是靠电压把黑、白墨粒推来推去，一个画面要分很多次（帧）刷完才稳定。刷整个屏幕叫全刷（full refresh），只刷局部区域叫局刷（partial refresh）。

波形由屏幕厂商提供，做成查表数据：本项目在 epd_configs_opm060d.c 里按"温区 × 刷新模式"组织了两张表——yzc085_wave_full_0_100（0~100℃ 温区、全刷，32 帧）和 yzc085_wave_partial_0_100（0~100℃ 温区、局刷，12 帧）。每张表是 [帧数][256] 的二维数组：256 对应 16×16 种"旧像素×新像素"组合（旧色占高 4 位、新色占低 4 位），每一帧为每种组合查出一个 0~3 的灰阶值。用一张 WaveTableEntry 把"温区范围 + 帧数 + 表地址"打包成一条记录：全刷 32 帧、局刷 12 帧，越刷越多越清晰，代价是时间。

波形表	温区	帧数	用途
yzc085_wave_full_0_100	0~100℃	32	全刷：整屏推倒重画，残影少、清晰
yzc085_wave_partial_0_100	0~100℃	12	局刷：只动变化区域，快但有残影
二进制波形 epd_waveform.bin	多温区	由库查表	厂商成品波形（38216 字节，见 4.3）

// src/boards/display_dbi/epd_configs_opm060d.c —— 波形表条目结构
typedef struct {
    int min_temp;
    int max_temp;
    uint32_t frame_count;
    const uint8_t (*wave_table)[256];
} WaveTableEntry;

static const WaveTableEntry full_wave_table =
    {0, 100, 32, &yzc085_wave_full_0_100[0]};

static const WaveTableEntry partial_wave_table =
    {0, 100, 12, &yzc085_wave_partial_0_100[0]};

// 按"温度 + 刷新模式"挑选波形表，并返回本次刷新的帧数
uint32_t epd_wave_table_get_frames(int temperature, EpdDrawMode mode)
{
    const WaveTableEntry *wave_table = NULL;
    if (EPD_DRAW_MODE_FULL == mode) {
        wave_table = &full_wave_table;
    } else {
        wave_table = &partial_wave_table;
    }
    if (temperature < wave_table->min_temp || temperature >= wave_table->max_temp) {
        wave_table = &full_wave_table; // 温区不匹配就退回全刷，稳妥
    }
    p_current_wave_from = (const uint8_t *)&wave_table->wave_table[0][0];
    return wave_table->frame_count;
}

4.3 把波形喂给屏：LUT 与 EPIC

有了波形表，还要把它"翻译"成屏能用的样子。这里的 LUT（Lookup Table，查找表）就是一张查表：给定"旧色×新色"，查出这一帧该输出的灰阶。代码注释说得很直白——"8bit lookup table for the current frame (high 4 bits: old data, low 4 bits: new data). The output is 2-bit data"：输入是 8 位（旧 4 位 + 新 4 位），输出是 2 位灰阶。8-bit 并行屏走的是 EPIC（电子纸图像加速引擎，一个专门做墨水屏像素变换的硬件加速器），驱动把每一帧的 256 项 LUT 填进 EPIC 的 LUT 寄存器，EPIC 再逐行把混合灰度帧缓冲转成屏上波形。

epd_wave_table_fill_lut 干的就是"逐帧填 LUT"这件小事：先取出当前帧的 256 字节波形（p_current_wave_from + frame_num * 256），再把每个字节左移 3 位塞进 32 位 LUT（p_epic_lut[i] = p_frame_wave[i] << 3）。为什么是左移 3 位？因为 EPIC 的 LUT 里每个输入组合要占一个 32 位字的低 3 位通道，8 位输入正好是 256 个 32 位字。与此同时，CopyToMixedGrayBuffer 在 PSRAM 上维护一块"混合灰度帧缓冲"（每字节高 4 位是旧像素、低 4 位是新像素），把新旧两层合起来供 LUT 查询——这就在第 3 章那个 psram1 分区上。它里面有一段真实的未实现代码，正适合当教学点：当图层格式是 LCDC_PIXEL_FORMAT_MONO 时，直接 RT_ASSERT(0)//Not implemented yet。

第 3 章提过 Kconfig.proj 里有个 EPD_WAVEFORM_USE_BIN 开关：不开时，波形是上面这种编译进固件的 C 数组（我们刚看的 opm060d.c 前半段）；开了时，波形从 waveform/ 目录的 epd_waveform.bin（38216 字节）读取——这是一份厂商给的二进制波形文件，通过 waveform/ 下的 epd_waveform_bin_reader.h 接口（配好的 libepd_waveform_bin_reader_gcc.a / .rvds.lib 库）按温区、模式查帧。它烧在 ptab.json 的 wave_table 分区（CUSTOM_EPD_WAVE_TABLE），由 SConstruct 用 AddCustomImg 打包进固件。两种波形来源各有利弊，对比如下。

对比项	C 数组波形（默认）	二进制波形（EPD_WAVEFORM_USE_BIN）
波形数据	编译进固件的 yzc085_wave_full/partial_0_100	独立文件 epd_waveform.bin（38216 字节）
存放位置	固件代码段（只读数据）	烧录到 wave_table 分区（CUSTOM_EPD_WAVE_TABLE）
读取方式	直接引用数组指针	waveform_bin_reader_* 库 + rt_flash_read / rt_nand_read
切换开关	不定义 EPD_WAVEFORM_USE_BIN	EPD_WAVEFORM_USE_BIN=y
适用场景	波形随代码一起发布、要改表需重编译	厂商单独交付波形、想按 Flash 分区热替换

// src/boards/display_dbi/epd_configs_opm060d.c —— 逐帧填 EPIC 的 32 位 LUT
void epd_wave_table_fill_lut(uint32_t *p_epic_lut, uint32_t frame_num)
{
    const uint8_t *p_frame_wave = p_current_wave_from + (frame_num * 256);
    // Convert the 8-bit waveforms to 32-bit epic LUT values
    for (uint16_t i = 0; i < 256; i++)
        p_epic_lut[i] = p_frame_wave[i] << 3;
}

// PSRAM 上的混合灰度帧缓冲 + 一个真实的"未实现"占位
L2_NON_RET_BSS_SECT(frambuf, ALIGN(4) static uint8_t
    mixed_framebuffer[LCD_HOR_RES_MAX * LCD_VER_RES_MAX]);

if (hlcdc->Layer[HAL_LCDC_LAYER_DEFAULT].data_format == LCDC_PIXEL_FORMAT_MONO)
{
    RT_ASSERT(0);//Not implemented yet
}

# 使用二进制波形的分支（epd_configs_opm060d.c · EPD_WAVEFORM_USE_BIN）
waveform_bin_reader_init(CUSTOM_EPD_WAVE_TABLE_SIZE);
frames = waveform_bin_reader_get_frames(temperature, WAVE_MODE_FULL);
waveform_bin_reader_fill_lut(p_epic_lut, frame_num);
# waveform/ 目录（配好的库，SConscript 按需选用）
epd_waveform.bin                    # 38216 字节二进制波形
epd_waveform_bin_reader.h
libepd_waveform_bin_reader_gcc.a    # GCC 工具链静态库
epd_waveform_bin_reader_rvds.lib    # RVDS 工具链静态库

4.4 时序与 VCOM：把帧"送"给屏幕

波形表定好了"每帧画什么"，接下来要定"每帧怎么扫过去"——这就是时序。驱动用 EPD_TimingConfig 一次性描述整屏扫描节奏：sclk_freq（像素时钟，单位 MHz）、fclk_freq（行/帧时钟，单位 KHz）、以及一堆 L/F 开头的前后沿长度。最值得记的是两个"按分辨率算"的字段：LDL = LCD_HOR_RES_MAX/4（每行有效数据时钟数，注释说得很清楚——"2bit+8数据线，需除以4"）和 FDL = LCD_VER_RES_MAX（每帧有效行数）。这印证了第 3 章"分辨率宏驱动一切"：改分辨率，时序自动跟着变，驱动主体不用动。

再说 VCOM（common voltage，公共电极电压）：墨水屏所有像素共享的一个参考电压，像素电极相对它产生的压差决定墨粒往哪边翻。它必须和屏幕面板匹配，调高了残影重、调低了对比度差。本项目里 epd_get_vcom_voltage() 是个很典型的"按屏编译"写法：编译目标是 R7D005 时返回 2100（mV），否则统一 1050。8-bit 并行屏的 VCOM 由电源管理芯片 TPS65185 通过 I2C 设置（oedtps_init(epd_get_vcom_voltage())、oedtps_vcom_enable()），而 SPI 小屏没有独立电源芯片，VCOM 相关参数直接写在寄存器配置里。

字段	含义	本项目的值
sclk_freq	像素时钟（MHz）	24
LDL	每行有效数据时钟数	LCD_HOR_RES_MAX/4
fclk_freq	行/帧时钟（KHz）	83
FDL	每帧有效行数	LCD_VER_RES_MAX
FSL/FBL/FEL	帧同步/起始/结束长度	1 / 3 / 5
SDMODE	源驱动模式（R7D005=1）	0（其余屏）

// src/boards/display_dbi/epd_configs_opm060d.c —— 整屏时序
const EPD_TimingConfig *epd_get_timing_config(void)
{
    static const EPD_TimingConfig timing_config = {
        .sclk_freq = 24,
#ifdef LCD_USING_EPD_R7D005
        .SDMODE = 1,
#else
        .SDMODE = 0,
#endif
        .LSL = 0, .LBL = 0,
        .LDL = LCD_HOR_RES_MAX/4,
        .LEL = 1,
        .fclk_freq = 83,
        .FSL = 1, .FBL = 3,
        .FDL = LCD_VER_RES_MAX,
        .FEL = 5,
    };
    return &timing_config;
}

// VCOM 电压：按屏编译的经典写法
uint16_t epd_get_vcom_voltage(void)
{
#if defined(LCD_USING_EPD_R7D005)
    return 2100;
#else
    return 1050;
#endif
}

// epd_display.c · LCD_Init：把时钟和 VCOM 接进初始化流程
lcdc_int_cfg.freq = epd_get_timing_config()->sclk_freq * 1000*1000;
oedtps_init(epd_get_vcom_voltage());

4.5 SPI 屏的寄存器世界

没有 EPIC 和 TPS 电源芯片的 SPI 小屏，把"波形"这件事全部收进屏幕自己的寄存器里。它内置了 5 组波形 LUT 寄存器：REG_LUT_VCOM(0x20)、REG_LUT_W2W(0x21)、REG_LUT_K2W(0x22)、REG_LUT_W2K(0x23)、REG_LUT_K2K(0x24)——分别描述"公共极"和"白→白 / 黑→白 / 白→黑 / 黑→黑"的过渡波形。驱动里的 EPD_LoadLUT 按当前刷新模式从 waveinit.h 的三套常量数组里挑一组写进寄存器：0=5S（清屏）、1=GC（全刷无残影）、2=DU（局刷有残影）。

这套"写寄存器"的流程还有个标志位细节：LUT_Flag 在 K2W 与 W2K 两组寄存器之间轮流切换（R22/R23 对调），用来抵消某些面板上反复刷带来的极性偏置。而"屏幕忙不忙"靠 EPD_BUSY 引脚的中断信号——驱动把 EPD_BUSY 挂成高电平中断，忙碌结束触发回调释放信号量 epd_busy_sem，写命令前 EPD_ReadBusy() 等信号量（2 秒超时兜底）。这与 8-bit 并行屏"等 LCDC 的 STATUS 寄存器"是两种不同的同步哲学：一个是硬件中断驱动的信号量，一个是轮询状态位。

LUT 模式	含义	说明
0	5S	清屏：全屏刷成黑或白
1	GC	全刷无残影：清晰但慢
2	DU	局刷有残影：快，翻页首选
寄存器	0x20~0x24	VCOM / W2W / K2W / W2K / K2K

// src/boards/display_spi/epd_display.c —— 按模式加载 LUT（节选）
static void EPD_LoadLUT(LCDC_HandleTypeDef *hlcdc, uint8_t lut_mode)
{
    switch (lut_mode)
    {
        case 0: // 5S模式（清屏）
            LCD_WriteReg(hlcdc, REG_LUT_VCOM, lut_R20_5S, 56);
            LCD_WriteReg(hlcdc, REG_LUT_W2W, lut_R21_5S, 42);
            LCD_WriteReg(hlcdc, REG_LUT_K2K, lut_R24_5S, 42);
            if (LUT_Flag == 0) {
                LCD_WriteReg(hlcdc, REG_LUT_K2W, lut_R22_5S, 56);
                LCD_WriteReg(hlcdc, REG_LUT_W2K, lut_R23_5S, 42);
                LUT_Flag = 1;
            } else {
                // R22/R23 对调，抵消极性偏置
                LCD_WriteReg(hlcdc, REG_LUT_K2W, lut_R23_5S, 56);
                LCD_WriteReg(hlcdc, REG_LUT_W2K, lut_R22_5S, 42);
                LUT_Flag = 0;
            }
            break;
        case 1: // GC模式（全刷无残影）
        case 2: // DU模式（局刷有残影）
            // ...同一套结构，换成 lut_Rxx_GC / lut_Rxx_DU
    }
}

// 忙信号：EPD_BUSY 中断 → 信号量，写寄存器前等待
static void epd_busy_callback(void *args)
{
    rt_sem_release(epd_busy_sem);
    rt_pin_irq_enable(EPD_BUSY, PIN_IRQ_DISABLE);
}

static void EPD_ReadBusy(void)
{
    rt_pin_irq_enable(EPD_BUSY, PIN_IRQ_ENABLE);
    rt_err_t result = rt_sem_take(epd_busy_sem, RT_TICK_PER_SECOND * 2);
    if (result != RT_EOK) {
        rt_kprintf("EPD busy wait timeout! (may cause display error)\n");
    }
    rt_sem_control(epd_busy_sem, RT_IPC_CMD_RESET, RT_NULL);
}

// 送一帧：写新数据寄存器 + 触发自动刷新
uint8_t lut_mode = epd_get_refresh_mode();  // 1=全刷 2=局刷
EPD_LoadLUT(hlcdc, lut_mode);
HAL_LCDC_LayerSetData(hlcdc, HAL_LCDC_LAYER_DEFAULT, (uint8_t *)RGBCode,
                      0, 0, LCD_HOR_RES_MAX_8 - 1, LCD_VER_RES_MAX - 1);
if (HAL_LCDC_SendLayerData2Reg_IT(hlcdc, REG_WRITE_NEW_DATA, 1) != HAL_OK) return;
parameter[0] = 0xA5;
LCD_WriteReg(hlcdc, REG_AUTO_REFRESH, parameter, 1); // 触发屏幕自刷
reflesh_times++;