Skip to content

Hardware adaptation guide #460

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
tanghao-xiaomi merged 2 commits into from
Feb 6, 2026
Merged

Hardware adaptation guide #460

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
37c0600
Hardware adaptation guide
tanghao-xiaomi Feb 6, 2026
f906314
Hardware adaptation guide
tanghao-xiaomi Feb 6, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 8 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down
8 changes: 8 additions & 0 deletions README_zh-cn.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 遵循严格的版本维护生命周期：
Expand Down
108 changes: 37 additions & 71 deletions en/quickstart/openvela_macos_quick_start.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Expand All @@ -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)
<img src="./figures/006.png" alt="" width="75%">

### 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)
<img src="./figures/007.png" alt="" width="75%">

## 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)
<img src="./figures/008.png" alt="" width="75%">

## 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)
67 changes: 16 additions & 51 deletions zh-cn/quickstart/openvela_macos_quick_start.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
```

> **操作技巧**
Expand All @@ -222,33 +189,31 @@ cmake --build cmake_out/goldfish-arm64-v8a-ap -t menuconfig
> - 按 `空格键` 可切换选中状态（启用/禁用/模块化）。
> - 配置完成后，选择 **Save** 保存并退出。

![alt text](./figures/006.png)
<img src="./figures/006.png" alt="" width="75%">

### 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)
<img src="./figures/007.png" alt="" width="75%">

## 步骤四：运行模拟器

在 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)
<img src="./figures/008.png" alt="" width="75%">

## 后续步骤

Expand Down