SEMX — Soft Error Mitigation for Xilinx

English version: README.md

SEMX 是 SDS³（Software Defined Satellite Service Stack）的功能组件，面向 Xilinx 7 系列 SRAM 型 FPGA（当前验证器件 XC7K325T）提供单粒子翻转（SEU）缓解能力：周期性校验配置存储器，检出由 SEU 引起的配置位翻转，并在安全门约束下按帧执行局部热修复。此外提供基于 SEM IP 的 SEU 注入验证能力——仅要求 JTAG 与时钟的最小硬件方案，可 在地面无辐射环境下评估用户 FPGA 设计的 SEU 敏感度。

工作原理

背景：配置存储器与单粒子翻转

SRAM 型 FPGA 的逻辑功能、布线和存储初始化全部由片上配置存储器 （configuration memory，SRAM 单元阵列）决定。空间辐射环境中的高能粒子 可能在配置存储器中引发单粒子翻转（SEU）：一个或多个配置位被改变，并 一直保持到下次重配置。翻转积累到一定程度会导致逻辑功能异常，因此需要 周期性校验配置存储器并在发现差异时修复（这一过程称为 scrubbing）。

RBCRC：片上回读 CRC 与帧 ECC

RBCRC（Readback CRC）是 7 系列 FPGA 器件预先存在的配置自检机制， 由片上专用硬件实现，不占用用户逻辑与外部链路，是常开的第一道检测：

1. 后台 CRC 扫描：使能 POST_CRC 后，配置逻辑以独立后台时钟 （如 6 MHz）持续扫描全部配置帧，重算 CRC 并与配置时寄存的参考值 比较；不一致时置位 STAT.CRC_ERROR，可选拉低 INIT_B （POST_CRC_INIT_FLAG）给出带外硬件告警。
2. 动态位置硬件屏蔽：后台扫描自动屏蔽 SLICEM LUT（RAM/SRL 模式）、 跳过块 RAM 内容帧、屏蔽 DRP 存储——运行态存储写入不会触发误报 （块 RAM 数据可选由其内建 ECC 电路保护）。
3. 逐帧 SECDED：FRAME_ECCE2 原语输出每帧 13 位 Hamming SECDED 状态——ECCERROR / ECCERRORSINGLE、出错 FAR、 SYNWORD / SYNBIT / SYNDROME，可将单比特错误定位到帧内具体 字与位。
4. 动作模式：POST_CRC_ACTION 支持 HALT、CONTINUE（仅指示）、 CORRECT_AND_HALT、CORRECT_AND_CONTINUE（自动纠正单比特）， 可按产品策略选择。
5. 扫描互斥：JTAG / ICAPE2 / SelectMAP 配置访问期间后台扫描自动 暂停，访问结束（DESYNC 收尾、IR 退出配置指令）后自动恢复。
6. 片上遥测：粘滞寄存器锁存事件细节，经 BSCANE2 的 USER2 链以 CRC32 保护的 192 位移位寄存器协议读出，链路损坏可识别。

BITSECC：配置回读校验与选择性重写

BITSECC 是 SEMX 在 RBCRC 之上的外部增强通道：配置存储器回读 校验与选择性重写，补齐 RBCRC 所缺的逐位取证与受控修复能力。名称与 接口无关（当前实现为 JTAG，架构预留 ICAP/SelectMAP 支持）：

1. 帧组织：7 系列配置存储器按帧（frame）组织，XC7K325T 每帧为 101 个 32 位字。每帧由 FAR（Frame Address Register）唯一寻址 （块类型 / 上下半区 / 行 / 列 / 帧内偏移）。
2. 回读：外部主机经配置接口（当前实现为 JTAG）发出 FDRO 读回， 分段取得全部配置帧（XC7K325T 为 28,292 帧、35 个读段）。
3. 比较：回读帧与同源构建的黄金数据包（golden package，内含 部署位流 SHA-256 绑定）逐位比较。运行态动态位（BRAM 内容、 LUTRAM/SRL、IOB 状态等）会合法变化，使用 Vivado 官方掩码 （由 RBD/MSD 与 BIT/MSK 双路径生成）排除，避免误报。
4. 身份门：差异帧比例超过门限时判定当前加载的设计与黄金绑定不符 （例如设备回退到出厂位流），拒绝进入差异判定，防止错误告警。
5. 修复路径（安全门默认禁用）：确认差异帧属于安全白名单后，按帧 执行局部写回（FDRI），不触发 JPROGRAM、全局清空或全局启动；写 事务统一以 DESYNC 收尾，写后回读复核。

混合策略

两通道硬件独立、互为备份，组合部署而非二选一：

