IncludeOS LiveUpdate 库实战指南:热更新机制与 Conan Editable 开发工作流

原创2026-10-14 12:06:001,912 阅读
文章标签:操作系统云原生虚拟化网络

IncludeOS LiveUpdate 库实战指南:热更新机制与 Conan Editable 开发工作流

本文以 IncludeOS 仓库中的 lib/LiveUpdate/README.md 为骨架,系统讲解如何在 IncludeOS 中启用 LiveUpdate 库的 Conan editable 开发模式,并结合仓库源码深入剖析其热更新(hot-swap)实现原理:序列化与恢复 API、存储分区格式、ELF 热切换流程、软重置与回滚机制。读完本文,你将能在自己的 IncludeOS 服务中注册数据分区、触发 live update、恢复状态,并能把 LiveUpdate 作为本地可编辑包接入 Conan 构建体系。

LiveUpdate 是什么

LiveUpdate 是 IncludeOS 的在线热更新库,它允许一个正在运行的服务进程接收新内核镜像(update blob),把当前内存中的关键状态序列化到一块固定存储区域,然后通过 hotswap 机制把新内核覆盖到内存中并跳转到其入口,实现"无缝换核"。更新完成后,新内核通过 resume() 从同一存储区域恢复此前保存的状态(TCP 连接、统计计数器、自定义数据结构等)。

整个库位于 lib/LiveUpdate,对外头文件是 include/liveupdate.hpp(薄包装 include/liveupdate 直接包含它),内部存储格式定义在 include/storage.hpp。

一、把 LiveUpdate 注册为 Conan Editable 包

README 的核心内容是一套将 LiveUpdate 置于 Conan editable 模式的操作流程。开发 LiveUpdate 时,我们不希望每次改动都要重新执行完整的 conan create,而是让本地源码目录直接成为可被消费的包,从而在 IncludeOS 主工程中实时看到改动效果。

前置条件:确保当前处于 IncludeOS 源码根目录(即仓库根目录,README 中的 src 目录),且环境已安装 Conan 包管理器。

1. 移除 conanfile.py 中的版本变量

Conan 生成/管理的 conanfile.py 中通常会通过 version = conan_tools 一类代码生成版本号。editable 模式要求使用固定引用,因此需要先剔除该行:

awk '!/version = conan_tools/' lib/LiveUpdate/conanfile.py > temp && mv temp lib/LiveUpdate/conanfile.py

该命令用 awk 过滤掉所有包含 version = conan_tools 的行,将结果写入临时文件后覆盖回原文件(mv temp lib/LiveUpdate/conanfile.py)。说明:当前仓库快照中未包含 conanfile.py 实体文件,它属于 Conan 打包工作流的生成物,执行本步骤前请确保该文件已存在于 lib/LiveUpdate/ 目录。

2. 添加 editable 包

使用 conan editable add 把本地目录注册为可编辑包,并显式指定布局文件:

conan editable add lib/LiveUpdate liveupdate/9.9.9@includeos/latest --layout lib/LiveUpdate/layout.txt

这里把本地路径 lib/LiveUpdate 映射为包引用 liveupdate/9.9.9@includeos/latest(用户通道 includeos/latest),布局规则取自 lib/LiveUpdate/layout.txt:

[includedirs]
include

[libdirs]
build/lib

[includedirs] 声明了包的头文件目录为 include(实际路径即 lib/LiveUpdate/include,其中的 liveupdate 与 liveupdate.hpp 是公开头);[libdirs] 声明静态库位于 build/lib,与 CMake 中 add_library(liveupdate STATIC ...) 及 install(... ARCHIVE DESTINATION lib PUBLIC_HEADER DESTINATION include) 的安装布局保持一致。

3. 运行 Conan install

安装依赖并生成构建信息到指定目录:

conan install -if lib/LiveUpdate/build lib/LiveUpdate

