From 37c0600a58d3d66b46c26086e9e5a4cf1e3c0375 Mon Sep 17 00:00:00 2001 From: zhangxiaowei16 Date: Fri, 6 Feb 2026 16:07:24 +0800 Subject: [PATCH 1/2] Hardware adaptation guide --- README.md | 8 +++ README_zh-cn.md | 8 +++ .../quickstart/openvela_macos_quick_start.md | 67 +++++-------------- 3 files changed, 32 insertions(+), 51 deletions(-) diff --git a/README.md b/README.md index b3b9b7ab..09c659fb 100644 --- a/README.md +++ b/README.md @@ -86,6 +86,14 @@ Below are the currently released stable versions and their change logs: - **trunk-5.2**: Please refer to the [v5.2 Release Notes](./en/release_notes/v5.2.md) for detailed changes. +### Hardware Adaptation Guide + +To maximize efficiency and ensure code stability, we offer the following recommendations for developers performing hardware porting: + +- **Recommended Baseline**: We strongly recommend **basing your development on the latest openvela release version** (i.e., Release Tags on the `trunk` branch). +- **Risk Warning**: The current **`dev` branch** is undergoing rapid iteration with frequent code updates. It may be subject to underlying interface changes or temporary instability. Therefore, it is **NOT recommended** as a baseline for hardware adaptation. +- **Get Support**: If you have adaptation requirements or encounter technical difficulties, please feel free to **submit an Issue** or contact us via the **WeChat Community**. The openvela team is ready to provide the necessary development support. + ### Version Maintenance Strategy openvela follows a strict version maintenance lifecycle: diff --git a/README_zh-cn.md b/README_zh-cn.md index ae402eb5..af8161b7 100644 --- a/README_zh-cn.md +++ b/README_zh-cn.md @@ -87,6 +87,14 @@ Vela 的命名源自拉丁语中船帆的含义，也是南方星空中船帆星 - **trunk-5.2**：请查阅 [v5.2 版本发布说明](./zh-cn/release_notes/v5.2.md) 了解详细变更。 +### 硬件适配特别说明 (Hardware Adaptation Guide) + +为提升适配效率并确保代码稳定性，针对进行硬件移植（Porting）的开发者，我们提供以下建议： + +- **推荐基准**：建议**优先基于 openvela 最新发布版本**（即 `trunk` 上的 Release Tag）进行硬件适配开发。 +- **风险提示**：当前 **`dev` 分支** 处于快速迭代期，代码更新较为频繁，可能存在底层接口变动或临时性问题，**不推荐**作为硬件适配的基准代码。 +- **获取支持**：如有适配需求或在过程中遇到技术疑问，欢迎**提交 Issue** 或者通过**微信社区**与我们取得联系，openvela 团队将提供必要的开发支持。 + ### 版本维护策略 openvela 遵循严格的版本维护生命周期： diff --git a/zh-cn/quickstart/openvela_macos_quick_start.md b/zh-cn/quickstart/openvela_macos_quick_start.md index 96a9788f..8c42cd72 100644 --- a/zh-cn/quickstart/openvela_macos_quick_start.md +++ b/zh-cn/quickstart/openvela_macos_quick_start.md @@ -164,56 +164,23 @@ sudo mv repo /usr/local/bin repo sync -c -j8 ``` -## 步骤三：编译源代码 - -完成源代码下载后，请在 openvela 根目录下执行以下编译步骤。 - -### 1. 设置环境变量 - -执行以下命令，将预编译的工具链路径添加到当前终端会话的环境变量中。 - -```Bash -uname_s=$(uname -s | tr '[A-Z]' '[a-z]') -uname_m=$(uname -m | sed 's/arm64/aarch64/g') -export PATH=$PWD/prebuilts/build-tools/${uname_s}-${uname_m}/bin:$PATH -export PATH=$PWD/prebuilts/cmake/${uname_s}-${uname_m}/bin:$PATH -export PATH=$PWD/prebuilts/python/${uname_s}-${uname_m}/bin:$PATH -export PATH=$PWD/prebuilts/gcc/${uname_s}-${uname_m}/aarch64-none-elf/bin:$PATH -export PATH=$PWD/prebuilts/gcc/${uname_s}-${uname_m}/arm-none-eabi/bin:$PATH -export PYTHONPATH=$PWD/prebuilts/tools/python/dist-packages/cxxfilt -export PYTHONPATH=$PWD/prebuilts/tools/python/dist-packages/kconfiglib:$PYTHONPATH -export PYTHONPATH=$PWD/prebuilts/tools/python/dist-packages/pyelftools:$PYTHONPATH -``` - -> **注意**： 此环境变量配置仅在当前终端窗口有效。若新开终端，需重新执行此脚本。 + ![alt text](./figures/004.png) -### 2. 配置 CMake 项目 (Out-of-Tree) + > **操作提示** + > + > - 首次同步耗时较长，具体时间取决于您的网络状况和磁盘性能。 + > - 若因网络问题中断，可重复执行 `repo sync` 进行增量同步。 -openvela 采用 **Out-of-tree build** 模式，该模式将编译产物与源代码分离，以保持源码目录的整洁。 - -运行以下 `cmake` 命令来配置项目。此命令将： - -- 在 `cmake_out/goldfish-arm64-v8a-ap` 目录下生成构建系统文件。 -- 使用 Ninja 作为构建工具以提升编译速度。 -- 指定目标板的配置文件。 - -```Bash -cmake \ - -B cmake_out/goldfish-arm64-v8a-ap \ - -S $PWD/nuttx \ - -GNinja \ - -DBOARD_CONFIG=../vendor/openvela/boards/vela/configs/goldfish-arm64-v8a-ap \ - -DEXTRA_FLAGS="-Wno-cpp -Wno-deprecated-declarations" -``` +## 步骤三：编译源代码 -![alt text](./figures/005.png) +完成源代码下载后，请在 openvela 根目录下执行以下编译步骤。 -### 3.（可选）自定义内核配置 +### 1. （可选）自定义内核配置 您可以通过 `menuconfig` 命令打开图形化界面，以调整 NuttX 内核与组件的配置。 ```Bash -cmake --build cmake_out/goldfish-arm64-v8a-ap -t menuconfig +./build.sh vendor/openvela/boards/vela/configs/goldfish-arm64-v8a-ap/ --cmake menuconfig ``` > **操作技巧** @@ -222,33 +189,31 @@ cmake --build cmake_out/goldfish-arm64-v8a-ap -t menuconfig > - 按 `空格键` 可切换选中状态（启用/禁用/模块化）。 > - 配置完成后，选择 **Save** 保存并退出。 -![alt text](./figures/006.png) + -### 4. 执行编译 +### 2. 执行编译 执行以下命令，构建整个项目。 ```Bash -cmake --build cmake_out/goldfish-arm64-v8a-ap +./build.sh vendor/openvela/boards/vela/configs/goldfish-arm64-v8a-ap/ --cmake -j$(nproc) ``` -编译成功后，您将在 `cmake_out/goldfish-arm64-v8a-ap` 目录下找到 `nuttx` 等编译产物。 +编译成功后，您将在 `cmake_out/vela_goldfish-arm64-v8a-ap` 目录下找到 `nuttx` 等编译产物。 -![alt text](./figures/007.png) + ## 步骤四：运行模拟器 在 openvela 根目录下，执行以下脚本启动 `Vela Emulator` 并加载您的编译产物。 ```Bash -./emulator.sh cmake_out/goldfish-arm64-v8a-ap +./emulator.sh cmake_out/vela_goldfish-arm64-v8a-ap/ ``` 模拟器启动后，您将看到 `goldfish-armv8a-ap>` 提示符，表明 openvela 已成功运行。 -![alt text](./figures/008.png) - -![alt text](./figures/009.png) + ## 后续步骤 From f9063141ea90c4391d99d777255bb49b75f9d21a Mon Sep 17 00:00:00 2001 From: zhangxiaowei16 Date: Fri, 6 Feb 2026 16:10:28 +0800 Subject: [PATCH 2/2] Hardware adaptation guide --- en/quickstart/openvela_macos_quick_start.md | 108 +++++++------------- 1 file changed, 37 insertions(+), 71 deletions(-) diff --git a/en/quickstart/openvela_macos_quick_start.md b/en/quickstart/openvela_macos_quick_start.md index e4b0be0f..4eda8732 100644 --- a/en/quickstart/openvela_macos_quick_start.md +++ b/en/quickstart/openvela_macos_quick_start.md @@ -117,13 +117,13 @@ After installation, you can run `repo --version` to verify it. This method requires you to add your SSH public key to your GitHub account first. Please refer to the [official GitHub documentation](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/adding-a-new-ssh-key-to-your-github-account). ```bash - repo init -u ssh://git@github.com/open-vela/manifests.git -b trunk -m openvela.xml + repo init -u ssh://git@github.com/open-vela/manifests.git -b trunk -m openvela.xml --git-lfs ``` - Method 2: HTTPS ```bash - repo init -u https://github.com/open-vela/manifests.git -b trunk -m openvela.xml + repo init -u https://github.com/open-vela/manifests.git -b trunk -m openvela.xml --git-lfs ``` #### Option B: Download from Gitee @@ -133,13 +133,13 @@ After installation, you can run `repo --version` to verify it. This method requires you to add your SSH public key to your Gitee account first. Please refer to the [official Gitee documentation](https://gitee.com/help/articles/4191). ```bash - repo init --u ssh://git@gitee.com/open-vela/manifests.git -b trunk -m openvela.xml --repo-url=https://mirrors.tuna.tsinghua.edu.cn/git/git-repo/ + repo init --u ssh://git@gitee.com/open-vela/manifests.git -b trunk -m openvela.xml --repo-url=https://mirrors.tuna.tsinghua.edu.cn/git/git-repo/ --git-lfs ``` - Method 2: HTTPS ```bash - repo init -u https://gitee.com/open-vela/manifests.git -b trunk -m openvela.xml --repo-url=https://mirrors.tuna.tsinghua.edu.cn/git/git-repo/ + repo init -u https://gitee.com/open-vela/manifests.git -b trunk -m openvela.xml --repo-url=https://mirrors.tuna.tsinghua.edu.cn/git/git-repo/ --git-lfs ``` #### Option C: Download from GitCode @@ -149,115 +149,81 @@ After installation, you can run `repo --version` to verify it. This method requires you to add your SSH public key to your GitCode account first. Please refer to the [official GitCode documentation](https://docs.gitcode.com/docs/help/home/user_center/security_management/ssh). ```bash - repo init -u ssh://git@gitcode.com/open-vela/manifests.git -b trunk -m openvela.xml --repo-url=https://mirrors.tuna.tsinghua.edu.cn/git/git-repo/ + repo init -u ssh://git@gitcode.com/open-vela/manifests.git -b trunk -m openvela.xml --repo-url=https://mirrors.tuna.tsinghua.edu.cn/git/git-repo/ --git-lfs ``` - Method 2: HTTPS ```bash - repo init -u https://gitcode.com/open-vela/manifests.git -b trunk -m openvela.xml --repo-url=https://mirrors.tuna.tsinghua.edu.cn/git/git-repo/ + repo init -u https://gitcode.com/open-vela/manifests.git -b trunk -m openvela.xml --repo-url=https://mirrors.tuna.tsinghua.edu.cn/git/git-repo/ --git-lfs ``` -3. Run the sync command. `repo` will download all relevant source code repositories according to the manifest file (`openvela.xml`). +3. Execute the sync command. `repo` will download all related source code repositories according to the manifest file (`openvela.xml`). - ```Bash + ```bash repo sync -c -j8 ``` -## Step 3: Compile the Source Code - -After downloading the source code, perform the following build steps in the openvela root directory. - -### 1. Set Up Environment Variables - -Run the following commands to add the prebuilt toolchain paths to the environment variables for the current terminal session. - -```Bash -uname_s=$(uname -s | tr '[A-Z]' '[a-z]') -uname_m=$(uname -m | sed 's/arm64/aarch64/g') -export PATH=$PWD/prebuilts/build-tools/${uname_s}-${uname_m}/bin:$PATH -export PATH=$PWD/prebuilts/cmake/${uname_s}-${uname_m}/bin:$PATH -export PATH=$PWD/prebuilts/python/${uname_s}-${uname_m}/bin:$PATH -export PATH=$PWD/prebuilts/gcc/${uname_s}-${uname_m}/aarch64-none-elf/bin:$PATH -export PATH=$PWD/prebuilts/gcc/${uname_s}-${uname_m}/arm-none-eabi/bin:$PATH -export PYTHONPATH=$PWD/prebuilts/tools/python/dist-packages/cxxfilt -export PYTHONPATH=$PWD/prebuilts/tools/python/dist-packages/kconfiglib:$PYTHONPATH -export PYTHONPATH=$PWD/prebuilts/tools/python/dist-packages/pyelftools:$PYTHONPATH -``` - -> **Note**: This environment variable configuration is only valid for the current terminal window. If you open a new terminal, you must run this script again. - -### 2. Configure the CMake Project (Out-of-Tree) + ![alt text](./figures/004.png) -openvela uses an **Out-of-tree build** approach, which separates the build artifacts from the source code to keep the source directory clean. + > **Tip** + > + > - The initial sync can be time-consuming, depending on your network connection and disk performance. + > - If the sync is interrupted due to network issues, you can run `repo sync` again to resume. -Run the following `cmake` command to configure the project. This command will: +## Step 3: Compile Source Code -- Generate the build system files in the `cmake_out/goldfish-arm64-v8a-ap` directory. -- Use Ninja as the build tool to improve compilation speed. -- Specify the configuration file for the target board. +After downloading the source code, execute the following compilation steps in the openvela root directory. -```Bash -cmake \ - -B cmake_out/goldfish-arm64-v8a-ap \ - -S $PWD/nuttx \ - -GNinja \ - -DBOARD_CONFIG=../vendor/openvela/boards/vela/configs/goldfish-arm64-v8a-ap \ - -DEXTRA_FLAGS="-Wno-cpp -Wno-deprecated-declarations" -``` +### 1. (Optional) Custom Kernel Configuration -![alt text](./figures/005.png) - -### 3. (Optional) Customize Kernel Configuration - -You can use the `menuconfig` command to open a graphical interface for adjusting the NuttX kernel and component configurations. +You can use the `menuconfig` command to open a graphical interface to adjust the NuttX kernel and component configurations. ```Bash -cmake --build cmake_out/goldfish-arm64-v8a-ap -t menuconfig +./build.sh vendor/openvela/boards/vela/configs/goldfish-arm64-v8a-ap/ --cmake menuconfig ``` -> **Tips** +> **Operation Tricks** > -> - Press `/` to search for a configuration item. -> - Press the `Spacebar` to toggle the selection state (enable/disable/modularize). -> - After configuring, select **Save** to save and exit. +> - Press `/` to search for configuration items. +> - Press `Space` to toggle selection status (Enable/Disable/Modularize). +> - After configuration, select **Save** to save and exit. -![alt text](./figures/006.png) + -### 4. Run the Build +### 2. Execute Compilation -Run the following command to build the entire project. +Execute the following command to build the entire project. ```Bash -cmake --build cmake_out/goldfish-arm64-v8a-ap +./build.sh vendor/openvela/boards/vela/configs/goldfish-arm64-v8a-ap/ --cmake -j$(nproc) ``` -After a successful build, you will find `nuttx` and other build artifacts in the `cmake_out/goldfish-arm64-v8a-ap` directory. +Upon successful compilation, you will find build artifacts such as `nuttx` in the `cmake_out/vela_goldfish-arm64-v8a-ap` directory. -![alt text](./figures/007.png) + -## Step 4: Run the Emulator +## Step 4: Run Emulator -In the openvela root directory, run the following script to start the `Vela Emulator` and load your build artifacts. +In the openvela root directory, execute the following script to start the `Vela Emulator` and load your build artifacts. ```Bash -./emulator.sh cmake_out/goldfish-arm64-v8a-ap +./emulator.sh cmake_out/vela_goldfish-arm64-v8a-ap/ ``` -After the emulator starts, you will see the `goldfish-armv8a-ap>` prompt, indicating that openvela is running successfully. - -![alt text](./figures/008.png) +After the emulator starts, you will see the `goldfish-armv8a-ap>` prompt, indicating that openvela has run successfully. -![alt text](./figures/009.png) + ## Next Steps - Frequently Asked Questions - [Quick Start FAQ](../faq/QuickStart_FAQ.md) + - [Developer FAQ](../faq/QuickStart_FAQ.md) - Further Reading - - [Debugging with the Emulator](./emulator/Debugging_Vela_with_Vela_Emulator.md) - - [ADB Commands](./emulator/Android_Debug_Bridge_commands.md) - - [Sending Emulator Console Commands](./emulator/Send_emulator_console_commands.md) + - [Debugging Vela with the Vela Emulator](./emulator/Debugging_Vela_with_Vela_Emulator.md) + - [Android Debug Bridge commands](./emulator/Android_Debug_Bridge_commands.md) + - [Send emulator console commands](./emulator/Send_emulator_console_commands.md) \ No newline at end of file