编译和烧录

概述

本章介绍如何搭建 GCC 编译环境，包括 Windows 平台和 Linux 平台。

  • Windows 平台：以 Windows 10 64-bit 为例

  • Linux 平台：以 Ubuntu 22.04 x86_64 为例

环境准备

准备 GCC 编译环境

所需的软件及其版本要求如下表所示：

软件

版本

cmake

3.20 及以上

ninja

1.10.1 及以上

make

3.82 及以上

ccache

4.5.1 及以上

Python3

建议 3.10 及以上

wget

推荐最新版

7zip

推荐最新版

如果用户手动将以上软件安装到操作系统，可能会污染原有的软件环境，或者产生版本兼容问题。

为此，Realtek 提供了一个 软件包合集 ，包含了所需的软件工具，支持在独立环境中运行。

配置软件包后，Ameba SDK 开发环境将被隔离在当前终端中。该终端之外的软件环境不受任何影响，同时也避免了软件版本兼容性问题。

下面将分别介绍在 Linux 和 Windows 中配置软件环境的详细步骤。

  1. 下载压缩包并解压至 /opt/rtk-toolchain 文件夹下

    mkdir /opt/rtk-toolchain
cd /opt/rtk-toolchain
wget https://github.com/Ameba-AIoT/ameba-toolchain/releases/download/prebuilts-v1.0.3/prebuilts-linux-1.0.3.tar.gz
tar -xzf prebuilts-linux-1.0.3.tar.gz

    如果下载遇到问题，可尝试使用 aliyun 地址：

    wget https://rs-wn.oss-cn-shanghai.aliyuncs.com/prebuilts-linux-1.0.3.tar.gz

    备注

    压缩包需要解压到默认的 /opt/rtk-toolchain 路径下。如需更改默认路径，请参考 更改工具链安装路径。

  2. 预安装 Python（Linux 下不提供 Python 的免安装版本）

    sudo apt install python3 python3-pip python3-venv

    备注

    • 运行 python --version 检查 Python 版本， 建议大于 3.10。

    • 如果提示 pip 版本落后，建议通过 pip install --upgrade pip 命令更新版本。

    • 如果主机中存在多个 Python 版本，可以使用命令 update-alternatives --install /usr/bin/python python /usr/bin/python3.x 1 选择特定 Python 版本，x 代表期望的版本号。

    • 如果报错 command 'python' not found，尝试运行 ln -s /usr/bin/python3 /usr/bin/python 解决问题。

  3. 安装依赖库

    sudo apt install libssl-dev libncurses-dev

  4. 进入 SDK 根目录，运行 env.sh 脚本，自动配置环境变量。

    source env.sh

PIP CHECK... All packages are installed correctly!
================================================================================
|  Setup complete. The Ameba SDK is now ready for use.
|  Go to the project root directory and run ameba.py
|  Usage:      ameba.py [COMMAND] [ARGS]
|  Build:      ameba.py build
|  Select SoC: ameba.py soc
|  Help:       ameba.py help
================================================================================
(.venv)

备注

每次重启终端后，都需要执行 source env.sh 命令设置环境变量。

安装工具链 (TODO)

交叉编译工具链的安装和更新是自动完成的。

首次编译某个 SOC 项目时，所需的工具链会被自动安装到如下默认路径：

  • Linux：/opt/rtk-toolchain

  • Windows：C:\rtk-toolchain

需要注意的是，不同的 MCU 可能使用不同版本的工具链。之后每次执行编译时，都会自动检查并更新。

如果弹出报错信息，请根据报错信息修复问题并尝试重新编译。

安装完成后，在 rtk-toolchain 路径下将有以下文件：

|--- prebuilts-[win/linux]-1.x.x
|
|--- asdk-1x.3.1-xxxx     # for ARM
|
|--- [vsdk-10.3.1-xxxx]   # for RISC-V (if required)

备注

  • 如果已有下载好的工具链压缩包，可以将压缩包移动到安装路径后，再次执行 ameba.py build。

  • 如果报错 Download Failed, 请检查网络连接。如果问题仍然存在，请参考 更换下载源。

  • 如果报错 Create Toolchain Dir Failed. May Not Have Permission，请尝试手动创建文件夹。如果问题仍然存在，请参考 更改安装路径 。

备用下载源

工具链压缩包默认托管在 GitHub 上，系统默认从 GitHub 下载工具链压缩包。如果下载遇到问题，或者下载速度缓慢，请尝试通过以下命令更换下载源：

ameba.py build -D USE_ALIYUN_URL=True

执行此命令后，将会从 aliyun 下载工具链，然后开始编译。

自定义安装路径

如果不希望工具链被安装在上述的默认路径，通过设置环境变量 RTK_TOOLCHAIN_DIR 可以自定义安装路径，设置方法如下：

  1. 打开 ~/.bashrc 文件，在其末尾添加：

    export RTK_TOOLCHAIN_DIR="/path/to/your/toolchain/dir"

  2. 运行以下命令使环境变量立即生效：

    source ~/.bashrc

修改安装路径后，请将 Realtek 软件包解压到该目录；交叉编译工具链将在执行编译时被自动安装到该目录。

安装 Python 依赖项

运行以下命令创建 python 虚拟环境并安装 Python 依赖项：

./nuwa.py setup

创建应用程序

SDK 采用 CMake 作为编译系统。该编译系统以应用程序为中心，将应用程序代码与 Zephyr 内核源代码编译成一个统一的二进制文件。主要包括两部分：

  • Zephyr 基本目录：包含 Zephyr 自己的源代码、内核配置选项和编译定义。

  • 应用程序目录：包含所有指定用于应用程序的文件，例如配置选项和源代码。

