# ILI9486 驱动开发完整指南

## 目录
1. [开发环境准备](#1-开发环境准备)
2. [驱动架构说明](#2-驱动架构说明)
3. [SPI通信协议详解](#3-spi通信协议详解)
4. [初始化序列解析](#4-初始化序列解析)
5. [编译与测试](#5-编译与测试)
6. [调试技巧](#6-调试技巧)
7. [优化方向](#7-优化方向)

---

## 1. 开发环境准备

### 1.1 交叉编译工具链
```bash
# Orange Pi PC 使用 arm-linux-gnueabihf 工具链
sudo apt-get install gcc-arm-linux-gnueabihf

# 设置环境变量
export CROSS_COMPILE=arm-linux-gnueabihf-
export ARCH=arm
```

### 1.2 获取内核源码
```bash
# 从Orange Pi官方GitHub获取
git clone https://github.com/orangepi-xunlong/linux-orangepi.git
cd linux-orangepi

# 或使用Armbian内核源码
git clone https://github.com/armbian/build.git
```

### 1.3 项目文件结构
```
ili9486-driver/
├── ili9486.c          # 主驱动文件
├── ili9486.h          # 寄存器定义（可选）
├── Makefile           # 编译脚本
├── Kconfig            # 内核配置菜单
└── README.md          # 说明文档
```

---

## 2. 驱动架构说明

### 2.1 整体架构
```
用户空间 (应用程序)
    ↓ read/write/mmap
Linux Framebuffer (/dev/fb0)
    ↓ fb_ops 回调
ILI9486 驱动 (ili9486.c)
    ↓ SPI传输
ILI9486 控制器
    ↓ RGB信号
TFT LCD 面板
```

### 2.2 关键数据结构

```
fb_info              ← frame buffer核心结构
├── fb_var_screeninfo  ← 可变参数（分辨率、色深等）
├── fb_fix_screeninfo  ← 固定参数（行长度、显存大小等）
├── screen_base        ← 显存虚拟地址
└── fb_ops            ← 操作函数集
    ├── fb_write       ← 写屏回调
    ├── fb_ioctl       ← ioctl处理
    └── fb_mmap        ← 内存映射
```

### 2.3 驱动入口流程
```
module_spi_driver(ili9486_driver)
    ↓
spi_driver.probe()
    ├── devm_gpiod_get()     ← 获取GPIO
    ├── spi_setup()          ← 配置SPI
    ├── framebuffer_alloc()  ← 分配fb_info
    ├── ili9486_init_sequence()  ← 初始化LCD
    └── register_framebuffer()   ← 注册fb0
```

---

## 3. SPI通信协议详解

### 3.1 ILI9486 SPI时序

```
        ┌─────────────────────────────────────────────┐
   CS   │█████████████████████████████████████████████│
        └─────────────────────────────────────────────┘
            ↑ 片选拉低开始传输
        
        ┌─────────────────────────────────────────────┐
   SCK  │  ↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑ │
        └─────────────────────────────────────────────┘
            ↑ 时钟上升沿采样数据
        
        ┌─────────────────────────────────────────────┐
   DC   │█████│░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░│
        └─────────────────────────────────────────────┘
            ↑   ↑
            命令  数据
            (0)  (1)
        
   MOSI │  D7  D6  D5  D4  D3  D2  D1  D0 │  D7...
        └─────────────────────────────────────────────┘
            ↑ MSB先发，8位一组
```

### 3.2 DC引脚时序要求

| 操作 | DC电平 | 说明 |
|------|--------|------|
| 发送命令 | LOW (0) | DC=0时，MOSI上的数据是命令码 |
| 发送数据 | HIGH (1) | DC=1时，MOSI上的数据是参数或像素 |
| 命令+参数 | 先低后高 | 先DC=0发命令，再DC=1发参数 |

### 3.3 SPI模式选择

ILI9486支持两种SPI模式：

| 模式 | CPOL | CPHA | 说明 |
|------|------|------|------|
| Mode 0 | 0 | 0 | 空闲时SCK低，上升沿采样（推荐） |
| Mode 3 | 1 | 1 | 空闲时SCK高，上升沿采样 |

```c
// Orange Pi PC上设置SPI模式
spi->mode = SPI_MODE_0;  // 或 SPI_MODE_3
spi->bits_per_word = 8;
spi->max_speed_hz = 32000000;  // 32MHz
spi_setup(spi);
```

---

## 4. 初始化序列解析

### 4.1 ILI9486初始化流程

```
┌─────────────────────────────────────┐
│           上电                        │
└──────────────┬──────────────────────┘
               ↓
┌─────────────────────────────────────┐
│  硬件复位 (RST引脚)                   │
│  RST=1 → 等待20ms → RST=0 → 等待20ms  │
│  → RST=1 → 等待120ms                  │
└──────────────┬──────────────────────┘
               ↓
┌─────────────────────────────────────┐
│  软件复位 (命令0x01)                   │
│  等待150ms                            │
└──────────────┬──────────────────────┘
               ↓
┌─────────────────────────────────────┐
│  退出睡眠 (命令0x11)                   │
│  等待50ms                             │
└──────────────┬──────────────────────┘
               ↓
┌─────────────────────────────────────┐
│  配置寄存器                            │
│  ├── 电源控制 (0xC0, 0xC1)            │
│  ├── VCOM控制 (0xC5, 0xC7)            │
│  ├── 像素格式 (0x3A) → 0x55 (16位)    │
│  ├── 帧率控制 (0xB1)                  │
│  ├── 显示功能 (0xB6)                  │
│  ├── Gamma校正 (0xE0, 0xE1)           │
│  └── 屏幕旋转 (0x36)                  │
└──────────────┬──────────────────────┘
               ↓
┌─────────────────────────────────────┐
│  开显示 (命令0x29)                     │
│  等待20ms                             │
└──────────────┬──────────────────────┘
               ↓
┌─────────────────────────────────────┐
│  开背光 (LED引脚拉高)                  │
└─────────────────────────────────────┘
```

### 4.2 MADCTL旋转控制 (0x36)

| 旋转角度 | MADCTL值 | 说明 |
|----------|----------|------|
| 0° | 0x48 | 竖屏，正常方向 |
| 90° | 0x28 | 横屏，向右旋转 |
| 180° | 0x88 | 竖屏，上下翻转 |
| 270° | 0xE8 | 横屏，向左旋转 |

MADCTL位定义：
- Bit 7 (MY): 行地址顺序
- Bit 6 (MX): 列地址顺序  
- Bit 5 (MV): 行/列交换
- Bit 4 (ML): 垂直刷新顺序
- Bit 3 (RGB): RGB/BGR顺序

### 4.3 像素格式 (0x3A)

| 值 | 格式 | 说明 |
|----|------|------|
| 0x55 | RGB565 | 16位，常用 |
| 0x66 | RGB666 | 18位 |
| 0x77 | RGB888 | 24位 |

---

## 5. 编译与测试

### 5.1 Makefile

```makefile
# Makefile for ILI9486 driver (out-of-tree build)
obj-m := ili9486.o

KDIR := /path/to/linux-orangepi
CROSS_COMPILE := arm-linux-gnueabihf-
ARCH := arm

all:
	$(MAKE) ARCH=$(ARCH) CROSS_COMPILE=$(CROSS_COMPILE) \
		-C $(KDIR) M=$(PWD) modules

clean:
	$(MAKE) ARCH=$(ARCH) CROSS_COMPILE=$(CROSS_COMPILE) \
		-C $(KDIR) M=$(PWD) clean

install:
	scp ili9486.ko root@orangepi:/lib/modules/$(shell uname -r)/extra/
	ssh root@orangepi "depmod -a && modprobe ili9486"
```

### 5.2 设备树配置

在Orange Pi的设备树中添加：

```dts
&spi0 {
    status = "okay";
    pinctrl-names = "default";
    pinctrl-0 = <&spi0_pins &spi0_cs_pin>;
    
    cs-gpios = <&pio 0 2 GPIO_ACTIVE_LOW>;  // CE0
    
    ili9486@0 {
        compatible = "ilitek,ili9486";
        reg = <0>;
        spi-max-frequency = <32000000>;
        
        rotate = <270>;
        bgr;
        fps = <30>;
        
        dc-gpios = <&pio 1 8 GPIO_ACTIVE_LOW>;   // RS/DC
        reset-gpios = <&pio 1 9 GPIO_ACTIVE_LOW>; // RST
        led-gpios = <&pio 1 7 GPIO_ACTIVE_HIGH>;  // LED
    };
};
```

### 5.3 编译测试步骤

```bash
# 1. 编译驱动
make

# 2. 传输到Orange Pi
scp ili9486.ko root@orangepi:~/

# 3. SSH登录并加载
ssh root@orangepi
insmod ili9486.ko

# 4. 检查framebuffer设备
ls -la /dev/fb*

# 5. 查看内核日志
dmesg | tail -20

# 6. 测试显示（需要X11环境）
DISPLAY=:0 startx &
xterm -geometry 80x25 &
```

### 5.4 命令行测试（无需X11）

```bash
# 直接写framebuffer测试
echo -n "Hello LCD!" > /dev/fb0

# 使用fbtest工具
apt-get install fbset
fbset -a

# 使用fbgrab截图
fbgrab /tmp/screenshot.png
```

---

## 6. 调试技巧

### 6.1 SPI通信调试

```bash
# 启用SPI调试日志
echo 8 > /proc/sys/kernel/printk
echo 1 > /sys/module/spi_bitbang/parameters/debug

# 检查SPI设备
ls -la /dev/spidev*
cat /sys/class/spi_master/spi0/spi0.0/modalias
```

### 6.2 GPIO调试

```bash
# 查看GPIO状态
cat /sys/kernel/debug/gpio

# 手动测试GPIO
echo 8 > /sys/class/gpio/export
echo out > /sys/class/gpio/gpio8/direction
echo 1 > /sys/class/gpio/gpio8/value
```

### 6.3 Framebuffer调试

```bash
# 查看fb信息
cat /sys/class/graphics/fb0/virtual_size
cat /sys/class/graphics/fb0/bits_per_pixel
cat /sys/class/graphics/fb0/stride

# 使用fbset查看详细信息
fbset -i
```

### 6.4 常见问题排查

| 问题 | 可能原因 | 解决方法 |
|------|----------|----------|
| 白屏 | 未初始化或SPI通信失败 | 检查接线、SPI配置、初始化序列 |
| 花屏 | 时序问题或数据错误 | 降低SPI频率、检查时序 |
| 无显示 | 背光未开启 | 检查LED引脚 |
| 触摸不准 | 校准参数错误 | 运行xinput_calibrator |
| 颜色错误 | BGR/RGB顺序错误 | 修改MADCTL的RGB位 |

### 6.5 使用逻辑分析仪

推荐使用Saleae或DSLogic抓取SPI波形：
1. 捕获CS、SCK、MOSI、DC四根线
2. 检查时序是否符合要求
3. 验证发送的数据是否正确

---

## 7. 优化方向

### 7.1 DMA传输

使用SPI DMA可以大幅提高传输效率：

```c
// 使用DMA传输像素数据
static void ili9486_fb_write_dma(struct fb_info *info,
                                  int x, int y, int w, int h)
{
    struct ili9486_priv *priv = info->par;
    struct spi_transfer t = {
        .tx_buf = priv->txbuf,
        .len = w * h * 2,
        .speed_hz = priv->spi->max_speed_hz,
    };
    struct spi_message m;
    
    spi_message_init(&m);
    spi_message_add_tail(&t, &m);
    spi_sync(priv->spi, &m);
}
```

### 7.2 部分刷新

只更新改变的区域，减少数据传输：

```c
// 双缓冲 + 脏矩形检测
struct ili9486_priv {
    u16 *fbmem;        // 当前显示缓冲
    u16 *fbmem_back;   // 后台缓冲
    bool dirty;
    int dirty_x, dirty_y, dirty_w, dirty_h;
};
```

### 7.3 硬件加速

利用ILI9486内置功能：
- 硬件滚动（垂直/水平）
- 矩形填充
- 字符显示

### 7.4 性能指标

| 方案 | 刷新率 | CPU占用 | 说明 |
|------|--------|---------|------|
| 基础写屏 | 15 FPS | 80% | 简单实现 |
| DMA传输 | 30 FPS | 30% | 使用DMA |
| 部分刷新 | 60 FPS | 10% | 只更新变化区域 |
| 双缓冲 | 60 FPS | 5% | 前后台缓冲 |

---

## 参考资源

1. ILI9486 Datasheet
2. Linux Kernel Documentation - fbdev
3. Linux Kernel Documentation - spidev
4. fbtft驱动源码：drivers/video/fbdev/fbtft/
5. Orange Pi PC官方文档

---

## 作者

ILI9486 Driver Guide for Orange Pi PC
版本：1.0
日期：2026-06-04