-if(--install-folder)指定安装目录为 lib/LiveUpdate/build,同时该目录也是后续编译产物(如 build/lib/libliveupdate.a)的存放位置,与 layout.txt 中的 build/lib 呼应。

4. 运行 Conan build

在源目录执行构建:

conan build -sf . -bf lib/LiveUpdate/build lib/LiveUpdate

-sf(--source-folder)指定源码目录为当前目录 .,-bf(--build-folder)指定构建目录为 lib/LiveUpdate/build。构建成功后,LiveUpdate 就以 editable 方式被 IncludeOS 主工程消费,修改 lib/LiveUpdate/src 下的源码后重新执行该命令即可生效。

二、LiveUpdate 库的源码结构与构建

源码布局

从仓库目录树可以看到,LiveUpdate 由公开头文件与实现文件构成:

  • 公开头:include/liveupdate.hpp、include/storage.hpp;
  • 序列化/恢复实现:src/storage.cpp、src/partition.cpp、src/update.cpp、src/resume.cpp、src/rollback.cpp;
  • 平台热切换:src/hotswap.cpp(x86)、src/hotswap64.asm(x86_64 汇编)与 src/hotswap64_blob.asm(将编译好的 hotswap64.bin 以 incbin 嵌入);
  • 内核侧配合:src/os.cpp(存储区域的高内存映射);
  • 网络状态序列化:src/serialize_tcp.cpp、src/serialize_tcp.hpp、src/serialize_s2n.cpp(TLS 流恢复);
  • ELF 入口定位:src/elfscan.cpp。

CMake 构建要点

lib/LiveUpdate/CMakeLists.txt 展示了关键构建步骤:

  • 用 NASM 将 hotswap64.asm 编译为裸二进制 hotswap64.bin(add_custom_command + add_custom_target(hotswap64));
  • 生成静态库 liveupdate,x86_64 平台额外编译 serialize_s2n.cpp;
  • set_target_properties(liveupdate PROPERTIES PUBLIC_HEADER "include/liveupdate;include/liveupdate.hpp"),与 layout.txt 的 includedirs 相对应。

LiveUpdate 的头文件被多个模块直接引用,例如 src/CMakeLists.txt、src/plugins/CMakeLists.txt、src/drivers/CMakeLists.txt、src/util/CMakeLists.txt 都通过 include_directories(.../lib/LiveUpdate/include) 引入;测试工程则在 test/CMakeLists.txt 中以 add_subdirectory(../lib/LiveUpdate liveupdate) 方式直接纳入构建。此外,userspace/includeos/CMakeLists.txt 会把 elfscan/hotswap/partition/resume/rollback/serialize_tcp/storage/update 等 .cpp 直接编入用户态版本,使 LiveUpdate 也可在 Linux 用户态模拟运行。

三、核心 API:序列化(Storage)与恢复(Restore)

LiveUpdate 的完整生命周期由 exec() 与 resume() 一对函数包住:exec() 把用户数据序列化到固定内存位置后热切换;重启后的新内核通过 is_resumable() 验证同一位置的数据,再用 resume() 按分区键触发恢复回调。

LiveUpdate 静态接口总览

include/liveupdate.hpp 中 LiveUpdate 结构体的核心接口:

接口 作用
register_partition(std::string key, storage_func) 注册一个序列化分区,key 用于恢复时定位
exec(const buffer_t& blob, void* storage_area = nullptr) 以新内核 blob 触发热更新;area 为空时从 OS 获取
exec(const buffer_t& blob, std::string key, storage_func func) 注册分区并立即执行
restore_environment() exec 抛异常后恢复中断等环境(x86 上重新 sti)
store() 仅序列化用户数据、不跳转,返回缓冲区
is_resumable() / is_resumable(location) 校验存储区域是否完整一致
resume(std::string key, resume_func) 对指定分区执行恢复回调
partition_exists(key, area) 查询分区是否存在
resume_from_heap(void* location, key, func) 从堆中显式恢复(此时关闭堆越界检查)
stored_data_length(area) 返回存储区域总字节数
set_rollback_blob(const void*, size_t) 设置回滚用的"已知良好"blob
has_rollback_blob() 是否已设置回滚 blob
rollback_now(const char* reason) 立即回滚(soft-reset,几乎不停机)
os_is_liveupdated() 内核状态是否已标记为"被 liveupdate 过"

