Merge pull request #129 from KevinMX/meles-20241229

KevinMX · web-flow · commit f9d39c7b51e7 · 2025-01-02T23:58:28.000+08:00
Meles/RevyOS: update to 20241229
diff --git a/Meles/README.md b/Meles/README.md
@@ -10,18 +10,19 @@ cpu_core: XuanTie C910 + XuanTie C906 + XuanTie E902
 
 ### Operating System Information
 
-- RevyOS (provided by official source)
-    - Download link: https://github.com/milkv-meles/meles-images/releases
+- RevyOS
+    - Download link: https://mirror.iscas.ac.cn/revyos/extra/images/meles/20241229/
     - Reference Installation Document: https://milkv.io/zh/docs/meles/getting-started/boot
 
 ### Hardware Information
 
-- Milk-V Meles 4GB/8GB
+- Milk-V Meles 4GB/8GB/16GB
+    - The board tested here in the documents is the 16GB variant
 
 ## Test Results
 
-| Software Category | Package Name | Test Results (Test Report)            |
-|-------------------|--------------|---------------------------------------|
-| RevyOS Image Boot | N/A          | [CFT][RevyOS] (Milk-V Official Image) |
+| Software Category | Package Name | Test Results (Test Report) |
+| ----------------- | ------------ | -------------------------- |
+| RevyOS Image Boot | N/A          | [Good][RevyOS]             |
 
 [RevyOS]: ./RevyOS/README.md
diff --git a/Meles/README_zh.md b/Meles/README_zh.md
@@ -4,18 +4,19 @@
 
 ### 操作系统信息
 
-- RevyOS（官方提供）
-    - 下载链接：https://github.com/milkv-meles/meles-images/releases
+- RevyOS
+    - 下载链接：https://mirror.iscas.ac.cn/revyos/extra/images/meles/20241229/
     - 参考安装文档：https://milkv.io/zh/docs/meles/getting-started/boot
 
 ### 硬件开发板信息
 
-- Milk-V Meles 4GB/8GB
+- Milk-V Meles 4GB/8GB/16GB
+    - 文档中测试的为 16GB 版本
 
 ## 测试结果
 
-| 软件分类        | 软件包名 | 测试结果（测试报告）             |
-|-------------|----------|----------------------------|
-| RevyOS 镜像启动 | N/A      | [CFT][RevyOS]（Milk-V 厂商镜像） |
+| 软件分类        | 软件包名 | 测试结果（测试报告） |
+| --------------- | -------- | -------------------- |
+| RevyOS 镜像启动 | N/A      | [Good][RevyOS]        |
 
 [RevyOS]: ./RevyOS/README_zh.md
diff --git a/Meles/RevyOS/README.md b/Meles/RevyOS/README.md
@@ -1,10 +1,10 @@
 ---
 sys: revyos
-sys_ver: 12
+sys_ver: 20241229
 sys_var: null
 
-status: cft
-last_update: 2024-06-21
+status: good
+last_update: 2025-01-02
 ---
 
 # RevyOS Meles Version Test Report
@@ -13,29 +13,89 @@ last_update: 2024-06-21
 
 ### Operating System Information
 
-- System Version: root-meles-20231210_134926.ext4.tar.gz
-- Download Link: https://github.com/milkv-meles/meles-images/releases
+- System Version: RevyOS Meles 20241229
+- Download Link: https://mirror.iscas.ac.cn/revyos/extra/images/meles/20241229/
+    - iw-single-line binary: https://mirror.iscas.ac.cn/revyos/extra/images/meles/20240720/iw-single-line.bin
 - Reference Installation Document: https://milkv.io/zh/docs/meles/getting-started/boot
 
 ### Hardware Information
 
-- Milk-V Meles 4GB/8GB
+- Milk-V Meles 4GB/8GB/16GB
 - eMMC module > 16GB
 - A USB A to C cable
