构建系统与配置¶

FreeRTOS 应用由 make 驱动 CMake 构建。应用的 .config 列出所有 CONFIG_* 配置项，构建时转换成 C 头文件 autoconf.h，并据此决定要编译哪些组件。本页说明这套流程与 Reef 各组配置的构建方式；Zephyr 使用 west 构建，见 Zephyr RTOS。

构建流程¶

flowchart LR
  A[".config 或 defconfig_*"] --> B["project.build（make）"]
  B --> C["CMake 配置<br/>生成 autoconf.h"]
  C --> D["编译与链接<br/>make -j4"]
  D --> E["&lt;应用&gt;_IPRO7.elf"]
  E --> F["&lt;应用&gt;_IPRO7.bin"]

所有命令都在 SDK 根目录运行：

make -C apps/platform/ipro7ai_reef_demo          # 构建出厂固件
make -C apps/platform/ipro7ai_reef_demo clean    # 删除 build/
./build_freertos.sh -l                           # 按分类列出全部应用
./build_freertos.sh build ipro7ai_reef_demo      # 按应用名称构建，日志写入 build/build.log

构建时依次发生：

1. 应用的 Makefile 调用 make -C <SDK> -f project.build PROJECT_PATH=<应用目录>。项目名称取自应用目录名称。
2. project.build 从配置文件读取 CONFIG_CPU_ID 与 CONFIG_CROSS_COMPILE，并查找 CMake：先用 PATH 中的 cmake，再用随附的 tools/cmake/（CMake 3.15，仅 Linux x86-64）。两者都没有时以 No cmake found 停止。
3. CMake 以 Unix Makefiles 生成器配置构建目录，由 cmake/generate_autoconf.cmake 根据配置文件写出 include/generated/autoconf.h，再加入 bsp/、components/ 与应用目录。
4. make -j4 编译与链接。多数 SDK 组件库以 -Werror 编译，其中任何警告都会让构建停止。链接器在结尾打印各内存区域的用量，objcopy 生成 .bin。
5. compile_commands.json 复制到 SDK 根目录，供编辑器的代码索引使用。

CMake 开始前，构建会打印 [INFO] Build Path: <目录> 与 CPU: intelpro_ipro7，可以确认所用的目录与工具链目标。

工具链前缀¶

编译器前缀按以下顺序取第一个已设置的来源：

1. 环境变量或 make 命令行中的 CROSS_COMPILE：make -C <应用> CROSS_COMPILE=<目录>/bin/riscv64-unknown-elf-。
2. 配置文件中的 CONFIG_CROSS_COMPILE。多数随附配置写的是 /opt/toolchain/riscv_ipro7/bin/riscv64-unknown-elf-。
3. /opt/toolchain/riscv_ipro7/bin/riscv64-unknown-elf-（不适用于 Windows）。

cmake/toolchain.cmake 只在前缀后面接上 gcc、g++、ld 与 objcopy，不会另外搜索路径。接着它试编译 DSP 扩展指令：编译器接受时加上 DSP 编译选项，否则改用标准 GCC 的编译选项。

发布包记载的构建主机是 macOS 与 Linux（bash）。project.build 虽有 Windows 分支（用 python 解析配置文件、使用 PATH 中的 cmake），但在 Windows 上不设默认前缀，必须自行提供 CROSS_COMPILE；build_freertos.sh 与 tools/serial_monitor.py 需要 POSIX shell。

输出文件¶

位于 build/build_out/（替代配置则是 build_<名称>/build_out/）：

<CHIP> 是 CONFIG_CHIP 的值：所有 IPRO7 与 IPRO7AI 配置（包括 Reef）为 IPRO7，ipro6_demo、ipro6_if_wifi 与 ipro6_fmac 为 IPRO6。build_freertos.sh 的其他操作与选项见工具命令行。

配置文件 .config¶

.config 每行一个配置项，格式与 Linux kernel 相同。构建时的转换规则：

每个配置项也会以 -D 传给编译器，并设为同名的 CMake 变量，应用的 CMakeLists.txt 可以直接写 if(CONFIG_SHELL)。

选项的说明位于根目录 Kconfig、bsp/Kconfig、components/**/Kconfig 与部分应用的 Kconfig 中，但构建只读取配置文件，不会解析 Kconfig。因此：

• select 不会生效。例如 CONFIG_IPRO7AI_REEF 与 CONFIG_MM_SUPPORT 在 Kconfig 中 select USE_PSRAM，配置文件仍要明确写出 CONFIG_USE_PSRAM=y。
• Kconfig 的默认值不会生效。配置文件没写的选项就是未设置。
• 只有一个默认值由构建补上：Reef 的配置文件中没有 CONFIG_IPRO7_XTAL_CAPCODE 时，bsp/board/ipro7/CMakeLists.txt 会加上 -DCONFIG_IPRO7_XTAL_CAPCODE=95，并打印 [board] IPRO7AI Reef: CONFIG_IPRO7_XTAL_CAPCODE=95 (board default)。配置文件中明确写出的值优先；0 表示沿用芯片启动时的值。这是编译器定义，不会出现在 autoconf.h 中。
• 新的配置请从最接近的随附配置复制后再修改，不要从空白文件开始。

