# uart_terminal.py 命令参考

## 用法

```bash
python uart_terminal.py --port COM3 [--baud 2000000]
```

## 寄存器地址表

| 地址 | 名称 | 类型 | 说明 |
|------|------|:--:|------|
| 0x80000000 | CTRL | R/W | [0]=enable, [3:1]=target_bpp |
| 0x80000004 | IMG_ADDR | R/W | 原始图像 DDR 地址 |
| 0x80000008 | IMG_LEN | R/W | (保留) |
| 0x8000000C | CMPR_ADDR | R/W | 压缩输出 DDR 地址 |
| 0x80000010 | STATUS | RO | [0]=busy, [1]=compress_done |
| 0x80000014 | CMPR_LEN | RO | 总压缩字节数 |
| 0x80000018 | VERSION | RO | 模块版本号 |
| 0x8000001C | STORAGE_MODE | R/W | 存储模式 1/2/3 |
| 0x80000020 | MEM_BLOCK_SZ | R/W | 内存块大小 (128 or 64 MB) |
| 0x80000024 | PAN_BYTES | RO | PAN 压缩字节数 |
| 0x80000028 | B1_BYTES | RO | B1 压缩字节数 |
| 0x8000002C | B2_BYTES | RO | B2 压缩字节数 |
| 0x80000030 | B3_BYTES | RO | B3 压缩字节数 |
| 0x80000034 | B4_BYTES | RO | B4 压缩字节数 |
| 0x80000038 | TOTAL_BYTES | RO | S2MM 总字节 (aux+压缩) |
| 0x8000003C | IMG_PER_REGION | R/W | 每区域最大图像数 (0=不限) |

## DDR 地址表

| 地址范围 | 说明 |
|---------|------|
| 0x00000000 - 0x07FFFFFF | 原始图像 DDR (128MB) |
| 0x00000000 | PAN 图像起始 (96MB, stride=12288) |
| 0x06000000 | B1 图像起始 (6MB, stride=3072) |
| 0x06600000 | B2 图像起始 |
| 0x06C00000 | B3 图像起始 |
| 0x07200000 | B4 图像起始 |
| 0x07800000 | 辅助数据起始 |
| 0x07FFF000 | 元数据 (mode + 5×row_count, big-endian) |
| 0x40000000 | 压缩输出 DDR |

## 命令全类型

### 1. 读寄存器 — `r`

```
r <addr>
```

| 示例 | 说明 |
|------|------|
| `r 0x80000018` | 读 VERSION |
| `r 0x80000010` | 读 STATUS — 同时解码 busy/done 位 |
| `r 0x80000000` | 读 CTRL — 同时解码 enable/bpp 位 |
| `r 0x80000024` | 读 PAN_BYTES |

### 2. 写寄存器 — `w`

```
w <addr> <data>
```

| 示例 | 说明 |
|------|------|
| `w 0x80000000 0x00` | CTRL=0 (清除 enable) |
| `w 0x80000000 0x01` | CTRL=1, bpp=0 (触发无损压缩) |
| `w 0x80000000 0x05` | CTRL=1, bpp=2 |
| `w 0x80000004 0x00000000` | IMG_ADDR=0 |
| `w 0x8000000C 0x40000000` | CMPR_ADDR=0x40000000 |
| `w 0x80000020 128` | MEM_BLOCK_SZ=128MB |
| `w 0x80000020 64` | MEM_BLOCK_SZ=64MB |
| `w 0x8000001C 1` | STORAGE_MODE=1 (PAN+B1~B4) |
| `w 0x8000001C 2` | STORAGE_MODE=2 (仅PAN) |
| `w 0x8000001C 3` | STORAGE_MODE=3 (仅B1~B4) |
| `w 0x8000003C 1` | IMG_PER_REGION=1 (每行1幅) |
| `w 0x8000003C 0` | IMG_PER_REGION=0 (不限) |

### 3. 读全部寄存器 — `dump`

```
dump
```

一次性读取全部 16 个寄存器并显示，含 STATUS/CTRL 解码。

### 4. 读 DDR — `ar`

```
ar <addr> <len>              → 屏幕 hex dump
ar <addr> <len> <file>       → 保存到文件
```

| 示例 | 说明 |
|------|------|
| `ar 0x07FFF000 32` | 读元数据 32 字节，屏幕输出 |
| `ar 0x00000000 512` | 读 PAN 第 1 行 |
| `ar 0x06000000 512` | 读 B1 第 1 行 |
| `ar 0x40000000 1024` | 读压缩输出 1KB，屏幕输出 |
| `ar 0x40000000 4096 out.bin` | 读压缩输出 4KB，存到 out.bin |

### 5. 写 DDR — `aw`

```
aw <addr> <file>             → 从文件写入
aw <addr> hex:<hexstr>       → 从 hex 字符串写入
```

| 示例 | 说明 |
|------|------|
| `aw 0x00000000 pan.bin` | 将 pan.bin 写入 DDR 地址 0 |
| `aw 0x07FFF000 hex:000000010000010000000100000001000000010000000100` | 写元数据 (24字节 hex) |
| `aw 0x00000000 hex:08000000` | 手动写 upload 帧头 128MB |
| `aw 0x06000000 hex:AABBCCDD` | 写 4 字节到 B1 起始地址 |

### 6. 其他

| 命令 | 说明 |
|------|------|
| `help` | 显示帮助 |
| `quit` / `exit` / `q` | 退出 |

## 上板完整操作流程

```
# 1. 配寄存器
uart> w 0x80000000 0x00         # CTRL=0
uart> w 0x80000004 0x00000000   # IMG_ADDR=0
uart> w 0x8000000C 0x40000000   # CMPR_ADDR=0x40000000
uart> w 0x80000020 128          # MEM_BLOCK_SZ=128
uart> w 0x8000001C 1            # STORAGE_MODE=1
uart> w 0x8000003C 1            # IMG_PER_REGION=1

# 2. 写元数据
uart> aw 0x07FFF000 hex:000000010000010000000100000001000000010000000100

# 3. 写图像数据 (PAN 第 0 行)
uart> aw 0x00000000 pan_row0.bin

# 4. 触发
uart> w 0x80000000 0x01         # enable=1

# 5. 轮询
uart> r 0x80000010              # STATUS → busy=1 → 等几秒 → 再读
uart> r 0x80000010              # STATUS → busy=0, done=1

# 6. 看结果
uart> dump                      # 全寄存器
uart> ar 0x40000000 1024        # 读压缩开头 1KB
```

## 协议对照

| 命令 | UART 协议 | 字节数 |
|------|----------|--------|
| `r` | `R` + 4B addr BE | 5 |
| `w` | `W` + 4B addr BE + 4B data BE | 9 |
| `ar` | `D` + 4B addr BE + 4B len BE | 9 |
| `aw` | `A` + 4B addr BE + 4B len BE + data | 9 + len |