| 版本 | 日期 | 修改人 | 说明 |
| v1.0 | 2026-07-06 | — | 初版 |
前言
lm620 平台提供了一套完整的默认配置。当开发者需要自定义内存布局或 NV 参数时， 可以通过本文档描述的 build_profile 额外配置机制进行覆盖，而无需修改平台源码。
**读者对象**：应用开发者。
一、配置体系概览
lm620 平台的额外配置通过 build_profile 目录 实现：
lm620/
├── r4f4/
│ └── build_profile/ ← 平台默认配置（最低优先级）
│ ├── xpartition.ini ← 分区表
│ ├── cpu-ap.lds ← 链接脚本模板
│ └── nv/ ← NV 客制配置
│ ├── nvCustCfg.json
│ └── nvparam_customcfg.h
│
└── r4f2/
└── build_profile/ ← 同上（r4f2 版本）
二、build_profile 双级配置覆盖机制
2.1 设计目的
build_profile 实现**双级优先级的覆盖**：开发者通过 set_config 指定自定义配置目录， 放入要覆盖的文件，其余文件自动回退到平台默认值。
2.2 双级优先级
| 优先级 | 来源 | 路径 | 适用场景 |
| 1（高） | set_config | set_config("xt_sdk_platform_build_profile_path", ...) | 项目自定义配置 |
| 2（低） | 平台默认 | <target>/build_profile/ | 平台出厂默认值 |
2.3 解析逻辑
按优先级查找文件，第一个存在的即生效：
set_config 路径 → 平台默认 build_profile/
**关键行为**：
- bp.file("xxx")：文件级逐文件回退，覆盖路径存在则用，否则回默认
- bp.dir()：目录级覆盖，返回 set_config 路径或平台默认路径
- 未覆盖的文件自动回退到平台默认
2.4 使用方法
在项目 xmake.lua 中通过 set_config 指定自定义 build_profile 路径：
-- 项目 xmake.lua 中
set_config("xt_sdk_platform_build_profile_path", path.join(os.scriptdir(), "build_profile"))
目录结构：
my_project/
├── xmake.lua
└── build_profile/ ← 只放需要覆盖的文件
├── xpartition.ini ← 自定义分区布局
└── nv/
└── nvCustCfg.json ← 自定义 NV 配置
不需要覆盖的文件（如 cpu-ap.lds）会自动使用平台默认值。
**多项目共享配置**：
set_config("xt_sdk_platform_build_profile_path", "/path/to/shared/build_profile")
三、分区配置（xpartition.ini）
3.1 文件格式
xpartition.ini 定义 Flash 的分区布局。每行描述一个分区：
- 分区名：分区标识符
- 起始地址：十六进制绝对地址（0x 前缀）
- 分区大小：十六进制大小（0x 前缀）
- 属性：FAL_PART_INFO_FLAGS_LOCKED（锁定）或 FAL_PART_INFO_FLAGS_UNLOCKED（可擦写）
必须包含 part_begin（首行）和 part_end（末行）标记。
3.2 r4f4 默认分区表
{"part_begin", 0x00000000, 0x55555555, FAL_PART_INFO_FLAGS_UNLOCKED},
{"mbl", 0x00000000, 0x00009000, FAL_PART_INFO_FLAGS_LOCKED},
{"part_tbl", 0x00009000, 0x00001000, FAL_PART_INFO_FLAGS_LOCKED},
{"xip", 0x0000A000, 0x00001000, FAL_PART_INFO_FLAGS_LOCKED},
{"nvf", 0x0000B000, 0x00007000, FAL_PART_INFO_FLAGS_LOCKED},
{"xboot", 0x00012000, 0x00010000, FAL_PART_INFO_FLAGS_LOCKED},
{"cmn", 0x00022000, 0x00001000, FAL_PART_INFO_FLAGS_UNLOCKED},
{"nvd", 0x00023000, 0x00006000, FAL_PART_INFO_FLAGS_LOCKED},
{"xknl", 0x00029000, 0x002C0000, FAL_PART_INFO_FLAGS_LOCKED},
{"zknl", 0x002E9000, 0x000D8400, FAL_PART_INFO_FLAGS_LOCKED},
{"data", 0x003C1400, 0x0003EC00, FAL_PART_INFO_FLAGS_UNLOCKED},
{"part_end", 0xFFFFFFFF, 0xFFFFFFFF, FAL_PART_INFO_FLAGS_UNLOCKED},
3.3 自定义分区
场景：增大 xknl 分区以容纳更多功能代码
- 在项目的 build_profile/ 中创建 xpartition.ini（通过 set_config 指向该目录）
- 修改 xknl 和 zknl 的大小（注意保持地址连续，总和不超出 Flash 容量）
- 重新编译
# 示例：增大 xknl，减小 zknl
{"xknl", 0x00029000, 0x00300000, FAL_PART_INFO_FLAGS_LOCKED},
{"zknl", 0x00329000, 0x00098400, FAL_PART_INFO_FLAGS_LOCKED},
{"data", 0x003C1400, 0x0003EC00, FAL_PART_INFO_FLAGS_UNLOCKED},
**注意事项**：
- 各分区地址必须连续，不能有重叠或间隙
- 修改后需确认镜像大小不超过分区容量
- 编译后如出现 "exceeds partition" 错误，检查镜像大小与分区的关系
四、链接脚本（cpu-ap.lds）
4.1 模板机制
cpu-ap.lds 是 GNU ld 链接脚本模板，构建时通过 GCC 预处理展开宏定义， 根据 CP 固件的实际大小动态计算 XIP 起始地址。
4.2 自定义链接脚本
一般情况下不需要修改 cpu-ap.lds。如有特殊需求（如添加自定义 section）， 在项目 build_profile/ 中放置修改后的 cpu-ap.lds（通过 set_config 指向该目录）即可。
五、NV 客制配置
5.1 文件说明
| 文件 | 说明 |
| nvparam_customcfg.h | 平台默认的 NV 结构体定义（NV_CustomConfig），包含基础字段和扩展机制 |
| nvCustCfg.json | NV 参数的 JSON 描述，配合 nvparam_customcfg.h 使用 |
| nvparam_customcfg_extra.h | **项目扩展文件**（用户自行创建，可选） |
5.2 覆盖与追加的区别
两个文件的生效机制不同，使用时需注意：
| 文件 | 机制 | 效果 | 适用场景 |
| nvparam_customcfg.h | build_profile 文件查找 | **覆盖**平台默认——项目版本完全替代平台版本 | 需要彻底重定义 NV 结构体 |
| nvparam_customcfg_extra.h | __has_include 编译时检测 | **追加**到平台默认——额外字段通过 extra 子结构体拼接 | 仅需扩展字段，保留平台默认（推荐） |
**推荐使用 nvparam_customcfg_extra.h**：大多数场景只需追加自定义字段， 无需覆盖整个 nvparam_customcfg.h。平台默认结构体已通过 __has_include 预留了扩展点：
typedef struct {
uint32_t power_on_delay_ms;
#if __has_include("nvparam_customcfg_extra.h")
NV_CustomConfig_Extra extra;
#endif
} NV_CustomConfig;
- **不提供 nvparam_customcfg_extra.h**：NV 结构体仅包含平台默认字段
- **提供 nvparam_customcfg_extra.h**：额外字段通过 extra 成员追加，不影响平台默认部分
仅当需要完全重定义 NV 结构体布局时，才在项目 build_profile 中放置完整的 nvparam_customcfg.h 覆盖默认版本。
5.3 nvparam_customcfg_extra.h 的编写要求
项目如需扩展 NV 字段，在 build_profile/nv/ 下创建 nvparam_customcfg_extra.h，必须满足：
- 定义 NV_CustomConfig_Extra 类型（结构体）
- 实现 NV_CustomConfig_Extra_Default() 函数（初始化默认值）
- **结构体字段必须使用定长类型**（uint32_t、int16_t、uint8_t 等），禁止使用 int、char、short 等平台相关类型——NV 数据是跨系统持久化存储，类型宽度必须确定
#include <stdint.h>
typedef struct {
uint32_t my_custom_field;
uint8_t my_other_field;
} NV_CustomConfig_Extra;
static void NV_CustomConfig_Extra_Default(NV_CustomConfig_Extra *cfg)
{
memset(cfg, 0x00, sizeof(*cfg));
cfg->my_custom_field = 100;
}
5.4 注意事项
- nvparam_customcfg.h 中必须 #include <stdint.h>
- NV_CustomConfig 总大小受 NV_CUSTOMCFG_SIZE 限制，超出时编译报错
- nvparam_customcfg.h 通常不需要修改，扩展字段应放在 nvparam_customcfg_extra.h 中
六、扩展配置
用户可在工程 xmake.lua 中通过 set_config() 开启编译选项：
-- 用户工程 xmake.lua 中
set_config("mqtt", true) -- 启用 MQTT 客户端
具体可用的 option 由各组件定义，参照对应组件的文档或源码中的 option() 声明。
1.17.0