AxVisor 实习计划 - 客户机之间通信

[baitwo02]

AxVisor 实习计划 - 客户机之间通信

当前已有工作

目前工作已经从 IVC 基础数据面的补全推进到 vPCI/ivshmem 客户机接口迁移阶段。

IVC 数据面方面，通道已经从单页扩展为最大 1 MiB 的连续多页共享内存，并完成 ArceOS 双 VM 全双工通信。协议从固定 slot 升级为 region v3 + Message V1：每条逻辑消息可以跨多个 cell 和 ring 瞬时容量传输，使用 FIRST/LAST/ABORT、message ID、分片序号和声明长度完成重组，同时通过 endpoint ownership 和单 subscriber 约束保护 SPSC 不变量。Linux 侧也已完成 region v3、Message V1 和消息级读写接口迁移，现有 HVC publish/subscribe/notify ABI 保持不变。

vPCI 基础方面，axdevice 已加入架构无关的 PCI Type-0/ECAM、类型化 BDF/BAR、配置空间和 capability 模型，并接入 resolved device graph 的资源规划、运行时路由和事务回滚。AArch64 主线 VM 构建流程可以在存在 PCI endpoint 时按需创建 generic ECAM host，从统一 MMIO 池分配 ECAM 和 memory aperture，并从同一份解析结果生成 pci-host-ecam-generic FDT 节点。当前 PCI 中断尚未接入；后续 ivshmem 中断路径计划仅实现 MSI-X，不提供 INTx fallback。

因此，当前已经具备多页共享内存、双工消息协议、Linux/ArceOS 基线以及 AArch64 vPCI 枚举与 BAR 路由基础，下一阶段重点是把这些能力组合成可由 Linux 和 Zephyr 使用的最小 ivshmem 设备。

待完成工作

后续任务分为四类：

1. 最小 ivshmem endpoint：定义稳定的 PCI identity、BAR0 最小控制寄存器和 BAR2 共享内存区域，建立 link、peer 和共享 backing 的类型化关系；中断路径仅实现 MSI-X 和 doorbell 定向通知。
2. root cell 与客户机接入：由 ArceOS/AxVisor root cell 管理共享内存和 endpoint 生命周期，启动 Linux 与 Zephyr 两个客户机，分别完成 PCI 枚举、BAR 映射和最小收发适配。
3. 协议迁移与生命周期：先以简单 mailbox 跑通 BAR2 基本通信，再将已有 region v3 + Message V1 复用到 ivshmem 数据面；补齐 VM 创建失败、停止、重启和异常退出时的资源清理。
4. 测试与治理：增加 MSI-X、畸形访问、资源冲突、backpressure 和回滚测试，建立三 cell QEMU smoke；后续再处理 quota、ACL、多 peer 权限隔离、状态表、可观测性和性能评估。

现有 HVC IVC 路径在 PCI 接口稳定前继续保留，不在迁移初期直接删除或改变 ABI。

三个月大致规划

• 第一个月：完成 IVC 数据面基线。 完成多页共享内存、ArceOS 全双工通信、SPSC 约束、region v3 + Message V1，以及 Linux 侧协议迁移和本地联调能力。
• 第二个月：完成 vPCI/ivshmem 迁移。 先建立架构无关的 PCI Type-0/ECAM 和 AArch64 generic ECAM/FDT 基础，再实现最小 ivshmem endpoint、MSI-X doorbell，并跑通 ArceOS root cell 下 Linux 与 Zephyr 的基本通信。
• 第三个月：完成稳定化与治理。 将 Message V1 完整迁移到 ivshmem 数据面，补齐生命周期回收、错误语义、资源限制和测试矩阵；根据进度继续推进多 peer 权限隔离、状态表、调试接口、性能评估及协议文档。

每周记录

• 第一周（7/17 - 7/19）：整理上一阶段工作并 rebase 到最新 dev；放弃 linker section 隐式设备发现方案，回到显式、可审计的 composition root。#1
• 第二周（7/20 - 7/26）：将 IVC 通道从单页扩展为最大 1 MiB 的连续多页共享内存，按 TDD 补充回归测试，并通过 64 KiB 通道的 ArceOS publisher + Linux subscriber QEMU smoke。#2
• 第三周（7/27 - 8/2）：完成 ArceOS 双 VM 全双工通信，收紧 endpoint ownership 和单 subscriber 约束；将固定 slot 升级为 region v3 + Message V1 分片协议，支持跨 ring 容量的逻辑消息。#3
• 第四周（8/3 - 8/9）：完成 Linux 侧 region v3 和 Message V1 迁移，对齐共享区布局、分片收发、消息级 read/write、协议错误处理和有界等待；跨仓库发布与干净镜像端到端验证进入收尾阶段。#4
• 第五周（8/10 - 8/16）：完成架构无关的 vPCI Type-0/ECAM、类型化 BDF/BAR、确定性拓扑和事务回滚基础，并将 PCI host、endpoint 和 generic ECAM FDT 接入 AArch64 主线 VM 构建流程。#5

近两周计划

第六周计划（8/17 - 8/23）：最小 ivshmem 与 Linux/Zephyr 基本通信

• 在 configured device catalog 中注册最小 ivshmem PCI endpoint，定义 PCI identity、BAR0 最小控制寄存器和 BAR2 共享内存区域。
• 仅实现 MSI-X 中断路径，通过 doorbell 定向通知目标 peer，不提供 INTx fallback。
• 由 ArceOS/AxVisor root cell 分配并持有共享 backing，为 Linux 和 Zephyr 分别创建 endpoint，并将同一共享区域映射到双方 BAR2。
• Linux 侧验证 generic ECAM 枚举、PCI probe 和 BAR 映射；Zephyr 侧完成对应的最小映射与读写适配。
• 使用 mailbox、序列号和 checksum 跑通 Linux → Zephyr 请求与 Zephyr → Linux 应答。
• 增加 AArch64 QEMU 三 cell smoke，检查 PCI 枚举、BAR2 映射、MSI-X doorbell、双向消息和 payload 校验结果。

本周以“设备可枚举、共享区可映射、MSI-X 可定向通知、Linux 与 Zephyr 可双向交换并校验数据”为完成标准。

