依据说明（重要）

• 文中所有事实性结论均标注出处 文件路径:行号。
• 无法从现有源码/产物直接确认的，标注 【推断】。
• 尚未核对、需要后续确认的，标注 【待核实】。
• 路径基准：除特别说明外，路径相对于 bs_hmi_base_s3/，即 [project_root]/。
• Brookesia 源码全部位于 so_build/ref/。
• 本文档不含推测性评价；涉及"建议"的部分集中在第 4 章，且均给出依据。

目录

• 0. 结论速览
• 1. elf_loader 基座架构
  • 1.1 全貌
  • 1.2 基座固件
  • 1.3 ELF 动态加载层
  • 1.4 符号与宿主能力导出
  • 1.5 Lua 运行时层
  • 1.6 共享内存数据通道
  • 1.7 包分发与加密
  • 1.8 关键指标实测
  • 1.9 特征总结
• 2. ESP-Brookesia 架构
  • 2.1 组件全景
  • 2.2 运行时层
  • 2.3 四个后端
  • 2.4 服务层
  • 2.5 系统层
  • 2.6 HAL 层
  • 2.7 旧线 esp-brookesia 0.5.0
  • 2.8 WAMR 集成事实
  • 2.9 落地门槛
  • 2.10 特征总结
• 3. 对比分析
  • 3.1 抽象位置
  • 3.2 分层图对照
  • 3.3 维度对比表
  • 3.4 Lua 层定位差异
  • 3.5 强项弱项
• 4. 可借鉴项与验证计划
• 5. 附录
  • 5.1 依据索引
  • 5.2 待核实清单

0. 结论速览

1. elf_loader 基座架构

命名说明：本文档用 “elf_loader 基座架构” 指代我们当前的实现（基座固件 + elf_loader + .so + Lua）， 而不使用"我方架构"这类表述。原因有二：

1. 它描述的是架构形态（单一 ELF 执行基座）而非归属，便于与 Brookesia 的"多后端对等"形态直接对照；
2. Brookesia 的 runtime_elf 后端同样复用官方 espressif/elf_loader（ref/brookesia_runtime_elf/idf_component.yml:5-7）， 若用"我方"会掩盖"同一个 loader、两种用法"这一关键对照点。

后文对比表格中该列简称为 “elf_loader 基座”。

1.1 全貌

核心特征：.so 是唯一的扩展单元；脚本（Lua）不直接由基座执行，而是由运行在 .so 内的解释器执行。

依据：

• so_build/lua_engine/CMakeLists.txt:154-155 的自定义链接命令（-shared -fPIC -nostdlib -nostartfiles -Wl,--allow-shlib-undefined）
• components/elf_loader/src/esp_elf.c:127（读文件到 PSRAM）、:432-442（pdata 分配）
• components/elf_ext/src/elf_so_loader.c:247-283（dlsym("app_main") → 起任务）

1.2 基座固件（bs_hmi_base_s3）

1.2.1 平台与关键配置

1.2.2 分区

出处：partitions.csv:1-7

1.2.3 构建产物规模（实测）

出处：build/bs_hmi_base_s3.map 输出段统计（解析脚本 build/analyze_map.py）

1.2.4 组件级 flash 占用 Top（实测归因）

关于 esp_app_format 的 227,983 B：该数字挂在 esp_app_desc.c.obj 名下，但该源文件仅 5,394 B（[idf_path]//components/esp_app_format/esp_app_desc.c）。实际读取固件 rodata 后确认，这是全工程 .rodata.str1.1 合并字符串池（SHF_MERGE 段的 map 归属特性）。池内容实测：227,496 B / 7,746 条字符串，其中日志格式串合计 62,477 B（E (%lu) 978 条、W (%lu) 74 条、I (%lu) 138 条、[%6u][E] 170 条、I (%d) 101 条）、ESP_ERR_* 223 条、LVGL 断言串（lv_obj_* 137 条、lv_style_* 111 条）、断言文件路径（//IDF/components/*）78 条共 6,648 B。 出处：build/bs_hmi_base_s3.map:115809-115810（.rodata.__esp_system_init_fn_init_show_app_info.str1.1 = 0x378a8）、ELF .flash.rodata 起始内容解析。