板型配置¶

板型配置项通过 board_config.h 决定使用 bsp/board/ipro7/ 中的哪个板级头文件，只能设置一个。board_config.h 按固定顺序判断，CONFIG_EVB／CONFIG_DVK 与 CONFIG_IPRO7AI_EVK 都排在 CONFIG_IPRO7AI_REEF 之前：同时设置了 CONFIG_EVB=y 与 CONFIG_IPRO7AI_REEF=y 的配置会构建成 IPRO7 EVB 版本，而且不会有任何提示。

所有随附的 Reef 配置都设置了 CONFIG_IPRO7AI_REEF=y 与 CONFIG_BOARD="IPRO7AI_REEF"，没有其他板型配置项。

常用配置项¶

构建后，构建目录下的 include/generated/autoconf.h 就是实际生效的值。以 make -C apps/bluetooth/ble/ipro_ble_remote DEFCONFIG=defconfig_reef 为例：

#define CONFIG_IPRO7 1
#define CONFIG_CHIP "IPRO7"
#define CONFIG_IPRO7AI_REEF 1
#define CONFIG_BOARD "IPRO7AI_REEF"
#define CONFIG_IPRO7_FLASH_2M 1
/* CONFIG_EASYFLASH4 is not set */
#undef CONFIG_EASYFLASH4
#define CONFIG_IPRO_BLE_REMOTE_OTA 1
#define CONFIG_IPRO_BLE_CTLR_LIB "link1_periph"
#define CONFIG_EM_SIZE 16

配置工具¶

替代配置¶

支持多种开发板或功能的应用会附带多个配置文件。选用其中一个即可，不必改动 .config：

• DEFCONFIG= 把指定文件复制成 build_<名称>/.config 再构建。<名称> 是文件名去掉 defconfig_ 前缀与扩展名：defconfig_reef_ov5640 输出到 build_reef_ov5640/，config_evk 输出到 build_config_evk/。
• 输出文件名不变，同样是 <应用>_IPRO7.bin，位于 build_<名称>/build_out/。
• BOARD= 只有两个 Makefile 实现：ipro_agora_sentino（默认 reef，即 .config；BOARD=evk 选用 config_evk）与 ipro_pdm_mic_demo（IPRO7 EVB／IPRO7AI EVK 的应用），其他应用会忽略它。build_freertos.sh 没有 BOARD 选项，请用 -d 指定配置文件。
• make clean 的行为取决于应用的 Makefile。把 clean 交给 project.build 的应用（ipro_ble_remote、ipro_throughput_test、ipro_le_audio_headset、ipro7_uvc_cam、ipro_agora_sentino），make clean DEFCONFIG=<文件名> 会删除 build_<名称>/；ipro7ai_reef_demo、ipro_reef_teach 与 ipro_ai_link 只删除 build/，ipro7_jpeg_decode 删除 build/ 与所有 build_*/。其他构建目录请自行删除。
• 命令行中的 -j N 或 build_freertos.sh -j N 只作用于外层 make；实际编译固定以 -j4 执行。

本版本的 Reef 配置：

ipro_ble_remote、ipro_throughput_test、ipro_le_audio_headset、ipro7_uvc_cam、ipro_ai_link 与 ipro7_jpeg_decode 直接 make 会构建成其他开发板的版本；在 Reef 上一律指定 Reef 的配置文件。除了 ipro_throughput_test/defconfig_reef，所有 Reef 配置都设置了 CONFIG_USE_PSRAM=y。各配置的烧录方式（包括分区表、boot2 与 mfg 数据）见示例与应用的 README。

内存布局¶

OCRAM 可用大小随配置而变：

AI 与图像同时开启时，NPU 会占用 OCRAM 的高地址区段，再加上 BLE 的 Exchange Memory，OCRAM 就很紧张；三者都需要的应用，可能得拆成不同的配置。

• Flash 链接大小不可超过板上实际容量，默认 1 MB 是为了避免镜像在不知不觉中超出物理 Flash。Reef 的 IPRO7AI 内封 2 MB Flash（见 IPRO7AI Reef EVK），上表中的 Reef 配置分别按 1 MB 或 2 MB 链接。ipro7ai_reef_demo 的 .config 注明 1 MB 布局适用于两种内封 Flash，加上 CONFIG_IPRO7_FLASH_2M=y 可让链接器使用整颗 Flash。
• 按 2 MB 链接不会加大固件分区：镜像仍要放得进烧录时所用分区表的固件区（partition_cfg_2M.toml 为 1180 KB）。
• 链接脚本由 bsp/board/linker/ 生成（模板 ipro7/ipro7_common.ld.in，内存参数在 configs/ipro7_flash.cmake 中）。应用目录下有 <应用>.ld（例如 ipro7_uvc_cam.ld），或配置文件设置了 CONFIG_LINKER_SCRIPT="<文件名>" 时，改用该链接脚本，Flash 大小配置项也就不再适用。
• 构建结尾打印的内存用量是判断能否放得下的依据。