第七周计划（8/24 - 8/30）：ivshmem 协议迁移与稳定化

• 在最小 mailbox 闭环基础上，将已有 region v3 + Message V1 接到 ivshmem BAR2，保持消息分片、重组、backpressure 和协议错误语义一致。
• 整理 Linux 与 Zephyr 的公共 guest 侧接口，隔离 PCI/BAR/MSI-X 平台适配与上层消息协议，避免复制 wire layout 和 ring 不变量。
• 补齐 VM 创建失败、endpoint 注册失败、peer 重启和 VM 停止时的共享 backing、BAR binding 与 MSI-X 资源回收。
• 增加错误路径和确定性测试，覆盖越界 BAR 访问、非法 doorbell、无效 peer/vector、畸形消息、ring 满和重试行为。
• 将三 cell 用例纳入稳定的 QEMU smoke，并从干净构建环境验证客户机镜像和测试资产准备流程。

第七周以“Message V1 可通过 ivshmem 稳定双向传输，失败路径不遗留资源，三 cell smoke 可重复通过”为完成标准。多 peer 权限隔离、完整状态表、quota/ACL 和性能优化继续放在接口稳定后推进。

[baitwo02]

第一周工作总结（7/17 - 7/19）：上一阶段工作收尾

整理了上一阶段的工作，并 rebase 到最新的 dev 分支。上一阶段的方案是基于 linker section discovery 的设备注册，经讨论认为该方案欠考虑：显式 composition root 多一行设备注册是合理且可审计的依赖，不需要用隐式链接机制消除，因此该方案未合入，本周工作主要是收尾和基线对齐。

第二周计划（7/20 - 7/26）：多页共享内存管理。

• 阅读和理解当前 IVC/HVC 的设计与架构：axhvc 的 hypercall ABI 约定（参数为 GPA 指针）、axvm/src/runtime/hvc.rs 的 publish/subscribe 处理流程与错误回滚路径、axvm/src/runtime/ivc.rs 的通道表与 IVCChannel 生命周期、axdevice 的每 VM IVC GPA 池分配
• 设计 SharedPageSet 实现多页映射：用 SharedPageSet 统一管理为 hypervisor 分配的 frames（基于已有的 alloc_frames/dealloc_frames 接口），负责连续 HPA 区间的持有、页数记录和统一释放；IVCChannel 由持有单个 frame 改为持有 SharedPageSet，publish 路径按请求大小分配多页并逐段做 stage-2 映射。
• 确定 size 对齐策略（4 KiB 对齐）与最大值分档，明确 SharedPageSet 与 IVCChannel、GPA 池之间的职责边界。

[baitwo02]

第二周工作总结（7/20 - 7/26）：多页共享内存管理

完成 IVC 通道从单页到多页的扩展，并按 TDD 策略开发：先写确定性回归测试并验证其在旧实现上必然失败，再实现功能使测试通过。

• 现状分析：梳理 axhvc hypercall ABI（GPA 指针参数、实际大小写回）、hvc.rs 的 publish/subscribe 流程与错误回滚、ivc.rs 的通道表与 IVCChannel 生命周期、axdevice 的每 VM GPA 池。定位单页假设集中于 IVCChannel::alloc/Drop 与 MAX_IVC_CHANNEL_SIZE 三处，链路其余环节（map_linear、GPA 池、axivc 协议层）原生支持多页。
• 方案决策：对比"连续 HPA 一次分配"与"逐帧分配 + 分段映射"后选择前者——alloc_frames 提供连续物理页、map_linear 要求 HPA 连续，一组连续帧用 base + size 即可完整描述，订阅路径一次调用完成整段 stage-2 映射，无需引入 SharedPageSet 页帧列表（仅在将来支持非连续散列页时才必要，记录为后续可能改进方向）。
• 实现：IVCChannel::alloc 改用 alloc_frames 连续分配，Drop 改用 dealloc_frames 按页数统一释放；大小 4 KiB 向上对齐，上限提升至 1 MiB，超限截断并写回实际大小，0 大小显式报错；ABI 不变。
• 测试与验证（TDD）：先编写 4 个回归测试（mock PagingHandler，覆盖多页分配/释放、单页、超限截断、0 大小拒绝），确认多页与 0 大小两项在旧实现上失败；实现后 cargo test -p axvm 98 项全过。demo 通道扩至 64 KiB（16 页），publisher/subscriber 的 iomap 改用写回的实际大小；axvm 全 feature 组合 clippy、fmt、QEMU 端到端 smoke（ArceOS publisher + Linux subscriber，双方确认映射 65536 字节、request/ack 全通）全部通过。

第三周计划（7/27 - 8/2）：双工通信完善

• 弄清 commit 52180bf 把 Linux subscriber 改成只读的原因，修复根本问题后恢复其 ACK 写路径。
• 把双向 demo 做成 issue 描述的效果：publisher 发 Request、subscriber 收后回 Ack、publisher 打印 acked seq=N，用 notify IRQ 驱动双向事件而非纯轮询。
• 在 test-suit smoke 测试中加双向断言：subscriber 的 recv seq 连续递增、publisher 的 acked seq 连续递增；按 TDD 先补失败断言再实现；本地跑通 axvisor qemu IVC 测试后收尾。

[baitwo02]

第三周工作总结（7/27 - 8/2）：双工通信与 Message V1 协议加固

本周围绕双工通信继续推进。排查 Linux subscriber 只读路径后，确认仅恢复一次 ACK 写入不足以形成可扩展、可验证的双向协议：现有 Linux 镜像中的 axvisor.ko 仍使用 region v2 固定 slot，而 Rust 侧需要支持跨 slot、跨 ring 容量的完整逻辑消息。因此先完成 Rust 协议层和 ArceOS 双 VM 基线，再进入 Linux 配套适配。

