2026-09-27 ENB：从原厂工具接入到跨平台 NVMe 基础设施
- 项目：Etherealm NVMe Bridge，简称 ENB
- 当前源码：
040d38f，基础版本0.1.0 - 当前重点：SMI NVMe 主控与 JMS583 USB-NVMe 桥
- 产品方向：面向主流操作系统的通用底层基础设施，支撑研究、诊断、数据恢复和 Agent
我们希望，一套存储工具在更换操作系统、USB 桥或主控协议后，仍然能够清楚回答几个问题：连接的是哪台设备，提交了什么请求，底层实际返回了什么，以及下一步由谁决定。
ENB 把这些共同需求收进一个可独立运行的 C++ 后端，通过统一 RPC 提供给上层工具。 它负责设备访问、连接生命周期、命令执行和原始结果；研究脚本、诊断界面、恢复软件或 Agent 在上层组织自己的流程。仓库同时提供可选的 JavaScript 参考库与命令行 enb-js，展示如何接入、编排和解释主控协议。
Windows x64 与 macOS arm64 已经跑通独立 native 后端，EasyTools 的完整后端能力也继续保留。 这套架构同时具备 Linux 实现，开发重点集中在 SMI 与 JMS583。长期目标是覆盖主流操作系统，逐步减少存储研究对某一款原厂程序、某一种开发语言和某一套桌面环境的依赖。
两条工程路线，在 ENB 汇合
在此前的 EasyTool Bridge 文章中，我们讨论过怎样把原厂 EasyTool 里的能力变成可调用的硬件接口。EZTHook 从原厂程序内部接入，复用已有 helper、界面和命令观察路径，再通过本机 RPC 向脚本开放。
这条路线很实用。面对尚未完整理解的设备协议，原厂工具保留了大量可观察、可复用的行为。它也带来明确的依赖：Windows 进程、具体 EXE 版本、内部调用约定和当前界面状态，都会影响一次操作。随着研究推进，我们需要让已经理解的协议离开原厂程序，获得独立执行的路径，同时保留原厂工具仍有价值的能力。
另一条路线来自 smartmontools 的 Darwin USB SMART 工作。那项工作解决的是 macOS 外置 USB 存储访问中的传输缺口：上层已经拥有 SMART 与桥接协议知识，底层仍需要完成 USB 设备接管、BOT/UASP 传输和释放。
两项工作的连接点逐渐清晰：原厂工具接入和独立传输，可以共享同一套执行与结果接口。 上层关心的目标身份、请求、完成状态和返回字节，不必随底层实现一起重写。
ENB 因此保留两种后端。easytools 继续接入原厂环境；native 通过操作系统提供的路径独立访问设备。macOS 的 USB 接管与释放实现迁自我们为 smartmontools 编写的代码，JMS583 线格式适配也保留了 smartmontools 的来源。
设计：让三种变化分别发生
存储工具经常需要同时面对三种变化：操作系统访问设备的方式变了，USB 桥封装命令的方式变了，SSD 主控理解命令的方式也变了。
如果把它们写进一套按主控命名的后端，每增加一个组合，就容易复制一份设备发现、传输、解析和错误处理。ENB 将这些职责拆开。
flowchart TD Apps["研究脚本 / 诊断界面 / 恢复软件 / Agent"] --> Client["自有客户端或 enb-js 参考库<br/>主控协议与流程编排"] Client --> RPC["ENB RPC<br/>能力描述、请求校验、结果查询"] RPC --> Core["共享执行器与执行记录<br/>目标绑定、互斥、状态与原始结果"] Core --> Native["native 后端<br/>设备发现与连接生命周期"] Core --> Easy["EasyTools 后端<br/>精确 EXE / ABI 适配"] Native --> Bridge["桥接协议<br/>当前重点：JMS583"] Bridge --> OS["macOS USB / Windows SCSI / Linux SG_IO"] OS --> Device["USB 桥与 NVMe 设备"] Easy --> Official["原厂程序与既有 helper"] Official --> Device
稳定的底层能力留在 C++
ENB 的产品入口是一个 C++17 可执行文件：enb，Windows 上为 enb.exe。它负责连接生命周期、执行记录、标准 NVMe 请求编译与解码、桥接传输和 RPC 服务。native 运行不依赖 Node.js、EasyTools EXE、注入 DLL 或 Windows 虚拟机。
内部执行核心处理类型化计划，不依赖 JSON、socket 或平台句柄。RPC 层负责报文解析与编码，平台 adapter 负责操作系统 I/O，桥协议层负责设备之间的线格式。macOS framework 对象留在 Objective-C++ adapter 内，公共核心保持普通 C++。
这让平台移植有一个较小的工作边界：新平台实现设备发现、打开关闭和传输接口后，可以继续复用执行器、RPC 和已有桥协议。测试也能替换底层 adapter，在没有真实设备的环境下检查状态机与接口行为。架构与依赖
主控协议由参考库或自有客户端表达
SMI 厂商协议的字段、布局和适用条件仍在持续研究。ENB 将这部分定义集中在 lib/enb/protocols/smi/：参考库把主控语义编译为底层步骤，并按已知布局解释结果。服务端提供标准 NVMe 读取与 raw Features 执行能力，不再维护另一份 SMI 操作目录。
标准 Identify、Namespace 和 SMART 的编译与二进制解码则由 C++ 统一提供，参考库直接消费结果。这一区分让成熟的标准能力保持一致，也让变化较快的主控协议能够单独迭代。
USB 桥与主控是两个独立维度。JMS583 说明请求如何穿过桥；SMI profile 说明桥后面的主控如何理解请求。EasyTools 的 EXE/ABI profile 又是第三个维度，说明某个原厂程序版本如何被调用。连接到某款桥以后，主控型号与固件仍需独立识别。
enb-js 是可选参考实现
enb-js 提供 RPC client、流程编排、结果等待、原执行查询、主控协议和参考 CLI。库可以嵌入自己的应用，CLI 可以用于研究流程；只有显式启动入口才会拉起后端，导入协议库本身不会启动进程。
其他语言可以直接实现公开的 RPC 约定。仓库已有 Python 标准库示例；GUI、测试框架或其他语言 SDK 也可以沿用同一接口。C++ 后端和 enb-js 因而具有各自的生命周期，上层应用无需为了访问设备而整体采用 Node.js 技术栈。参考库说明
Windows x64 与 macOS arm64 已跑通 native，EasyTools 完整能力继续保留
这是 ENB 当前最重要的工程进展：我们已经将独立后端带到 Windows x64 和 Apple Silicon 的 macOS arm64，同时把既有 EasyTools 后端完整保留下来。开发者可以按设备和任务选择路径，已经积累的原厂工具能力也继续可用。
Windows x64 的 enb.exe 已完成构建、独立进程启动、真实环回 RPC 与离线执行链验证，底层编入系统 SCSI passthrough adapter。独立路径摆脱了原厂 32 位进程的 ABI 约束，可以直接成为 64 位应用的本机设备服务。跨平台运行记录
macOS arm64 同样能够独立运行后端，并已有 JMS583/BOT 下真实标准读取与释放记录。对 Mac 上的研究工具而言，这提供了本机设备访问路径：从 C++ 服务到 USB 桥直接通信，无需经 Windows 虚拟机或原厂程序中转。
EasyTools 仍是功能完整的另一条后端路径。 既有 UI 操作、命令 capture、直接设备调用、Flash 读写擦、厂商读取、复位和 MPISP 等实现都保留在 ENB 中，并接入共享执行器与结果接口。当前清单包含 26 个后台设备/UI 方法，capture 等内存查询另列。能力由匹配的 EXE/ABI profile 和运行时清单决定；接口已迁移到 ENB 的方法名与会话契约，旧 EZTHook 客户端需要适配。EasyTools 方法参考
这使迁移可以逐项推进。已有清晰协议与验证结果的操作进入 native，依赖原厂内部实现的能力继续由 EasyTools 承接，两条路径还可以用于结果对照。上层使用统一的执行与查询方式，同时按照实际后端选择操作集合。
三个平台，共用执行合同
ENB 当前覆盖三条平台访问路径。
| 平台 | native 访问路径 | 平台相关行为 |
|---|---|---|
| macOS | IOUSBHost DeviceCapture，直接 BOT/UASP 传输 | 接管 USB 设备，处理卷卸载与释放恢复；framework 对象封装在平台层 |
| Windows | IOCTL_SCSI_PASS_THROUGH_DIRECT | 经系统存储驱动透传，检查磁盘接口、对齐和返回长度；不安装替代 USB 驱动 |
| Linux | SG_IO | 通过 SG 节点传输，检查整盘、节点身份与占用状态，保留 SCSI、host、driver 状态 |
Windows 和 Linux 的 BOT/UASP 由系统驱动决定；macOS 直接管理 USB transport。权限、设备占用和释放后的重新枚举，也有平台差异。ENB 将这些差异留在 adapter 与明确的生命周期结果里，使上层可以使用统一请求，同时看见必要的底层事实。
EasyTools 后端目前使用 Windows/MSVC x86 构建与外置 enb_ezt.dll，对应原厂程序的 32 位 ABI；它也可在 Windows x64 系统上运行。Windows x64 的 native 构建则是独立的 64 位程序。macOS、Linux 和 Windows x64 构建提供 native，Windows x86 构建同时包含两种后端入口。它们共同使用 enb.rpc.v1，服务端按实际后端发布方法与能力清单。平台实现
一次请求，需要留下什么
硬件操作的难点经常出现在请求已经发出、客户端却没有得到完整回复的时候。进程暂时无响应、桥返回短数据、完成状态丢失，都可能让“再试一次”产生新的设备动作。
ENB 将请求准入、设备执行与结果读取分开。调用方先取得当前能力和会话绑定，提交带有 executionKey 的计划；服务端记录计划与目标，在工作线程执行。上层再查询状态、读取结果和按需取得原始数据块。设备执行期间，控制面仍可响应查询。
executionKey 在当前进程会话中关联已经接受的请求。同一个 key 与同一计划关联原记录，换成不同计划会被拒绝。提交回执丢失时，调用方可以查询原记录，底层不会自动重发、复位、重连或切换后端。
执行记录同时保留几个不同层次的事实：
- 请求事实：实际提交的操作、参数、顺序与编译结果。
- 传输事实：操作系统、SCSI/USB 状态，以及可取得的传输长度。
- 设备事实：NVMe completion、原始字节和可选解码结果。
- 执行状态：已接受、运行中、完成、停止或结果未知。
例如，EasyTools helper 返回后，ENB 仍会分别记录 helper 返回码、设备 completion 和长度证据。保存了 4096 字节缓冲区，却没有实际长度证据时，结果会保留缓冲区，同时把有效长度标为未知。短传输或完成阶段失败时，已经取得的字节也可以保留下来，供上层诊断。
outcome_unknown 是这套接口中的正式状态。它让调用方知道，需要先判断设备与原执行的情况，再决定后续动作。默认执行记录位于内存；进程退出后不会自动恢复记录，文件记录也需要显式开启。需要长期留存的研究和恢复软件，应在上层保存自己的任务与证据。执行与结果约定
当前能力，已经走到哪里
ENB 已经形成独立服务、双后端、统一执行接口和参考库。当前的能力范围可以分为四组。
| 能力 | 当前实现 | 当前验证范围 |
|---|---|---|
| 标准 NVMe 读取 | Identify Controller、Identify Namespace、SMART，以及可选标准解码 | macOS/JMS583/BOT 有三个独立会话的标准读取与释放记录 |
| raw Features | 经 JMS583 或匹配的 EasyTools ABI 执行 Data-In、Data-Out 与无数据命令 | Windows/JMS583/无 NAND SM2263XT AB 有限定动作记录 |
| SMI 参考协议 | SM2263XT、SM2267XT、SM2268XT2、SM2269XT 的部分信息与诊断读取；SM2263XT 的显式动作编排 | 操作、参数和布局逐项定义；新参考封装有离线验证，四个 profile 的完整硬件适用范围仍待验收 |
| EasyTools 专用能力 | 保留 UI、capture、Flash 等既有实现，接入共享执行记录与互斥 | 依赖具体原厂程序与 ABI；native 尚未覆盖全部专用能力 |
2026 年 9 月 23 日的 macOS 记录覆盖 Identify Controller、Namespace 1 和 SMART，共三个独立会话、九条 NVMe 操作，均取得准确长度与成功 completion，并完成设备释放。当时设备没有原挂载卷，因此后续仍需覆盖挂载恢复与异常路径。macOS 验证记录
9 月 24 日的 Windows 记录使用 JMS583 与无 NAND 的 SM2263XT AB (ROM 0235)，native 和 EasyTools 两条路径完成了限定的原版 MPISP 下载与复位操作，并有 completion 和动作后单独读取的 DriveInfo 佐证。这说明部分过去依赖原厂工具的流程，已经获得独立执行路径。带 NAND 目标盘、其他主控与桥、完整恢复链仍需要各自的验证。Windows 双后端记录
这些是对应历史版本和硬件组合的实机结果。当前代码经过后续执行契约与参考库整理，已有跨平台构建和离线回归记录；Linux 实机、UASP 及更多异常恢复场景仍在待验收范围。我们会按平台、桥、主控、固件和具体操作积累支持证据。当前验证状态
Vision：把设备访问变成可复用的基础设施
ENB 的长期定位，是面向主流操作系统的通用 NVMe 底层基础设施。上层可以有不同的产品目标，底层共同拥有稳定的设备访问、执行和结果接口。
研究工具可以用它组织可重复的协议实验，保存请求与原始结果，在更换平台或后端时对照差异。已经理解的原厂流程逐步迁到 native，仍有研究价值的原厂能力继续保留。
诊断软件可以在统一接口上建立设备身份、健康信息与故障定位界面。它既能消费标准解码，也能在异常时查看原始数据和传输证据，把问题定位到主控、桥或主机访问路径。
数据恢复软件可以将 ENB 作为设备接入与执行底座，再在上层组织状态识别、受支持的数据读取、镜像管理、地址转换和文件完整性验证。当前 ENB 提供这条链的底层部分；NAND 读取、Translator/FTL 重建与恢复结果验证仍由对应协议和恢复系统逐项实现。
Agent可以通过结构化接口取得设备事实、组织任务并分析执行结果。enb-js 提供了一份可参考的接入方式，Agent 框架也可以使用自己的客户端。授权、操作选择、实验计划和长期证据管理属于上层应用；ENB 负责忠实执行显式请求，并把已知与未知结果完整交回。尤其是 raw Data-Out 等能力可能改变设备状态，上层应用需要根据具体任务管理权限与流程。
这四类应用可以共享一个执行底座，而各自保留产品逻辑。ENB 无需理解每一种研究假设、故障诊断和恢复策略，上层也无需重复实现每个操作系统的设备访问细节。
先做深 SMI 与 JMS583，再判断扩展方向
当前重点仍然是 SMI 主控和 JMS583 桥。它们提供了一组具体的工程对象，适合把跨平台传输、原厂与独立后端对照、主控协议和结果证据逐步做扎实。
未来可能扩展 USB-SATA、原生 SATA、原生 PCIe NVMe，也可能加入 PHISON 主控。这些方向目前属于可选路线，没有统一的交付时间表。它们分别涉及新的桥协议、设备访问路径、命令族或主控语义，不能仅靠增加一个型号名称完成支持。
现有分层为这些扩展保留了位置：新增操作系统路径主要落在平台 adapter，新增 USB 桥主要落在桥协议层，新增主控主要进入协议库；跨入 SATA 时，还需要补充 ATA/SAT 等命令表达与结果合同。执行身份、记录与原始结果等共性机制可以继续复用，具体实现则由新的设备证据推动。
我们希望最终形成这样的使用体验：开发者选择操作系统与设备，读取能力描述，使用 enb-js 或自己的库组织请求，再得到可以检查、保存和继续处理的结果。原厂工具、独立传输、研究脚本与产品界面由清晰的接口连接起来。ENB 承担其中稳定的底层，使存储工具的下一次进步能够从已有基础上继续。
延伸阅读与实现依据
- Etherealm EasyTool Bridge：面向 SMI SSD Controller 的 Agentic 硬件 Harness：原厂工具接入与早期产品构想。
- 在 macOS 上打通外置 USB 存储的 SMART 读取：Darwin USB transport 的接入与实机验证进展。
本文的实现说明以 040d38f 源码快照为准；历史实机记录保留各自版本与环境，未来方向按项目愿景表述。