• RBCRC 负责快：后台扫描常开、延迟低、不占用外部链路；硬件自动 屏蔽动态存储位置，运行态写入不引发误报。局限在于：只能报告”存在 错误”并定位到帧（FRAME_ECCE2 可到单比特），无法与黄金参考逐位比对 取证，也无法执行白名单、敏感资源等修复策略；CORRECT_AND_* 模式 虽可自动纠正单比特，但对设计策略无甄别能力，多比特翻转仅能检测。
• BITSECC 负责准与修：外部全帧比较提供帧级取证（哪个 FAR、哪些 字、多少位），配合官方掩码消除误报，并提供受控修复通道。
• 组合状态机：RBCRC 报警 → BITSECC 巡逻复核与取证 → 白名单内 局部修复；不可分类或不可修复的差异进入受控完整回滚，而非盲目写入。 外部巡逻链路（主机、适配器、软件）故障不影响片上检测继续工作。
• 已知交互：回读与 POST_CRC 扫描并发在个别区域可能产生伪 ECC 标志，工程上通过伪签名标注与遥测 clear-on-read 缓解，详见 docs/known-issues.md。

组合与独立使用

两通道可按任务阶段选择组合或独立部署：

• 组合部署（默认推荐）：RBCRC 常开快检 + BITSECC 周期取证，兼顾 响应速度与判决质量；任一通道失效时另一通道继续工作。
• 仅 BITSECC（关闭 RBCRC）：构建 POST_CRC=DISABLE 的位流即可 在位流级关闭后台扫描，守护服务无需改动（遥测探测自动回退 unsupported，绝不伪报健康）。适用于在轨 SEU 敏感度统计：掩码 逐位比较在每次巡逻给出精确的翻转位置清单（FAR / 字 / 位），既不 存在自动纠正对事件的掩盖，也消除了回读与后台扫描并发的伪标志 干扰，便于按帧地址、块类型累积 SEU 截面、位置敏感度与多比特翻转 比例。代价是检出延迟为巡逻周期量级。
• 仅 RBCRC：主机与链路负担最低，INIT_B 可提供不依赖软件的带外 硬件告警，适合资源受限或纯告警应用；局限是无逐位取证、无修复 策略，粘滞寄存器仅保留事件概要。

SEU 注入验证：仅 JTAG + 时钟的最小硬件方案

帧 ECC 硬件交叉验证（见测试报告） 的 SEM 轨实现顺带产出了一种硬件需求极低的 SEU 注入验证方案，主要用途是 在地面无辐射环境下评估用户 FPGA 设计的 SEU 敏感度——加速器辐照试验 前的低成本预筛与定位手段：

1. 硬件需求极小：一路 JTAG（任意 OpenOCD 支持的适配器）加一个送到 SEM/ICAP 的时钟（可与被测设计共用时钟源），不需要 UART、监视器串口 或任何额外引脚；SEM 控制器与桥接逻辑合计约 738 Slice LUT （XC7K325T 的 0.36%），可与用户设计同片集成。
2. 注入通道：BSCANE2 的 USER3 扫描链接收 PG036 线性注入命令（线性 帧地址 + 帧内字 + 位），经 toggle CDC 桥接到 SEM 控制器的 injection shim；按 PG036 约束仅在控制器空闲态选通，观察态下的注入被静默忽略。
3. 遥测通道：BSCANE2 的 USER2 扫描链输出 CRC32 保护的 192 位遥测 （协议 v0x03）：FRAME_ECCE2 事件粘滞位（syndrome / synword / synbit / FAR / 状态标志），事件时钟锁存、clear-on-read。
4. 单比特精确定位：注入单比特故障后，片上 FRAME_ECCE2 将其回报到 具体帧内字与位；离线 frame_ecc 模型已经 21 个硬件向量校准并固化为 回归测试，syndrome 与帧内位置的映射逐位确定。
5. 敏感度评估方法：对用户设计占用的配置帧逐点注入单比特故障，观察 设计自身输出或状态是否异常，即可统计敏感位比例、定位关键帧与关键 资源；配合 BITSECC 逐位回读比较，还可区分”配置已翻转但功能未受影响” 的惰性位。
6. 实测证据：XC7K325T 上跨六轮共 47 次注入，注入 → 检测 → 定位 → 修复 → 复查闭环全部符合最终校准模型（17 PASS + 2 预期掩码 SKIP、 0 FAIL，syndrome 硬门控逐位相等）。

性能评估

以 XC7K325T（28,292 帧 × 101 字 ≈ 286 万字）与本仓库参考配置估算：

