明确 DLI Host、Controller Backend 与内部 Channel Seam

[sanchuanhehe]

What to build

根据已公开的 OpenHarmony NearLink 调用链，为 OpenSparkLink 定义一个有深度的 Controller Backend Interface，并把 vendor lifecycle、channel 和物理 transport 留作 Adapter 内部 Seam；不要在 Linux 内核复刻 HDF/HDI IPC 服务。

建议结构：

Host Modules
  -> DLI Host Module
  -> Controller Backend Interface
     -> NativeBackend
     -> UserspaceProxyBackend -> slk-vendord -> OpaqueVendor Adapter
     -> VirtualBackend
     -> ExternalKernelBackend（可选、非首选）

公开 Controller Backend Interface 应是 probe/start/send/stop/recover 加 RX/fault/hangup callback 和 capability；它收发完整标准 DLI packet，但不暴露 SSAP、配对或 PHY policy。

DLI Host Module 独占标准 DLI command/event/data 语义、opcode 参数编码、event 解码、命令排序、completion 关联、timeout、version/capability 协商与恢复。

Backend variants

• NativeBackend：可在 Implementation 内组合 kernel DliChannel 与 USB、serdev/UART、SPI Transport Adapter。
• UserspaceProxyBackend：内核 Adapter 通过版本化 backend channel 与独立 slk-vendord 通信。daemon 在用户态加载闭源 vendor library，并将 vendor lifecycle ABI 与 fd channel 归一化为完整 DLI packet。
• VirtualBackend：通过内存 queue 和可控 event 实现相同 Interface，用于测试 DLI Host transaction、故障与恢复。
• ExternalKernelBackend：只在厂商无法提供标准 DLI 固件或用户态库时作为最后选项，通过小型 versioned C registration Interface 接入 out-of-tree module；不对厂商暴露 Rust ABI。

这里将“Opaque vendor 路径”定义为 UserspaceProxyBackend + slk-vendord + OpaqueVendor Adapter。内核中不 dlopen，也不让闭源库、vendor opcode 或 void * 参数进入公共 kernel Interface。若厂商固件能直接暴露标准 DLI，应优先使用 NativeBackend。

Internal seams

• Kernel DliChannel Interface：用于 Native/Virtual Adapter，负责 send packet、set receiver、close、backpressure、hangup 与 ownership；可由 USB endpoint、serdev、SPI 或 virtual queue 实现，并集中 framing、长度校验和 partial I/O。
• BackendProxy UAPI：仅供受信任 slk-vendord 注册/拥有一个 controller。它传输 lifecycle message 和完整标准 DLI packet，不等同于普通管理 chardev、raw DLI Interface 或 snoop Interface。
• Userspace VendorLifecycle Interface：在 slk-vendord 内将 size/init/op/close 封装成 typed operation；vendor opcode 和 void * 不得越过 Adapter。
• Userspace VendorDliChannel Interface：独占 vendor fd，集中 H4/DLI framing、partial I/O、epoll、backpressure、hangup 与 packet validation。

每个 SleDev 独占 DLI Host、Backend handle、channel/parser、queue、pending command、lease/generation 和 recovery state，不通过全局 active state 共享。

Closed vendor userspace integration

kernel DLI Host
  -> UserspaceProxyBackend
  <-> /dev/sparklink-backendN
  <-> slk-vendord
  -> typed VendorLifecycle Adapter
  -> closed vendor .so
  -> vendor fd / chip

BackendProxy UAPI v1 至少包括：

• REGISTER(abi_version, size, descriptor, capabilities, max_packet)，返回 controller id、独占 lease 与 generation；
• START/STOP/RESET/RECOVER 和 READY/FAILED/FAULT/HANGUP/UNREGISTER；
• kernel → daemon 的完整 DLI command/data packet；
• daemon → kernel 的完整 DLI event/data packet；
• version、message type、flags、controller id、generation、length、sequence/correlation id；
• 有界队列、背压、超时、overflow counter 和 fd-close 自动 detach。