1.3 ELF 动态加载层（elf_loader）

1.3.1 内存分配策略（决定性）

// components/elf_loader/src/esp_elf_adapter.c:29-51
void *esp_elf_malloc(uint32_t n, bool exec)
{
#ifdef CONFIG_ELF_LOADER_LOAD_PSRAM
    caps = MALLOC_CAP_SPIRAM | MALLOC_CAP_8BIT;
#else
    caps = MALLOC_CAP_EXEC / MALLOC_CAP_8BIT;
#endif
    caps |= MALLOC_CAP_CACHE_ALIGNED;   // IDF >= 5.3
    return heap_caps_malloc(n, caps);
}

因为基座开了 CONFIG_ELF_LOADER_LOAD_PSRAM=y，.so 的 text 与 data（含 bss）全部从 PSRAM 分配。

1.3.2 加载流程

要点：.so 文件缓冲只是加载期峰值，不常驻（dlmod.c:251）。lua_engine.so 当前 257,972 B，即单次加载峰值约 252 KB PSRAM。

1.3.3 任务与栈

// components/elf_ext/src/elf_task_api.c:111,115
core_id, MALLOC_CAP_SPIRAM | MALLOC_CAP_8BIT   // .so 入口任务栈默认放 PSRAM

出处：elf_ext/include/elf_task_api.h:58（文档：“默认用 PSRAM (MALLOC_CAP_SPIRAM) 分配任务栈”）

1.3.4 崩溃保护

elf_so_loader.c:166-170：s_dynamic_loading_enabled 为假时拒绝加载（crash loop protection）。

1.4 符号与宿主能力导出（elf_ext）

1.4.1 机制

基座在编译期从指定静态库用 nm 抽取符号，生成 generated/<name>_syms.c，由 elf_sym_register.c 在启动时注册进 ELF 符号表。

// components/elf_ext/src/elf_tab_syms.c:188-192（部分）
ESP_ELFSYM_EXPORT(heap_caps_malloc),
ESP_ELFSYM_EXPORT(heap_caps_calloc),
ESP_ELFSYM_EXPORT(heap_caps_get_free_size),

// components/elf_ext/src/elf_sym_register.c:55
(esp_elf_symbol_table_t *)s_tables[i]

符号表宏与容器：so_build/lua_engine/elf_api/include/private/elf_symbol.h:24-34（ESP_ELFSYM_EXPORT / esp_elfsym / ESP_ELFSYM_END）

1.4.2 符号表清单（21 张）

出处：components/elf_ext/CMakeLists.txt:74-95

gpio, uart, lfs, log, freertos, wifi, netif, event, nvs, lvgl, lcd,
libgcc, libm, newlib, ping, mdns, i2c, mcpwm, syshal, vfs

生成方式：components/elf_ext/CMakeLists.txt:97-160（symbols.py -t l -i <lib.a> -of gen_<name>_syms.c） 过滤机制：components/elf_ext/tools/filter_syms.py（支持 --drop-pattern，如对 netif 过滤 esp_netif_action_、_unsafe$、_api$ 等）

1.4.3 关键特性

1.5 Lua 运行时层（lua_engine.so）

1.5.1 组成

构建源集合（so_build/lua_engine/CMakeLists.txt:160-188）：

Lua 版本：5.5（so_build/lua_engine/components/georgik__lua/lua/lua.h:20-22：LUA_VERSION_MAJOR_N 5 / MINOR 5 / RELEASE 0）

1.5.2 引擎能力（源码事实）

1.5.3 静态数据落点

.so 的 .data/.rodata/.bss/.data.rel.ro 被 esp_elf_malloc(..., false) 整块分配到 PSRAM（见 1.3.1），因此：

• s_jobs[LUA_ASYNC_MAX_JOBS] 4,480 B → PSRAM
• g_log_buffer 4,112 B → PSRAM
• instructions[20] 1,680 B → PSRAM
• 全部 .bss 11,612 B / .data 2,696 B → PSRAM