通道	指标	估算值	依据
RBCRC	单轮全片扫描周期	≈ 0.5 s（一轮）	按扫描引擎每时钟约读 1 字：286 万字 ÷ 6 MHz（POST_CRC_FREQ=6）≈ 0.48 s
RBCRC	单比特错误纠正响应	平均 ≈ 0.25 s，最差 ≈ 0.5 s（CORRECT_AND_CONTINUE）	UG470：检出即停扫，利用 syndrome 定位、重写该帧后从头续扫；单帧重写约百字，微秒级可忽略
RBCRC	多比特错误	仅检测，延迟同扫描轮次	SECDED 双比特仅检不纠
BITSECC	单比特错误检出响应	平均 ≈ 间隔/2 + 6.4 s，最差 ≈ 间隔 + 6.4 s	全片回读实测 ≈ 6.4 s（35 段、JTAG）；巡逻间隔可配（参考配置 60–300 s）
BITSECC	修复附加延迟	单帧 < 1 s（估）	FDRI 按帧写回 101 字 + 命令开销，多帧线性叠加；写后回读复核另计一个回读周期

说明：扫描周期按”每时钟 1 字”一阶估算，轮次实测待补；扫描频率可经 POST_CRC_FREQ 调整，响应时间与频率成反比。当前构建写门禁用 （write_gate=disabled），修复行为受控，BITSECC 修复延迟为设计估算。

巡逻守护服务：错误报告与审计

守护服务（semxd）对在轨试验的价值在于结构化、可追溯的错误记录：

• 状态机：healthy（本周期无掩码后差异）、suspect（存在差异或 RBCRC 报警）、identity-mismatch（加载设计与黄金绑定不符，如回退 到出厂位流）、unknown（链路或软件异常，绝不伪报健康）。
• 可报告的错误类型与内容：
  • suspect-difference：掩码后差异统计（帧数 / 字数 / 位数 / 比例） 与示例帧清单（每帧 FAR、差异字数、差异位数，最多 32 例）；
  • rbcrc-crc-error：STAT 寄存器 CRC_ERROR 置位（含完整 STAT 值），即片上后台扫描检出配置翻转；
  • identity-mismatch：差异比例超身份门限，拒绝误判；
  • cycle-error：回读 / 探测失败的异常信息；
  • 每周期的 RBCRC 遥测快照：遥测序号、出错 FAR、crc / ecc / single 粘滞标志（SYNWORD / SYNBIT / SYNDROME 原始字段见 遥测协议文档）。
• 记录与访问：审计为 JSONL 文件（默认 /var/opt/sds3/semx/log/audit.jsonl），每条记录含 UTC 毫秒时间戳、事件名、 semxd 版本，10 MB 自动轮转；当前状态快照在 state.json；运行日志 经 journalctl -u semx-daemon.service 查看。审计文件可直接用于 在轨 SEU 计数、位置分布与敏感性统计的地面回收分析。

安装、配置项与判读细节见 docs/semx-daemon-ops.md。

术语解释

术语	含义
SEU（Single Event Upset）	单粒子翻转：高能粒子撞击导致的存储位状态翻转
MBU（Multiple Bit Upset）	多比特翻转：单次事件翻转多个位
配置存储器	决定 SRAM FPGA 功能的片上 SRAM 阵列，运行期不回写
配置帧 / FAR	配置存储器的最小寻址单元及其地址寄存器
回读（readback）	经配置接口读出当前配置存储器内容（FDRO）
黄金数据包	与同源构建绑定的可信参考帧集合及 SHA-256 清单
动态位 / 掩码	运行中合法变化的配置位；掩码将其排除出比较
FDRI / FDRO	7 系列配置数据输入 / 输出寄存器（写帧 / 读帧通道）
POST_CRC	内建后台回读 CRC 扫描功能
FRAME_ECCE2	7 系列逐帧 ECC 状态原语，输出错误类型与定位
SECDED	Single Error Correction, Double Error Detection，单纠双检码
BSCANE2 / USER2	JTAG 用户扫描链原语；USER2 为第二条用户链
JPROGRAM / DESYNC	完整重配置指令 / 配置会话退出指令
ICAP / SelectMAP	FPGA 内部 / 外部并行配置接口（BITSECC 预留）
SEM IP	Xilinx Soft Error Mitigation 参考设计 IP
巡逻（patrol）	周期性”回读—比较—记录”的巡检动作
粘滞位（sticky）	事件发生后保持置位、直到显式清除或重配置的标志位
Scrubbing	周期校验并修复配置存储器的整体过程

功能特性