• 双工通信：将 ArceOS publisher/subscriber 改为独立收发流程，完成 Request/Ack/Data 双向交互；publisher 校验有序 ACK 和 Data，subscriber 校验 Request 后返回 ACK。
• SPSC 约束加固：增加 endpoint ownership 检查，并限制每个 SPSC 通道只允许一个 subscriber，避免重复初始化或多消费者破坏 ring 不变量。
• Message V1：将固定 slot 消息替换为分片逻辑消息。每个 64 字节 cell 使用 24 字节帧头和 40 字节载荷，通过 FIRST/LAST/ABORT、传输 ID、分片序号和声明长度完成重组；发送端和接收端均支持非阻塞部分进度与严格帧校验。
• 兼容性策略：region 版本升级到 v3，v2/v3 peer 显式拒绝互通，不做静默降级；ring 基础布局、事件接口和 HVC publish/subscribe/notify ABI 保持不变。
• 测试与验证：补充单帧边界及超过 ring 瞬时容量的测试，覆盖 39/40/41/640/700 字节 Request 和 41/641/700 字节 Data；Rust 单测、clippy、fmt 以及 ArceOS publisher + ArceOS subscriber 的 QEMU 双 VM 全双工测试均通过。

Linux 端尚不能直接使用当前 tgosimages v0.0.10：其中的内核模块仍实现 region v2。后续需要同步更新 axvisor-tools 驱动、Linux 用户态 demo 和 tgosimages rootfs，才能恢复 ArceOS 与 Linux 的干净环境端到端测试。

第四周计划（8/3 - 8/9）：完成 Linux Message V1 互操作与发布闭环

• 在 axvisor-tools 中实现 region v3 与 Message V1：加入分片发送/重组、消息级 read/write 语义、协议错误处理和 host 侧确定性单测，同时保持现有 HVC ABI 不变。
• 同步 Linux publisher/subscriber 用户态协议，实现 Request/Ack/Data 编解码、有序序列和长度校验；短写按消息错误处理，不能将一条逻辑消息拆成多次 write()。
• 跑通 ArceOS publisher + Linux subscriber 的 QEMU 全双工用例，验证跨分片、跨 ring 容量消息以及 Linux 专用 ACK 标记。
• 完成跨仓库发布顺序：先提交并合入 axvisor-tools，再由 tgosimages 构建并发布包含新 axvisor.ko 的 Alpine rootfs，最后更新 tgoskits 镜像 registry，并从干净缓存复跑 CI 。

[baitwo02]

第四周工作总结（8/3 - 8/9）：Linux 侧 region v3 与 Message V1 迁移

本周主要在 axvisor-tools 完成 Linux 侧 IVC 协议向 region v3 + Message V1 的迁移，并与 Rust 侧 axivc 的协议实现对齐，相关工作集中在 ivc-message-v1 分支。

• region v3：新增 includes/region.h 和 region.c，对齐 axvm host 侧 IVCChannelHeader 布局，包括 magic/version/features 和双向 ring offset。实现 axivc_region_init_publisher，用于 publisher 侧协议区域复位，同时保留 host 写入的 publisher_id 和 key；实现 axivc_region_validate，用于 subscriber 侧校验，并区分不同错误情况：尺寸或归属不匹配返回 -EINVAL，对端尚未发布返回 -EAGAIN，v2 等不兼容布局返回 -EPROTO。
• Message V1 移植：新增 includes/message.h 和 message.c，将 Rust 侧 IvcMessageSender / IvcMessageReceiver 的逻辑移植到 C。每个 64 字节 cell 由 24 字节小端帧头和 40 字节分片载荷组成，通过 FIRST/LAST/ABORT 标志、message_id 和声明长度完成消息重组。行为上保持与 Rust 侧一致：不允许消息交织，接收时先校验再消费；遇到协议错误后 receiver 进入 poison 状态，后续调用持续返回同一错误，因为 V1 协议本身没有可靠的重同步标记。
• 统一 send/recv API：调整 ivc.c 的收发逻辑，将一次 read(2) / write(2) 对应为一条完整逻辑消息，短写直接按消息发送失败处理。由于返回值 0 已用于表示 ring 为空，POSIX 适配层暂不支持空消息。ring.c 进一步简化为 opaque-cell 的 SPSC 语义，并同步更新 ulib、pybind 和 publish/subscribe demo。
• 修复：修正 aarch64 下 HVC 返回值和输出指针的处理；针对 -EAGAIN 增加带 deadline 的有界等待和重试，避免忙等，同时保证 peer 恢复后能够继续观察到 ABORT。补齐错误路径下的资源清理和 recv buffer 校验，避免底层协议错误码被后续错误覆盖。
• 兼容性策略：保持与 Rust 侧一致，v2/v3 peer 之间显式拒绝互通并返回 -EPROTO，不做静默降级。HVC 的 publish/subscribe/notify ABI 保持不变。

目前还剩两个收尾项：一是走通 axvisor-tools → tgosimages rootfs → tgoskits registry 的跨仓库发布流程，并验证干净缓存环境下的 CI；二是重新完成 ArceOS publisher + Linux subscriber 的 QEMU 全双工端到端验证。

第五周计划（8/10 - 8/16）：IVC 设备向 PCI（ivshmem）迁移

• 梳理现有 ivshmem 的共享内存映射、设备配置、通知中断、VM 生命周期以及各 OS glue，明确可以直接复用的 IVC / shared-memory 能力，并确定迁移后的接口边界和兼容目标。
• 设计 PCI 设备形态，包括 vendor/device ID、BAR 布局、region 共享内存映射方式以及中断机制（MSI-X / INTx）。与 AxVisor host 侧设备模型对齐后，形成一版初步设计方案。
• 按 backend core、AxVisor 接入和 guest 可见接口几个阶段推进迁移，优先打通一个行为等价的最小端到端用例。继续复用现有 region/message 协议层，主要工作放在 PCI probe、资源映射和生命周期管理上。
• 迁移阶段只补充保证重构安全所必需的底层确定性测试和 smoke 测试，不在接口尚未稳定时提前扩展完整测试矩阵。Linux publisher 反向角色、错误路径和资源回收等场景，等 PCI 迁移稳定后再统一补齐。

[baitwo02]

第五周工作总结（8/10 - 8/16）：vPCI 基础实现与 AArch64 主线接入

本周围绕 ivshmem 迁移所需的 PCI 基础设施开展工作，完成了架构无关的虚拟 PCI Type-0/ECAM 基础，并将 PCI 设备接入 AArch64 主线 VM 构建流程。

