# zvm_release_files

**Repository Path**: johhz/zvm_release_files

## Basic Information

- **Project Name**: zvm_release_files
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-16
- **Last Updated**: 2026-09-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ZVM RK3588 v2.1 发行文件

当前发布：`v2.1-delivery2-20260916`。二进制通过 Releases 附件提供，单个分卷不超过 90MiB。

| 资源 | Release |
| --- | --- |
| ZVM 启动内核与部署工具 | [下载](https://gitee.com/johhz/zvm_release_files/releases/tag/v2.1-delivery2-20260916) |
| Android | [下载](https://gitee.com/johhz/zvm_android_images/releases/tag/v2.1-delivery2-20260916) |
| OpenHarmony | [下载](https://gitee.com/johhz/zvm_openharmony_images/releases/tag/v2.1-delivery2-20260916) |
| Buildroot | [下载](https://gitee.com/johhz/zvm_buildroot_images/releases/tag/v2.1-delivery2-20260916) |
| openEuler | [下载](https://gitee.com/johhz/zvm_open-euler_images/releases/tag/v2.1-delivery2-20260916) |
| Ubuntu | [下载](https://gitee.com/johhz/zvm_ubuntu_images/releases/tag/v2.1-delivery2-20260916) |

## 按需下载

[`downloads.json`](downloads.json) 列出每组的全部分卷、HTTPS 附件链接、大小和 SHA256。
下载所选 rootfs 的全部分卷，并获取内核及部署工具。不要混用原后端的 190MiB 分卷与这里的 90MiB 分卷。

## Windows 终端脚本

下载仓库中的 [`rk3588-v2.1.ps1`](rk3588-v2.1.ps1)，使用 Windows PowerShell 5.1 运行：

```powershell
powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\rk3588-v2.1.ps1
```

按提示选择操作、rootfs 和目标 SD 卡；确认磁盘编号后直接开始下载、解压和制作，不再二次询问。仅下载无需管理员权限；刷写需要管理员权限。
运行期间脚本会关闭控制台的快速编辑模式并阻止系统空闲睡眠，结束时自动还原，避免鼠标点中黑框把进度暂停；写入过程中仍不要关闭窗口、按 Ctrl+C 或拔卡。
脚本默认读取本仓库 main 分支的下载清单，支持按需下载、分卷 ZIP、断点续传和 SHA256 检查。
无需 Python、WinRAR、WSL 或开发工具；Windows PowerShell 和 .NET Framework 为运行依赖。

这是基础实现，新版脚本尚未进行完整刷卡验证。镜像附件的重新分卷不修改解压后的镜像内容；发布与下载检查不代表板端启动验证。

## 板卡适配版（Firefly / iTop / 鲁班猫 / Forlinx）

四种板卡的入口分别使用对应的 `boot.scr` 与 `zvm_release_rk3588v2.1.bin`，其余流程（下载、校验、分区、槽位、更新）完全一致。
这两个文件分别放在 [`firefly/`](firefly)、[`itop/`](itop)、[`lubancat/`](lubancat)、[`forlinx/`](forlinx)，清单是同目录下的 `*-boot.json`，按 SHA256 校验后才使用。
Non-RTOS 镜像（`nrtos_images.bin`）及 rootfs 仍来自标准发行包。

四个入口（命令要连最后的 `| iex` 一起复制）：

```powershell
# Firefly（标准版）
irm 'https://gitee.com/johhz/zvm_release_files/raw/main/start-firefly.ps1' | iex

# iTop
irm 'https://gitee.com/johhz/zvm_release_files/raw/main/start-itop.ps1' | iex

# 鲁班猫
irm 'https://gitee.com/johhz/zvm_release_files/raw/main/start-lubancat.ps1' | iex

# Forlinx（飞凌）
irm 'https://gitee.com/johhz/zvm_release_files/raw/main/start-forlinx.ps1' | iex
```

原来的 `start.ps1` 仍然可用：它从固定版本的 Release 内核包里取启动文件；`start-firefly.ps1` 使用 `firefly/` 中后续更新的文件。

也可以把图形界面指向对应的板卡脚本：

```powershell
powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\zvm-gui.ps1 -MainUrl 'https://gitee.com/johhz/zvm_release_files/raw/main/lubancat/rk3588-v2.1-lubancat.ps1'
```

[`start.ps1`](start.ps1) 和 [`rk3588-v2.1.ps1`](rk3588-v2.1.ps1) 保持不变，标准版链接不受影响。
板卡版是基础脚本的生成副本，只多了启动文件替换；基础脚本更新后运行
`powershell -File build-board-entry.ps1` 重新生成全部板卡版本，`-Check` 可以检查是否已经不同步。

Forlinx 文件来源、SHA256 和验证范围见[新增入口记录](roadmap/01_forlinx_entry_20260928.md)。

## Windows 图形界面

不想用终端时，在 Windows PowerShell 中运行：

```powershell
irm 'https://gitee.com/johhz/zvm_release_files/raw/main/start-gui.ps1' | iex
```

窗口里选择操作（整卡制作 / 仅下载解压 / 更新槽位）、勾选文件系统、选择目标 TF 卡和工作目录，然后点“开始”。
窗口本身只是外壳：它下载 `rk3588-v2.1.ps1`，再用 `-Action … -Rootfs … -DiskNumber … -Unattended` 以子进程方式调用同一条流程，
所以下载、校验、分区和写入行为与控制台完全一致，输出实时显示在窗口里，写入进度反映到进度条上。
刷写需要管理员权限：非管理员点“开始”时，窗口会请求以管理员身份重新打开自己。任务运行期间关闭窗口会二次确认。

也可以把 [`zvm-gui.ps1`](zvm-gui.ps1) 保存到本地，用
`powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\zvm-gui.ps1` 运行；它同样会从本仓库获取最新主脚本。
`powershell.exe -NoProfile -File .\zvm-gui.ps1 -SelfTest` 只检查清单读取、磁盘标签、子进程命令行拼装和进度解析，不打开窗口。

## 分仓库发布

Gitee 普通项目单附件不能超过 100M，每仓库所有附件累计不能超过 1G。各 rootfs 分仓库发布，统一由本仓库清单引用。
后续保留多个历史版本时仍需关注每个仓库的累计附件配额。

清单与脚本保存在 Git 仓库中，二进制通过版本固定的 Release 附件链接下载。

## 多文件并行下载

默认同时下载 4 个文件，每个文件仍为单连接；不拆分单个文件。
可以用 `-ParallelFiles 2` 降低并发，或用 `-ParallelFiles 1` 恢复串行，最大为 8。
已有缓存和 `.partial` 文件继续复用，失败文件会重试，全部下载通过 SHA256 后才进入解压、刷写。
下载阶段做过小文件并发、续传及错误处理检查；没有进行新的刷卡或板端验证。
正在运行的旧脚本不会自动更新，需要结束或取消旧任务后重新启动。

## PowerShell 一行启动

在 Windows PowerShell 中粘贴以下命令；刷卡时需要管理员窗口：

```powershell
irm 'https://gitee.com/johhz/zvm_release_files/raw/main/start.ps1' | iex
```

`start.ps1` 使用无 BOM 的 ASCII 文本，下载主脚本后移除开头的 BOM 再执行。
主脚本保留 UTF-8 BOM，保证 Windows PowerShell 5.1 从本地文件运行时正确读取中文。
因此一行启动请使用 `start.ps1`；本地运行仍使用 `rk3588-v2.1.ps1` 或已有管理员快捷方式。

## Linux / macOS 一行启动

在普通终端运行：

```sh
curl -fsSL 'https://gitee.com/johhz/zvm_release_files/raw/main/rk3588-v2.1.sh' | bash
```

共用同一份下载清单，支持 rootfs 选择、4 文件并发、缓存续传、分卷 ZIP 解压和整卡制作。
需要 Bash、curl、Python 3.8+ 标准库，无 pip 依赖。Linux 刷卡还需要 util-linux 和
dosfstools；macOS 使用系统 diskutil、newfs_msdos。缺少依赖会在分区前说明原因。

磁盘按 `Number` 列的数字编号选择，例如输入 `2`；刷卡前输入对应的 `ERASE 2`，再按 sudo 提示授权。核对列表中的设备名、容量和序列号；仅下载不需要管理员权限。
管道启动的交互输入来自 `/dev/tty`，不需要下载脚本到当前目录。

```sh
# 先保存，按需仅下载
curl -fL 'https://gitee.com/johhz/zvm_release_files/raw/main/rk3588-v2.1.sh' -o rk3588-v2.1.sh
bash rk3588-v2.1.sh --action prepare --rootfs buildroot,ubuntu --parallel-files 4
```

已下载 ZIP 分卷时，可直接校验并解压，不重新下载镜像、不操作磁盘：

```sh
bash rk3588-v2.1.sh --action unpack --rootfs ubuntu --package-dir "$PWD" --work-dir "$PWD/prepared"
```

Ubuntu 的 `ubuntu.z01` 至 `ubuntu.z06` 和 `ubuntu.zip` 必须在同一目录；输出为
`prepared/images/file_system_images/ubuntu.bin`。缺卷或校验失败会指出具体文件。
不要使用系统 `zip -s 0` 合并这些分卷：已在 macOS 上复现合并结果截断。

Linux 缓存位于 `~/.cache/zvm/rk3588-v2.1`；macOS 位于 `~/Library/Caches/ZVM/rk3588-v2.1`。
源码在 `unix/rk3588.py`，运行 `python3 unix/build-entry.py` 可重新生成单文件入口。
已检查下载、续传和分卷处理，并在 macOS 临时磁盘映像上检查分区、FAT32 格式化和启动文件复制。
没有用这个 Shell 入口刷写真实 SD 卡或执行板端启动测试。

## Windows 更新所选 rootfs

在管理员 Windows PowerShell 中下载脚本，更新 Buildroot 的槽 3：

```powershell
Invoke-WebRequest -UseBasicParsing 'https://gitee.com/johhz/zvm_release_files/raw/main/rk3588-v2.1.ps1' -OutFile .\rk3588-v2.1.ps1
powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\rk3588-v2.1.ps1 -Action Update -Rootfs buildroot
```

`-Rootfs` 可选 `android`、`openharmony`、`buildroot`、`openeuler`、`ubuntu`；省略时交互选择。
按磁盘 Number 选择已完成部署的 TF 卡，核对镜像及槽位，输入 `UPDATE 编号` 后开始更新。
该模式保留分区、启动文件、Non-RTOS 镜像和未选槽位，只覆盖所选文件系统槽位。

## 文件系统槽位

全选时写入五份 rootfs，每种系统一份，空槽从槽 6 开始。

| 槽位 | 文件系统 | 第二分区内偏移（MiB） |
| --- | --- | --- |
| 1 | Android | 3072 |
| 2 | OpenHarmony | 6144 |
| 3 | Buildroot | 9216 |
| 4 | openEuler | 12288 |
| 5 | Ubuntu | 15360 |
| 6 起 | 空白 | 18432 起 |

卡的分区布局固定为：第一分区从 1 MiB 起、长 8201 MiB（约 8 GiB），放 `boot.scr`、`zvm_release_rk3588v2.1.bin` 和 Non-RTOS 之外的全部启动文件；
第二分区从 8202 MiB 起，直接占用到 TF 卡末尾，不再保留未分配空间，槽位按上表从其内部偏移开始。
第二分区不创建文件系统，始终保持未格式化（Windows 也无法把大于 32 GiB 的卷格式化成 FAT32）：槽位镜像按字节偏移直接写入，MBR 类型字节仍按发行布局保留。
写入方式是把镜像直接写到物理磁盘的对应偏移（`\\.\PhysicalDriveN`），因此不依赖卷 GUID、盘符或文件系统；写之前会锁定并卸载卡上的卷，保持到写完为止。
制作过程中两个分区都不会保留盘符，资源管理器里不会出现可被误格式化的 IMAGE 卷。
如果 Windows 仍然弹出 AutoPlay 或“需要格式化”提示，直接取消即可，不要执行格式化。

Windows、Linux/macOS 整卡制作及 Windows 文件系统更新使用此布局。整卡制作会清除空槽的旧镜像标记。