其中 storage_func 与 resume_func 是 delegate 类型回调:前者签名 void(Storage&, const buffer_t*),buffer_t 即新内核 blob(为 nullptr 时表示当前并非 live update,仅做状态存储);后者签名 void(Restore&)。

Storage:序列化端

Storage 对象在 exec() 流程中由系统构造并传给注册的 storage_func 回调,用户用 add_* 系列按 uid(uint16_t)存入数据:

  • add(uid, const T&):把任意 POD 结构按 sizeof(T) 以裸缓冲区方式存入(内部转 add_buffer);
  • add_int(uid, int):整数有专用压缩格式(直接用条目 length 字段存值);
  • add_string(uid, const std::string&)、add_buffer(uid, const void*, size_t):变长数据;
  • add_vector(uid, const std::vector<T>&):POD 向量(std::vector<std::string> 走专用字符串向量路径);
  • add_connection(uid, Connection_ptr):序列化整条 TCP 连接(见下文网络状态);
  • add_stream(net::Stream&):序列化流对象但不含底层传输,UID 被用作其子类型标识;
  • put_marker(uid):写入标记,用于圈定变长结构的结束位置。

值得注意的设计取舍:add() 存储的裸类型在恢复端无法用 type_info 验证(新内核可能由不同编译器编译,type_info 不保证跨版本可靠),因此类型一致性需由调用方约定,恢复时只能通过长度等间接手段校验。

Restore:恢复端

Restore 对象在 resume() 时由系统创建并传给 resume_func,用户按之前存储的顺序读取:

  • 类型探测:is_end()、is_marker()、is_int()、is_string()、is_buffer()、is_vector()、is_string_vector()、is_stream();
  • 数据读取:as_int()、as_string()、as_buffer()、as_type<S>()、as_vector<T>()、as_tcp_connection(net::TCP&)、as_tcp_stream(net::TCP&)、as_tls_stream(ctx, outgoing, transport);
  • 遍历:go_next() 跳到下一条目;pop_marker() / pop_marker(id) 跳过直到并越过下一个 marker(可校验 id)。

注意:as_type<S>() 要求 sizeof(S) 与条目长度完全一致,否则抛出 std::runtime_error("Mismatching length for id ...");as_int() 对非整数类型、as_buffer() 对非缓冲区类型也都会抛出运行时错误。头文件中的注释特别提醒:即使 is_resumable() 校验通过,resume() 仍可能失败——因为恢复出的数据如果过大,可能侵入 LiveUpdate 的存储区域并破坏它,此类失败均为 std::runtime_error,因此 务必为 VM 分配足够内存。

存储格式与校验机制