• vPCI 基础实现：在 axdevice 中新增类型化的 BDF、配置空间偏移、BAR 和 capability 模型，实现 Type-0 配置空间、ECAM 访问、设备标识与 capability 链。支持 32/64 位 Memory BAR 的探测、地址分配与重定位，并根据 PCI command register 的 Memory Space Enable 状态控制 BAR 访问。
• 确定性资源规划：PCI host 与 endpoint 作为独立节点接入 resolved device graph。ECAM、PCI memory aperture、BDF 和 BAR 均由统一资源规划阶段确定，能够检测重复 BDF、BAR 冲突、地址越界和 aperture 耗尽，避免固件描述与运行时路由使用两套资源信息。
• 生命周期与事务接入：新增 PciEndpointModel 和对应的 bundle 绑定机制。endpoint handler 与设备资源 lease 保持同一生命周期；设备注册、资源 claim 或 VM 构建失败时会自动回滚，避免 root complex 中残留失效 function。
• 配置层接入：在现有 configured device catalog 中增加类型化 PCI endpoint 注册，与 platform device 分流处理，同时共用 model-name namespace，不依赖字符串扫描或运行时 downcast。
• AArch64 主线接入：仅在 VM 配置包含 PCI endpoint 时创建 generic ECAM host，从 AArch64 MMIO 池中统一分配 1 MiB ECAM 和 64 MiB 32-bit non-prefetchable memory aperture，并按 VGIC/ITS → PCI host → endpoint 的依赖顺序完成构建。
• 客户机固件描述：从解析后的 PCI bus 生成 pci-host-ecam-generic FDT 节点，包括 reg、bus-range、ranges 和 dma-coherent。已有 PCI bridge、与顶层 reg 冲突或没有 DTB 的配置会显式失败，不进行静默覆盖。
• 测试覆盖：补充配置空间访问、capability、BAR probe/relocation、确定性拓扑分配、冲突检测、注册失败回滚、AArch64 PCI 计划和 FDT 生成等确定性测试。

本阶段完成的是后续 ivshmem endpoint 所需的 PCI 枚举、配置空间、BAR 路由和 AArch64 固件基础，PCI 中断暂未接入；后续 ivshmem 中断路径计划先仅实现 MSI-X，不支持 INTx fallback。

第六周计划（8/17 - 8/23）：最小 ivshmem 与 Linux/Zephyr 通信

本周计划基于已经完成的 vPCI 基础实现一个最小化 ivshmem endpoint，并以 ArceOS/AxVisor 作为 root cell，启动 Linux 和 Zephyr 两个客户机，优先跑通共享内存基本通信。

• 在 configured device catalog 中注册最小 ivshmem PCI endpoint，定义稳定的 vendor/device ID、BAR0 最小控制寄存器和 BAR2 共享内存区域。
• 中断路径仅实现 MSI-X，通过 doorbell 定向通知目标 peer，不提供 INTx fallback。
• 由 root cell 负责共享内存 backing、peer 关系和 endpoint 生命周期，将同一共享区域映射到 Linux 与 Zephyr 的 BAR2，并保证 VM 创建失败、停止或重启时能够正确回收。
• Linux 侧先验证 generic ECAM 枚举、PCI probe 和 BAR 映射；Zephyr 侧完成对应的最小映射与读写适配。
• 使用简单 mailbox、序列号和 checksum 跑通 Linux → Zephyr 请求、Zephyr → Linux 应答的双向通信，形成可重复验证的基本数据面闭环。
• 增加 AArch64 QEMU 三 cell smoke 测试，检查 PCI 枚举、双方 BAR2 映射、消息序列和 payload 校验结果。

本周以“设备可枚举、共享区可映射、MSI-X doorbell 可定向通知、Linux 与 Zephyr 可双向交换并校验数据”为完成标准。完整 Message V1、多 peer 权限隔离和完整错误矩阵暂不作为本周目标；现有 HVC IVC 路径继续保留，避免 PCI 接口尚未稳定时影响已有通信基线。

[baitwo02]

第六周工作总结（8/17 - 8/23）：vPCI 设计收敛与最小设备框架

上周继续推进 PR #2169。在重新审查前期代码后，对 PCI 架构设计进行了调整，重点收敛职责边界，移除冗余流程和非必要抽象，并优先形成可以运行和验证的最小实现。

• PCI 架构调整：重新梳理 PCI host、PCI function、配置空间和 VM 设备框架之间的关系，移除重复状态、中间转换以及现阶段不需要的额外抽象，使设备声明、资源规划和运行时构建之间的边界更加清晰。
• 最小 PCI 设备框架：完成 PCI host 和 endpoint 的基本注册、初始化及生命周期接入，使 PCI 设备能够随 VM 设备图完成资源规划和运行时构建。
• 配置空间访问：实现最小 Type-0 配置空间和 ECAM 访问路径，Guest OS 已能够枚举 PCI 设备，并读取 vendor ID、device ID、class 和 BAR 等基本属性。
• 资源规划基础：将 ECAM、PCI memory aperture、BDF 和 BAR 纳入统一规划，为后续 BAR MMIO 路由和 ivshmem 设备接入建立基础。
• 基础验证：通过单元测试和 Guest 侧验证，确认 PCI 设备可以正常注册和初始化，Guest OS 能够发现设备并获取预期的配置空间属性。

当前已经形成一个可运行、可验证的最小 PCI 设备框架。下一阶段将在此基础上实现完整的 ivshmem 功能，并补充相应的设计与使用文档。

第七周计划（8/24 - 8/30）：完成 ivshmem 功能与相关文档

下一周优先实现完整的 ivshmem 功能，在数据面和通知路径稳定后，再完善 PCI 与 ivshmem 文档。