• RBCRC：POST_CRC=ENABLE 在线检测部署支持，片上遥测经 CRC32 保护的 USER2 协议输出，支持错误定位（FAR/ECC 细节）。
• BITSECC：JTAG 配置寄存器访问与批量帧回读（基于定制 OpenOCD， 适配器无关）；全器件分帧回读与逐 FAR 黄金比较；Vivado 官方掩码； 帧级选择性写入（默认禁用）；统一配置事务收尾。
• 巡逻守护服务：systemd 集成（notify/看门狗/单实例锁/最小权限）、 JSONL 审计、Debian 打包与载荷 SHA-256 绑定；黄金/掩码/部署位流为 /var/opt/sds3/semx/ 下用户自主部署的数据（启动校验绑定）；空配置 自动恢复（STAT DONE_IN 低时自动加载部署位流并复核）。
• SEU 注入验证：SEM IP + BSCANE2 USER2/USER3 的纯 JTAG 注入与遥测 通道（仅 JTAG + 时钟，无 UART/额外引脚）；PG036 线性注入单比特故障， 片上 FRAME_ECCE2 定位到帧内字/位；离线帧 ECC 模型经 21 个硬件向量 校准（回归测试固化）；适用于用户 FPGA 设计的 SEU 敏感度地面评估， 见交叉验证测试报告。
• 工程支撑：无 PCIe 最小验证设计、位流/帧/掩码解析器与测试套件、 版本化黄金数据包、SHA-256 归档完整性清单。

仓库结构

semx/
├── README.md                        # 本文件
├── LICENSE                          # MIT
├── docs/                            # 已知问题、守护运维手册、遥测协议、测试报告
├── openocd/                         # 定制 OpenOCD（Git submodule）
├── lib/                             # sds3_bitstream 库（位流/帧/黄金包/掩码/帧ECC）与测试
├── tools/sem_xval/                  # SEM 注入硬件交叉验证驱动
├── scripts/                         # 目标侧部署与回读脚本
├── semxd/                           # 巡逻守护服务、配置与测试
├── packaging/semx/                  # Debian 打包骨架
├── fpga/
│   ├── rtl/                         # 可复用 RTL 核心（rbcrc_telemetry、sem_telemetry）
│   ├── parts/                       # 器件帧几何数据
│   └── tests/                       # 验证设计：minimal-xc7k325t（外壳）、sem-xc7k325t（SEM 注入）
├── vivado/scripts/                  # Vivado 构建 Tcl（含 RBCRC 派生）
├── references/                      # 第三方资料（清单管理，不入 Git）
└── archive/                         # 构建产物与快照（清单管理，不入 Git）

openocd/ 为 Git submodule：Maiar 维护的 OpenOCD fork 的 semx 分支（上游官方 master + SEMX 专用补丁），克隆本仓库后执行 git submodule update --init（或克隆时加 --recursive）获取。

快速开始

环境要求：Python 3（解析器与守护服务）、Vivado（位流构建，2019.2 实 测）、实板巡逻需运行定制 OpenOCD 的主机、OpenOCD 支持的任意 JTAG 适 配器及目标 7 系列 FPGA。所有配置操作经 OpenOCD 统一完成，不依赖特定 厂商的适配器驱动或设备。

# 位流解析器测试（62 项）
cd lib
python3 -m pytest tests/ -q
cd ..

# 守护服务离线测试（19 项）
PYTHONPATH=semxd \
  python3 -m pytest semxd/tests/ -q

# 构建最小验证位流（输出到 /tmp）
vivado -mode batch -source vivado/scripts/minimal-xc7k325t/build.tcl \
  -tclargs /tmp/semx-minimal-vivado

守护服务的安装、配置与判读见 docs/semx-daemon-ops.md。

文档

文档	内容
docs/semx-daemon-ops.md	巡逻守护服务安装、配置、运行判读与回滚
docs/rbcrc-telemetry-protocol.md	RBCRC USER2 遥测协议与读数解释
docs/xval-2026-07-31/sem-xval-report.md	SEU 注入硬件交叉验证测试报告（含帧 ECC 模型校准过程与原始数据）
docs/known-issues.md	已知硬件交互问题与修正计划
fpga/tests/minimal-xc7k325t/README.md	最小验证设计构建指南
lib/README.md	位流解析器用法

安全须知

写配置功能默认禁用。除显式授权的受限实验外，所有写配置 SRAM 的命令必 须保持拒绝状态；敏感资源和未知帧默认只读。

许可证

MIT。版权所有：Jonah Liu liujiahan@gmail.com。

归属

SEMX 是 Maiar Lab SDS³ 开源卫星计算软件栈的功能组件，与 sds3_ttc、 sds3_firmware 等组件共同构成星上服务体系。