xt_ota - OTA 升级

版本：0.1 | 日期：2026-07-03 | 路径： platforms/components/xtiny/xt_ota/

---

一、概述

xt_ota 是 XTINY 固件 OTA（Over-The-Air）升级模块。将升级包写入固定路径的存储分区 /usr/ota.bin ，随后校验包合法性并执行 FOTA 重启完成升级。

1.1 设计原则

• 三阶段流程 ：setup（初始化）→ write（逐块写入）→ upgrade（校验+升级）
• 幂等 setup ：重复调用 xt_ota_setup 不会重复初始化，已写入的临时文件会被删除
• 透明文件操作 ：每次 write 独立打开→追加→同步→关闭，无需用户管理文件句柄
• 一次性升级 ：调用 upgrade 后模块生命周期结束（校验成功则重启，失败则返回错误）

---

二、核心概念

2.1 升级流程

xt_ota_setup()   → 初始化，清除旧包，获取上次升级结果
xt_ota_get_info() → 查询可用空间和上次升级结果（可选）
xt_ota_write()   → 逐块写入升级包数据（可多次调用）
xt_ota_write()   → ...
xt_ota_upgrade() → 校验→升级→重启

2.2 固定路径 /usr/ota.bin

升级包存储在 /usr 分区下的固定路径。 xt_ota_setup 首次调用时会删除该路径上的旧文件，确保干净状态。

2.3 幂等 setup

xt_ota_setup 通过内部 b_inited 标志实现幂等：

• 首次调用：删除旧包→获取上次升级结果→清除结果→标记已初始化
• 重复调用：仅删除旧包，跳过已初始化步骤

2.4 写操作模式

每次 xt_ota_write 调用是独立的文件操作：每次写入独立打开、追加、同步、关闭，确保每次写入后数据持久化，断电后已写入部分不丢失。

2.5 升级校验与重启

xt_ota_upgrade 执行两步操作：

1. 校验升级包完整性
2. 启动升级流程

若 reboot=true ，升级后执行系统重启进入升级模式（此调用不应返回）。

---

三、API 参考

以下为函数签名大纲，完整的参数说明、返回值、注意事项请查看 xt_ota（OTA 升级） 。

3.1 生命周期

函数签名	说明
xt_err_t xt_ota_setup(void)	初始化 OTA 模块（幂等）
xt_err_t xt_ota_close(void)	关闭 OTA 模块，重置内部状态

3.2 状态查询

函数签名	说明
xt_err_t xt_ota_get_info(void *info)	获取可用空间和上次升级结果

3.3 升级操作

函数签名	说明
xt_err_t xt_ota_write(const void *src, size_t size)	写入一块升级数据（追加到 /usr/ota.bin ）
xt_err_t xt_ota_upgrade(bool reboot)	校验升级包并启动 FOTA 升级

四、编译配置

无编译配置项。

五、常见模式

5.1 完整升级流程（分块下载+升级）

#include "xt_ota.h"
 
static uint8_t chunk_buf[1024];
 
void ota_process(void) {
    struct xt_ota_info info;
    size_t total_written = 0;
    xt_err_t ret;
 
    // 1. 初始化
    ret = xt_ota_setup();
    if (ret != XT_EOK) {
        xt_log_error("OTA 初始化失败: %d", ret);
        return;
    }
 
    // 2. 检查空间
    ret = xt_ota_get_info(&info);
    if (ret != XT_EOK) {
        xt_log_error("获取 OTA 信息失败: %d", ret);
        goto cleanup;
    }
    xt_log_info("上次升级结果: %d, 可用空间: %u 字节", info.latest_result, info.free_size);
 
    if (info.free_size < expected_pkg_size) {
        xt_log_error("空间不足: 需要 %u, 可用 %u", expected_pkg_size, info.free_size);
        goto cleanup;
    }
 
    // 3. 逐块写入
    while (has_more_data()) {
        size_t chunk_size = download_next_chunk(chunk_buf, sizeof(chunk_buf));
        if (chunk_size == 0) {
            xt_log_error("下载数据失败");
            goto cleanup;
        }
        ret = xt_ota_write(chunk_buf, chunk_size);
        if (ret != XT_EOK) {
            xt_log_error("写入第 %u 块失败: %d", total_written / sizeof(chunk_buf) + 1, ret);
            goto cleanup;
        }
        total_written += chunk_size;
    }
    xt_log_info("写入完成，总计 %u 字节", total_written);
 
    // 4. 校验并升级
    ret = xt_ota_upgrade(true);  // 升级后自动重启
    xt_log_error("升级失败: %d（不应到达此处）", ret);
 
cleanup:
    xt_ota_close();
}

5.2 不立即重启（手动控制重启时机）

void ota_upgrade_no_reboot(void) {
    xt_err_t ret;
 
    ret = xt_ota_setup();
    if (ret != XT_EOK) return;
 
    // ...逐块写入...
 
    ret = xt_ota_upgrade(false);  // 不自动重启
    if (ret == XT_EOK) {
        xt_log_info("升级包校验通过，等待手动重启");
        // 执行其他清理工作...
        xt_soc_reboot();
    } else {
        xt_log_error("升级包校验失败: %d", ret);
        xt_ota_close();
    }
}

5.3 上次升级结果查询

void check_last_ota_result(void) {
    struct xt_ota_info info;
 
    xt_ota_setup();                    // 初始化以获取 latest_result
    xt_ota_get_info(&info);
    xt_log_info("上次 OTA 结果: %d", info.latest_result);
    xt_ota_close();
}

5.4 错误恢复——中途失败后重新开始

void ota_with_retry(void) {
    xt_err_t ret;
 
    // xt_ota_setup 会删除旧包，幂等安全
    ret = xt_ota_setup();
    if (ret != XT_EOK) return;
 
    // 逐块写入，中途失败可重新调用 setup 从头开始
    while (has_more_data()) {
        size_t sz = download_next_chunk(chunk_buf, sizeof(chunk_buf));
        ret = xt_ota_write(chunk_buf, sz);
        if (ret != XT_EOK) {
            xt_log_error("写入失败，重新开始");
            xt_ota_setup();  // 幂等：删除旧包重新开始
            continue;        // 从头下载
        }
    }
 
    ret = xt_ota_upgrade(true);
}

---

六、已知行为与限制

行为	说明
固定路径 /usr/ota.bin	不可配置，升级包只能写到此路径
setup 幂等但不保留旧包	每次 setup 都会删除旧包
write 每次打开-关闭	每次写入都是独立文件操作，频繁小块写入性能较低
upgrade 后不应调用 close	reboot=true 时 xt_ota_upgrade 不会返回
upgrade 不自动关闭	升级失败需手动调 xt_ota_close 清理
close 清零全部状态	包括 b_inited 、 latest_result 、 free_size
xt_ota_info 定义在 xt_soc.h	使用 void *info 参数类型，需自行包含 xt_soc.h
无分片校验	不校验单次 write 内容的完整性，仅最终 upgrade 时校验整体包
单实例	不支持多路并行升级
free_size 实时查询	反映调用时刻的实际可用空间

七、示例

示例代码位于 examples/platform_specific/lm620/ota/。

cd examples/platform_specific/lm620/ota
xt --target lm620/r4f4 fullclean build
xt --target lm620/r4f4 run