应用结构¶

apps/<分类>/<应用>/
├── .config            构建配置（必需）
├── Makefile           调用 SDK 根目录的 project.build
├── CMakeLists.txt     源文件、include 路径与 setup_project()
├── main.c             入口
├── Kconfig            （可选）应用专属选项的说明
├── defconfig_*        （可选）替代配置
├── <应用>.ld          （可选）应用自带的链接脚本
├── src/  include/
└── build/             构建输出（自动生成）
    ├── include/generated/autoconf.h
    └── build_out/<应用>_IPRO7.{elf,bin,map}

应用的 CMakeLists.txt 不需要 cmake_minimum_required() 或 project()，直接使用 SDK 的构建宏：

在 CMakeLists.txt 中使用 if(CONFIG_…)，可以只在需要的配置中加入源文件。出厂固件就是这样加入 Wi-Fi 与 RTSP 的源文件，同一个目录同时构建 .config 与 defconfig_wifi_ipro6s：

# Wi-Fi through the IPRO6S_FIN in CARD1 (ipronet_host over SDIO).
if(CONFIG_WIFI_USE_IPRO6S)
    target_sources(app PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/src/wifi_ipro6s.c)
    ...
endif()

# RTSP MJPEG camera stream over that Wi-Fi; camera ch0 at sensor / 2.
if(CONFIG_WIFI_USE_IPRO6S AND CONFIG_RTSP_SERVER)
    target_sources(app PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/src/wifi_rtsp.c)
    target_compile_definitions(app PRIVATE CAM_SCALE_DIV=2u)
endif()

所有 FreeRTOS 应用共用 components/os/freertos/freertos_app_hooks：heap、FreeRTOS hook（idle、tick、stack overflow、malloc failed）与 assert 都有 weak 默认实现。main() 只需调用 ipro_platform_init()、创建任务并启动调度器。

• ipro_platform_init() 依次完成平台初始化（开发板配置与控制台 UART）、heap、boot2 分区表、日志，以及 CONFIG_SHELL=y 时的 shell。应用不要再初始化一次 shell。
• main.c 中不要再添加 heap、hook 或 assert 的样板代码。要覆盖某个 hook（例如 vApplicationIdleHook），在自己的源文件中定义同名的非 weak 版本即可，链接器会自动采用。

在 Reef 上动手实践¶

为出厂固件创建自己的替代配置，确认构建如何处理它，再上板运行。本例按照 .config 注释中的建议，让 ipro7ai_reef_demo 按整颗 2 MB 内封 Flash 链接。

要还原时，重新烧录 build/ 下的镜像即可。接下来：按照创建第一个自己的应用编写一个自己的应用，再用测试你的应用验证它。

创建新应用¶

创建第一个自己的应用从空目录开始一步步创建 Reef 应用。它遵循的规则：

• 应用放在 apps/<分类>/<应用>/。复制来的 Makefile 用 IPRO_SDK_BASE ?= $(abspath ../../../) 找到 SDK 根目录；多一层（例如 apps/bluetooth/ble/<应用>）时要改成 ../../../../。Makefile 请复制现有文件，不要从网页粘贴：recipe 行必须以 tab 开头。
• .config 从 apps/platform/ipro7ai_reef_demo/.config 开始，删掉用不到的部分。第一行的注释就是 ./build_freertos.sh -l 显示的说明。
• CMakeLists.txt 使用应用结构中列出的宏；setup_project() 的名称要与目录名称相同。

• main.c 保持精简：

  main.c

  #include <FreeRTOS.h>
  #include <task.h>
  
  #include "freertos_app_hooks.h"
  
  static void app_task(void *arg)
  {
      (void)arg;
      for (;;) {
          vTaskDelay(pdMS_TO_TICKS(1000));
      }
  }
  
  int main(void)
  {
      ipro_platform_init();   /* platform, heap, boot2, log, shell */
      xTaskCreate(app_task, "app", 1024, NULL, 5, NULL);
      vTaskStartScheduler();
      for (;;) {
      }
  }
  

本版本的限制¶

• 没有交互式配置工具：发布包中 make menuconfig 与 make defconfig 无法使用（见配置工具）。
• 不解析 Kconfig，依赖的选项必须自己写进配置文件；构建唯一补上的默认值是 Reef 的晶振微调。
• BOARD= 只在 ipro_agora_sentino 与 ipro_pdm_mic_demo 中有作用。
• 发布包只记载 macOS 与 Linux 构建主机。

相关文档¶

• 创建第一个自己的应用：从空目录创建 Reef 应用。
• 测试你的应用：控制台检查、自检与 build_freertos.sh test。
• 架构：分层、组件与目录。
• BLE 开发：.config 中的 BLE 配置。
• 工具命令行：build_freertos.sh 的所有操作与选项。
• 示例：各应用附带的配置文件。