第一版使用 read/write/poll 或 readv/writev。只有 benchmark 证明 copy/context switch 成为瓶颈时，才增加可协商的 mmap ring + eventfd；不要让共享内存布局成为 v1 的必要条件。

slk-vendord 必须独立于 slkd：前者只提供 controller transport/backend，后者继续拥有产品启用、D-Bus、配对/信任、SSAP/Profile 和 PHY policy。daemon 或 vendor library 崩溃、阻塞或 fd 关闭时，只使对应 controller unavailable，不拖垮 slkd 或其他 controller。

对应用户态实现与隔离要求由 OpenSparklink/sparklink#7 跟踪。

OpenHarmony reference evidence

已公开的调用链是：

ArkTS/C++ → nearlink_service → nearlink_dli_adapter → NearLink HCI HDI → 通用 peripheral NearLink HDI Implementation → vendor adapter → libnearlink_sle_vendor[_chiptype].z.so → chip

• drivers_interface PR 2004，提交 9ddb3c88f1ff7305034f5dfe8fe4f67e5382539e：HCI v1.0 只有 SleHalInit、SleSendHciPacket、Close 以及 initializationComplete、hciPacketReceived callback；v1.1 只增加 CheckOnBoardState。
• drivers_peripheral PR 8987，提交 b97be697c9cf0484305446f9a3f5104b74c8a629：通用 Implementation 负责 H4/DLI framing、fd watcher、HDI service、动态库加载和 packet callback。
• 公开 vendor ABI 是 SleVendorInterfaceT { size, init(), op(opcode,param), close() }。SLE_OP_DLI_CHANNEL_OPEN 返回 channel fd；通用 watcher/H4 parser 从 fd 读取后，再通过 HDI callback 上送。
• ABI 声明 power、init、LPM、wake、EVENT_CALLBACK 等 opcode，但当前通用 HCI 主路径只实际调用 channel open/close。init 不接收 callback，EVENT_CALLBACK 也没有当前调用点。
• 动态库按 const.nearlink.slechiptype 选择 libnearlink_sle_vendor[_chiptype].z.so，并要求 NEARLINK_VENDOR_LIB_INTERFACE；公开源码树没有真正芯片 vendor library。
• 通用 CheckOnBoardState 当前硬编码 true，不能作为真实硬件探测。
• 通用 HDI 还在下层编码 DLI_SET_SLE_ADDR 并处理其 CommandComplete。这是标准 DLI 知识向下泄漏的反例，不应复制到 OpenSparkLink Backend。

上述事实说明：值得借鉴的是小型 vendor Adapter 及通用 channel/framing Implementation，不是 OpenHarmony 的 IPC/HDF 服务形态。OpenSparkLink 在 Linux 上进一步把闭源 library 隔离到独立用户态 daemon。

Proposed ownership

能力	内核	用户态
标准 DLI command/event/data、事务、timeout、capability/version	DLI Host Module	不直接操作
Native H4/DLI framing、channel ownership、backpressure、hangup	Backend 内部 DliChannel	不拥有
闭源 vendor lifecycle、vendor fd/H4 framing	只见 Proxy message	slk-vendord 私有
power、channel、LPM、wake、probe、recover	Controller Backend mechanism	slk-vendord 只执行 vendor Adapter mechanism
固件、mailbox、USB/UART/SPI、厂商私有协议	Adapter 私有 Implementation	仅 opaque vendor Adapter 私有
链路状态、数据面、加密执行	拥有	slkd 配置与观察
配对 mechanism 与时序敏感密码学	拥有	slkd 拥有 Agent、认证/trust policy、Bond 持久化
TCID/链路数据通道、低层分片流控、安全上下文	拥有	不拥有
SSAP codec、session、MTU、事务、服务数据库、Profile	不拥有	slkd 拥有
PHY capability、合法性、原子应用、actual state	拥有	slkd 拥有偏好、QoS、自动调优与功耗 policy
产品启用、服务策略、D-Bus 与本地授权	不拥有	slkd、发行版或产品配置拥有