• 完善 ivshmem PCI 设备模型：补齐 ivshmem 所需的设备标识、控制寄存器、BAR 布局和配置空间行为，使 Guest OS 能够完成标准 PCI 枚举、BAR 映射和设备初始化。
• 实现共享内存数据面：为 BAR2 接入由 root cell 管理的共享 backing，将同一共享区域映射给参与通信的 Guest，并明确 owner、peer 和访问权限。
• 实现 BAR 访问路由：打通 Guest MMIO 访问、PCI memory aperture、BAR 匹配和 endpoint handler 之间的完整路径，并保证 Guest 重编程 BAR 后运行时路由能够同步更新。
• 实现 MSI-X 通知：补齐 MSI-X capability、table/PBA 和 doorbell 通知路径，使 Guest 能够通过中断定向通知目标 peer；本阶段不提供 INTx fallback。
• 完善生命周期和错误处理：覆盖 VM 创建失败、endpoint 注册失败、Guest 停止或重启等场景，确保共享 backing、BAR binding 和 MSI-X 资源能够正确回收，不遗留失效状态。
• 完成端到端验证：增加确定性单元测试和 AArch64 QEMU 测试，验证 PCI 枚举、BAR2 映射与读写、MSI-X 通知以及 Guest 间共享内存通信。
• 补充 PCI 文档：整理 PCI host、function、配置空间、资源规划、BAR 分配与动态路由、设备注册和生命周期等设计，说明新增 PCI endpoint 的接入方式。
• 补充 ivshmem 文档：说明设备模型、BAR 布局、共享 backing、peer 关系、MSI-X doorbell、Guest 侧使用流程、限制条件和测试方法。

下一周以“ivshmem 设备能够被 Guest 正常枚举和初始化，Guest 间可以通过 BAR2 共享内存与 MSI-X 通知完成稳定通信”为主要完成标准；功能闭环后同步完成 PCI 和 ivshmem 文档，保证实现、设计和使用方式保持一致。

[baitwo02]

第七周工作总结（8/24 - 8/30）：CI 收尾与 ivshmem 功能推进

PR #2068 第七周主要处理 Linux 测试镜像和 CI 的收尾问题。此前测试需要在本地拉取 Linux 源码并现场编译内核模块，但 CI 环境经常因网络问题无法完成下载和构建。现在改为在本地编译并打包包含新版 axvisor.ko 和用户态程序的镜像，通过个人 fork 的 tgosimages 仓库发布，再由 tgoskits 的测试流程直接拉取固定版本镜像运行。这样减少了 CI 对外部源码和现场编译环境的依赖，也让 Message V1 的 Linux 互操作测试可以使用一致的镜像重复执行。

PR #2169 ，第七周重点处理这些改动在 CI 和 OrangePi 板卡上的兼容问题。原先 PCI host 使用的地址范围可能与 OrangePi 上已有设备的 MMIO 区域冲突，即使虚拟机没有配置 PCI endpoint，也会创建不需要的 PCI host。

当前实现改为仅在配置文件中存在 PCI endpoint 时初始化 PCI host，未使用 PCI 设备的虚拟机保持原有设备布局。同时扩大 PCI host 的资源搜索范围，从 4 GiB 以下的可用 MMIO 空间中选择不冲突的 ECAM 和 PCI memory aperture，避免与板载设备竞争固定地址。该调整兼顾了 QEMU 中的虚拟 PCI 用例和实体板卡上原有虚拟机配置。

PR #2239 在已有 vPCI 基础上，初步完成了 ivshmem PCI 设备的大部分功能，包括设备标识、BAR 布局、共享内存 backing、状态表、访问权限以及设备生命周期管理。

Guest 镜像中加入了 pciutils，Linux Guest 现在可以通过 lspci 枚举并检查 ivshmem PCI 设备。设备侧实现了 BAR0 控制寄存器模型以及 peer、state、event status 和 doorbell 等寄存器，并完成 doorbell 事件的基本路由。BAR2 已接入共享内存，可以按 peer 划分区域并设置不同的访问权限。目前单 VM 下的 PCI 枚举、寄存器访问、共享内存读写和轮询通知已经能够运行，但同时启动多个 VM 时仍存在问题，多 peer 端到端通信还没有完全跑通。

第八周计划（8/31 - 9/6）：解决多 VM 通信并完成通知闭环

本周优先解决多个 VM 同时启动失败的问题，重点检查 ivshmem link 的 reservation、runtime attachment、peer ID 分配、共享 backing 生命周期和 BAR2 stage-2 映射，确认多个 endpoint 能够加入同一 link，并在退出或失败时正确释放资源。在此基础上增加确定性的双 VM QEMU 用例，验证两个 Guest 都能枚举设备、映射同一块共享内存，并看到对方发布的状态和数据。

多 VM 基础路径稳定后，继续完善 doorbell 通知。当前通知主要依赖 Event Status 轮询，本周计划进一步检查 MSI-X table、PBA 和中断注入路径，争取完成从 doorbell 写入到目标 Guest 接收中断的闭环。如果 MSI-X 接入无法在本周全部完成，至少固定寄存器和 doorbell 行为，并保留可重复运行的轮询测试。

[baitwo02]

第八周工作总结（8/31 - 9/6）：完成多 peer 接入

上周主要完成了 ivshmem-pci 的多 peer 接入，继续推进 PR #2239。此前已经跑通单 VM 下的 PCI 枚举、寄存器访问、共享内存读写和轮询通知，但多个 VM 同时启动及加入同一 ivshmem link 的路径尚未打通。本周重点解决了这一阶段的接入问题，使多个 Guest 的 endpoint 能够共同接入同一 link，为后续多 peer 通信验证建立基础。

接下来的重点是整理配套 Guest 镜像，把所需驱动、用户态程序和测试工具纳入固定版本镜像，减少联调过程中手工准备环境的步骤。

第九周工作计划（9/7 - 9/13）：镜像集成与跨仓库合入

本周按照三仓库协同计划处理镜像及配套改动，正式推进顺序为 axvisor-tools → tgosimages → 官方镜像发布与验证 → TGOSKits。构建和测试可以先在 fork 上准备，但最终沿用官方的常规 QEMU + Alpine 镜像流程，不新增独立镜像生产线。

整理协议与驱动源码

从 axvisor-tools 最新上游基线重新整理两个独立 feature：已有 Message V1 协议及 Linux 配套实现，以及从 TGOSKits 迁入顶层 uio_ivshmem/ 的设备驱动。先确认协议名称和兼容边界，将名称调整与线格式变化分开处理；驱动则明确 KDIR、ARCH、CROSS_COMPILE 和 UIO 符号表等构建接口。两个 feature 分开审核、提交并推进上游合入，为镜像仓库提供可复现的源码引用和构建方式。

接入常规镜像流程

