# RK3568 板 —— Debian 系统镜像 交付说明

> 板子：TL3568-EVM（Rockchip `rk3568-evb1-ddr4-v10` 定制版）
> 内核：沿用板子现有的 **Linux 5.10.198**（本次不改内核）
> 生成日期：2026-10-10
>
> **成品镜像**：`rootfs-bookworm.img`（bookworm 版，**已生成**）
> - 大小：**4,294,967,296 字节** = **4096.0 MiB** = **4.295 GB**（不铺满 6144 MiB 分区）
> - 板上 `apt` 可用：**3.1 GB**（挂载实测）
> - SHA256：`7fca8abb6a8c4350431d2638bf297f6aadecf3b595fecba33284fcf3b5c7cf66`
> - 属主核查：`nunu` 属主项 **0**；仅 3 项合法 `_apt:root`（apt 沙箱目录）；`etc/shadow` = root:shadow 640
> - 文件系统：ext4 + journal，`e2fsck` 干净（21387 文件 / 0.1% 碎片）
> - 文件数：**17573**
> - 需要更多空间：上板 `resize2fs /dev/disk/by-partlabel/rootfs` → 无损扩到分区上限 6144 MiB

---

## 一、这套镜像是干什么的

板子原来的系统是别人做的 **Buildroot 裁剪版**，**没有包管理器**，装不了软件。这套是**真正的 Debian**，按你的要求做：

| 你的要求 | 实现 |
|---|---|
| **`apt-get` 能用** | ✓ 真 Debian，`apt` 完整可用 |
| **国内源** | ✓ **中科大**（main/contrib/non-free/non-free-firmware + updates + security） |
| **能 SSH** | ✓ `openssh-server`，root 可登录 |
| **能测 DDR 与 eMMC 速度** | ✓ `fio` `hdparm` `mbw` `sysbench` `bonnie++` `iperf3` + 一键脚本 |
| **支持 nano** | ✓ `nano`（另附 `vim-tiny` `tmux`） |
| **不要桌面** | ✓ 无 X/Wayland/Chromium/任何 GUI，纯命令行。系统本体 **bookworm 808 MiB / trixie 1055 MiB**；镜像**默认 4096 MiB**（不铺满 6144 MiB 分区），板上 `apt` 可用约 **3.0 GB** |

**与内核的关系**：本套系统沿用板子现有内核（5.10.198），只换 rootfs，因此：

- **屏、触摸**：驱动**编译在内核里**（builtin：`rockchip_lvds` / `panel-simple` / `goodix`），换 rootfs 完全不影响
- **WiFi、蓝牙**：是**外挂模块**（`cc33xx.ko` `cc33xx_sdio.ko` `btti.ko` `btti_uart.ko`），已连同固件随本 rootfs 带到 `/system/lib/modules/` 与 `/lib/firmware/ti-connectivity/`，由 `rk-wifi-bt.service` 开机自动加载 —— 它们按 5.10.198 编译，与本内核**版本匹配，无需重编**

---

## 二、两种版本，任选（或都留着刷着玩）

| 版本 | systemd | 特点 |
|---|---|---|
| **bookworm**（Debian 12） | 252 | **推荐先用这个**。cgroup v1/v2 都支持，兼容性最稳 |
| **trixie**（Debian 13） | 257 | 版本最新，支持到 2030。但 systemd 257 **强制要求 cgroup v2**，你内核 `CGROUP_PIDS`/`CGROUP_BPF`/`PSI` 未开，属**未验证**项 |

> 想从 bookworm 升 trixie：`apt dist-upgrade` 一条命令即可（Debian 官方支持原地升级）。

---

## 三、刷机（**只刷 rootfs 一个分区**）

### 关键事实：为什么只需要刷 rootfs

板子内核的启动参数是：

```
root=PARTUUID=614e0000-0000 rw rootwait
```

而 `parameter.txt` 里写的是 `uuid:rootfs=614e0000-0000-4b53-8000-1d28000054a9` —— **rootfs 是按分区 UUID 定位的**，跟文件系统自身的 UUID 无关。

**所以：只要不动分区表，loader / boot / recovery / oem / userdata 全部原封不动，只写 rootfs 分区即可。**

### 分区布局（来自板子原厂 parameter.txt）

| 分区 | 起始扇区 | 大小 |
|---|---|---|
| uboot | 0x00004000 | 0x2000 |
| misc | 0x00006000 | 0x2000 |
| boot | 0x00008000 | 0x20000 |
| recovery | 0x00028000 | 0x20000 |
| backup | 0x00048000 | 0x10000 |
| **rootfs** | **0x00058000** | **0x00c00000 = 6144 MiB = 6.44 GB** ← 镜像不能超过这个 |
| oem | 0x00c58000 | 0x40000 |
| amp | 0x00c98000 | 0x10000 |
| userdata | 0x00ca8000 | 自动扩展 |

### 方式一：Linux + `rkdeveloptool`（本机已装 1.32）

```bash
# 板子进 loader/maskrom 模式（按住 RECOVERY 上电，或串口里输 rockusb）
rkdeveloptool ld                      # 确认识别到设备
rkdeveloptool wl 0x58000 rootfs-bookworm.img   # 写 rootfs 分区
rkdeveloptool rd                      # 重启
```

### 方式二：Windows + RKDevTool（你先前用的那个）

1. 打开 `RKDevTool`
2. 切到 **高级功能 / Advanced** 页
3. 只需填一行：**Start Sector `0x58000`** → 选 `rootfs-bookworm.img` → 勾选该行 → **执行**
4. 其他分区**全部留空不勾**