注意：源码中这些变量标注了 EXT_RAM_BSS_ATTR（lua_async.c:95-98、lua_bootlog.c:87,613），但该宏在本 .so 编译环境中展开为空（so_build/lua_engine/build/config/sdkconfig.h 中不存在 CONFIG_SPIRAM_ALLOW_BSS_SEG_EXTERNAL_MEMORY），所以落的是普通 .bss。当前不影响结果（loader 统一放 PSRAM），但语义上名不副实。

刻意保留在内部 RAM 的少数（有源码注释依据）：

1.5.4 编译与裁剪现状

# so_build/lua_engine/CMakeLists.txt:150-152
# -Os：手工调用编译器绕过了 IDF 默认编译选项，不加优化会按 -O0 编译，
#      导致 .text/.rela.dyn/.got 显著膨胀（见 release 目录 .so 体积分析）。
set(so_compile_flags -c -fPIC -Os -ffunction-sections -fdata-sections)

# so_build/lua_engine/CMakeLists.txt:222-226
# .xt.prop / .xt.lit 是 Xtensa relaxation 元数据（非 ALLOC），链接完成后
# 无任何作用，占成品 .so 约 1/3 体积，直接移除（PT_LOAD 内容不受影响）。
COMMAND ${CMAKE_STRIP_SO} --strip-unneeded -R .comment -R .note
    -R .xt.prop -R .xt.lit
    ${so_output}

其它 .so 工程（bs_link_hmi、ui_mirror、terminal、bs_link_scpi、bs_hmi_320x240）在同一次优化中做了相同改动（各自 CMakeLists.txt 的 so_compile_flags 与 strip 命令）。

1.6 共享内存数据通道

1.6.1 组件实现（基座侧）

1.6.2 布局登记链路

已登记的 7 个区域与字段数：bat_ch_data(9)、bat_ch_cfg(10)、bat_dev_state(7)、bat_ota_state(12)、bat_pending_fw(4)、bat_fps(1)、bat_mode_slots(6) 出处：state_layout.c:27-117

1.6.3 Lua 侧读取路径

// lua_module_shared_memory_lua.c:573-592
shared_mem_region_t* region = shared_mem_get(name);
int count = shared_mem_get_layout(region, out_fields);
if (count <= 0) { lua_pushnil(L); lua_pushfstring(L, "No layout registered for '%s'", name); return NULL; }

关键约束：layout / read_struct / write_struct 依赖已有登记；Lua 侧没有 set_layout API（lua_module_shared_memory_lua.c:820-831 的导出清单中无登记接口）。因此若设备上未运行带 state_layout.c 的 HMI .so，这三个接口必然返回 nil。

shared_mem_destroy 在整个 bs_hmi_base_s3/ 内只有定义、没有调用（检索结果），shared_mem_create 同名幂等（shared_memory.c:127-136），所以区域一旦创建，其 layout 不会被销毁路径清掉。

1.7 包分发与加密

LFS 分发：lfs_storage 分区 7 MB（partitions.csv:5），.so/脚本/资源经该分区下发（multi-partition-lfs 组件）。

1.8 关键指标实测

1.8.1 lua_engine.so 优化前后

1.8.2 当前 .so 段构成（257,972 B）

PT_LOAD 两段：off=0 filesz=254,272 memsz=254,272 (R+X)、off=254,272 filesz=2,876 memsz=14,512 (RW)

1.8.3 -Os 后各模块体积（code + rodata + data = 198,001 B）

1.8.4 静态对象清单（从 .o 符号表统计，.so 已 strip）

1.9 elf_loader 基座架构特征总结

2. ESP-Brookesia 架构

以下内容全部来自 so_build/ref/ 下的源码。

2.1 组件全景

2.1.1 组件与版本（16 个目录）

批次判断：14 个 brookesia_* 均含共同的 v0.8.0 - 2026-06-28 基线条目，互引 0.8.*，属同一 v0.8 训练线；patch 号差异（0.8.0~0.8.5）是各自独立迭代。

2.1.2 依赖关系图（源码确认）

缺失的第一方组件（被引用但 ref/ 中不存在，必须联网拉取）：

