Upgrade README

2023-12-23 17:12:11 +08:00
parent dd82b68199
commit 1ef1e15cd1
3 changed files with 402 additions and 105 deletions
--- a/README-zh.md
+++ b/README-zh.md
@ -13,9 +13,9 @@ Milk-V Duo 是一个基于 CV1800B 芯片的超紧凑嵌入式开发平台。它

 # SDK目录结构

-```text
+```
 ├── build               // 编译目录，存放编译脚本以及各board差异化配置
-├── build_milkv.sh      // Milk-V Duo 一键编译脚本
+├── build.sh            // Milk-V Duo 一键编译脚本
 ├── buildroot-2021.05   // buildroot 开源工具
 ├── freertos            // freertos 系统
 ├── fsbl                // fsbl启动固件，prebuilt 形式存在
@ -32,6 +32,9 @@ Milk-V Duo 是一个基于 CV1800B 芯片的超紧凑嵌入式开发平台。它

 # 快速开始

+> [!TIP]
+> 以下 SDK 的编译和使用方法，您也可以转到我们的 [官方文档](https://milkv.io/zh/docs/duo/getting-started/buildroot-sdk) 中查看，会有更好的阅读体验。另外，我们的官方文档网站也是开源的，如果您有兴趣来丰富文档的内容或者翻译成其他语言，可以在 [这个仓库](https://github.com/milk-v/milkv.io/) 中提交您的 PR，我们会不定期为贡献者赠送精美的礼物。
+
 准备编译环境，使用本地的 Ubuntu 系统，官方支持的编译环境为 `Ubuntu Jammy 22.04.x amd64`。

 如果您使用的是其他的 Linux 发行版，我们强烈建议您使用 Docker 环境来编译，以降低编译出错的概率。
@ -48,19 +51,50 @@ sudo apt install -y pkg-config build-essential ninja-build automake autoconf lib

 ### 获取 SDK

-```
+```bash
 git clone https://github.com/milkv-duo/duo-buildroot-sdk.git --depth=1
 ```

 ### 1、一键编译

- 执行一键编译脚本 `build_milkv.sh`
-
+执行一键编译脚本 `build.sh`：
 ```bash
 cd duo-buildroot-sdk/
-./build_milkv.sh
+./build.sh
 ```
- 编译成功后可以在 `out` 目录下看到生成的SD卡烧录镜像 `milkv-duo-*-*.img`
+会看到编译脚本的使用方法提示：
+```bash
+# ./build.sh
+Usage:
+./build.sh              - Show this menu
+./build.sh lunch        - Select a board to build
+./build.sh [board]      - Build [board] directly, supported boards asfollows:
+milkv-duo
+milkv-duo-python
+milkv-duo256m
+milkv-duo256m-python
+```
+最下边列出的是当前支持的目标版本列表，带 `python` 后缀的包含 python，pip, pinpong库。
+
+如提示中所示，有两种方法来编译目录版本。
+
+第一种方法是执行 `./build.sh lunch` 调出交互菜单，选择要编译的版本序号，回车：
+```bash
+# ./build.sh lunch
+Select a target to build:
+1. milkv-duo
+2. milkv-duo-python
+3. milkv-duo256m
+4. milkv-duo256m-python
+Which would you like:
+```
+
+第二种方法是脚本后面带上目标版本的名字，直接一键编译，比如需要编译 Duo 带 python 和 pinpong 库的的镜像，命令如下:
+```bash
+# ./build.sh milkv-duo-python
+```
+
+编译成功后可以在 `out` 目录下看到生成的SD卡烧录镜像 `milkv-duo-python-*-*.img`

 *注: 第一次编译会自动下载所需的工具链，大小为 840M 左右，下载完会自动解压到 SDK 目录下的 `host-tools` 目录，下次编译时检测到已存在 `host-tools` 目录，就不会再次下载了*

@ -68,15 +102,31 @@ cd duo-buildroot-sdk/

 如果未执行过一键编译脚本，需要先手动下载工具链 [host-tools](https://sophon-file.sophon.cn/sophon-prod-s3/drive/23/03/07/16/host-tools.tar.gz)，并解压到 SDK 根目录：

-```
+```bash
 tar -xf host-tools.tar.gz -C /your/sdk/path/
 ```

-再依次输入如下命令完成分步编译：
+再依次输入如下命令完成分步编译，命令中的 `[board]` 和 `[config]` 替换为需要编译的版本，当前支持的 `board` 和对应的 `config` 如下：
+```
+milkv-duo               cv1800b_milkv_duo_sd
+milkv-duo-python        cv1800b_milkv_duo_sd
+milkv-duo256m           cv1812cp_milkv_duo256m_sd
+milkv-duo256m-python    cv1812cp_milkv_duo256m_sd
+```

 ```bash
-export MILKV_BOARD=milkv-duo
-source milkv/boardconfig-milkv-duo.sh
+source device/[board]/boardconfig.sh
+
+source build/milkvsetup.sh
+defconfig [config]
+clean_all
+build_all
+pack_sd_image
+```
+
+比如需要编译 Duo 带 python 和 pinpong 库的的镜像，分步编译命令如下：
+```bash
+source device/milkv-duo-python/boardconfig.sh

 source build/milkvsetup.sh
 defconfig cv1800b_milkv_duo_sd
@ -85,7 +135,11 @@ build_all
 pack_sd_image
 ```

-生成的固件位置: `install/soc_cv1800b_milkv_duo_sd/milkv-duo.img`。
+生成的固件位置：
+```
+Duo:      install/soc_cv1800b_milkv_duo_sd/[board].img
+Duo256M:  install/soc_cv1812cp_milkv_duo256m_sd/[board].img
+```

 ## 二、使用 Docker 编译

@ -95,19 +149,19 @@ pack_sd_image

 ### 在 Linux 主机上拉 SDK 代码

-```
+```bash
 git clone https://github.com/milkv-duo/duo-buildroot-sdk.git --depth=1
 ```

 ### 进入 SDK 代码目录

-```
+```bash
 cd duo-buildroot-sdk
 ```

 ### 拉取 Docker 镜像并运行

-```
+```bash
 docker run -itd --name duodocker -v $(pwd):/home/work milkvtech/milkv-duo:latest /bin/bash
 ```

@ -118,7 +172,7 @@ docker run -itd --name duodocker -v $(pwd):/home/work milkvtech/milkv-duo:latest
 - `milkvtech/milkv-duo:latest` Milk-V 提供的 Docker 镜像，第一次会自动从 hub.docker.com 下载

 Docker 运行成功后，可以用 `docker ps -a` 命令查看运行状态：
-```
+```bash
 $ docker ps -a
 CONTAINER ID   IMAGE                        COMMAND       CREATED       STATUS       PORTS     NAMES
 8edea33c2239   milkvtech/milkv-duo:latest   "/bin/bash"   2 hours ago   Up 2 hours             duodocker
@ -126,37 +180,74 @@ CONTAINER ID   IMAGE                        COMMAND       CREATED       STATUS

 ### 1. 使用 Docker 一键编译

+```bash
+docker exec -it duodocker /bin/bash -c "cd /home/work && cat /etc/issue && ./build.sh [board]"
 ```
-docker exec duodocker /bin/bash -c "cd /home/work && cat /etc/issue && ./build_milkv.sh"
+
+注意命令最后的 `./build.sh [board]` 和前面在 Ubuntu 22.04 中一键编译说明中的用法是一样的，直接 `./build.sh` 可以查看命令的使用方法，用 `./build.sh lunch` 可以调出交互选择菜单，用 `./build.sh [board]` 可以直接编译目标版本，`[board]` 可以替换为:
 ```
+milkv-duo
+milkv-duo-python
+milkv-duo256m
+milkv-duo256m-python
+```
+*带 `python` 后缀的版本包含 python，pip, pinpong 库*

 命令中部分参数说明:
 - `duodocker` 运行的 Docker 名字, 与上一步中设置的名字要保持一致
 - `"*"` 双引号中是要在 Docker 镜像中运行的 Shell 命令
 - `cd /home/work` 是切换到 /home/work 目录，由于运行时已经将该目录绑定到主机的代码目录，所以在 Docker 中 /home/work 目录就是该 SDK 的源码目录
 - `cat /etc/issue` 显示 Docker 使用的镜像的版本号，目前是 Ubuntu 22.04.3 LTS，调试用
- `./build_milkv.sh` 执行一键编译脚本
+- `./build.sh [board]` 执行一键编译脚本

-编译成功后可以在 `out` 目录下看到生成的SD卡烧录镜像 `milkv-duo-*-*.img`
+比如需要编译 Duo 带 python 和 pinpong 库的的镜像，编译命令如下:
+```bash
+docker exec -it duodocker /bin/bash -c "cd /home/work && cat /etc/issue && ./build.sh milkv-duo-python"
+```
+
+编译成功后可以在 `out` 目录下看到生成的SD卡烧录镜像 `[board]-*-*.img`

 ### 2. 使用 Docker 分步编译

+如果未执行过一键编译脚本，需要先手动下载工具链 [host-tools](https://sophon-file.sophon.cn/sophon-prod-s3/drive/23/03/07/16/host-tools.tar.gz)，并解压到 SDK 根目录：
+
+```bash
+tar -xf host-tools.tar.gz -C /your/sdk/path/
+```
+
 分步编译需要登陆到 Docker 中进行操作，用命令 `docker ps -a` 查看并记录容器的 ID 号，比如 8edea33c2239。

 登陆到 Docker 中:
-```
+```bash
 docker exec -it 8edea33c2239 /bin/bash
 ```

 进入 Docker 中绑定的代码目录：
-```
+```bash
 root@8edea33c2239:/# cd /home/work/
 ```

-分步编译：
+再依次输入如下命令完成分步编译，命令中的 `[board]` 和 `[config]` 替换为需要编译的版本，当前支持的 `board` 和对应的 `config` 如下：
+```
+milkv-duo               cv1800b_milkv_duo_sd
+milkv-duo-python        cv1800b_milkv_duo_sd
+milkv-duo256m           cv1812cp_milkv_duo256m_sd
+milkv-duo256m-python    cv1812cp_milkv_duo256m_sd
+```
+
 ```bash
-export MILKV_BOARD=milkv-duo
-source milkv/boardconfig-milkv-duo.sh
+source device/[board]/boardconfig.sh
+
+source build/milkvsetup.sh
+defconfig [config]
+clean_all
+build_all
+pack_sd_image
+```
+
+比如需要编译 Duo 带 python, pip 和 pinpong 库的的镜像，分步编译命令如下：
+```bash
+source device/milkv-duo-python/boardconfig.sh

 source build/milkvsetup.sh
 defconfig cv1800b_milkv_duo_sd
@ -165,10 +256,14 @@ build_all
 pack_sd_image
 ```

-生成的固件位置: `install/soc_cv1800b_milkv_duo_sd/milkv-duo.img`。
+生成的固件位置：
+```
+Duo:      install/soc_cv1800b_milkv_duo_sd/[board].img
+Duo256M:  install/soc_cv1812cp_milkv_duo256m_sd/[board].img
+```

 编译完成后可以用 `exit` 命令退出 Docker 环境：
-```
+```bash
 root@8edea33c2239:/home/work# exit
 ```
 在主机代码目录中同样也可以看到生成的固件。
@ -176,12 +271,12 @@ root@8edea33c2239:/home/work# exit
 ### 停用 Docker

 编译完成后，如果不再需要以上的 Docker 运行环境，可先将其停止，再删除:
-```
+```bash
 docker stop 8edea33c2239
 docker rm 8edea33c2239
 ```

-## 其他编译注意事项
+## 三、其他编译注意事项

 如果您想尝试在以上两种环境之外的环境下编译本 SDK，下面是可能需要注意的事项，仅供参考。

@ -197,13 +292,13 @@ cmake --version

 比如在`Ubuntu 20.04`中用 apt 安装的 cmake 版本号为

-```text
+```
 cmake version 3.16.3
 ```

 不满足此SDK最低要求，需要手动安装目前最新的 `3.27.6` 版本

-```
+```bash
 wget https://github.com/Kitware/CMake/releases/download/v3.27.6/cmake-3.27.6-linux-x86_64.sh
 chmod +x cmake-3.27.6-linux-x86_64.sh
 sudo sh cmake-3.27.6-linux-x86_64.sh --skip-license --prefix=/usr/local/
@ -214,6 +309,21 @@ sudo sh cmake-3.27.6-linux-x86_64.sh --skip-license --prefix=/usr/local/
 cmake version 3.27.6
 ```

+### 使用 Windows Linux 子系统 (WSL) 进行编译
+
+如果您希望使用 WSL 执行编译，则构建镜像时会遇到一个小问题，WSL 中的 $PATH 具有 Windows 环境变量，其中路径之间包含一些空格。
+
+要解决此问题，您需要更改 `/etc/wsl.conf` 文件并添加以下行：
+
+```
+[interop]
+appendWindowsPath = false
+```
+
+然后需要使用 `wsl.exe --reboot` 重新启动 WSL。再运行 `./build.sh` 脚本或分步编译命令。
+
+要恢复 `/etc/wsl.conf` 文件中的此更改，请将 `appendWindowsPath` 设置为 `true`。 要重新启动 WSL，您可以使用 Windows PowerShell 命令 `wsl.exe --shutdown`，然后使用`wsl.exe`，之后 Windows 环境变量在 $PATH 中再次可用。
+
 ## SD卡烧录

 > 注意: 将镜像写入 TF 卡会擦除卡中原有数据，记得在烧录前备份重要的数据!!!
@ -264,8 +374,7 @@ mv /mnt/system/blink.sh_backup /mnt/system/blink.sh && sync
 使用底板上的 4 个 USB 口，需要修改一下配置，将默认固件中的 `usb-rndis` 功能修改为 `usb-host`：

 ```bash
-rm /mnt/system/usb.sh
-ln -s /mnt/system/usb-host.sh /mnt/system/usb.sh
+ln -sf /mnt/system/usb-host.sh /mnt/system/usb.sh
 sync
 ```
 修改完，重启或重新上电即可生效。
@ -294,8 +403,7 @@ umount /mnt/udisk
 不使用底板时，恢复 USB 网卡 (RNDIS) 的方法：

 ```bash
-rm /mnt/system/usb.sh
-ln -s /mnt/system/usb-rndis.sh /mnt/system/usb.sh
+ln -sf /mnt/system/usb-rndis.sh /mnt/system/usb.sh
 sync
 ```

@ -305,7 +413,7 @@ sync

 1. 为什么只显示单核?

-   CV1800B 芯片采用双核设计，当前 Linux 系统运行在其中的一个核上，另外一个核用来运行实时系统，这个核的 SDK 尚未公布，待后续更新。
+   CV1800B 芯片采用双核设计，当前 Linux 系统运行在其中的一个核上，另外一个核用来运行实时系统，该核的使用请查看[官方文档](https://milkv.io/zh/docs/duo/getting-started/rtoscore)。

 2. 为什么查看 RAM 只显示 28M?