在 tgosimages 现有 qemu.sh 构建和 overlay 注入流程中接入上述产物，为 Alpine 加入 pciutils，不再维护 uio_ivshmem 驱动源码副本。Guest kernel、uio.ko、axvisor.ko 和 uio_ivshmem.ko 使用同一内核构建树，检查最终内核配置、符号依赖及缓存复用，避免旧内核与新模块混用。

前期使用 fork 的明确提交验证；待 axvisor-tools 上游合入后，切回官方依赖并重新验证，再推进 tgosimages 合入。随后跟踪标准 QEMU bundle、Alpine rootfs 和官方 registry 的发布，下载实际归档核对 SHA-256、模块内容及启动结果。源码合入不视为镜像已经可用。

迁移测试镜像并验证

官方镜像发布验证通过后，按 ivc-message-v1 → vpci → ivshmem-pci 的顺序整理 TGOSKits 分支，执行时重新核对实际依赖。统一使用同一发布批次的 kernel/rootfs，复用公共镜像消费逻辑；对自行组装 initramfs 的测例，显式提取并注入模块、工具及动态依赖，不再将开发机模块目录作为默认 CI 的必备输入。驱动权威来源迁到 axvisor-tools 后，同步清理重复源码并调整调用链。

验证保留已有 IVC 协议覆盖，并按各分支范围检查 PCI 枚举、BAR 访问、Linux/ArceOS peer、双/三 peer、轮询和 MSI-X 通知。中断测试要求真实跨 peer 送达，不能以模块加载成功代替通信验证。

本周目标是推进这条官方镜像集成与消费链路；各阶段按前置条件逐项完成，不跳过上游合入和正式发布关卡。记录各仓库提交、镜像版本、验证结果及剩余阻塞，满足条件后再推进后续分支合入和解除 draft。

[baitwo02]

第九周工作总结（9/7 - 9/13）：Guest 侧代码整理与镜像构建集成

第九周主要整理了 axvisor-tools 中的协议、驱动及配套程序，并完成 tgosimages 常规镜像构建流程的接入。目前相关改动均已合入，后续等待镜像发布，再调整 TGOSKits 的镜像使用方式。

axvisor-tools 代码整理

PR #9 已合入。

• 将已有 region v3 + Message V1 实现按协议、ring 布局、用户态接口和示例程序分拆整理，统一 publisher/subscriber 的双向消息收发接口，同步更新 demo 和 Python bindings。
• 将传输单元统一称为 slot，大小调整为 256 字节，ring 容量调整为 32 个 slot。这部分涉及实际共享区布局变化，后续需要与 TGOSKits 侧同步验证兼容性。
• 将 uio_ivshmem 驱动迁入顶层独立目录，整理外部模块构建接口，支持指定内核构建树、目标架构、交叉编译工具链和额外符号表。由 axvisor-tools 统一维护驱动源码，镜像仓库不再维护副本。

tgosimages 镜像构建集成

PR #19 已合入。

• 为 Alpine 默认包加入 pciutils，方便 Guest 使用 lspci 检查 PCI 设备。
• 在现有 QEMU 构建流程中配置 UIO、PCI MSI 和 ITS 支持，从 Guest 内核树构建 uio.ko，从 axvisor-tools 构建 axvisor.ko 和 uio_ivshmem.ko，保证相关模块使用同一内核构建树。
• 将模块与配套程序通过现有 overlay 注入 Alpine rootfs，继续沿用常规 QEMU + Alpine 镜像构建与发布流程，不新增独立镜像生产线。
• 完成本地模块构建和 rootfs 注入验证，并在收尾中补充内核缓存一致性检查，避免旧内核与新模块混用。

目前源码整理和构建集成已经合入，剩余前置条件是包含上述改动的官方镜像正式发布。源码合入和本地构建通过，尚不等同于发布镜像及跨 peer 通信验证完成。

第十周工作计划（9/14 - 9/20）：发布镜像验证与消费端迁移

第十周重点转向镜像发布后的使用方式调整，完成“官方镜像发布 → TGOSKits 消费端迁移 → 干净环境回归”的闭环。

1. 跟进镜像发布并验收：等待包含上述改动的官方 QEMU bundle、Alpine rootfs 和 registry 发布。下载实际归档，核对 SHA-256、模块及工具内容，确认 kernel/rootfs 来自同一发布批次，并完成启动和模块加载验证。
2. 调整 TGOSKits 镜像使用方式：按实际依赖依次整理 ivc-message-v1、vpci 和 ivshmem-pci，更新镜像引用，统一使用新发布的 kernel/rootfs，复用公共镜像获取逻辑，移除对本地编译产物和开发机模块目录的默认依赖。
3. 整理测试资产与驱动调用链：对自行组装 initramfs 的测例，调整模块、用户态工具及动态依赖的提取和注入方式；清理 TGOSKits 中重复的 uio_ivshmem 驱动源码，统一消费镜像中的配套产物。
4. 完成回归与端到端验证：从干净缓存复跑已有 IVC 协议测试，确认新的 slot/ring 布局与 TGOSKits 实现一致；随后按各分支范围验证 PCI 枚举、BAR 访问、多 peer 共享内存通信、轮询及 MSI-X 通知。中断测试以真实跨 peer 送达为准，不以模块加载成功代替通信验证。

镜像发布前先梳理消费端改动和测试入口；发布验收通过后再切换正式引用，并根据回归结果推进后续分支合入。

[baitwo02]

第十周工作总结（9/14 - 9/20）：统一内核模块与消费端协议对齐

本周原计划在官方镜像发布后完成消费端迁移，实际推进时先把跨仓库构建链路收敛为“一个内核模块 + 一套镜像”：axvisor-tools 通过根目录 Kbuild 把 IVC 与 IVSHMEM 两个 feature 链接为单个 axvisor.ko，tgosimages 的 QEMU 构建改为只构建、注入这一个模块；TGOSKits 侧同步把 axivc 的共享区布局对齐到新的 256 字节 slot，并把 StarryOS 的 IVC 设备迁移到 Message V1。

axvisor-tools：统一模块构建 PR #10 。