2.2 运行时层（runtime_manager）

2.2.1 核心接口

// brookesia_runtime_manager/include/brookesia/runtime_manager/backend.hpp:19-62
class IRuntimeBackend {
public:
    struct Attributes { std::string name; };
    virtual void set_native_modules(std::vector<NativeModule> modules) = 0;
    virtual std::expected<void, std::string> init() = 0;
    virtual void deinit() = 0;
    virtual std::expected<void, std::string> load_app(AppId id, const AppConfig &config) = 0;
    virtual std::expected<void, std::string> unload_app(AppId id) = 0;
    virtual std::expected<void, std::string> start_app(AppId id) = 0;
    virtual std::expected<void, std::string> stop_app(AppId id) = 0;
    virtual std::expected<NativeValue, std::string> call_function(
        AppId id, std::string_view module_name, std::string_view function_name, const NativeArgs &args) = 0;
    virtual AppState get_app_state(AppId id) const = 0;
protected:
    IRuntimeBackend(BackendType type, Attributes attributes);
private:
    Attributes attributes_;
    BackendType type_ = BackendType::Unknown;
};

2.2.2 数据模型

// types.hpp:22-29
enum class BackendType { Unknown, Lua, JavaScript, Wasm, Elf };
// types.hpp:31-38
enum class AppState { Unloaded, Loaded, Running, Stopped, Error };
// types.hpp:60-67
struct AppConfig {
    BackendType type = BackendType::Unknown;
    std::string app_path;
    std::string entry;
    std::string resource_dir;
    std::vector<std::string> arguments;
};

2.2.3 注册与选择

2.2.4 宿主桥接

2.2.5 职责边界（关键）

brookesia_runtime_manager/docs/main.md:3-24 明确：

brookesia_runtime_manager 只负责 runtime backend 的 app 生命周期和 native host bridge。 .bpk 解包、发布验签与 app package manifest 解析均在 system/brookesia_system_core。

即：运行时管理器不认识包格式、不做验签、不解 manifest。

2.3 四个后端

2.3.1 后端能力对照（源码确认）

出处：

• ELF：runtime_elf/src/backend.cpp:101-104（set_native_modules 无操作）、:266-281（call_function 不支持）、:258-261（不可中断）、:160-183（esp_elf_init+esp_elf_relocate）、:233-235（esp_elf_request）
• Lua：runtime_lua/src/backend.cpp:93-104（闭包注入）、:74-76（异步不支持）、:229-237（luaL_dofile）、:185-190（luaL_newstate+luaL_openlibs）
• JS：runtime_js/src/backend.cpp:481-503（CFunc magic）、:412-479（Promise 异步）、:681-701（JS_NewRuntime/JS_SetMemoryLimit）、:188-224（app 生命周期 hook）
• WASM：runtime_wasm/src/backend.cpp:627-651（单桩注册）、:601-610（结果句柄）、:656-735（加载流程）、:494-518（PSRAM 分配器）、:682-683（64 KB 栈 / 256 KB 堆）

2.3.2 各后端细节

ELF 后端

• 委托给 IDF 官方 elf_loader（idf_component.yml:5-7：espressif/elf_loader: 1.*）
• relocate 前用 BROOKESIA_THREAD_CONFIG_GUARD({ .stack_in_ext = false; }) 强制内部栈，注释说明"因为 relocate 会操作 flash"（backend.cpp:169-176）
• 文件读取走 Storage 服务（backend.cpp:38-59），非直接 fopen
• PC 平台直接 FATAL_ERROR（cmake/pc_platform.cmake:4）

Lua 后端

• 每个 app 一个 lua_State + luaL_openlibs（backend.cpp:185-190）
• 宿主模块注入：把每个函数用 lua_pushlightuserdata + lua_pushcclosure 包成闭包挂到全局表（backend.cpp:93-104）
• PC 侧找 Lua 5.4（pkg_check_modules(LUA54 REQUIRED lua5.4)，cmake/pc_platform.cmake:24），与 IDF 侧 5.5 不一致

JS 后端

