星核火花赛车科技

标签： openpilot

  • 比亚迪 / Proton 的 openpilot 移植：指纹规模与功能替换边界

    结论：bukapilot 是 openpilot 之上的维护型补丁集，目标是把 ADAS 带到马来西亚在售车型（尤其 Perodua 与 Proton），并在既有能力上补齐完整的右舵支持。落到 CAN 适配层，判断一个车型「算不算移植完成」要看两件事：DBC 字典有没有映射、指纹有没有登记。按这个口径，BYD ATTO 3 有 2 组指纹（144 与 110 个地址），Proton X50 有 1 组（179 个地址），而 Proton S70 与 X90 只有 DBC 映射、没有指纹，属于未完成的端口条目。

    车型移植的两张表：DBC 映射与指纹

    移植数据集中在两个 values.py 里：一份按品牌给出 CAR 常量、DBC 字典与指纹字典，另一份给出 HUD 倍率。DBC 字典走 openpilot 的 dbc_dict 形式，第二项为 None，即未登记雷达侧 DBC。HUD 倍率直接影响仪表与抬头显示上的速度呈现，BYD 侧为 0.718，Proton 侧为 1.035 且在源码里留着「Todo」标记，说明它仍是待标定的值。

    品牌 车型常量 DBC 字典 指纹组数 HUD 倍率
    BYD ATTO3 = "BYD ATTO 3" byd_general_pt（雷达侧 None） 2 0.718
    Proton S70 = "PROTON S70" proton_general_pt（雷达侧 None） 0 1.035（Todo）
    Proton X50 = "PROTON X50" proton_general_pt（雷达侧 None） 1 1.035（Todo）
    Proton X90 = "PROTON X90" proton_general_pt（雷达侧 None） 0 1.035（Todo）

    指纹规模与非 8 字节 DLC

    指纹记录的是「地址到长度」的映射，是车型识别的第一道判据。三组的规模差异很大，而真正有价值的信号藏在那些长度不等于 8 的地址里。

    指纹 地址数 长度非 8 的地址 地址范围
    ATTO 3 指纹一 144 204:20、287:5、385:3、682:2、1542:2、1798:3 85 – 2027
    ATTO 3 指纹二 110 287:5、385:3、682:2、1542:2、1798:3 85 – 1832
    Proton X50 指纹 179 385:3、1542:2、1798:3 32 – 2025

    把三组放在一起比对，能读出三条结论。其一，ATTO 3 的两组指纹共有 107 个地址，第一组独有 37 个、第二组独有 3 个，说明第二组几乎是第一组的子集，多数组差异来自配置或年款导致的报文增减。其二，三组指纹共有 17 个地址，其中 385（长度 3）、1542（长度 2）、1798（长度 3）长度都不是 8，这类跨品牌稳定的短帧通常是通用或诊断相关报文，不应作为车型特征。其三，X50 的 179 个地址里有 159 个不在 ATTO 3 两组指纹的并集（147 个地址）之内，两个品牌的报文空间基本不重叠，因此 DBC 也必须分成 byd_general_pt 与 proton_general_pt 两套。

    另有一个需要单独确认的点：ATTO 3 第一组指纹里出现 204:20，长度 20 超出经典 CAN 的 8 字节上限。它可能来自 CAN FD 采集，也可能来自采集工具的合并口径，在把它写进匹配规则之前必须先确认采集链路。

    功能替换边界：哪些被替换，哪些叠加

    移植不只是接上 CAN，还要说清接管了哪些原厂功能。README 把这件事分成「所有受支持车型」与「特定受支持车型」两层，处理逻辑完全不同。

    功能 所有受支持车型 特定受支持车型
    LKA 原厂 LKA 被替换，仅在用户启用后生效 同上
    LDW 原厂 LDW 被替换 同上
    ACC 不替换 原厂 ACC 被替换
    FCW 不声明 在原厂 FCW 之外叠加运行
    AEB、自动远光、盲区警示、侧向碰撞警示 原厂功能一律保留 原厂功能一律保留

    这套划分的工程含义是：横向控制（LKA/LDW）是移植的必选项，纵向控制（ACC）只在完成标定的车型上接管，前向碰撞预警采取「叠加而非替换」以保留原厂兜底，其余主动安全功能不动。开发车端口时，也应按同样的层次逐项确认，而不是一次性接管全部。

    数据上传与责任边界

    默认情况下驾驶数据会上传到项目方服务器。日志范围按项列出，可退出性并不一致，做合规评估时要逐项核对。

    数据项 默认状态 可否关闭
    路面相机、CAN、GPS、IMU、磁力计、热传感器、崩溃与操作系统日志 记录并上传 仅在设置中显式退出驾驶员相机一项，其余未说明可关闭
    驾驶员朝向相机 默认记录 可在设置中显式 opt-out
    麦克风 不录制 不适用
    数据使用权 授予项目方不可撤销、永久、全球范围的使用权 使用即视为同意

    责任侧同样写得很硬：软件以 MIT 许可发布（部分组件按各自许可），但被明确定性为 alpha 质量的 research-only 软件，不是产品；使用者须自行遵守当地法律法规，无明示或默示担保，并须就使用该软件产生的一切索赔向项目方作出赔偿与免责。性能限制也被逐条列出：恶劣能见度、相机被遮挡或损坏、车身贴膜贴纸或橡胶涂层造成的遮挡、设备安装不当、急弯与匝道路口的转向扭矩上限、受限车道与施工区、大横坡或强侧风、极热极冷、强光直射、坡道窄路与蜿蜒道路。它不会自动驾驶，也不减轻驾驶者必须付出的注意力；变道时它无法查看盲区，确认安全后由人工轻推方向盘发起。

    常见问题

    bukapilot 与 openpilot 是什么关系？

    bukapilot 是 openpilot 的维护型补丁集，目标是支持马来西亚在售车型（尤其 Perodua 与 Proton），使用为这些车型专门设计的硬件，并在 openpilot 既有能力之上补齐完整的右舵支持。它实现 ACC、LKA、FCW、LDW，并在启用时叠加基于相机的驾驶员监测；作为 openpilot 的补丁集，它也继承了 openpilot 的软件安全模型，并针对补丁部分逐步补充增量测试。

    为什么 Proton S70 与 X90 不能算已适配？

    因为它们在 values.py 里只有 DBC 映射（proton_general_pt）而没有指纹条目。指纹是车型识别的第一道判据，缺失意味着无法在实车上完成确定的车型匹配；同为 Proton 的 X50 则有 1 组含 179 个地址的指纹。此外 Proton 侧的 HUD 倍率 1.035 在源码里仍带 Todo 标记，属于待标定值。

    指纹里的 204:20 该怎么理解？

    它表示地址 204 的帧长度为 20 字节，超出经典 CAN 的 8 字节上限，可能来自 CAN FD 采集或采集工具的合并口径。在把它写进车型匹配规则之前必须先确认采集链路与总线类型，否则会在不支持该长度的接口上造成误匹配。

    默认会上传哪些数据，能不能关掉？

    默认上传驾驶数据，日志包括路面朝向相机、CAN、GPS、IMU、磁力计、热传感器、崩溃与操作系统日志；驾驶员朝向相机默认记录但可在设置中显式退出；麦克风不录制。使用即视为授予项目方不可撤销、永久、全球范围的数据使用权，除驾驶员相机外其余项的关闭方式在文档中未作说明。

    bukapilot 会接管原厂 AEB 和盲区警示吗？

    不会。文档要求保留车辆其他全部原厂功能，明确列举的包括 FCW、自动紧急制动（AEB）、自动远光、盲区警示与侧向碰撞警示。被替换的是原厂 LKA 与 LDW；在受支持的特定车型上，原厂 ACC 被替换，而 bukapilot 的 FCW 是在原厂 FCW 之外叠加运行，不是替换。

    延伸阅读

    参考资料

    • 项目 01 —— public-can-dbc-datasets/additional/alienware-sa-bukapilot-byd-proton/README.md（项目定位、功能替换层次、限制清单、数据上传与许可责任条款）
    • 项目 01 —— public-can-dbc-datasets/additional/alienware-sa-bukapilot-byd-proton/selfdrive/car/byd/values.py（ATTO 3 的 DBC 映射、HUD 倍率与两组指纹）
    • 项目 01 —— public-can-dbc-datasets/additional/alienware-sa-bukapilot-byd-proton/selfdrive/car/proton/values.py（S70/X50/X90 的 DBC 映射、HUD 倍率与 X50 指纹）

    免责声明

    本文所述内容为公开开源项目的移植数据与文档摘录，不代表车辆制造商或项目方的官方承诺。素材自身已声明：该软件为 alpha 质量的 research-only 版本，不是产品，无明示或默示担保，使用者须自行遵守当地法律法规并承担相应责任；它不会自动驾驶，也不减轻驾驶者必须付出的注意力。文中指纹地址与长度均按公开文件统计，未经实车复现，不同年款、市场与配置可能存在差异，涉及行车安全的改装请务必在封闭场地与专业监督下进行。

    更新记录

    • 2026-10-14 初稿

  • 2025 Corolla TSS 3.0 的 0x160：32 字节控制报文与 E2E 校验

    结论：2025 Corolla Hybrid TSS 3.0 的横向与纵向控制都收敛到同一条报文：摄像头发出的 32 字节 CAN FD 帧 0x160，约 40 Hz。加速度是字节 4–5 的 15 位有符号量（0.001 m/s²/count），转向请求是字节 22–23 的大端有符号量（537.7 counts/degree），E2E 保护为对字节 2–31 做 CRC-16/CCITT 并附加小端数据 ID 0x444A。这一条报文也是 Panda 白名单里的唯一入口。

    三条总线上的报文分工

    移植说明把总线关系写得很清楚：动力总成在 Panda bus 1，被中继的 ADAS 报文对在 bus 0，摄像头在 bus 2。控制指令只在 bus 0 上发出，且只有 32 字节这一种形态被接受。网关发出的 0x1A0 属于另一条路径，该分支从不发送它。

    总线 承载内容 在控制链中的角色
    Panda bus 1 动力总成 被观测，不作为指令出口
    Panda bus 0 中继后的 ADAS 报文对 唯一允许发送 32 字节 0x160 的出口
    摄像头 bus 2 摄像头原始 0x160 E2E 计数器与未知字节的来源

    配套的 DBC 规模是 15 条 CAN/CAN FD 报文、120 条信号条目。需要留意的是，DBC 自带的表头写的是「2023 Toyota Corolla」，并标注位位置是从被动日志推断的，而移植目标是 2025 年款。因此它应被当作候选研究定义，而不是已验证的年款网络地图。

    0x160 的字段布局与 E2E 校验

    E2E 保护是这套控制路径里最容易被低估的部分。它不是简单的校验和，而是 AUTOSAR E2E 风格的「计数器 + CRC」组合：字节 2 是摄像头计数器，字节 0–1 是小端 CRC，CRC 覆盖字节 2–31 并附加小端数据 ID 0x444A。

    字节位置 含义 编码 换算
    0–1 E2E CRC 小端 16 位 CRC-16/CCITT，覆盖字节 2–31 + 数据 ID 0x444A
    2 摄像头计数器 8 位 控制器每收到一个新计数器只发一次
    4–5 加速度请求 15 位有符号 0.001 m/s²/count
    22–23 转向请求 大端有符号 16 位 537.7 counts/degree
    其余字节 摄像头未知字段 — 原样保留，不做猜测

    控制器的行为边界也由这张布局决定：它只改已知的加速度与转向字段，保留摄像头的未知字节，重算计数器与 E2E 校验，并且当某个轴不由 openpilot 控制时，原样中继该轴的字段。这意味着「替换控制」不是构造新报文，而是在原报文上做最小改动。

    为什么 537.7 counts/degree 是关键数字

    转向字段的换算系数决定了限幅的实际含义。Panda 侧的转向限幅写的是每接受一帧最多变化 1,500 counts，换算后对应的角度增量才具备物理意义。脱离换算系数去谈限幅是没有意义的——这也是为什么这类移植必须先把 scale 钉死，再谈安全包络。

    安全边界：三层限幅与单一白名单

    TSS3 的 Panda 模式只有在使用 ALLOW_DEBUG 构建时才存在。它的发送白名单里只有一条指令：bus 0 上的 32 字节 0x160。旧款 8 字节 0x160、0x1A0、老款丰田转向报文以及所有无关地址都被拦在白名单外。

    约束项 Panda 侧包络 控制器侧实现
    加速度 -3.5 .. 2.0 m/s²（实测原厂中继包络） 额外夹到 -1.5 .. 1.5 m/s²
    转向变化率 每接受帧最多 1,500 counts 被拒绝的帧不推进限幅基线
    发送地址 仅 bus 0 的 32 字节 0x160 从不发送 0x1A0
    构建开关 需 ALLOW_DEBUG 生产构建会拒绝该输出

    「被拒绝的帧不推进限幅基线」这一条值得单独注意。如果拒绝帧也推进基线，攻击者或故障状态就能通过连续发送被拒帧把限幅额度消耗掉，进而让下一次合法大动作被吞掉。这里的实现避免了这个问题。

    仍然没有闭环的部分

    项目明确列出了几项未解决项：转向灯信号不在三条被接的总线上，因此无法用已验证信号来暂停转向；脱手警告看起来由扭矩超时强制执行，未找到可抑制的 CAN 位，仍需手扶方向盘；0xDA 报文里的四个字段尚未可靠区分驾驶员扭矩与 EPS 扭矩，因此 steeringPressed 保持为 false 而不猜测；驾驶员物理扭矩信号已知在 0x030 上，但可接受的超控阈值未做动态验证。车辆参数目前沿用 E210 Corolla 的 3,060 lb、2.67 m 轴距、13.9 转向比。

    常见问题

    0x160 的 E2E 校验到底覆盖了哪些字节？

    覆盖字节 2 到字节 31，算法为 CRC-16/CCITT，并附加小端序的数据 ID 0x444A。字节 0–1 存放小端序的 CRC 结果，字节 2 是摄像头计数器，这两部分不参与自身校验。

    为什么必须手动选择车型而不是自动指纹识别？

    因为现有的行驶日志无法唯一关联到 2025 年的 F181 身份。已处理的 rlog 在逻辑 bus 1 上有 147 个地址/DLC 对，加上启动段后并集为 152 对，逻辑 bus 0 上有稳定的 22 条报文 ADAS CAN FD 结构；但这一并集与一份 TSS3 Camry 的普查结果重叠，且行驶日志里 carParams 为 MOCK 而非在路上的 F181 响应。自动匹配存在误判车型身份的风险。

    生产版 Panda 能用这套控制吗？

    不能。TSS3 Panda 模式只在以 ALLOW_DEBUG 构建时编译进固件，生产安全构建不会启用这个实验性白名单，因此会拒绝控制器发出的 0x160 输出。这是有意设置的状态，直到剩余的车辆级策略与验证工作完成。

    这份 DBC 能当作 2025 年款的完整网络地图吗？

    不能。DBC 表头写的是 2023 Toyota Corolla，并注明位位置由被动日志推断；移植目标却是 2025 年款。上游也明确把若干字段身份、比例与整车标定列为未解决项，另有不透明的 BYTE* 信号与已解释信号重叠，严格解析器可能报重叠。它是候选研究定义。

    EPS 应用层的比对结论能推到整车 CAN 信号吗？

    不能。证据只支持转移 EPS 应用代码的结论：2025 与 2023 的高应用区从 0x17E00 起逐字节相同，F181 记录为 8965F1208000 与 8A3111213000，MCU 为 R7F701383。这不等于证明每一条整车 CAN 信号与标定都相同。

    延伸阅读

    参考资料

    • 项目 02 —— public-can-dbc-datasets/additional/spanconstant5-corolla-tss3-2025/docs/COROLLA_2025_TSS3_PORT.md（0x160 字段布局、E2E 算法、失败闭合边界与 CAN 普查数据）
    • 项目 02 —— public-can-dbc-datasets/additional/spanconstant5-corolla-tss3-2025/README.md（状态表、安全边界、已知车辆行为与离线检查命令）
    • 项目 02 —— public-can-dbc-datasets/additional/spanconstant5-corolla-tss3-2025/SOURCE.md（DBC 规模 15 报文 / 120 信号、年款偏差与证据边界）

    免责声明

    本文所述控制路径来自公开仓库的移植说明，属于实验性研究成果，未经过独立实车验证。文中涉及的报文 ID、字节偏移、换算系数与安全限幅仅适用于该仓库描述的目标车辆与固件状态，不同年款、市场与 ECU 版本可能存在差异。任何涉及车辆控制的实现都必须以实际测量与合规的安全验证为准，本文不构成发送报文的操作指引。

    更新记录

    • 2026-10-14 初稿

  • Ranger EV 改装的 CarState 规格：五个真信号与一个 vEgo 陷阱

    结论：把一辆 1986 年 Ranger 的 EV 改装车接进 openpilot，真正能被真实信号填满的 carState 字段只有五个：vEgo、gas、brakePressed、gearShifter、standstill。四轮转速是从 vEgo 复制的假值，全部转向字段为零且必须保持为零，巡航状态留到第三阶段。而在进入纵向控制之前，还有一个前置阻塞项：vEgo 目前只在 3 挡正确。

    两条总线与 openpilot 侧的编号映射

    改装车上有两条独立的 250 kbit/s 总线：can0 挂 Thunderstruck MCU/BMS 与 TSM2500 充电机（ZEVCCS 相关 0x351/0x355/0x356），can1 是 X1 / Hyper9 电机的 CANopen TPDO 总线（0x181/0x182/0x183/0x184）。在移植中它们被重新编号为 Hyper9 = bus 0、MCU = bus 1。

    总线 速率 设备 openpilot bus
    can0 250 kbit/s Thunderstruck MCU/BMS + TSM2500 充电机 1
    can1 250 kbit/s X1 / Hyper9 电机控制器 0

    安装时有一处容易踩的坑：Panda 默认是 500 kbit/s，而这辆车的总线是 250 kbit/s，必须先把 Panda 的总线速率改到 250 k，再确认设备能看到 0x181 与 0x183。

    哪些字段有真实来源，哪些是占位

    规格表按「必须有」的驱动信号逐行列出来源与变换。判断标准是：能否在 ranger-dashboard/dbc/*.dbc 里找到对应的报文与信号。

    carState 字段 来源报文 信号与变换 状态
    vEgo / vEgoRaw HYPER9_STATUS 0x181 VEHICLE_SPEED（km/h，有符号 ×0.1），abs(kmh)/3.6 转 m/s 有，但挡位相关
    gas HYPER9_MOTOR 0x183 THROTTLE_REQUEST（-100..100 %），clip(req,0,100)/100 有
    brakePressed HYPER9_STATUS 0x181 SYSTEM_FLAGS bit5（FLAG_PEDAL_BRAKE） 有
    gearShifter HYPER9_MOTOR 0x183 有符号 MOTOR_RPM：大于 20 为 D，小于 -20 为 R，否则 N；FLAG_PARK_BRAKE 置 P 有
    standstill 派生 vEgoRaw 小于 0.1 有
    wheelSpeeds.fl/fr/rl/rr 无 四轮全部等于 vEgoRaw 伪造，无轮速传感器
    steeringAngleDeg / RateDeg / Torque / Pressed 无 全部为 0.0 或 False 缺传感器与 EPS
    cruiseState.available / enabled 无 暂为 False 第三阶段
    doorOpen / seatbeltUnlatched 无 固定 False 无传感器

    转向全为零在只读阶段是可以接受的：openpilot 会照常构建完整的 carState 并完成指纹匹配，只是无法转向。规格里把转向角传感器列为第 1.5 阶段要补的第一件东西——没有它，后续的横向控制就没有反馈闭环。

    vEgo 的挡位依赖问题

    这是进入纵向控制前必须先修掉的问题。X1 报出的 VEHICLE_SPEED 本身是「电机转速 × 一个固定内部速比」，而这辆车用的是 M5OD-R1 五速手动变速箱，速比每换一挡就变一次，因此单一常数的车速只在一个挡位上正确。2026 年 8 月的实测结果是：3 挡基本正确，4 挡读数约为实际值的一半。只读阶段可以容忍，纵向控制绝对不能——错误的 vEgo 会直接破坏速度控制。

    规格给出的修法不是去反推挡位，而是在变速箱下游测速，两个候选来源是 comma 设备自带的 GPS（无需新增布线，巡航准确但低速迟滞）与 M5OD 输出端的尾轴 VSS（真实车速，低速表现好）。拿到挡位无关的真实车速后，显示与日志用的前进挡位反而可以由「电机转速 / 真实车速」对照已知速比四舍五入得到——openpilot 本身只需要 vEgo 与 D/R/N。

    EV 专属信号为什么不进 carState

    openpilot 的 carState 结构里没有电池包电压、SoC、电机温度这类字段。规格明确把这些信号留在仪表盘与 MQTT 上做带外暴露，移植层不处理。

    信号 来源 展示位置
    BATTERY_SOC 0x181 或 MCU 0x355 仪表盘 SoC 表
    DC_BUS_VOLTAGE / CURRENT、power_kw HYPER9_POWER 0x182 仪表盘功率表
    MOTOR_TEMP、INVERTER_TEMP HYPER9_MOTOR 0x183 仪表盘温度
    电池包 V/I/温度、单体极值 MCU 0x356 等 仪表盘与 Home Assistant
    故障等级与系统标志 0x181 或 MCU 0x35a 仪表盘诊断

    如果后续要让这些信号进入 openpilot 内部（比如在 comma 界面显示 SoC，或用电池包故障来门禁接管），规格建议的做法是在 fork 的 carState 上加几个自定义字段，或者走一条旁路的 cereal 消息，而不是硬塞进标准结构。

    分阶段现实阶梯与安全前提

    这份规格把整件事拆成了三级阶梯，并标出了明确的硬件阻塞点。第一阶段只读是这套脚手架当前所处的状态。

    阶段 目标 状态 阻塞项
    1 只读 openpilot 通过 CAN 看到车辆 本脚手架 无
    2 纵向 通过 Hyper9 扭矩/动能回收控速 未开始 safety_ranger.h、vEgo 挡位无关化
    3 横向 转向 被阻塞 车辆无 EPS，需加装转向执行器

    第二阶段的执行路径已经写明：纵向加速度映射到发给 X1 的 MOTOR_TORQUE 命令 RPDO；制动权先由负扭矩/动能回收承担，且需要先实测动能回收的减速度上限。但在这些生效前，必须有 panda 固件里的 safety_ranger.h 钩子逐报文施加限制。第一阶段跑的是 SILENT 安全模式——记录一切，不发送任何东西。

    常见问题

    为什么四个轮速信号要伪造？

    因为这辆车没有独立轮速传感器，规格只能把四个 wheelSpeeds 全部赋成 vEgoRaw。对只读阶段和纵向控制够用，但横向调校最终需要真实的逐轮转速，属于后续要补的硬件。

    vEgo 在 4 挡读数约为实际值的一半，怎么处理？

    不要在总线里反推挡位，改在变速箱下游测速。两个方案：直接用 comma 设备自带的 GPS（无需新增布线，巡航速度准确，低速迟滞），或在 M5OD 输出端装尾轴 VSS（真实车速，低速表现好）。把 carstate.py 的 vEgo 来源从 VEHICLE_SPEED 换成其中之一。

    没有 EPS 是不是就完全做不了 openpilot？

    不是。openpilot 的两件事是转向和控速，这辆车缺的是转向执行器，因此横向被阻塞，但纵向控制不依赖 EPS，仍可在加装转向执行器之前实现。完全脱手的完整功能才需要 EPS 改装这个独立硬件项目。

    EV 的 SoC 和电池温度为什么不在 carState 里？

    因为 openpilot 的 carState 结构本身不建模电池包电压、SoC 与电机温度字段。这些信号保留在仪表盘与 MQTT 上带外暴露。若确实需要在 openpilot 内部使用，规格建议加自定义字段或走旁路 cereal 消息。

    接上 Panda 后第一件事要改什么？

    改总线速率。Panda 默认 500 kbit/s，而这辆改装车的两条总线都是 250 kbit/s，必须先把 Panda 设为 250 k，再确认设备能看到 0x181 与 0x183，之后才进入版本对齐与指纹匹配步骤。

    延伸阅读

    参考资料

    • 项目 03 —— public-can-dbc-datasets/additional/wstewarttennes-ranger-ev-conversion/openpilot-port/spec/ranger_carstate_spec.md（总线映射、逐字段来源与变换、vEgo 挡位依赖与带外 EV 信号清单）
    • 项目 03 —— public-can-dbc-datasets/additional/wstewarttennes-ranger-ev-conversion/openpilot-port/README.md（三阶段阶梯、文件职责、版本对齐步骤与安装流程）
    • 项目 03 —— public-can-dbc-datasets/additional/wstewarttennes-ranger-ev-conversion/README.md（仓库布局与仪表盘仓库关系）

    免责声明

    本文内容来自公开仓库中的自定义移植规格，描述的对象是一辆特定年份的改装车辆，其总线构成、控制器型号与变速箱配置均不具备通用性。文中数字（报文 ID、缩放系数、挡位相关性）来自该仓库的实测记录，未经独立复现。任何涉及车辆控制的改动都应以实际测量与合规验证为准，本文不构成改装或上路操作指引。

    更新记录

    • 2026-10-14 初稿

  • tinygrad 神经网络层：形状、状态与 Embedding 边界

    结论：tinygrad 的 nn/__init__.py 是通用模型层库，它的层按「形状契约 + 状态契约」工作：BatchNorm 的 running_mean/running_var/num_batches_tracked 是推理结果相关状态，Conv1d/ConvTranspose1d 复用二维实现，Embedding 默认路径对越界索引返回零向量而非显式拒绝。openpilot 是通过 ONNX 构建已捕获模型，不能把层库的训练能力直接等同于车端在线学习。

    组件与关键函数

    基线是 source/ 固定快照，逐类解析公开层和两个 Embedding 内部路径。各层的形状契约必须写清楚，不能只按名字替换。

    组件 实现与输入输出契约
    BatchNorm 通道轴固定为 1，均值/方差跨其余轴。训练时以 momentum 更新累计统计量；方差更新含 x.numel()/(x.numel()-x.shape[1]) 无偏校正，单通道单样本等分母为零的输入不属于可直接保证的有效域。BatchNorm2d/3d 只是别名。
    Conv1d / Conv2d 一维接口以单元素 kernel tuple 复用通用卷积层。权重为 (out_channels, in_channels/groups, *kernel)；padding='same' 只接受 stride=1，按反向空间轴生成不对称 pad。
    ConvTranspose1d / ConvTranspose2d 初始化后重建权重为 (in_channels, out_channels/groups, *kernel)，调用 conv_transpose2d() 并传入 stride、padding、dilation、groups 与 output_padding。加载普通卷积权重不能只凭同名字段互换。
    Linear 初始化权重 (out_features, in_features)，前向转置后调用 x.linear()，在最后一维做变换；支持前置批/时间维。
    LSTMCell weight_ih/weight_hh 产生四门 i/f/g/o，输入为 (batch,input_size)，可选 (h,c) 形状为 (batch,hidden_size)；省略时创建零状态，调用者负责跨时间步保存与回传状态。

    归一化层各有约定：GroupNorm 把输入 reshape 为 (N, groups, -1)、InstanceNorm 为 (N, channels, -1)，借 layernorm() 沿末维归一化再还原形状；输入通道数/分组整除与 NCHW 布局是适配契约。LayerNorm 断言输入尾维与 normalized_shape 完全一致，LayerNorm2d 把 NCHW 暂转 NHWC 归一化通道再转回，二者都不更新运行统计量。RMSNorm 按末维平方均值计算逆 RMS，先转 float 计算、再转回输入 dtype，半精度目标后端需单独比对数值误差。

    形状契约上还有几处必须显式记住：BatchNorm2d/3d 只是同一类的别名；ConvTranspose 系列在重建权重后调用 conv_transpose2d()，并把 output_padding 一并传入，普通卷积权重不能只凭字段同名就替换；Linear 前向会先转置权重、在最后一维做变换，因此前置的批/时间维是允许的。

    Embedding 的两条内部路径

    Embedding.__call__() 仅接受整数索引。默认通过与 arange(vocab) 全量比较、选取权重再沿词表归约，输出形状为 indices.shape + (embed_size,)；索引超出词表时默认路径得到零向量，并非显式拒绝。当 USE_ATOMICS=1 时把前向包成 CALL，反向先清零 FP32 梯度，再按 token 原子 scatter-add。

    这里有一条语义差异：原子实现仅列出 CPU/NULL/AMD，词表分片只支持轴 0、其他分片会断言；索引在反向内 clip 到词表边界，因此无效 token 在默认前向和原子反向可能产生不同语义。插件入口应先验证索引在 0 到 vocab_size 范围内。

    状态管理方面，LSTMCell 在省略初始状态时创建零状态，返回新的 (h,c)，跨时间步的保存与回传由调用者负责；LayerNorm、LayerNorm2d、GroupNorm、InstanceNorm 与 RMSNorm 都不更新运行统计量，只有 BatchNorm 会写入累计统计量，这也是它在导出时必须与权重一起版本化的原因。

    状态、硬件与插件契约

    BatchNorm 的运行统计量属于推理结果相关状态，模型导出必须与权重、eps、仿射配置一起版本化；切换 TRAINING 会改变统计来源及写入行为。TRAINING 与 USE_ATOMICS 默认都关闭。Conv2d、Linear 等初始化使用随机权重，加载模型工件后才能代表实际训练模型。

    契约项 必须声明的内容
    张量 ABI 输入 shape/dtype/布局、权重 hash、运算版本、目标后端、数值容差。
    状态 运行统计量、状态复位条件、最坏时延。
    权限 模型层实现不得获得 CAN 发送、panda 安全配置或车辆控制发布权限。
    原子路径 若启用原子自定义内核，需单独审计设备支持、重复索引并发与越界 token 行为。

    「万物即插件」宜以可验证的模型工件和张量 ABI为边界，而不是把每个层都做成车端可热替换插件。相机/推理硬件插件提供帧、时间戳、缓冲所有权和执行能力；模型层实现只消费签名/版本绑定的工件。

    反过来说，层库能训练、能加载随机权重，并不代表它在车端可用；只有把权重、运行统计量与运算版本一起冻结、并对目标后端做数值与时延验收之后，这些层才具备进入推理链的前提。

    与 openpilot 的关系与验证范围

    compile_model() 构建 ONNX/JIT 工件；运行期 ModelState.run() 调用已捕获模型。对 openpilot 与 examples 目录的 nn.<层名> 搜索未发现直接实例化上述层；这只说明可见 Python 源码，不能推断缺失的 LFS 模型图里没有对应 ONNX 算子。

    验证层面，以 PYTHONPATH=. DEV=PYTHON RUN_SLOW=1 运行六项上游定向测试：BatchNorm2d、Linear、LayerNorm2d、RMSNorm、Embedding、LSTMCell，全部通过（51.793 秒）。转置卷积、原子路径、分片、多后端、真实模型数值与目标车载硬件仍未验证；LFS 模型实体缺失，不能声称整模型或整车验证。

    常见问题

    Embedding 遇到越界索引会发生什么？

    默认路径会得到零向量，并非显式拒绝：_embedding_fwd() 通过与 arange(vocab) 全量比较、选取权重再沿词表归约。但索引在原子反向内会被 clip 到词表边界，所以无效 token 在默认前向和原子反向可能产生不同语义，插件入口应先验证索引在 0 到 vocab_size 范围内。

    BatchNorm 的运行统计量需要一起导出吗？

    需要。running_mean/running_var/num_batches_tracked 是推理结果相关状态，源码要求模型导出必须与权重、eps、仿射配置一起版本化；切换 TRAINING 会改变统计来源及写入行为。TRAINING 默认关闭。

    Conv1d 能直接用 Conv2d 的权重换吗？

    不能只凭同名字段互换。Conv1d 以单元素 kernel tuple 复用通用卷积层；而 ConvTranspose1d/2d 会在初始化后重建权重为 (in_channels, out_channels/groups, *kernel) 并调用 conv_transpose2d()，加载普通卷积权重不能只靠字段名相同就替换。

    可以把每个 nn 层做成车端热替换插件吗？

    不建议。源码建议以可验证的模型工件和张量 ABI 为边界，而不是把每个层都做成车端可热替换插件；契约至少包括输入 shape/dtype/布局、权重 hash、运算版本、目标后端、数值容差、运行统计量、状态复位条件和最坏时延。模型层实现不得获得 CAN 发送、panda 安全配置或车辆控制发布权限。

    延伸阅读

    参考资料

    • 项目 02 —— openpilot-research/TINYGRAD_NN_LAYERS_STATE_SHAPE_EMBEDDING_CONTRACT_DEEP_DIVE.md（取用了各层形状/状态契约、Embedding 两条内部路径、插件边界与六项上游测试结论）。
    • 项目 02 —— openpilot-research/TINYGRAD_DTYPE_UOP_LOWERING_EMULATION_DEEP_DIVE.md（仅用于确认 dtype 降解专题的接续关系，未取用其未公开内容）。

    说明：本文为对固定源码快照的静态结构分析，未运行完整测试套件、未连接硬件、未验证目标车型的真实参数组合。文中所有阈值、行号索引与配置均出自源文档，标注为未验证的结论保留其原有边界。

    更新记录

    首次发布 2026-10-11 最近核对：2026-10-11

  • tinygrad 优化器为何不能只存权重：zero_grad 置 None

    结论：tinygrad 的优化器是训练期参数更新器，不是车端规划器或控制器；把它接进车端推理链没有意义。有两个事实最容易被忽略。第一，zero_grad() 是把每个参数的 .grad 设为 None，不是对梯度缓冲填零，下一轮 backward() 才重新生成梯度。第二，step() 的执行包含参数、动量/矩和偏置幂三组状态的同批 realize，只序列化权重而遗漏优化器状态，不能无损续训。此外 FUSE_OPTIM 与 TRAINING 默认都是 0，它们是 tinygrad 的上下文/构建配置，不是车辆安全授权。以下为固定快照的静态分析，未运行完整优化器矩阵或实车测试，本地没有模型实体。

    公共生命周期

    Optimizer.__init__() 拒绝负学习率，只把 is_param 张量作为可更新参数并按对象去重，非参数进入 buffers；无可更新参数会断言。device 默认取第一个参数的设备，OPTIM_DTYPE 默认 float32，学习率 dtype 至少为 float32。_new_optim_param() 为动量/矩状态创建零张量：普通模式逐参数创建，设备为 tuple 时使用 zeros_like，融合模式只创建一条展平状态，长度由 pos_params 决定。

    调度与执行上，schedule_step() 要求 TRAINING=1：融合模式拼接参数与梯度、执行一次 _step() 再按原形状拆回，普通模式逐参数更新；它调用 assign() 排定状态和参数写入，返回额外状态、参数和 buffer 的实现列表，梯度缺失则通过 unwrap() 报错。step() 把 schedule_step() 返回的张量交给 Tensor.realize()；_apply_update() 将更新量搬到参数设备并从 detach() 后的参数中减去。由于 schedule_step() 已有 assign 副作用，不应视为只读计划 API。

    入口 实现及外部契约
    Optimizer.__init__() 拒绝负学习率；仅 is_param 张量可更新并按对象去重；OPTIM_DTYPE 默认 float32。
    _new_optim_param() 创建零状态张量；融合模式只建一条展平状态，长度由 pos_params 决定。
    zero_grad() 把 .grad 设为 None，不是填零；下轮反传重新生成。
    schedule_step() 要求 TRAINING=1；融合拼接后一次 _step() 再拆回；有 assign 副作用。
    step() / _apply_update() 前者把张量交给 realize()；后者在参数设备上从 detach() 参数减去更新量。
    OptimizerGroup 汇集多优化器的参数/buffer/排定更新；无跨组参数去重，也未调用基类构造器。

    优化器族与状态布局

    优化器族大致分为 LARS 家族与 LAMB 家族。SGD() 是 LARS(tcoef=0, pre_wd=True) 的包装；LARS._step() 可按参数/梯度范数计算 trust ratio，支持两种动量与 Nesterov，权重衰减和学习率在 classic 分支的作用次序不同。Muon() 复用 LARS 更新主干，先对梯度应用 Newton-Schulz，再做学习率及后置权重衰减，并明确拒绝 fused=True。

    优化器 实现要点 边界
    SGD() LARS(tcoef=0, pre_wd=True) 包装 复用 LARS 主干与权重衰减次序。
    LARS._step() 按参数/梯度范数算 trust ratio；两种动量与 Nesterov 权重衰减与学习率次序在 classic 分支不同。
    Muon() 先 Newton-Schulz 再学习率与后置权重衰减 拒绝 fused=True；形状与数值稳定性不能由接口名保证。
    Adam() 包装 LAMB(adam=True)，trust ratio 固定为 1 不加权重衰减。
    AdamW() 同 Adam 包装 默认衰减为 0.01。
    LAMB._step() 更新幂状态与一、二阶矩，做偏置修正与 eps 分母稳定，可选算 trust ratio 梯度与状态设备不同则先搬至状态设备；更新量 shard_like(t) 在参数设备应用。

    状态布局的关键是 OPTIM_DTYPE 默认 float32、FUSE_OPTIM 默认关闭；融合时会把参数和梯度展平拼接，切换融合配置或设备布局不能直接复用旧状态形状。学习率 dtype 至少为 float32。

    状态机与调用顺序

    典型训练调用为：loss.backward() 前先 zero_grad()，随后 loss.backward()、step()。step() 的执行包含参数、动量/矩和偏置幂的实现；仅序列化权重而遗漏优化器状态，不能无损续训。FUSE_OPTIM 默认 0、TRAINING 默认 0，这两个开关是 tinygrad 的上下文/构建配置，不是车辆安全授权。OptimizerGroup 的交叉参数重叠、状态文件版本兼容、多设备搬运以及异常发生在部分 assign() 之后的恢复语义，均应列入训练插件测试矩阵。

    开关 / 状态 默认值 含义
    OPTIM_DTYPE float32 优化器状态张量的默认 dtype。
    FUSE_OPTIM 0（关闭） 融合时参数与梯度展平拼接为单条状态。
    TRAINING 0（关闭） schedule_step() 要求其为 1；是构建/上下文配置，非安全授权。
    优化器状态集合 — 参数 + 动量/矩 + 偏置幂，step() 时同批 realize。

    ONNX 与车端关系

    OnnxRunner._init_from_graph() 通过图中训练域节点设置 is_training，OnnxRunner.__call__() 在该标志下设置 Context(TRAINING=...)。ONNX 的 Adam() 借用 TinyAdam，但把外部 V/H 及学习率装入临时优化器，并依据步数初始化偏置幂——这属于 ONNX 训练域功能，不表明 openpilot 车端执行在线学习。

    车端一侧，openpilot 的 compile_model() 在构建时把 ONNX 编译为捕获的模型工件；运行期 ModelState.run() 调用 run_warp/run_model 并解析输出。当前本地源码未见该路径实例化 tinygrad.nn.optim 或调用 step()；由于缺少模型实体，只能确认可见源码的调用边界，不能断言模型图内部的全部节点。

    硬件与插件重构建议

    把优化器、梯度、训练域 ONNX 和权重写入归入离线训练/构建插件；车端推理插件只接受已验证、版本绑定、只读的模型工件，不要给训练插件 CAN 发送、panda 安全模式或控制消息发布权限。模型工件契约应记录 ONNX/opset、tinygrad 版本、dtype、输入输出 shape、目标设备、权重哈希和参考数值；优化器状态另行版本化，fused、参数顺序和设备分片都需一致。硬件替换只接管相机帧、时间戳、缓冲拷贝/映射和推理执行端，保持 modelV2 等输出 schema、延迟预算和健康信号稳定，不可通过更换优化器绕开感知、规划、车型协议与 panda 固件安全门。

    常见问题

    zero_grad() 是把梯度清零吗？

    不是。它把每个参数的 .grad 设为 None，而不是对已有梯度缓冲填零；下一轮 backward() 会重新生成梯度。

    只保存权重就能无损续训吗？

    不能。step() 的执行包含参数、动量/矩和偏置幂三组状态的同批 realize；只序列化权重而遗漏优化器状态，无法无损续训，优化器状态需要另行版本化保存。

    tinygrad 优化器与 openpilot 车端推理是什么关系？

    没有直接关系。优化器是训练期参数更新器；openpilot 在构建时把 ONNX 编译为捕获的模型工件，运行期 ModelState.run() 只运行该工件，当前可见源码未见车端实例化 tinygrad.nn.optim 或调用 step()。

    FUSE_OPTIM 或 TRAINING 打开会影响车辆安全吗？

    不应这样理解。这两个开关默认都是 0，是 tinygrad 的上下文/构建配置，不是车辆安全授权；训练数值测试也不等于整车安全验证。

    延伸阅读

    参考资料

    • 项目 02 —— openpilot-research/TINYGRAD_OPTIMIZER_TRAINING_STATE_INFERENCE_BOUNDARY_DEEP_DIVE.md（取用了优化器族与状态表、zero_grad 置 None、三组状态同批 realize、ONNX 训练域与车端推理边界）。

    说明：本文为对固定源码快照的静态结构分析，未运行完整测试套件、未连接硬件、未验证目标车型的真实参数组合。文中所有阈值、行号索引与配置均出自源文档，标注为未验证的结论保留其原有边界。

    更新记录

    首次发布 2026-10-11 最近核对：2026-10-11

  • JotPluggler 视频与缩略图：8 帧缓存与解码器共享

    结论：JotPluggler 的相机与缩略图路径是离线路段媒体查看——实时模式会排除四类编码索引/编码数据、直播编码索引及 thumbnail，因此不能把它描述成实时行车画面输入。build_camera_index() 按数组最短长度合成 (timestamp, segment, decode_index, frame_id) 并按时间排序，但不逐项核对多条字段曲线时间戳一致性、也不在建索引时验证 decode_index 在媒体帧数内，无效索引要到取帧时才失败。解码器按 (CameraType, width, height) 复用，锁只覆盖获取/建立过程，若两路映射到相同组合并发解码，存在共享可变解码状态竞争风险（跨文件静态推断，未复现）。以下为固定快照 c8fb906 的静态阅读，未下载视频、未解码损坏媒体、未运行 GUI、未测内存/帧时延。

    路段中的图像索引

    load_route_data() 在路段数据归一化后，调用 build_camera_index() 分别建立窄路、座舱、广角路和 qcamera 四类索引。它先收集有文件路径的片段，再从对应 *EncodeIdx 曲线读取 segmentNum、segmentId（缺失时 segmentIdEncode）及可选 frameId；按数组最短长度和同一索引组合成 (timestamp, segment, decode_index, frame_id)，最后按时间排序。缺少索引曲线时虽然有文件路径，也不会形成可按时间选帧的条目。

    frame_id 会保留在结构中，但本工具取帧请求使用的是 decode_index。build_camera_index() 没有逐项核对多条字段曲线时间戳一致性，也没有在建索引时验证 decode_index 在媒体文件帧数内；实际无效索引要到 FrameReader::get() 才失败。这与 GPS 字段按索引拼接的风险类似：对丢字段、乱序、跨段切换需要带真实日志的对齐测试。

    extract_segment_thumbnails() 另从 THUMBNAIL 事件提取 JPEG，时间优先用 timestampEof，为零时退回事件 logMonoTime；build_route_data() 排序并与其他数据共用时间原点。

    相机请求、解码与纹理

    四个 CameraFeedView 各自有需求线程，围绕「选帧 → 解码 → 上传纹理」运转。下表列出实现行为与边界。

    函数 / 组件 实现行为 边界
    CameraFeedView::Impl::setCameraIndex() 替换相机索引、清空待处理请求和 8 帧结果缓存、递增 generation，按首个片段组织预加载 切换路段会重置纹理与请求；旧下载/解码通过 generation/serial 检查避免结果误入新路段
    request_for_time() / update() 根据 tracker 时间选最近索引帧；优先当前帧或缓存，允许先显示同片段附近帧，再排入最新请求 附近帧只是临时可视回退，不应作为精确时间证据；失败帧记入 failed_request，相同请求不立即重试
    demand_worker_loop() 加载片段的 FrameReader，按 decode_index 解码进 VisionBuf，NV12 转 RGBA；完成后向 UI 交付并向前预取两帧 RGBA 按 width * height * 4 分配；媒体尺寸异常时需端到端限制和压力测试
    preload_worker_loop() / ensure_reader_loaded() 两个预加载线程按与当前片段距离预开其他视频，需求线程可等待同片段的在途加载 readers 是按片段保存的 map，本路径未见固定数量/字节上限
    upload_pending_result() / drawSized() UI 线程上传 RGBA 到 GL 纹理；Fit 模式裁切填满 pane，另一模式保持原比例完整显示 8 帧 RGBA 缓存之外还有纹理、解码缓冲及预加载 reader
    FrameReader::load() / DecoderManager::acquire() HTTP(S) 视频先走本地缓存再用 FFmpeg 探测/建帧索引；按相机类型和尺寸复用解码器 锁只覆盖获取/建立过程；FFmpegVideoDecoder::decode() 使用实例上下文与帧缓冲，未见同实例解码互斥

    这套链路也有资源上界缺口：readers 是按片段保存的 map，本路径未见固定数量或字节上限，长路段可能积累解析器与索引；四个 CameraFeedView 各自有需求线程，若两路映射到相同 (CameraType, width, height) 并发解码，存在共享可变解码状态竞争风险（跨文件静态推断，需并发用例确认）。

    缩略图与实时限制

    ThumbnailView::Impl::update() 用二分查找选离 tracker 最近的缩略图；decode_jpeg() 使用 FFmpeg MJPEG 解码，仅接受 YUV420/422/444 类格式，手工转换成 RGBA，随后上传单个 GL 纹理。成功图像按比例居中并叠加时间、片段、序号；失败索引在当前缩略图集合内不反复解码。rgba.resize(width * height * 4) 前只检查解码尺寸大于零，未见更小的像素/内存预算，应以异常 JPEG 测试资源约束。

    环节 行为 边界
    缩略图选图 二分查找选离 tracker 最近的缩略图，时间优先 timestampEof、为零退回 logMonoTime 失败索引在当前集合内不反复解码
    JPEG 解码 FFmpeg MJPEG，仅接受 YUV420/422/444 类格式，手工转 RGBA 后上传单个 GL 纹理 rgba.resize(width * height * 4) 前只检查解码尺寸大于零，无更小像素/内存预算
    实时订阅排除 实时模式排除四类编码索引/编码数据、直播编码索引及 thumbnail 相机与缩略图路径是离线路段媒体查看，不是实时行车画面
    隐私 座舱视频与缩略图可能涉及人脸、乘员与道路位置 导出、远程下载、缓存清理及访问控制应分开设计

    关键限制来自 should_subscribe_stream_service()：它在实时模式排除四类编码索引/编码数据、直播编码索引及 thumbnail，因此上述相机和缩略图路径是离线路段媒体查看，不能把它描述成实时行车画面输入。工具读到的座舱视频和缩略图可能涉及人脸、乘员与道路位置；导出、远程下载、缓存清理及访问控制应分开设计。

    对「万物即插件」的约束

    建议拆成 VideoIndexProvider、FrameDecoder、ThumbnailDecoder 和只读 MediaPane。索引契约必须声明时间基准、片段编号、解码帧序号及缺帧语义；解码器实例要么独占线程，要么明确同步。宿主统一限制像素数、缓存字节、打开的 reader 数及并发下载；出错时向用户标出「正在显示附近帧/上一帧」，避免将近似画面误当当前时刻。媒体插件不得获取 CAN TX、固件更新或安全配置权限。

    同目录测试仅检查帮助输出；本文未运行损坏 HEVC/JPEG、并发多路、远程下载、GPU 纹理或内存压力测试。

    常见问题

    这是实时行车画面吗？

    不是。实时模式会排除四类编码索引/编码数据、直播编码索引及 thumbnail，因此相机与缩略图路径是离线路段媒体查看，不能描述成实时行车画面输入。

    8 帧缓存就是内存上界吗？

    不是。8 帧 RGBA 缓存之外还有纹理、解码缓冲及预加载 reader，不能用「8 帧」估算总内存上界。

    索引里的 decode_index 一定有效吗？

    不一定。build_camera_index() 不在建索引时验证 decode_index 在媒体文件帧数内，实际无效要到 FrameReader::get() 才失败。

    两路相机同时解码安全吗？

    不能假定安全。解码器按 (CameraType, width, height) 复用，锁只覆盖获取/建立过程；若两路映射到相同组合并发解码，存在共享可变解码状态竞争风险。这是跨文件静态推断，需并发视频用例或 ThreadSanitizer 确认，不能视为已复现故障。

    延伸阅读

    参考资料

    • 项目 02 —— openpilot-research/JOTPLUGGLER_VIDEO_THUMBNAIL_DEEP_DIVE.md（相机索引、请求/解码/纹理链与缩略图边界）
    • 项目 02 —— openpilot-research/JOTPLUGGLER_DATA_PIPELINES_DEEP_DIVE.md（图像链所在的离线/实时数据管线，作为本文的补充阅读）

    说明：本文为对固定源码快照的静态结构分析，未运行完整测试套件、未连接硬件、未验证目标车型的真实参数组合。文中所有阈值、行号索引与配置均出自源文档，标注为未验证的结论保留其原有边界。

    更新记录

    首次发布 2026-10-11 最近核对：2026-10-11

  • 原生 util 的 I/O 契约：短写、退出标志与跨语言时间门

    结论：原生公共工具层把文件 I/O、资源所有权、退出信号和时间门做成了一组「低语义」原语：默认假设调用方会补齐持久化、超时与状态校验。write_file() 单次写入且不 fsync、check_output() 不返回退出码、ExitHandler 不打断阻塞 I/O，C++ 与 Python 的 system_time_valid 阈值也不相同，因此这些原语都不能单独作为「成功」的证据。

    I/O 原语与真实调用方

    原语 源码行为 消费边界
    HANDLE_EINTR 只在返回 -1 且 errno=EINTR 时重试，最多再试约 100 次；不负责短读/短写或其他错误。 参数文件操作、摄像头 V4L2 ioctl、panda 设备打开。
    read_file() 优先 seek 到末尾、预分配并读；不能可靠 seek 的 procfs 等回退到流缓冲；打开失败和空文件都返回空字符串。 启动日志、配置/状态读取。
    read_files_in_dir() 目录打开失败返回空 map；遍历非目录条目并用 read_file() 读内容，未区分非目录项类型或单项读取失败。 参数读取、pstore 读取。
    write_file() 打开后只调用一次 write，短写直接返回 -1；关闭结果不检查，无 fsync、临时文件或原子替换。 布局/DBC/地图缓存写入；不能将返回 0 解读为断电持久化。
    safe_fwrite() 按元素数继续写，直到写满或返回 0 且 errno != EINTR；未见错误位清理、总耗时/重试上限或刷新。 视频写入检查长度并记错；压缩写入用断言检查。
    safe_ioctl() EINTR 时重试；最终失败时仅在传入异常消息的模式记录并抛错，否则返回 -1。 原生设备调用方必须自己定义超时、状态回滚和故障上报。
    create_directories() 先试 mkdir，父目录缺失时递归创建；已存在路径必须确认为目录；无所有权/软链接隔离。 参数路径、路段目录及测试命名空间。
    check_output() popen(command, "r") 收集 stdout；打开失败返回空字符串，未把子进程退出码返回调用方。 启动日志 journalctl、设备状态命令、回放和地图工具。

    write_file 与 check_output：缺持久化与退出状态

    safe_fwrite() 若底层流进入错误状态而 errno 恰好仍为 EINTR，当前循环没有清理 FILE* 错误位或限定次数，存在无法前进的静态路径；是否在目标 libc/存储故障条件下实际触发，需故障注入验证。插件宿主不应直接把它用作无限等待的关键日志或控制输出。

    write_file() 和 check_output() 则分别缺少持久化保证与退出状态契约，不适合作为「更新成功」或「诊断命令成功」的唯一证据。前者单次写入且不 fsync，后者只收集 stdout、不返回退出码。

    信号与文件描述符所有权

    ExitHandler 构造时登记 SIGINT、SIGTERM，非 Apple 还登记 SIGPWR；静态原子量保存退出标志、最后信号和电源故障标志。它能让业务循环观察退出请求，但不自动中断阻塞的设备 I/O，也不恢复此前的信号处理器。插件进程不能默认通过复用它获得可取消的关闭协议。

    unique_fd 在析构时关闭非 -1 描述符；自定义移动赋值会直接覆盖目标 fd_ 而不先关闭旧值。因声明了移动赋值，复制构造/赋值在该定义下被隐式删除，也没有可用的显式移动构造。当前 SpectraMaster::init() 将新打开的相机 fd 赋给成员，首次赋值前默认是 -1；若以后允许重复初始化或对已持有 fd 的包装器再次赋值，就可能遗失旧 fd。这应视为资源所有权审计点，而非已观察到的相机泄漏。

    数值与通用类型方面，map_val() 先夹紧输入再做同类型线性映射，a1 == a2 未被拒绝，整数类型还会发生除法/乘法截断；FirstOrderFilter 把 dt/ts 固定为构造时系数，reset() 只改值、不改初始化标志；update_max_atomic() 用 CAS 维护最大帧号。这些函数是算法/并发原语，不自带传感器范围、NaN 或 deadline 校验。

    C++/Python 日期门差异

    C++ system_time_valid() 的下界是 2024-08-26 与系统服务文件 mtime 加一天的较大者，只有下界检查。Python system_time_valid() 则使用 2025-02-21 下界和 2035-01-01 上界。

    维度 C++ 实现 Python 实现
    下界 2024-08-26 与 systemd 文件 mtime 加一天的较大者 2025-02-21
    上界 无上界 2035-01-01
    主要消费者 安装器等待该门 更新、eSIM、GNSS 等服务依赖该门
    加一天算法 对 mtime 加 86400 个实际秒 先取本地无时区时间再加一天

    同一设备在 2024-08-26 到 2025-02-21 之间，或 2035-01-01 之后，可能呈现不同的「时间有效」判断；systemd 文件 mtime 也可能改变两边下界。它们都只是日期范围门，不证明 NTP/GNSS/RTC 可信。加一天的算术也不同：C++ 对 mtime 加 86400 个实际秒，Python 先取得本地无时区时间再加一天；若本地时区跨夏令时边界，两个阈值可差一小时。目标设备的时区配置尚未验证，不能将此条件差异直接写成实机安装故障。

    硬件与插件化要求

    插件文件服务应区分原子可见、落盘持久、写满重试、关闭错误与超时；受信任宿主负责路径所有权、配额和故障上报，不直接暴露 popen、设备 ioctl 或任意写路径。相机/编码器等资源包装器需单一所有权、明确移动语义及重复初始化测试；关闭流程不能依赖信号标志自动打断内核阻塞调用。跨语言时间有效性应使用统一策略与版本号，并在模拟时钟、未来日期、systemd mtime 异常和车端冷启动下验证，不能把任一布尔范围门当作可信时间证明。

    常见问题

    write_file() 返回成功是否代表数据已落盘？

    不代表。write_file() 打开后只调用一次 write，不检查关闭结果，也没有 fsync、临时文件或原子替换。因此不能将返回 0 解读为断电持久化。

    ExitHandler 能自动取消阻塞的设备 I/O 吗？

    不能。ExitHandler 让业务循环观察退出请求，但不自动中断阻塞的设备 I/O，也不恢复此前的信号处理器；插件进程不能默认通过复用它获得可取消的关闭协议。

    C++ 与 Python 的 system_time_valid 阈值一致吗？

    不一致。C++ 下界是 2024-08-26 与 systemd 文件 mtime 加一天的较大者且无上界；Python 用 2025-02-21 下界和 2035-01-01 上界。同一设备在某些时段可能得到不同的「时间有效」判断。

    为什么跨夏令时会让两边阈值差一小时？

    因为加一天的算术不同：C++ 对 mtime 加 86400 个实际秒，Python 先取本地无时区时间再加一天。若本地时区跨夏令时边界，两边的次日阈值可相差一小时；目标设备时区尚未验证。

    延伸阅读

    参考资料

    • 项目 02 —— openpilot-research/NATIVE_UTIL_IO_EXIT_CONTRACT_DEEP_DIVE.md（取用了 I/O 原语与调用方、信号与 fd 所有权、C++/Python 日期门差异）。
    • 项目 02 —— openpilot-research/COMMON_UTILS_IO_RETRY_RUNTIME_DEEP_DIVE.md（仅用于确认公共工具 I/O 与重试运行时的边界）。

    说明：本文为对固定源码快照的静态结构分析，未运行完整测试套件、未连接硬件、未验证目标车型的真实参数组合。文中所有阈值、行号索引与配置均出自源文档，标注为未验证的结论保留其原有边界。

    更新记录

    首次发布 2026-10-11 最近核对：2026-10-11

  • 视频编码：录制与直播分流，切段由帧号阈值决定

    结论：视频编码链里「录制」和「直播」是两条分流：loggerd 订阅非直播 EncodeData 并转为媒体文件与 EncodeIdx，直播主题由 WebRTC 消费、不按录制媒体流写盘。切段由帧号阈值决定——每路按 SEGMENT_LENGTH × MAIN_FPS 关闭/重开编码器，段长通常 60 秒、20 FPS，但输入缺帧时不能只按墙上时钟推断切段位置。

    本文基于固定源码快照的静态阅读，未取得完整 LFS/平台环境，也未在相机或 V4L 编码硬件上运行。采集端与落盘端属于相邻专题，这里聚焦编码进程、多相机同步、后端差异与切段/索引。

    进程、相机和消息边界

    encoderd 随 onroad 运行；stream_encoderd 用同一可执行文件加 --stream，在直播或非汽车模式运行；部分硬件另有 --clip 离线导出入口，不属于这两个实时进程。三者的输入都是 camerad 通过 VisionIPC 发布的帧。

    边界 已核对行为
    进程选择 encoderd 随 onroad 运行；stream_encoderd 同可执行文件加 --stream；--clip 是离线导出，不属于实时进程
    相机表 窄路面流发主录制流（硬件 HEVC、PC FFVHUFF）与低码率 qNarrowRoadEncodeData；广角、座舱各有主流
    座舱流 座舱主流的 record 取决于 RecordFront
    输入 启动时探测可用 VisionIPC 流，每个可用流起一个编码线程；连接后从帧缓冲及 VisionIpcBufExtra 读取帧号/时间戳
    输出 发布编码字节、尺寸、Unix 发布时刻、帧 ID、SOF/EOF、编码 ID、段号/段内 ID 与关键帧标记
    时间域 logMonoTime、采集 EOF 和 Unix 发布时间是不同时间域
    录制/直播分流 loggerd 订阅非直播 EncodeData 转媒体文件；直播主题由 WebRTC 消费，不写盘

    实时调度与切段

    sync_encoders() 意图在多编码器起始阶段汇总可用流帧号，把共同起点推到当前帧后两个帧号，每路达到阈值才编码。但父线程在增加 max_waiting 的同时逐个启动子线程，等待数尚未冻结，早启动的线程可能误走单路分支。即使门正常通过，也只同步起始帧 ID，不等于整段硬件时钟同步。

    encoder_thread() 检查 VisionIPC 缓冲自身帧 ID 与附加元数据的帧 ID 是否相等，失配则跳过，首次落后时记日志。每路按 SEGMENT_LENGTH × MAIN_FPS 的帧号阈值关闭/重开编码器。

    缩略图有独立的节拍：同一窄路面帧会分别送主编码器和 qcamera 编码器；缩略图由 JpegEncoder::pushThumbnail() 在 frame_id % 1200 == 100 时生成，使用 JPEG 消息发布，不是每帧都有缩略图。

    loggerd.handle_encoder_msg() 对齐编码器段号与当前日志段，新段创建 writer、等待关键帧后写入媒体，并把 EncodeData.idx 转为 EncodeIdx 写入事件日志。encoderd、loggerd 独立启停，段号对齐依赖首次收到的偏移，不能把编码器内部段号直接当路由段号。

    切段与索引的对应关系需要端到端核对：编码器按帧号阈值分段，loggerd 再按段号把媒体写入文件并把 EncodeData.idx 转为 EncodeIdx；两个进程独立启停，因此「编码器内部段号」与「路由段号」不能默认相同。跨段队列、音频等待与段边界处的关键帧对齐，都需要单独验证，不能只凭媒体文件存在就判定编码链完整。

    编码后端：硬件与 PC 不等价

    V4LEncoder 打开 Qualcomm V4L2 编码设备、提交 NV12 缓冲；后台 dequeue_handler() 接收配置头和编码包，以 EOF 时间戳断言输入/输出配对，关键帧带配置头发布，段结束时等待队列排空及 EOS。这些时序需实板确认。

    后端 行为与限制
    硬件（V4L） 打开 Qualcomm V4L2 编码设备、提交 NV12；以 EOF 时间戳断言输入/输出配对，关键帧带配置头发布，段结束等待队列排空及 EOS
    PC（Ffmpeg） NV12 转 I420、必要时缩放；qcamera 用 H.264，其他流用 FFVHUFF；header 为空，set_bitrate() 和 request_keyframe() 仅记「不支持」
    缩略图 NV12 下采样经 FFmpeg MJPEG 输出 thumbnail；尺寸与源流比例用断言约束

    软件后端不是硬件 HEVC 的等价替代。直播时 encoder_set_bitrate() 与 encoder_request_keyframe() 每帧读取参数，WebRTC 侧通过 LivestreamEncoderBitrate 和 LivestreamRequestKeyframe 交互；PC 后端只记录不支持。把直播插件换成独立编码器时，应明确参数所有权、关键帧请求的确认与超时。

    故障边界与验证

    源码可见的故障路径包括：VisionIPC 尚未可用时重试、帧号失配跳帧、编码失败记录、V4L poll 超时继续等待、V4L 输入/输出时间戳失配断言。一个容易被忽略的边界是：外层 VisionIPC 重连后并未清空已创建的编码器或重做多相机起始同步；若新流尺寸/帧号语义改变，恢复行为需要专门测试，不能从重连循环存在就推断安全恢复。

    故障路径 当前处理 未覆盖的部分
    VisionIPC 不可用 重试 重连后未清编码器、未重做起始同步
    帧号失配 跳过该帧，首次落后时记日志 恢复后帧号语义改变的行为待测
    V4L poll 超时 继续等待 无独立截止语义
    输入/输出时间戳失配 断言 需实板确认

    test_encoder.py 是硬件测试入口，会检查媒体文件、帧数、编码索引及多相机首帧一致性；本次未运行。面向新硬件，至少应验证缓冲所有权、帧号/时间戳、编码包与索引一一对应、关键帧切段、断流重连和录制/直播互不抢占。

    常见问题

    录制和直播走的是同一条链路吗？

    不是完全同一条。loggerd 订阅非直播 EncodeData 并转为媒体文件与 EncodeIdx；直播主题由 WebRTC 消费，不按录制媒体流写盘。两者共享编码器输出，但下游消费与落盘路径不同。

    切段是按墙上时钟还是按帧号？

    按帧号阈值。每路按 SEGMENT_LENGTH × MAIN_FPS 关闭/重开编码器，段长通常 60 秒、20 FPS；输入缺帧时不能只按墙上时钟推断切段位置。

    VisionIPC 重连后就等于安全恢复了吗？

    不能这样推断。源码里外层重连后并未清空已创建的编码器或重做多相机起始同步；若新流尺寸或帧号语义改变，恢复行为需要专门测试。重连循环存在，不等于恢复过程安全。

    PC 上的软件编码能替代硬件编码吗？

    不能当成等价替代。硬件走 Qualcomm V4L2、关键帧带配置头、段结束等待 EOS；PC 后端 NV12 转 I420、header 为空，set_bitrate() 和 request_keyframe() 仅记「不支持」。直播插件替换编码器时要明确参数所有权与关键帧确认。

    延伸阅读

    参考资料

    • 项目 02 —— openpilot-research/VIDEO_ENCODING_DEEP_DIVE.md（取用了编码进程与相机表、实时调度与切段、三类编码后端、故障边界与验证范围）。
    • 项目 02 —— openpilot-research/CAMERA_IMU_DEEP_DIVE.md（仅用于确认采集端 VisionIPC 帧边界，未取用其未公开内容）。

    说明：本文为对固定源码快照的静态结构分析，未运行完整测试套件、未连接硬件、未验证目标车型的真实参数组合。文中所有阈值、行号索引与配置均出自源文档，标注为未验证的结论保留其原有边界。

    更新记录

    首次发布 2026-10-11 最近核对：2026-10-11

  • 端侧推理工具链快速上手：从张量到 safetensors 的七步

    结论：要做端侧推理，公开资料给出的最小闭环是七步：装依赖 → 建张量 → 组模型 → 写训练循环 → 评估 → 上 JIT → 存取权重。它的三条关键性质是：张量运算是惰性的，只有调用 .realize() 或 .numpy() 才真正执行；神经网络就是一组张量运算，模块不必须继承任何基类；JIT 用于加速固定输入形状的推理，但不支持变化输入尺寸与非本框架操作。权重标准格式为 safetensors。

    准备：导入与依赖

    快速上手指南假定读者不熟悉任何深度学习框架，但具备神经网络基础。起步只需要少量导入：数值库、计时辅助、张量类与数据类型。

    张量是这套工具链的基础数据结构，可以理解为某个数据类型的多维数组；所有高层操作都作用在张量上。张量既能从 Python 列表或数值库数组构造，也能用工厂方法生成：

    工厂方法 作用
    full / zeros / ones 按给定形状生成定值、全零或全一张量
    full_like / zeros_like / ones_like 按另一张量的形状生成对应值
    eye 单位矩阵
    arange 按起止与步长生成序列
    rand / randn / uniform 均匀分布、标准正态分布或指定区间的随机张量

    所有创建方法都可以带上 dtype 参数指定数据类型。运算则为惰性：例如 (t + 1) * 2 之后再接 relu() 与 log_softmax()，表达式不会立即求值，直到用 .realize() 或 .numpy() 触发。

    模型就是一组张量运算

    神经网络在这个框架里就是张量运算的组合。常见做法是把一组运算放进一个类的调用方法里，以便模块化复用；这些类不必继承任何基类，若无需可训练参数，甚至可以不是类。

    指南用一个全连接层示例说明：构造时按初始化方式生成权重张量，可选的偏置为全零；前向时对输入做线性变换。基于它，指南搭了一个两层网络——输入 784 维、隐藏层 128 维、输出 10 维（对应十个数字），两层都不带偏置，激活使用 Leaky ReLU。前向过程就是依次做线性变换与激活，再返回输出。

    训练与评估循环

    训练循环非常直接：定好网络、损失与优化器，对损失调用反向传播得到梯度，再用优化器更新参数。指南在这部分点出一个关键取舍：加载 / 存储类运算在框架里不原生支持，因为它增加了移植到不同后端的复杂度，而且大多数模型并不需要；示例里的交叉熵损失就用 arange 掩码实现，绕开了原生加载 / 存储。

    环节 指南中的取值与做法
    损失 稀疏分类交叉熵
    优化器 随机梯度下降，学习率 3e-4
    参数来源 显式传入，或用工具函数取全部参数
    数据 数据集加载器提供的示例数据集
    训练设置 训练 1000 步，批大小 64，用上下文开启训练模式
    每步动作 取批 → 前向 → 算损失 → 清零梯度 → 反向传播 → 更新参数 → 计算准确率

    评估沿用同样的批大小 64，跑 1000 个批次，并用计时辅助输出耗时。值得注意的是，指南把 Context(TRAINING=1) 用作训练模式开关，退出上下文时该标志会恢复为之前的值——这是用上下文管理状态，而不是全局变量。

    JIT 与模型存取

    指南的「额外能力」部分给出两个工程要点。

    其一，JIT 可以加速某些网络的运算：做法是给前向过程加装饰器，并确保输入输出都是已实现的张量。但指南明确其限制——当前不支持变化输入尺寸的模型，也不支持非本框架的操作。启用后评估耗时通常显著下降，加速器利用率更高。

    其二，权重存取的标准格式是 safetensors：这意味着其他同样使用该格式的模型权重也能直接加载进来。存取由状态字典相关函数完成——先取状态字典，保存到文件，再加载并写回网络。此外，预设模型目录里的许多模型提供了「从预训练加载」的方法，通常会下载权重；这类权重多为另一框架的格式，加载时需要安装对应框架。

    调试与可视化

    再有两点对排查很有用：一是环境变量控制运行时行为，常见的有 DEBUG 与各后端启用开关，完整清单在环境变量文档里；二是设置 VIZ=1 可以可视化神经网络的计算图，用于确认运算是否按预期组织。

    常见问题

    为什么定义了运算却没有立刻执行？

    因为张量运算是惰性的，表达式只有在调用 .realize() 或 .numpy() 时才真正执行。这是该工具链的基础性质，也是理解性能与调试输出的前提。

    可以用 JIT 加速所有模型吗？

    不能。当前 JIT 不支持变化输入尺寸的模型，也不支持非本框架的操作。启用时还需保证输入与输出都是已实现的张量。

    模型权重用什么格式保存？

    标准格式是 safetensors。先取状态字典，保存到文件；加载时读取状态字典再写回网络。使用同样格式的其他模型权重也能直接加载。

    如何确认网络的计算图结构？

    设置 VIZ=1 即可可视化计算图。日常排查运行时行为还可以借助 DEBUG 等环境变量，完整清单见环境变量文档。

    延伸阅读

    参考资料

    • 项目 02 —— openpilot-research/source/tinygrad_repo/docs/quickstart.md（取用张量工厂方法、惰性求值、两层网络示例、训练与评估循环、JIT 限制、safetensors 存取与调试开关）。

    说明：本文为对固定文档快照的整理，未在本机运行完整训练、未验证各后端可用性与性能数字，也未核对示例数据集与预训练权重的实际下载内容。文中所有 API、取值与限制均出自源文档，标注为未验证的结论保留其原有边界。

    更新记录

    首次发布 2026-10-11 最近核对：2026-10-11

  • msgq 传输边界：15 个读者槽位、覆盖与发布者冲突

    结论：msgq 共享内存队列的「单一发布者」是当前写入者冲突检测，不是权限认证或优先级仲裁——第二个 PubSocket.connect() 会先改写共享 write_uid 并重置读者槽位，旧发布者要到下次 send() 才收到 EADDRINUSE。读者槽位固定 15 个，超出时清空并逐出原有读者，会导致读者重置与帧丢失；环形缓冲回绕覆盖慢读者时，msgq_reset_reader() 把读指针放到当前写指针，已跳过的历史帧不可补取，合并读取也不报告被跳过的消息数。以下为对固定源码归档的静态追踪，不等同对目标系统的并发、权限或最坏时延测试。

    进程间链路

    cereal.messaging.pub_sock() 与 sub_sock() 按 services.py 选择队列大小，最终调用 msgq_new_queue()。它在 Linux /dev/shm/msgq_、macOS /tmp/msgq_ 下用主题名建 mmap 文件，可用 OPENPILOT_PREFIX 改前缀；msgq.h 的默认容量为 1 MiB，读者槽位固定 15 个。services.py 对 CAN、视频编码等使用更大容量。

    共享内存文件创建模式为 0664，实际访问还受目录权限、umask 和进程用户影响；源代码中的这个模式本身不等于插件级授权策略。发布者经 PubMaster.send → PubSocket.send → 共享内存环形队列，消费者经 SubSocket.receive → SubMaster.update_msgs 到达应用。

    函数级索引

    下表按组件列出运行语义与容易误解的边界。

    函数 / 组件 运行语义 容易误解的边界
    msgq_new_queue() 打开并映射主题文件，设置头部与环形数据区指针 主题名/前缀区分队列，不负责验证发布者身份或消息 schema
    msgq_init_publisher() 生成本地 UID 并写共享 write_uid，同时重置读者计数和槽位 新发布者连接时替换共享发布者标识；不是拒绝第二个发布者接入
    msgq_msg_send() 旧本地 UID 与共享 UID 不一致时返回 EADDRINUSE；否则写长度/载荷、推进写指针并唤醒读者 冲突在旧发布者下次发送时显露；容量要求至少容纳三条当前尺寸消息
    msgq_init_subscriber() 分配读者槽；超出 15 个槽位时清空并逐出原有读者，再让读者重新连接 读者槽位不是可无限增长的服务注册表，满槽会造成读者重置和帧丢失
    msgq_msg_recv() 读者被逐出/缓冲无效时重置到当前写指针；read_conflate 时跳过中间消息，只拷贝最新 重置不回放旧帧，合并也不报告被跳过的消息数量
    msgq_poll() 检查可读状态并休眠等待唤醒或超时 poll 就绪不保证随后一定能读到消息；读取端有重试路径
    msgq_all_readers_updated() 检查现存有效读者指针是否追上写指针，且至少有一名读者 它不是业务处理完成或落盘确认；失效槽位不参与「未读」判断
    SubMaster.update() poll 指定主题，其他主题非阻塞读取；每次调用推进本地 frame 没有跨主题原子快照，某主题当前循环可沿用旧值
    SubMaster.all_checks() 汇总 alive、平均频率与消息 valid 只查 sm.valid[主题] 不等于执行全部健康检查

    覆盖、逐出与健康位

    msgq_msg_send() 写入前检查消息尺寸与队列容量；回绕或写入覆盖慢读者位置时标记该读者无效。msgq_msg_ready() 和接收函数看到失效读者后调用 msgq_reset_reader()，将读指针放到当前写指针。这保证不会把覆盖的字节当新消息，但意味着已跳过的历史帧不可补取。

    消费者行为 语义 边界
    SubMaster 合并读取 对所有主题使用 conflate=True，即使队列未满也只保留最新一条 需完整帧序列的记录器或分析工具不能复制这种消费模式
    alive 计算 正频率主题按本地单调时钟和服务频率的十倍周期另行计算 零频/on-demand 服务初始被视为 alive/valid
    update_msgs() 仅收到新消息时更新 data、valid、接收时间和 logMonoTime 没收到时 updated=False，保留最后数据与最后 valid
    all_checks() 才联合检查健康 调用方若只用最后 valid，旧数据可能继续被选中

    PubSocket.connect() 调用 msgq_init_publisher() 改写共享 UID；PubSocket.send() 的 Python 包装把后续 EADDRINUSE 转成 MultiplePublishersError。因此「单一发布者」是当前写入者冲突检测，并非在第二个进程连接前核查授权、阻止冒名或保护旧发布者连续运行。

    健康位与读取推进是两套机制：msgq_poll() 检查可读状态并休眠等待唤醒或超时，但 poll 就绪不保证随后一定能读到消息，读取端有重试路径；msgq_all_readers_updated() 只检查现存有效读者指针是否追上写指针且至少有一名读者，它不是业务处理完成或落盘确认，失效槽位也不参与「未读」判断。

    因此消费侧不能只看最后 valid：某主题在当前循环可能沿用旧值，而 all_checks() 才联合检查 alive、平均频率与消息 valid。模拟模式还放宽了部分时序检查，不能以仿真健康位直接替代实板时序证据。

    插件化与验证边界

    以 msgq 承载插件候选仍可行，但必须在受信任进程/OS 层限制谁能创建权威主题发布者；候选各用自己的主题，固定仲裁器独占 carControl 等权威输出。消息接口应包含版本、来源、单调时间、明确 TTL、状态位与序号；仲裁器记录来源切换和超时降级。

    队列大小/覆盖预算、十五读者上限、最坏消息尺寸、发布者重启时的读者复位，都应在目标硬件上压力测试。wait_for_readers_to_update() 只证明读取指针条件，不证明候选被理解、执行或持久记录；安全关键命令和审计日志需要独立的确认/落盘机制，不能把实时队列当事务通道。现有 msgq_tests.cc 和 test_messaging.py 覆盖一般/合并读取、慢读者和回绕等单元行为；本轮未运行，发布者竞争、读者槽位耗尽、进程 crash/restart、权限隔离和负载极限仍需专门故障注入与板上测量。

    常见问题

    「单一发布者」是一种安全认证吗？

    不是。它是当前写入者冲突检测：第二个 PubSocket.connect() 会改写共享 UID 并重置读者槽位，旧发布者到下次 send() 才收到 EADDRINUSE；连接前不核查授权，也不保护旧发布者连续运行。

    SubMaster 会保留完整帧序列吗？

    不会。SubMaster 对所有主题使用 conflate=True，队列未满也只保留最新一条；需要完整序列的记录器或分析工具不能复制这种消费模式。

    alive 和 valid 是一回事吗？

    不是。update_msgs() 只在收到新消息时更新 valid，没收到时保留最后 valid；而 alive 按本地单调时钟与服务频率的十倍周期另行计算。调用方若只用最后 valid，旧数据可能继续被选中。

    队列满了会补取历史帧吗？

    不会。回绕覆盖或读者被逐出时，msgq_reset_reader() 把读指针放到当前写指针，已跳过的历史帧不可补取；合并读取也不报告被跳过的消息数量。

    延伸阅读

    参考资料

    • 项目 02 —— openpilot-research/MSGQ_TRANSPORT_BOUNDARIES_DEEP_DIVE.md（共享内存队列的发布者替换、覆盖、合并与读者复位边界）
    • 项目 02 —— openpilot-research/SYSTEM_FOUNDATION_DEEP_DIVE.md（系统底座与图像主数据的独立通道，作为本文的补充阅读）

    说明：本文为对固定源码快照的静态结构分析，未运行完整测试套件、未连接硬件、未验证目标车型的真实参数组合。文中所有阈值、行号索引与配置均出自源文档，标注为未验证的结论保留其原有边界。

    更新记录

    首次发布 2026-10-11 最近核对：2026-10-11