include/storage.hpp 定义了磁盘上(内存中)的持久化布局:

  • storage_header:以魔法数 LIVEUPD_MAGIC = 0xbaadb33fdeadc0de 开头(src/storage.cpp),包含 CRC、条目计数、总长度、最多 16 个分区的分区表(std::array<partition_header, 16>);
  • partition_header:name<a href="https://link.gitcode.com/i/7da0b293173ee452178ffcf211b10f7f" target="_blank">16](分区名最长 15 字节,见 [src/partition.cpp 中 key.size() > sizeof(name)-1 的长度检查)、CRC、offset、length;
  • storage_entry:单条数据头(type、id、len + VLA 数据),next() 按 length() 步进到下一条目;
  • 类型常量:TYPE_END=0、TYPE_MARKER=1、TYPE_INTEGER=2、TYPE_STRING=10、TYPE_BUFFER=11、TYPE_VECTOR=12、TYPE_STR_VECTOR=13、TYPE_TCP=100、TYPE_TCP6=101、TYPE_WEBSOCKET=105、TYPE_STREAM=106。

完整性校验有两层开关:全局布尔量 LIVEUPDATE_USE_CHEKSUMS(默认 true)控制 header 与每个分区的 CRC32 校验(用 util/crc32.hpp 的 crc32_fast);LIVEUPDATE_ZERO_OLD_MEMORY(默认 false)控制在热切换时是否把新内核与堆末尾之间的旧内存清零。finalize() 在序列化完成时对 header 生成 CRC;validate() 在 is_resumable() 时重新计算 CRC 比对。恢复完成一个分区后 zero_partition(p) 会清零该分区数据(出于安全),全部消费后 try_zero() 把整个区域清零。

存储流程的兜底机制:add_end() 会写一个 canary 值(0xbeefc4f3)到条目长度字段验证该地址可写,并检查存储末端是否侵入堆区(kernel::heap_max() 比较),防患于未然。

四、Live Update 的完整执行流程

exec():ELF 校验与热切换

src/update.cpp 中 LiveUpdate::exec() 的执行顺序大致如下:

  1. 关闭中断:x86 上执行 asm volatile("cli");
  2. 输入校验:blob 长度必须 ≥ ELF_MINIMUM(164 字节);存储区域不得位于内核区(_ELF_START_ ~ _end)或堆区(kernel::heap_begin() ~ heap_end())内,也不得为空指针;
  3. 定位 ELF 头:先在偏移 0 处检查 \x7fELF 魔法,失败则在偏移 SECT_SIZE(512)处再试一次(跳过引导加载器占用的首扇区),仍失败则抛出 "Could not find any ELF header in blob";
  4. 解析 ELF 结构与入口:按 EI_CLASS 区分 32/64 位,用 section header 计算期望文件总大小并与 blob 长度比对(不匹配抛 "ELF file was incomplete");入口点优先取 src/elfscan.cpp 中从符号表找到的 fast_kernel_start(该函数还会先检查 multiboot 段中是否有 0xFEE1DEAD 魔数的快速入口),找不到才退化为 e_entry;
  5. 序列化用户状态:update_store_data() 在固定位置原地构造 storage_header,遍历已注册分区回调逐个写入;
  6. 关停外设:flush 所有 NIC、os::machine().deactivate_devices()(屏蔽 MSI-X 向量等)、__arch_system_deactivate();
  7. 保存软重置信息:__os_store_soft_reset() 把 CPU 频率、APIC tick、更新区域位置等写入低内存固定地址;
  8. 热切换:把 hotswap 代码拷贝到"甜蜜点"(HOTSWAP_AREA = 0x8000),传入新内核物理基址、长度、入口、软重置数据,hotswap()/hotswap64 完成拷贝后跳转。

若中途抛出异常(如 std::runtime_error),调用方应在 catch 中调用 restore_environment() 恢复中断状态;在单元测试与用户态平台上,exec() 最终抛出特殊的 liveupdate_exec_success 异常(include/liveupdate.hpp),用于在无需真实跳转的环境里模拟更新成功。

hotswap:x86 与 x86_64 的实现差异

  • x86(src/hotswap.cpp):代码通过 .org 0x8000 定位,逐字节把新内核拷贝到目标物理地址后,以 SOFT_RESET_MAGIC(0xFEE1DEAD)放入 eax、软重置数据放入 ebx、入口放入 ecx,jmp *%2 直接跳到新内核;
  • x86_64(src/hotswap64.asm):这是更复杂的路径。先用 rep movsb 拷贝内核;若 LIVEUPDATE_ZERO_OLD_MEMORY 开启且传入 zero_until(堆末尾),则 rep stosb 清空旧内核与堆之间的内存;随后加载 32 位 GDT、通过 iretq 进入 compatibility mode、清 CR0 的 PG 位关闭分页、清 EFER MSR 的 LM 位关闭长模式,最终在 32 位保护模式下跳转新内核入口。该汇编通过 NASM 编成 hotswap64.bin,再由 src/hotswap64_blob.asm 以 incbin "hotswap64.bin" 嵌入,导出符号 hotswap64 与 hotswap64_len。

resume():状态恢复

src/resume.cpp 中 resume(key, handler) 的流程:

  1. 检查存储区位于堆外(kernel::heap_end() < location),否则告警并抛异常;
  2. is_resumable() 校验存储区(magic + CRC);
  3. find_partition(key) 定位分区(期间会校验该分区 CRC,不符抛 "Invalid CRC in partition ...");
  4. 构造 Restore 包装器并调用用户恢复回调;回调内部按存储顺序调用 go_next() 遍历;
  5. 恢复完成后 serialized_tcp::wakeup_ip_networks() 唤醒休眠的 IP 栈(见下);
  6. zero_partition(p) 清零分区,try_zero() 在无剩余分区时整体清零。

网络状态序列化:TCP 连接与 TLS 流

src/serialize_tcp.cpp 展示了 LiveUpdate 对 TCP 连接的"深度冻结":serialized_tcp 结构(版本号 VERSION = 2,必须与 Connection::VERSION 一致)保存本地/远端 Socket、TCB、RTTM、重传与快速恢复参数、写队列(每个 buffer 的长度 + 数据)和读缓冲(seq/hole/push + 已收数据)。TCP 状态机被映射为 0~10 的整数(Closed、Listen、SynSent、SynReceived、Established、FinWait1、FinWait2、CloseWait、Closing、LastAck、TimeWait)。

恢复连接时,如果其发送队列非空,该连接的 IP 栈会被加入 slumbering_ip4 集合,待整个 resume 结束后统一 force_start_send_queues() 重发。Storage::add_connection() / Restore::as_tcp_connection() / as_tcp_stream() 提供用户侧 API;TLS 连接(s2n)则通过 src/serialize_s2n.cpp 的 Restore::as_tls_stream(ctx, outgoing, transport) 恢复(要求条目类型为 TYPE_STREAM 且 subid 与 s2n::TLS_stream::SUBID 匹配)。

软重置与存储区域的高内存映射

内核侧 src/kernel/liveupdate.cpp 负责把物理存储区域映射到虚拟地址:x86_64 下 liveupdate_loc = HIGHMEM_LOCATION = 1ull << 45(其他无分页平台直接用物理地址),通过 os::mem::vmmap().assign_range(...) 与 os::mem::virtual_move(...) 完成映射,之后 kernel::liveupdate_storage_area()(src/include/kernel.hpp)返回该虚拟地址,liveupdate_storage_end() 返回其末端。

软重置数据由 src/platform/x86_pc/softreset.cpp 管理:__os_store_soft_reset() 在 SOFT_RESET_LOCATION(0x8200)写入 softreset_t(含 CRC、liveupdate 位置/大小、high_mem、CPU 频率、APIC tick、额外的回滚 blob 指针),新内核启动时 resume_softreset() 校验 CRC 后恢复这些值并把 is_live_updated 置为 true,同时调用可选的 softreset_service_handler。

五、回滚机制

src/rollback.cpp 提供失败保护:set_rollback_blob(buffer, len) 记录一份"已知良好"的旧内核 blob 并注册 os::on_panic(LiveUpdate::rollback_now);has_rollback_blob() 要求 blob 非空且长度 > 164(最小合法 ELF 大小)。rollback_now(reason) 一旦被调用,会用该 blob 重新执行 exec()(即反向热更新回旧内核);若 exec 抛异常则打印失败原因,无论成败最终都会 os::reboot() 兜底(__builtin_unreachable())。软重置路径中,softreset_service_handler 会把重置时附带的数据深拷贝为回滚 blob。

六、测试与示例:从 VM 到用户态

内核集成测试

test/integration/kernel/LiveUpdate 提供了完整可运行的热更新演示:service.cpp 中 Service::start() 配置静态网络(10.0.0.59/255.255.255.0,网关 10.0.0.1)并在 TCP 666 端口启动接收服务;test.py 在虚拟机输出 "Ready to receive binary blob" 后把 kernel_LiveUpdate 二进制通过 socket 发送过去;liu.hpp 的 setup_liveupdate_server() 收到 blob 即调用 liu::LiveUpdate::exec(buffer, "test", save_function),异常时先 restore_environment() 再重新抛出。

test_boot.cpp 演示了典型的"存储-恢复"回路:boot_save 用 storage.add_vector(0, timestamps) 记录启动时间戳、add_buffer(2, *blob) 保存新内核 blob 供下一轮更新使用,并递增 Statman 计数器;boot_resume_all 依次 as_vector<uint64_t>()、as_buffer()、Statman 的 restore() 恢复,最后 pop_marker() 收尾。begin_test_boot() 先尝试 LiveUpdate::resume("test", boot_resume_all),若累计 30 次则打印中位启动时间;否则立即用保存的 blob 再次 exec()——形成一个连续热更新的自举循环。手工推送更新可复用 manual.sh:

cat build/kernel_LiveUpdate > /dev/tcp/10.0.0.59/666

用户态测试

test/userspace/liveupdate/service.cpp 在 Linux 用户态模拟整个流程:读取 build/linux_liu、通过 modify_kernel_base() 改写 ELF 的 p_paddr 让新内核落在堆上,然后循环 100 次 register_partition("test", store_func) + exec(bloberino, liu_storage_area),每次捕获 liu::liveupdate_exec_success 后调用 resume_from_heap(liu_storage_area, "test", restore_func) 完成恢复,最终统计中位启动时间并关机。这验证了 LiveUpdate 的逻辑不依赖真实硬件,可在普通 Linux 进程中调试。

单元测试

test/unit/memory/paging/unit_liveupdate.cpp 覆盖了 Storage/Restore 对 int、string、任意 POD(add<bool>、add<struct testable_t>)、buffer、std::vector<int>、std::vector<std::string>、TCP 连接(add_connection 后 as_tcp_connection)以及 Statman 统计的双次存储合并等读写路径,并严格断言条目 id、类型与值的对应关系——可作为理解各 API 语义的最小示例。

七、总结与使用建议

从 Conan editable 工作流到底层 hotswap 汇编,LiveUpdate 呈现出一条清晰的"序列化 → 校验 → 热切换 → 恢复 → 回滚"闭环。实际接入时建议遵循以下要点:

  1. 容量规划:恢复数据可能侵入存储区域,务必给 VM 分配足够内存;存储区域默认取 kernel::liveupdate_storage_area()(x86_64 高内存映射),也可在 exec()/resume_from_heap() 中显式指定。
  2. 分区键管理:key 最长 15 字节且不可重复(重复注册抛 "Storage key already used");恢复时 resume() 返回 false 表示分区不存在。
  3. 类型约定:跨版本恢复时 type_info 不可依赖,add<T>/as_type<S>() 的语义一致性由服务自身保证;标准类型用 add_int、add_string、add_buffer、add_vector、add_connection 等专用接口以获得更可靠的校验。
  4. 性能开关:基准测试场景可在 BENCHMARK_MODE 下关闭 LIVEUPDATE_USE_CHEKSUMS(如 test/integration/kernel/LiveUpdate/CMakeLists.txt 所示)以缩短更新耗时,代价是失去完整性校验。
  5. 开发迭代:在 IncludeOS 源码根目录按 README 的四步命令注册 editable 包后,conan build -sf . -bf lib/LiveUpdate/build lib/LiveUpdate 即可把对 LiveUpdate 的修改即时带入主工程,是本地迭代调试该库的标准姿势。
登录后查看全文
IncludeOS