• QuickJS-NG 0.14，支持 ES module 与全局脚本（backend.cpp:764-769）
• 内存上限硬编码 16 * 1024 * 1024（backend.cpp:42-47），不可通过 Kconfig 调整
• 唯一提供 app 级生命周期 hook 的后端：on_install / on_start / on_stop / on_pause / on_resume / on_uninstall / on_action / on_event / on_timer（backend.cpp:188-224）
• 异步宿主函数用 JS_NewPromiseCapability + TaskScheduler（组 RuntimeJsAsync）resolve（backend.cpp:412-479）
• 无 QuickJS 时有 fallback 后端（backend.cpp:878-1014）

WASM 后端

• 加载流程（backend.cpp:656-735）：read_wasm_file → register_wamr_brookesia_imports → wasm_runtime_load → wasm_runtime_set_wasi_args → wasm_runtime_instantiate(64KB, 256KB) → wasm_application_execute_main
• 宿主桥接：模块名固定 "env"，所有函数共用桩 wamr_dynamic_import，签名统一 (ii)i，通过 wasm_runtime_get_function_attachment 区分（backend.cpp:520-523, 620, 627-651）
• 符号名约定：<sanitized_module>_<sanitized_function>（private/import_descriptor.hpp:69-77）
• 结果回传：brookesia_result_len / brookesia_result_copy / brookesia_result_free，结果池最多 64 条（backend.cpp:601-610、private/host_utils.hpp:21-54）
• 运行时内存与线性内存都指向 PSRAM（backend.cpp:494-518, 781-793）

2.4 服务层（service_manager + helper + agent）

2.4.1 ServiceBase

// brookesia_service_manager/include/brookesia/service_manager/service/base.hpp:136-175
struct Attributes {
    std::string name;                 // RPC 稳定标识
    std::string description;
    std::string version;              // v0.8.1 起强制非空
    std::vector<std::string> dependencies = {};
    std::optional<lib_utils::TaskSchedulerStartConfig> task_scheduler_config;
    SchedulerType scheduler_type = SchedulerType::Main;
    bool bindable = true;
};

子类覆写：get_function_schemas() / get_event_schemas() / get_function_handlers()（base.hpp:228, 252, 536）；生命周期钩子 on_init/on_deinit/on_start/on_stop（base.hpp:446-477）

2.4.2 关键机制

2.4.3 service_helper（契约层）

• 纯头文件，0 个 .cpp，约 8.5k 行
• 核心 CRTP 基类 template <typename Derived> class Base（helper/base.hpp:77），要求 Derived 提供 FunctionId/EventId 枚举、get_name()、schema（helper/base.hpp:32-40）
• 类型安全调用：call_function_sync<ReturnType>(FunctionId, Args...)（helper/base.hpp:679）
• get_name() 是稳定 RPC 标识，改名属于破坏性变更（service_helper/README.md:11-13）

2.4.4 service_wifi（服务模板）

可复用要点（service_wifi/src/service_wifi.cpp、service_wifi.hpp）：

1. 属性在构造函数注入（service_wifi.hpp:66-96）
2. get_function_schemas() 直接返回 helper 的 schema（:122-132）
3. handler 用 BROOKESIA_SERVICE_HELPER_FUNC_HANDLER_N 逐条绑定（:133-205）
4. 业务函数返回 std::expected<T, std::string>
5. 底部静态注册 + CMake -u（service_wifi.cpp:1880-1885、CMakeLists.txt:32-38）

2.4.5 agent_manager

2.5 系统层（system_core）

2.5.1 定位

brookesia_system_core/README.md:7：

the app, GUI, runtime, storage, timer, and service bridge framework for products.

依赖（system_core/idf_component.yml:1-28）：brookesia_gui_interface(缺)、brookesia_runtime_manager、brookesia_service_helper、brookesia_service_storage(缺)、brookesia_service_usb(缺)、zlib ^1.3.0

2.5.2 .bpk 包格式

2.5.3 manifest 字段（完整）