> ⚠️ 不要点"下载镜像/升级固件"那种全盘烧写，会重建分区表 → 分区 UUID 变了 → 起不来。

---

## 四、登录

| 项 | 值 |
|---|---|
| 串口控制台 | `ttyFIQ0` @ **1500000**（UART2，与原来一致） |
| 用户名 / 密码 | `root` / `root`　（另有 `linaro`/`linaro` 备用） |
| SSH | 端口 22，允许 root 密码登录 |

---

## 五、上机后验证清单

```bash
# 1. 系统身份
cat /etc/os-release            # Debian GNU/Linux 12 (bookworm) 或 13 (trixie)
uname -a                       # Linux 5.10.198  ← 内核沿用原板

# 2. apt 能用 + 源是中科大
apt-get update
grep ustc /etc/apt/sources.list

# 3. nano
nano --version

# 4. 网络（双网口 DHCP）
ip -br addr
ping -c2 mirrors.ustc.edu.cn

# 5. DDR + eMMC 速度（一键）
bench-ddr-emmc.sh
#   或分开测： bench-ddr-emmc.sh ddr   /   bench-ddr-emmc.sh emmc

# 6. 屏 和 触摸（重点）
ls /dev/fb*  /dev/dri/          # 显示设备
cat /sys/class/drm/*/status     # 应为 connected
ls /dev/input/event*            # 触摸输入设备
cat /proc/bus/input/devices | grep -A5 -i goodix   # GT911 触摸

# 7. 存储与内存
df -h  /  /userdata  /oem
free -h
```

---

## 六、分区挂载说明

`/etc/fstab` 按原厂方式挂载（**用 LABEL，与原板一致**）：

```
LABEL=oem        /oem        ext2   defaults   0 2
LABEL=userdata   /userdata   ext2   defaults   0 2
```

`/userdata` 是数据区（测速脚本默认在 `/userdata/bench` 落临时文件，只写文件、不碰裸设备）。

---

## 七、已配好的服务（全部 systemd）

| 服务 | 作用 |
|---|---|
| `ssh` | SSH 登录 |
| `getty@ttyFIQ0` | 串口控制台，1500000 波特率 |
| `systemd-networkd` | 双网口 DHCP |
| `systemd-resolved` | DNS |
| `systemd-timesyncd` | NTP 对时 |
| `rk-wifi-bt` | 加载 WiFi/BT 模块（`/system/lib/modules/` 下那 4 个 `.ko`） |

---

## 八、数据库（与原厂一致）

原厂 rootfs 带的是 **SQLite + Qt5 的 SQL 插件**（**不是**数据库服务，没有 MySQL/Postgres/Redis）。
HMI 那个 Qt 应用通过 `QSqlDatabase("QSQLITE")` 使用，数据库文件运行时自建。

| 原厂文件 | 新系统对应包 | bookworm | trixie |
|---|---|---|---|
| `usr/bin/sqlite3` | `sqlite3` | 3.40.1 | 3.46.1 |
| `usr/lib/libsqlite3.so.0.8.6` | `libsqlite3-0` | 3.40.1 | 3.46.1 |
| `usr/lib/libQt5Sql.so.5.15` | `libqt5sql5` | 5.15.8 | 5.15.15 |
| `qt/plugins/sqldrivers/libqsqlite.so` | `libqt5sql5-sqlite` | 5.15.8 | 5.15.15 |

- **soname 与原厂完全一致**（都是 `libsqlite3.so.0.8.6`）→ ABI 兼容，原本链接它的程序可直接跑
- 原厂 SQLite 是 **3.21.0**，新系统版本更高；SQLite **3.x 文件格式向后兼容**，可直接读写原有 DB 文件
- **已实测**：建表 / 写入 / 查询全部通过

> ⚠️ `/root/HMI` 在原厂 rootfs 里是**空的** —— HMI 应用从外部介质加载
> （`S99gt` 里判断 `/media/sda1`、`/media/mmcblk1p1`），不随固件走。新系统同理。
> 所以换 rootfs **不会丢失**任何 HMI 相关数据；数据库文件本来就在运行时生成。

---

## 九、已知事项

1. **WiFi / 蓝牙**：模块在 `/system/lib/modules/`（非标准路径，沿用原厂做法），开机由 `rk-wifi-bt.service` 加载。首次会生成 `cc33xx-nvs.bin`（随机 MAC），与原来行为一致。
2. **镜像大小**：默认 **4096 MiB**（内容约 810 MiB，其余空余直接供 `apt` 使用，可用约 **3.0 GB**）。rootfs 分区上限是 6144 MiB，需要更多空间时上板执行 `resize2fs /dev/disk/by-partlabel/rootfs` 可无损扩到上限。第二个参数可调：`make-image.sh bookworm 5120`。
3. **传输/交付建议压缩**：4096 MiB 镜像用 `xz -9` 压后约 **147 MiB**（6.44 GB 满额版压后也是这个数 —— 被压掉的是零，数据量不变）。`zstd -19` 约 181 MiB、`gzip -9` 约 273 MiB。刷机前解压回 `.img` 即可。
3. **换内核（6.12）**：正在单独推进。屏（LVDS + `simple-panel`）、TP（GT911）、背光、PMIC 在 6.12 里全有现成驱动，**纯 DTS 移植、零驱动开发**；WiFi/BT 需要从厂商 SDK 取源码编外挂模块。