一个典型的应用程序目录结构如下：

<app>
├── CMakeLists.txt     编译入口脚本，链接 Zephyr 编译系统
├── app.overlay        应用专属 Kconfig 配置文件
├── prj.conf           设备树覆盖文件（可选）
├── VERSION            版本标识文件（可选）
└── src
    └── main.c         应用主程序源文件

编译应用程序

Zephyr 编译系统将应用程序的所有组件编译并链接到单个应用程序固件中，该固件可以在模拟硬件或真实硬件上运行。

与任何其他基于 CMake 的系统一样，编译过程分 两个阶段 进行。

  • 配置阶段（Configuration Phase）：在指定生成器时使用 cmake 命令行工具生成编译文件，但是 zephyr 还包括：

    • 基于 DTS 内容和 YAML 绑定，生成 build/zephyr/zephyr.dts 和 build/zephyr/include/generated/devicetree_generated.h

    • 收集所有 Kconfig 文件，加载默认配置，并结合 DTS 的输出，确定最终的配置选项集合和依赖关系，生成 build/zephyr/.config 和 build/zephyr/include/generated/autoconf.h

    • 生成编译系统文件，生成 CMakeCache.txt 和 build.ninja

  • 编译阶段（Build Phase）：使用本地编译工具（如 ninja）执行实际编译并链接生成固件。要了解有关这些概念的更多信息，请参阅 CMake 官方文档中的 CMake 介绍 。

编译命令

使用以下命令编译应用程序：

./nuwa.py build -d <device> -a <application> [-p]

参数说明：

  • build：执行 build 子命令；

  • -b BUILD_DIR：可选，设置 build 输出文件目录，所有编译过程中生成的文件均存此目录中，目录名可以任意指定；

  • -d <device>：指定目标开发板（如 rtl872xda_evb，编译工具链会自动从 zephyr/boards/realtek/rtl8721f_evb 目录下搜索需要的 board 配置文件）；

  • -a <application>：指定应用程序路径（相对 SDK 根目录）；

  • -p：重新编译（Rebuild），如果 build 目录中存在之前编译的信息，若不指定 -p 参数，则执行默认的增量编译操作，否则将执行重新编译操作；

示例：编译 Hello World 示例

./nuwa.py build -d rtl872xda_evb -a zephyr/samples/hello_world

部分清理（Clean）

删除 Build Phase 下生成的文件（如 .obj/.elf/.hex 等），但保留 Configuration Phase 下生成的配置文件（如 .config 文件等）：

west build -t clean 或者 ./nuwa.py build -c

完整清理（Pristine）

同时删除 Build Phase 与 Configuration Phase 下生成的文件：

west build -t pristine 或者 ./nuwa.py build -p

打开 Menu Config 菜单

menuconfig 是编译过程的一部分，依赖于配置阶段生成的编译系统中间文件，如果 build 目录为空时，则无法启动 menuconfig（因为此时编译系统不知道具体的应用程序目录）：

west build -t menuconfig 或者 ./nuwa.py config

build 目录内容

默认情况下，build 目录结构如下：

SDK/build
├── amebaxxx_gcc_project       多个 MCU bin 拼接的中间过程文件
├── build.ninja                Ninja 编译脚本（自动生成）
├── CMakeCache.txt             CMake 缓存配置
├── CMakeFiles                 CMake 中间文件
├── cmake_install.cmake        安装脚本（通常不使用）
├── rules.ninja                Ninja 规则定义
└── zephyr                     用于生成编译系统的工作目录，大部分生成的文件都是在其中创建和存储的。

运行 ninja 后，以下编译输出文件将被写入 build 目录的 zephyr 子目录。

  • .config ，包含用于编译应用程序的配置设置。

  • 包含已编译内核和应用程序代码的各种目标文件（ .o 文件和 .a 文件）。

  • zephyr.elf ，其中包含最终组合的应用程序和内核二进制文件。还支持其他二进制输出格式，例如 .hex 和 .bin 。

images 目录和固件下载

使用 .nuwa.py 编译完成后，供 ImageTool 下载的固件将放置在 SDK/images 目录下。 然后使用 ImageTool 进行固件下载，工具位于： SDK/tools/ameba/ImageTool 目录下，请参考 Image Tool 使用指南进行烧录。

west 编译烧录方法介绍

west build 用法介绍

需要添加两个环境变量（需要检查环境有没有配置，如果没有需要添加）：

export ZEPHYR_TOOLCHAIN_VARIANT='gnuarmemb'
export GNUARMEMB_TOOLCHAIN_PATH=/opt/rtk-toolchain/asdk-12.3.1/linux/newlib

常用命令示例：

west build -b <BOARD> path/to/build/directory //编译某个板型的某个工程
west build -t pristine                        //纯净编译，删除编译目录中的所有文件

west flash 用法介绍

Windows 电脑通过串口线连接开发板，Linux 服务器远程烧录。

  1. 在 window 电脑下载并打开 AmebaSerialServer_v1.0.2 (可在白名单软件网站下载);

  2. 使用串口线连接 windows 电脑和开发板，并按键进入下载模式；

  3. 在 Linux 服务器上执行命令，其中 ip 是 windows 电脑的 ip ：

    west flash --port port --remote-server ip

备注

  • 如果开发板中的固件在编译时打开了 CONFIG_SHELL 配置， 则可以识别 flash 下载前自动给开发板发送的命令进入烧录模式，就不需要手动按按键进入烧录模式了。