-- Optional: A USB-TTL Debugger
+- Optional: A USB-TTL Debugger (Flash U-Boot with SPL to SPI NOR Flash)
 - Optional: Keyboard, monitor, mouse (for graphical interface testing)
 
 ## Installation Steps
 
-### Flashing Image using `fastboot` onto the Development Board
+Milk-V Meles' Bootloader is stored inside the onboard SPI NOR Flash, which can be upgraded using `cct` tool provided by `yoctools`. This is different from Lichee Pi 4A which uses the same TH1520 SoC.
+
+You'll need UART serial connection to flash the firmware.
+
+> Note: please do not try to use `fastboot flash uboot` method to upgrade U-Boot firmware, which is the same as the LPi4A.
+> This method will NOT flash U-Boot to SPI NOR Flash which is loaded on boot by default. Thus you must use `cct` to flash the firmware.
+
+Known issue: some AMD boards might not pick up Meles in fastboot mode.
+
+Workaround: try connect Meles to a external USB Hub rather than the USB ports directly provided by the motherboard/PCH.
+
+### Use `cct` to flash Bootloader into SPI NOR Flash
+
+`cct` is the image flashing tool provided by `yoctools`, which requires Python 3.6~3.11 and Linux.
+
+If your distro has already upgrade to Python 3.12+, then you'll need to manually install Python 3.11, create a Python virtual environment with it.
+
+Since Python 3.12 and [PEP 668](https://peps.python.org/pep-0668/), you can not use `pip` to install packages globally.
 
-Download the system image and U-Boot SPL from [GitHub release](https://github.com/milkv-meles/meles-images/releases).
+And `yoctools` still depends on some packages which were already deprecated/replaced in Python 3.12+, thus you must create a Python venv in order to use `yoctools`.
 
-U-Boot with SPL version selection:
-- 4GB Version -> u-boot-with-spl-**single**rank.bin
-- 8GB Version -> u-boot-with-spl-**dual**rank.bin
+Take Arch Linux as an example. By the time this article was written (2025.01), the default Python is Python 3.13, directly install `yoctools` will not work. You should install Python 3.11 from [AUR](https://aur.archlinux.org/packages/python311/) and creating a virtual environment using this version in order to flash the firmware.
+
+Prepare Python 3.11 environment:
+
+```shell
+paru python311
+sudo pacman -S python-virtualenv
+virtualenv -p 3.11 meles
+source meles/bin/activate
+pip install yoctools
+cd meles/bin
+```
+
+For those distros still staying at Python 3.6~3.11, you can install `yoctools` directly with `pip`. Python venv is not required.
+
+Download the firmware:
+
+```shell
+wget https://mirror.iscas.ac.cn/revyos/extra/images/meles/20240720/iw-single-line.bin
+wget https://mirror.iscas.ac.cn/revyos/extra/images/meles/20241229/u-boot-with-spl-meles.bin
+```
 
-Press and hold the download button near the GPIO interface on the development board and connect the board to the computer.
+Note: choose the correct version depending on your board's RAM:
+
+- 4GB -> u-boot-with-spl-meles-4g.bin
+- 8GB -> u-boot-with-spl-meles.bin
+- 16GB -> u-boot-with-spl-meles-16g.bin
+
+For `iw-single-line.bin`, you can use it with all RAM versions.
+
+Connect the board and your PC with UART debugger. **DO NOT** run tools like `minicom` or `tio` which will occupy the serial port.
+
+Hold the recovery button and **THEN** power on the board.
+
+> The recovery button is located at the edge of the board near the GPIO pins, on the inner side it's the eMMC boot button. Don't mixed them.
+> For details please refer to: https://milkv.io/docs/meles/hardware/meles-main-board
+
+```shell
+sudo ./cct list -u /dev/ttyUSB0
+#Please change accordingly. Depending on your debugger, e.g. for CH343P it's ttyACM0 rather than ttyUSB0
+sudo ./cct download -d ram0 -f iw-single-line.bin -v checksum -r
+sudo ./cct download -u /dev/ttyUSB0 -d qspi0 -f ./u-boot-with-spl-meles.bin -v checksum -r -t 1200
+```
+
+Wait for the flashing progress to complete, then power off the board, hold the recovery button and reconnect it to PC.
+
+### Flashing Image using `fastboot` onto the Development Board
 
 Check connection status:
 
@@ -44,19 +104,24 @@ $ lsusb | grep T-HEAD
 Bus 001 Device 045: ID 2345:7654 T-HEAD USB download gadget
 ```
 
-Next, use `fastboot` to flash the image.
+Next, execute the following commands to download, extract and flash the images to your board's eMMC.
 
-If `fastboot` doesn't recognize the device or you encounter flashing issues, check the device connection and try running `fastboot` as a privileged user (`sudo`).
+> If `fastboot` doesn't pick up the board or you encounter flashing issues, check the device connection and try running `fastboot` as a privileged user (i.e. `sudo`). Doing so is usually required under Linux since the default USB VID/PID is not in the default udev rules.
 
 ```shell
-fastboot flash ram u-boot-with-spl-dualrank.bin
-fastboot reboot
-fastboot flash uboot u-boot-with-spl-dualrank.bin
-fastboot flash boot boot.ext4
-tar xvf root-meles-20231210_134926.ext4.tar.gz
-fastboot flash root root-meles-20231210_134926.ext4
+wget https://mirror.iscas.ac.cn/revyos/extra/images/meles/20241229/boot-meles-20241229_032258.ext4.zst
+wget https://mirror.iscas.ac.cn/revyos/extra/images/meles/20241229/root-meles-20241229_032258.ext4.zst
+zstd -T0 -dv *.ext4.zst
+sudo fastboot flash ram u-boot-with-spl-meles.bin
+sudo fastboot reboot
+sudo fastboot flash boot boot-meles-20241229_032258.ext4
+sudo fastboot flash root root-meles-20241229_032258.ext4
 ```
 
+After the flashing process, reset the board and you're good to go.
+
+Better do a system upgrade via `sudo apt update; sudo apt upgrade` after flashing. There's a kernel upgrade which fixed some known issues (e.g. the onboard Wi-Fi might not work)
+
 ### Logging into the System
 
 Logging into the system via serial port or graphical interface.
@@ -68,13 +133,21 @@ Default Password: `debian`
 
 The system should boot up normally and allow login through the serial port.
 
+HDMI output works and the user can login to the desktop environment.
+
 ## Actual Results
 
-CFT
+The actual results matches the expected results.
+
+### Boot Log
+
+[![asciicast](https://asciinema.org/a/GowOSUJ7oFYVH4igmtqB0s4ub.svg)](https://asciinema.org/a/GowOSUJ7oFYVH4igmtqB0s4ub)
+
+![](image/2025-01-02-19-41-20.png)
 
-### Boot Information
+![](image/2025-01-02-19-45-05.png)
 
-CFT
+(The screenshots are from an HDMI capture card.)
 
 ## Test Criteria
 
@@ -84,4 +157,4 @@ Failed: The actual result does not match the expected result.
 
 ## Test Conclusion
 
-CFT
+Test successful.
diff --git a/Meles/RevyOS/README_zh.md b/Meles/RevyOS/README_zh.md
@@ -4,29 +4,87 @@
 
 ### 操作系统信息
 
-- 系统版本：root-meles-20231210_134926.ext4.tar.gz
-- 下载链接：https://github.com/milkv-meles/meles-images/releases
+- 系统版本：RevyOS Meles 20241229
+- 下载链接：https://mirror.iscas.ac.cn/revyos/extra/images/meles/20241229/
+    - iw-single-line 烧录工具：https://mirror.iscas.ac.cn/revyos/extra/images/meles/20240720/iw-single-line.bin
 - 参考安装文档：https://milkv.io/zh/docs/meles/getting-started/boot
 
 ### 硬件信息
 
-- Milk-V Meles 4GB/8GB
+- Milk-V Meles 4GB/8GB/16GB
 - eMMC 模组 > 16GB
 - USB A to C 线缆一条
-- 可选：USB-TTL 调试器一个
+- USB-TTL 调试器一个（用于烧录 U-Boot with SPL 至 SPI NOR Flash）
 - 可选：键盘、显示器、鼠标（测试图形界面）
 
 ## 安装步骤
 
-### 使用 `fastboot` 刷写镜像至开发板
+与同为 TH1520 SoC 的 Lichee Pi 4A 稍有不同，Milk-V Meles 的 Bootloader 存储在板载 SPI NOR Flash 中，需要使用 `yotcools` 中的 `cct` 工具烧录。
 
-从 [GitHub release](https://github.com/milkv-meles/meles-images/releases) 下载系统镜像和 U-Boot SPL。
+这一过程需要使用 UART 串口连接。
 
-u-boot-with-spl 版本选择：
-- 4GB 版本 -> u-boot-with-spl-**single**rank.bin
-- 8GB 版本 -> u-boot-with-spl-**dual**rank.bin
+> Note: 请勿按照刷写 LPi4A 的方式使用 `fastboot flash uboot` 来更新 U-Boot 固件。
+> 这一操作并不会将 U-Boot 刷写至开机默认加载的 SPI NOR Flash 中。使用 `cct` 刷写固件是必须的。
 
-按住开发板 GPIO 接口附近的下载按钮并将开发板连接至计算机。
+已知问题：部分 AMD 主板可能会无法识别处于 fastboot 模式下的 Meles。
+
+规避方法：尝试将 Meles 连接至外接的 USB Hub，而非主板/桥片直接引出的 USB 端口。
+
+### 使用 `cct` 将 Bootloader 写入 SPI NOR Flash
+
+`cct` 是 `yoctools` 提供的镜像刷写工具，`yoctools` 目前依赖 Python 3.6~3.11 和 Linux 系统。
+
+若您所使用的发行版已经升级到 Python 3.12+，则需要手动安装 Python 3.11 并创建对应版本的 Python 虚拟环境 / venv。
+
+Python 3.12 后受 [PEP 668](https://peps.python.org/pep-0668/) 影响，不能直接全局使用 `pip` 安装；此外由于 `yoctools` 仍依赖部分 Python 3.12+ 中已被替换的包，创建虚拟环境的步骤是必须的。
+
+以 Arch Linux 为例，截止 2025.01，软件源内提供的 Python 版本为 3.13，在这一版本下安装 `yoctools` 后无法正常使用。需要从 [AUR](https://aur.archlinux.org/packages/python311/) 获取 Python 3.11，然后创建虚拟环境进行刷写操作。
+
+准备 Python 3.11 虚拟环境：
+
+```shell
+paru python311
+sudo pacman -S python-virtualenv
+virtualenv -p 3.11 meles
+source meles/bin/activate
+pip install yoctools
+cd meles/bin
+```
+
+对于 Python 版本为 3.6~3.11 的发行版，可直接通过 `pip` 安装 `yoctools`，创建虚拟环境不是必须的。
+
+获取所需固件：
+
+```shell
+wget https://mirror.iscas.ac.cn/revyos/extra/images/meles/20240720/iw-single-line.bin
+wget https://mirror.iscas.ac.cn/revyos/extra/images/meles/20241229/u-boot-with-spl-meles.bin
+```
+
+注意根据开发板内存大小选择正确的 `u-boot-with-spl` 固件：
+
+- 4GB 版本 -> u-boot-with-spl-meles-4g.bin
+- 8GB 版本 -> u-boot-with-spl-meles.bin
+- 16GB 版本 -> u-boot-with-spl-meles-16g.bin
+
+`iw-single-line.bin` 是通用的，不区分内存大小。
+
+通过 UART 调试器连接开发板和计算机。烧录 U-Boot SPL 时**不要**运行 `minicom` 或 `tio` 等程序占用串口。
+
+按住下载按钮，**然后**给开发板上电。
+
+> 下载按钮位于 GPIO 插针附近，PCB 边缘，其内侧为 eMMC 启动按钮，注意区分。
+> 详情请参照：https://milkv.io/zh/docs/meles/hardware/meles-main-board
+
+```shell
+sudo ./cct list -u /dev/ttyUSB0
+#取决于您的调试器型号，如 CH343P 则此处为 ttyACM0，请根据实际情况更改
+sudo ./cct download -d ram0 -f iw-single-line.bin -v checksum -r
+sudo ./cct download -u /dev/ttyUSB0 -d qspi0 -f ./u-boot-with-spl-meles.bin -v checksum -r -t 1200
+```
+
+等待烧写完成后，给开发板断电，然后按住下载按钮，将开发板重新连接至计算机。
+
+### 使用 `fastboot` 刷写镜像
 
 检查连接状态：
 
@@ -35,19 +93,25 @@ $ lsusb | grep T-HEAD
 Bus 001 Device 045: ID 2345:7654 T-HEAD USB download gadget
 ```
 
-接下来使用 `fastboot` 刷写镜像。
+执行如下命令，下载，解压并刷写镜像至 eMMC。
 
-如果出现 `fastboot` 不识别设备、无法刷写等情况，请检查设备连接，并尝试以特权用户身份（`sudo`）执行 `fastboot`。
+> 如果出现 `fastboot` 不识别设备、无法刷写等情况，请检查设备连接，并尝试以特权用户身份（`sudo`）执行 `fastboot`。
+> 通常在 Linux 下是需要使用 `sudo` 的，原因是 USB VID/PID 不在默认的 udev 规则内。
 
 ```shell
-fastboot flash ram u-boot-with-spl-dualrank.bin
-fastboot reboot
-fastboot flash uboot u-boot-with-spl-dualrank.bin
-fastboot flash boot boot.ext4
-tar xvf root-meles-20231210_134926.ext4.tar.gz
-fastboot flash root root-meles-20231210_134926.ext4
+wget https://mirror.iscas.ac.cn/revyos/extra/images/meles/20241229/boot-meles-20241229_032258.ext4.zst
+wget https://mirror.iscas.ac.cn/revyos/extra/images/meles/20241229/root-meles-20241229_032258.ext4.zst
+zstd -T0 -dv *.ext4.zst
+sudo fastboot flash ram u-boot-with-spl-meles.bin
+sudo fastboot reboot
+sudo fastboot flash boot boot-meles-20241229_032258.ext4
+sudo fastboot flash root root-meles-20241229_032258.ext4
 ```
 
+刷写完成后，重启开发板即可。
+
+进入系统后，建议执行一次系统升级（`sudo apt update; sudo apt upgrade`）。更新的内核修复了一些已知问题（如无线网卡可能不工作）。
+
 ### 登录系统
 
 通过串口或图形界面登录系统。
@@ -57,15 +121,21 @@ fastboot flash root root-meles-20231210_134926.ext4
 
 ## 预期结果
 
-系统正常启动，能够通过串口登录。
+系统正常启动，能够通过串口登录，HDMI 正常输出，能够登录进桌面。
 
 ## 实际结果
 
-CFT
+与预期结果一致。
 
 ### 启动信息
 
-CFT
+[![asciicast](https://asciinema.org/a/GowOSUJ7oFYVH4igmtqB0s4ub.svg)](https://asciinema.org/a/GowOSUJ7oFYVH4igmtqB0s4ub)
+
+![](image/2025-01-02-19-41-20.png)
+
+![](image/2025-01-02-19-45-05.png)
+
+（截图来自 HDMI 采集卡）
 
 ## 测试判定标准
 
@@ -75,4 +145,4 @@ CFT
 
 ## 测试结论
 
-CFT
+测试成功。
diff --git a/Meles/RevyOS/image/2025-01-02-19-41-20.png b/Meles/RevyOS/image/2025-01-02-19-41-20.png
diff --git a/Meles/RevyOS/image/2025-01-02-19-45-05.png b/Meles/RevyOS/image/2025-01-02-19-45-05.png