Integration states

必须区分：

1. Source registered：源码、Kconfig、package 或 build manifest 中存在。
2. Product enabled：具体产品或发行版显式启用内核 Module、slkd、必要的 slk-vendord 和 policy。
3. Backend present：匹配的 Native、UserspaceProxy/OpaqueVendor 或 Virtual Adapter 实际存在，proxy owner/lease 有效。
4. Controller ready：channel 已打开，初始化完成，DLI 可收发。

OpenHarmony 的 productdefine 变更只注册 drivers_peripheral_nearlink 和 drivers_interface_nearlink；nearlink_service 仍需产品 config 单独加入，并设置 const.nearlink.enable=1。OpenSparkLink 也不能把 source registered、vendor library 已安装或 daemon 进程存在当成 enabled、Backend present 或 controller ready。

Acceptance criteria

• 以架构文档或 ADR 固化 DLI Host、公开 Backend Interface、内部 DliChannel/BackendProxy/VendorLifecycle Seam、Adapter、所有权和四态启用模型。
• 公开 Backend Interface 采用 probe/start/send/stop/recover 与 RX/fault/hangup callback，不复制 HDI IPC、death recipient、动态服务框架或 op(int, void*)。
• 标准 DLI opcode 只由 DLI Host 编解码；Backend 不注入 SetAddress、广播、扫描、连接或伪造 CommandComplete。
• NativeBackend 可组合显式 Transport Adapter；UserspaceProxyBackend 不被强制暴露底层 bus；VirtualBackend 实现同一 Interface。
• kernel 不 dlopen vendor library；闭源 .so、vendor opcode、void * 和 vendor fd 仅存在于独立 slk-vendord 内。
• BackendProxy UAPI 有 version/size、descriptor、capability、controller id、独占 lease、generation、生命周期、完整 packet、queue/backpressure 和 fd-close detach 语义。
• slk-vendord 的写入只表示 controller RX/lifecycle，不成为绕过 DLI Host 的任意 command Interface；内核重新校验 packet type、length、controller ownership、generation 和状态迁移。
• daemon/library 缺失、ABI 不匹配、无效 channel、init timeout、crash/hangup 返回明确 unavailable/fault，不伪造成功。
• runtime availability 来自实际 probe、channel open 与 init complete，不由配置、library 存在或常量 onboard=true 决定。
• TX/RX 不在持有 subsystem/global mutex 时等待用户态；daemon 卡死只触发对应 controller timeout/recovery。
• 至少 VirtualBackend、一个 NativeBackend 和 fake OpaqueVendor Adapter 验证同一 DLI Host transaction。
• RX queue、parser、pending command、lease/generation 与 recovery 全部 per SleDev。
• 给出现有静态 enum/global state 到 runtime registry/per-device Backend handle 的分阶段迁移、feature flag、回滚与旧 Implementation 删除条件。
• out-of-tree proprietary kernel backend 如保留，只通过小型 versioned C Interface 接入，并明确 kABI、module taint、安全和法务支持边界。

Implementation slices

• 补齐广播、扫描与建链的真实 DLI 事务 #2
• 统一事件订阅、命令完成关联与原始 snoop #3
• 让每个控制器独立拥有协议状态与工作队列 #4
• 收窄控制面并限制 raw DLI 命令 #5
• 为用户态 SSAP Engine 暴露 per-connection channel #6
• 为 slkd 配对策略暴露机制型 Security Interface #7
• 解除 slkd 事件循环持锁等待 sparklink#1
• 让 slkd 与监控工具使用独立事件订阅 sparklink#2
• 把 SSAP Engine 与 Profile 数据迁入 slkd sparklink#3
• 把 PHY 选择策略迁入 slkd sparklink#4
• 让 slkd 拥有配对策略与持久化 Bond sparklink#5
• 为每个控制器创建独立 D-Bus 对象并暴露启用状态 sparklink#6
• 实现独立 slk-vendord 与闭源 Vendor Adapter sparklink#7

Blocked by

None - can start immediately.