// include/brookesia/system_core/app/types.hpp:200-245
struct AppManifest {
    std::string id;
    std::string name;
    std::map<std::string, std::string> localized_names;
    std::string version = "0.1.0";
    AppKind kind = AppKind::Native;        // Native / Runtime
    bool visible = true;
    bool preload_dom = false;
    std::string icon_id;
    std::vector<std::string> supported_systems;
    std::string icon_path;
    runtime::BackendType runtime_type = runtime::BackendType::Unknown;
    std::string app_path;
    std::string entry;
    std::string resource_dir;
    std::vector<std::string> arguments;
    std::vector<AppManifestService> services = {};
};

JSON 层级：顶层 package / runtime / services（package.cpp:672-700）

• package：id(必填)、name(对象形式 {"en":"..."}, 必填)、version(必填)、visible、systems
• runtime：type(必填)、entry(必填)、resource_dir、arguments
• services[]：name(必填)、version(必填)、component

2.5.4 验签

2.5.5 安装/卸载

// include/brookesia/system_core/system/system.hpp:158-175
std::expected<AppId, std::string> install_app(std::shared_ptr<IApp> app);
std::expected<AppId, std::string> install_runtime_app(const AppManifest &manifest);
std::expected<AppId, std::string> install_runtime_app_package(
    std::string_view package_path, bool replace_existing = true);
std::expected<void, std::string> install_registered_apps();
std::expected<void, std::string> uninstall_app(AppId app_id);

• 无独立 update API：更新 = install_runtime_app_package(..., replace_existing=true)
• 安装含回滚（src/app/manager.cpp:393-482）
• 启动时扫描已解包目录并安装（src/app/package_scan.cpp:30-119）
• 不存在 “App Store” 组件（ref/ 全境检索仅命中 esp-brookesia/README.md 规划文字）

2.6 HAL 层

与 LVGL 解耦（源码确认）：hal_interface/idf_component.yml:1-14 仅依赖 brookesia_lib_utils；hal_adaptor 依赖列表无 LVGL；display 仅提供 panel/touch/backlight 原生接口。

ESP32-S3 板子（boards/**/board_info.yaml）：esp_box_3、esp32_s3_korvo2_v3、waveshare/esp32_s3_touch_amoled_{1_75c,1_8,2_16}、rymcu/rymcu_bigsmart

2.7 旧线 esp-brookesia 0.5.0

2.8 WAMR 在 ESP-IDF / ESP32-S3 上的集成事实

2.9 落地门槛

2.9.1 IDF 版本（决定性）

其余 0.8 组件（service_manager / service_helper / service_wifi / agent_manager / runtime_* / system_core / hal_*）的 idf_component.yml 均未声明 IDF 约束，其下限由 lib_utils 决定。

2.9.2 其它门槛

2.9.3 缺失组件（需联网拉取）

brookesia_service_sntp、brookesia_gui_interface、brookesia_service_storage、brookesia_service_usb（出处见 2.1.2）

2.10 Brookesia 特征总结

3. 对比分析

3.1 根本差异：抽象放在哪一层

3.2 分层图对照

elf_loader 基座（层级式）

Brookesia（对等式）

3.3 逐维度对比

3.4 Lua 层的定位差异（重点）

Lua 版本相同这一点值得注意：两个方案底层用的是同一份 Lua 源码（georgik__lua/lua/lua.h:20-22 与 runtime_lua/idf_component.yml:5-7 的 georgik/lua 5.5.*）。差异全在宿主层设计，不在语言实现。

3.5 双方强项/弱项清单

elf_loader 基座架构强项（有依据）

elf_loader 基座架构弱项（有依据）

Brookesia 强项（有依据）

Brookesia 弱项（有依据）

4. 可借鉴项与验证计划

4.1 零成本借鉴（只读源码，不改架构）

4.2 需要实测验证的

4.3 不建议直接采用的部分

5. 附录

5.1 依据索引

elf_loader 基座架构

Brookesia

5.2 待核实清单

文档变更记录

📚 相关阅读

• ESP32-S3 三种执行方式效率对比：原生 / WebAssembly / Lua 的 1000 位圆周率对决 —— 同一算法三种执行方式的实测性能差距：原生 427ms、WASM 11.4×、Lua 63.9×