• 重新整理仓库布局：内核源码从 ivc/kernel_driver/ 移到 ivc/，内核与用户态共享的 ioctl 与设备名 ABI 头放入 ivc/uapi/，用户态库整理到 userspace/ivc/，示例程序移到 demo/，Python 绑定移到 pybind/。demo 的应用协议代码保留在 demo/，不再编入 libivc。
• 新增根目录 Kbuild，通过 obj-m := axvisor.o 把 ivc/ 和 uio_ivshmem/ 的源文件链接为单个 axvisor.ko；根 Makefile 提供 kernel_module、libivc、demo 和清理目标，模块产物统一为 ./axvisor.ko。
• IVSHMEM PCI 驱动不再单独成模块，改为提供 axvisor_ivshmem_register() 和 axvisor_ivshmem_unregister()，由 main.c 在模块初始化和退出时调用。系统没有 ivshmem 设备时注册也成功，单个设备 probe 失败由该设备自行清理。
• 合并后的模块统一使用 GPL 许可标签，因为 UIO 核心符号是 GPL-only；各源文件保留原有许可。驱动 ABI 以及 libivc.a、libivc.so 的产物名保持不变。

tgosimages：镜像构建适配 PR #20 。

• QEMU aarch64 Linux 把 UIO 从模块改为内建（CONFIG_UIO=y），并显式启用 CONFIG_PCI，与 CONFIG_PCI_MSI、CONFIG_ARM_GIC_V3_ITS 一起纳入内核缓存校验，保证 axvisor.ko 与 rootfs 使用同一内核构建树的符号。
• 镜像流程只构建、注入统一的 axvisor.ko，删除 uio.ko、uio_ivshmem.ko 的独立构建、KBUILD_EXTRA_SYMBOLS 传递、注入和校验；改从 axvisor-tools 根目录按 kernel_module 和 demo 两个入口取产物。
• 构建前先 fetch 指定的 axvisor-tools ref，避免复用未更新的本地分支；清理内核模块时使用 Kbuild clean，不会误删用户态 demo。
• 顺带把 Alpine 测试包的 xz-libs 更新到 5.8.4-r0。

TGOSKits：协议布局对齐与 StarryOS 迁移

• 共享区布局对齐：ring 传输单元统一称为 slot，slot 为 256 字节、每 ring 32 个，region 大小 17152 字节，两个 ring 头位于偏移 256 和 8704。feature 位随命名更新，region 版本保持 3，但旧 v3 布局和 v2 peer 都会显式拒绝，不做静默降级。
• 新增直接断言 region 尺寸、对齐和字段偏移的 ABI 测试。只做往返测试时，双方使用同一种错误布局也能通过，这个测试补上了这一缺口；ArceOS demo 的 payload 边界、文档和 std 测试白名单同步更新。
• axivc 侧接口在前几周已经切到 Message V1 的分片收发，StarryOS 侧仍使用固定 slot 的 producer 和 consumer，本次一并迁移：新增 DeviceMessageIo，让 read(2) 和 write(2) 把完整用户缓冲区交给设备层，不再按 VFS 字节块切分，一次读写对应一条完整逻辑消息。
• 收发方向各自持锁，且不与 channel 注册表锁嵌套；syscall 期间持有 mapping lease，取消和 ABORT 清理过程中区域不会被 unpublish 或 unsubscribe 提前释放。发送前检查消息就绪和 ring 容量，支持跨 ring 瞬时容量的分片；被中断的发送会发 ABORT，背压下保留待发的 ABORT；接收不完整时标记流失败，poll 按方向就绪返回 IN 或 OUT，失败时返回 ERR。
• 补充跨 ring 与 VFS 边界、非阻塞不丢输入、取消与拷贝失败、背压等确定性测试。rebase 到最新 dev 后收起了 axvm 中与上游重复的共享区清零逻辑，避免同一保证由两份实现维护。

统一构建和镜像适配已经合入，协议对齐与 StarryOS 迁移已经更新到 PR #2068，当前剩下的依赖是镜像。

第十一周工作计划（9/21 - 9/27）：镜像重建与跨仓库回归

1. 重建并锁定 IVC 镜像：按 tgosimages 新流程产出包含统一 axvisor.ko（256 字节 slot）的 QEMU aarch64 Alpine rootfs，核对归档 SHA-256、模块内容和内核与 rootfs 的发布批次；更新 .github/ci/checks/axvisor.toml 中的 registry 和 tag，替换当前 8 月下旬的旧镜像。
2. 完成 IVC 端到端回归：从干净缓存复跑 qemu-ivc（ArceOS publisher 与 Linux subscriber），确认 Request/Ack 全部通过以及 Linux 侧输出 linux ivc demo pass；补充 Linux publisher 反向角色和跨 ring 容量 payload 的覆盖。
3. 验证 StarryOS 侧设备：结合板卡的 Starry IVC 用例或在本地补充 QEMU 场景，确认 axivc 设备的分片收发、非阻塞读写和 poll 行为，验证这次迁移没有破坏 StarryOS 作为 IVC guest 的路径。
4. 推进 PR feat(ivc): add fragmented Message V1 full-duplex transport #2068 合入：根据审查意见收尾，确认布局兼容性说明和测试位置后推进合入。
5. 推进 vpci 和 ivshmem-pci 分支：按 ivc-message-v1、vpci、ivshmem-pci 的顺序 rebase 到最新 dev，更新 PR feat(axdevice): add typed virtual PCI and AArch64 ECAM support #2169 和 draft PR feat(axvisor): add ivshmem PCI shared-memory communication #2239，验证 PCI 枚举、BAR 访问、多 peer 共享内存和 MSI-X 通知，中断以真实跨 peer 送达为准。
6. 官方镜像发布后切换正式引用：跟踪包含统一模块的官方 registry 发布，验收后把 TGOSKits 测试从 fork 引用切到正式镜像，在消费端稳定后再解除 ivshmem PR 的 draft。

镜像重建和端到端回归是本周的主线；官方镜像未发布前先用固定提交的 fork 镜像验证，发布验收通过后再切换正式引用。

[baitwo02]

第十一周工作总结（9/21 - 9/27）：审查意见收尾与 PR 合入推进

本周主要围绕三个 PR 的审查反馈做收尾，推进合入：PR #2068（Message V1）、PR #2517（AArch64 ECAM PCI host 与初始 ivshmem endpoint）和 PR #2239（ivshmem 多 peer，仍为 draft）。包含统一 axvisor.ko（256 字节 slot）的官方镜像已经发布，#2068 和 #2517 的测试均已切换为消费上游正式发布的镜像。

