📚 课程目录第3章 RH850量产软件版本命名与标识规范

3. RH850量产软件版本命名与标识规范

在RH850量产项目中，版本标识不是简单的“打标签”，而是贯穿需求、开发、构建、测试、发布、售后追溯的治理主线。一个ECU固件可能同时存在多个“版本”：对外发布的语义化版本、内部迭代的版本号、每次编译产生的构建号，以及Git仓库中的提交与标签。若这些标识之间没有稳定映射，就会出现“测试报告写的是V2.1.0，但刷写文件实际来自另一个提交”的典型问题。本节围绕语义化版本、内部版本号、构建号、Git标签策略，以及版本元数据嵌入固件与读取验证的方法展开。

一、四层版本标识的职责划分

建议将版本信息拆成四个层次，各自承担不同职责：

语义化版本（SemVer）：面向外部发布，格式为 MAJOR.MINOR.PATCH，如 2.4.1。MAJOR 表示不兼容的接口或功能变更，MINOR 表示向后兼容的功能新增，PATCH 表示向后兼容的问题修复。量产件通常还会附加预发布标识，如 2.4.1-rc.2。
内部版本号：面向项目内部迭代，可采用 主版本.次版本.迭代号 或日期序列，如 02.04.0015，用于区分同一语义化版本下的多次内部提交。
构建号（Build Number）：由CI流水线自动生成，通常为递增整数或“日期+序号”，如 B20250612.037，保证每次编译产物唯一可区分。
Git标签与提交哈希：标签如 rel/rh850-2.4.1 指向发布提交，短哈希如 a1b2c3d 用于精确定位源码状态。

四者关系可以概括为：语义化版本决定“对外叫什么”，内部版本号决定“内部第几次迭代”，构建号决定“哪一次编译”，Git标签与哈希决定“源码在哪”。

二、Git标签策略

RH850项目建议采用“轻量标签+附注标签”组合策略。日常内部构建可使用轻量标签，发布节点必须使用附注标签，并携带发布说明。标签命名建议统一为 rel/<产品>-<语义化版本>，例如 rel/rh850-2.4.1；预发布使用 rel/rh850-2.4.1-rc.2。标签必须打在经过评审的发布提交上，禁止在未合并分支上直接打发布标签。

CI中可通过以下命令校验标签与版本一致性：

# 读取最近标签
git describe --tags --always
# 输出示例：rel/rh850-2.4.1-3-ga1b2c3d
# 其中 3 表示距标签3个提交，a1b2c3d 为当前短哈希

若输出中“距标签提交数”不为0，说明当前构建并非标签指向的发布提交，应阻止其进入量产发布通道。

三、版本元数据嵌入固件

版本信息不能只存在于CI日志或发布说明中，必须嵌入固件镜像，使任何一颗已烧录的RH850芯片都能被读取验证。常见做法是在链接脚本中划分一个只读的版本信息段，例如 .version_info，由构建脚本生成C文件并编译进镜像。

示例结构体定义如下：

typedef struct {
    uint32_t magic;          // 0x52483835  "RH85"
    uint8_t  semver[16];     // "2.4.1"
    uint8_t  internal[16];   // "02.04.0015"
    uint8_t  build[24];      // "B20250612.037"
    uint8_t  git_hash[12];   // "a1b2c3d"
    uint8_t  git_tag[32];    // "rel/rh850-2.4.1"
    uint32_t crc32;          // 结构体校验
} version_info_t;

const version_info_t g_version_info
    __attribute__((section(".version_info"))) = {
    .magic = 0x52483835,
    .semver = "2.4.1",
    .internal = "02.04.0015",
    .build = "B20250612.037",
    .git_hash = "a1b2c3d",
    .git_tag = "rel/rh850-2.4.1",
    .crc32 = 0x1A2B3C4D
};

构建脚本在编译前根据环境变量或Git信息自动生成该文件，避免手工填写导致不一致。链接脚本中需确保该段位于可读区域，并记录其起始地址与长度，便于后续读取。

四、读取与验证方法

验证分两个层面：一是离线验证，二是在线读取。离线验证可在构建后直接解析镜像文件，确认版本段内容与CI变量一致；在线读取则通过调试接口或诊断服务读取芯片内版本段。

离线验证示例：

# 从ELF中提取版本段
objcopy -O binary --only-section=.version_info firmware.elf version.bin
# 查看十六进制内容
xxd version.bin

在线读取可通过RH850的调试接口（如E1/E2 Lite配合CS+或GHS）读取 .version_info 段地址，也可在应用层提供诊断服务，例如UDS的 0x22 服务读取DID 0xF1A0，返回版本结构体。读取后应校验magic与CRC32，若magic错误或CRC不匹配，说明版本段损坏或被篡改，应拒绝将该件用于量产。

建议在产线EOL测试中增加版本读取工位：刷写后立即读取版本段，与MES中的发布版本比对，不一致则报警并拦截。

五、版本标识关系图

下图展示从Git提交到固件版本段、再到读取验证的完整链路，帮助理解四层标识如何协同工作。

六、量产落地要点

第一，版本号生成必须由CI自动完成，禁止开发人员手工修改版本文件。第二，发布标签必须与语义化版本严格对应，标签一旦推送不得移动或删除。第三，固件版本段必须包含CRC校验，防止读取到未初始化或损坏数据。第四，产线EOL工位应把版本读取作为强制项，与MES发布记录比对。第五，售后返回件应能通过诊断接口读出完整版本信息，用于快速定位问题批次。

通过上述规范，RH850量产软件的每一次发布都能形成“Git提交—CI构建—固件镜像—芯片读取”的闭环追溯链，版本标识不再是纸面约定，而是可验证、可拦截、可追溯的工程事实。