PR #2068：Message V1 阻塞项修复与 CI 收敛

• 修复 mai-team-app 指出的阻塞问题：IvcMessageReceiver 此前会接受"已收满声明长度但未带 LAST"的帧，使接收端停留在无法完成的 Receiving 状态；现在对这类帧显式返回 MissingLast 错误，并补充了回归测试。
• StarryOS 侧保留 in-tree 的 legacy IVC v2 协议路径，Message V1 迁移不影响其现有 /dev/axivc 行为。
• 处理 CI 相关问题：临时 QEMU 用例改为从源码构建 IVC publisher，不再依赖预构建产物；在 ivshmem 迁移完成前挂起 legacy IVC 检查；修复 nix dev shell 下共享 Cargo home 丢失的问题。
• 当前状态：当前 head 的组织 CI 23 项检查全部通过，包括 AxVisor aarch64 IVC QEMU 用例和 std tests；mai-team-app 复审已转为非阻塞建议（仅剩 PR 描述与实际差异需要收敛）。剩余待处理的是 Josen-B 9/24 的审查意见；其早先关于 cell 元数据开销的意见已由 256 字节 slot 布局解决，测试镜像也已改为复用现有 Alpine rootfs，不再单独发布新镜像。

PR #2517：vPCI 与初始 ivshmem endpoint 按审查意见重构

• 在 axvm-aarch64-pci-ecam 分支完成 AArch64 generic-ECAM PCI host（仅在被 endpoint 引用时才实例化，4 GiB 以下分配 1 MiB ECAM 和 64 MiB memory aperture，ECAM 与 memory frontend 共享一个 PciRootState）和初始 ivshmem PCI endpoint（BAR2 由 64 KiB 私有清零内存 backing，拒绝绕过 PCI BAR 路径的直接访问），并新增从工作区构建 ArceOS guest 的 QEMU CI 用例，验证 PCI 标识与 BAR2 读写。
• 按审查意见收敛实现：ECAM host 改为通过类型化 FDT PCI contribution 声明；PCI 冲突检查前先翻译嵌套 FDT reg ranges；ECAM 和 BAR 窗口改为从 guest DTB 发现，不再使用固定地址；移除跨架构源码引用并更新设计文档。
• 当前状态：CI 23 项全部通过。剩余一项阻塞：provided-DTB 路径没有注入已解析的 PCI host 窗口，启用 PCI endpoint 的 guest 无法枚举设备且跳过冲突校验；另有 Copilot 三项未解决意见。该 PR 取代 feat(axdevice): add typed virtual PCI and AArch64 ECAM support #2169 的 AArch64 接入方案，合入前需要协调 feat(axdevice): add typed virtual PCI and AArch64 ECAM support #2169 的状态，避免重叠实现并行推进。

PR #2239：ivshmem guest 侧与构建链路完善

• 新增 Linux guest 适配器与 smoke 程序：发现 revision-1 PCI function，通过共享的用户态适配器映射 BAR0/BAR2，支持显式轮询或 UIO event 两种后端，寄存器与共享内存契约写入公共头文件。
• ArceOS guest 用例切换到 link-backed 协议：保留 FDT 发现的 PCI host 和翻译后的 BAR 地址，增加 peer 共享内存、state table、doorbell 和 mailbox 检查，QEMU 用例配置为单 peer link。
• axbuild 集成：ivshmem 用例改为从 managed image 准备 guest 资产，交叉编译 Linux guest 程序和 ArceOS peer，随 BusyBox initramfs 打包与内核匹配的 axvisor.ko；模块缺失时显式失败，不再回退到已废弃的独立 UIO 驱动。
• 修复 PCI capability 跨 endpoint effect 的 dword 读取：guest 一次 dword 读取 capability 头和控制寄存器时保持 MSI-X Message Control 的实时值，只对跨越 effect 的读拆分，写仍拒绝，并补充确定性回归。
• 起草了 AArch64 stage-2 abort injection 契约文档，为后续 fault 路径定型。

第十二周工作计划（9/28 - 10/4）：推进合入与依赖收敛

1. 推进 PR feat(ivc): add fragmented Message V1 full-duplex transport #2068 合入：处理 Josen-B 9/24 关于 axvisor.toml IVC 检查配置的审查意见，按 mai-team-app 的非阻塞建议收敛 PR 描述使其与实际差异一致，取得复审通过后完成合入。
2. 收尾 PR feat(axvm): add AArch64 ECAM PCI host and ivshmem endpoint #2517：修复 provided-DTB 路径未注入 PCI host 窗口的阻塞项并补充回归测试，处理 Copilot 剩余意见；与维护者协调 feat(axdevice): add typed virtual PCI and AArch64 ECAM support #2169 的关闭或范围收窄后推进合入。
3. 整理 PR feat(axvisor): add ivshmem PCI shared-memory communication #2239 并重构通信方案：在前置 PR 合入后按 ivc-message-v1 → vpci → ivshmem-pci 的顺序 rebase 到最新 dev。通信协议计划直接引入现有的 Message V1 方案，复用 256 字节 slot 的 ring 布局和分片收发逻辑，不再为 ivshmem 维护一套独立协议；多 VM 状态同步部分重新设计，目前的 peer state table 和 link 成员管理方案需要结合多 peer 生命周期、退出与失败回收重新梳理，先形成设计方案再调整实现。条件满足后解除 draft。
4. 清理镜像迁移遗留的临时措施：包含统一 axvisor.ko（256 字节 slot）的官方镜像已经发布，feat(ivc): add fragmented Message V1 full-duplex transport #2068 和 feat(axvm): add AArch64 ECAM PCI host and ivshmem endpoint #2517 的测试均已切换为消费上游正式发布的镜像。本周逐项清理此前的临时 workaround，例如 axvisor.toml 中"临时从源码构建 IVC publisher"的 pre-step，改为直接使用镜像中的配套程序，并从干净缓存复跑端到端回归确认无回退。

本周以"消除审查阻塞项、推动 #2068 与 #2517 达到可合入状态"为主要完成标准。