pikastech
12 KiB
12 KiB
PJ2026-05 PikaPython 总规格
修改历史
| 版本 | 对应 commit id | 更新日期 | 变更说明 |
|---|---|---|---|
| v0.1 | 205e3a70 |
2026-07-21 | 创建 PikaPython 双路线战略、系统边界和全局验收规格。 |
| v0.2 | d72a1f52 |
2026-07-21 | 已批准：明确 V2 重写优先、阶段性 parser 适配器、原子 capability、职责化实现命名和冷/热 benchmark 生命周期。 |
修改历史只记录规格语义变更，不记录实现进度、阶段基线或一次性证据。
v0.2 及其引用的 PIKA-CAP v0.1 已批准生效，作为当前实现合同。
正文
PJ2026-05 PikaPython 总项目需求规格
1. 文档控制
| 字段 | 内容 |
|---|---|
| 编号 | PJ2026-05 |
| 短名 | PikaPython |
| 层级 | L0 总项目 |
| 规格状态 | 已生效 |
| 当前生效版本 | v0.2 |
| 实现引用版本 | v0.2 |
| 需求规格模板 | ISO/IEC/IEEE 29148 需求规格模板 |
本文采用 ISO/IEC/IEEE 29148 需求规格模板的项目裁剪版。
本文的正文边界如下：
- 只定义预期终态、稳定使命、路线边界、原子需求和验收契约；
- 当前实现状态和阶段差距进入 TaskTree 或阶段报告；
- 提交、PR、benchmark 作业和日志进入执行 issue，不进入本规格正文。
2. 目的和范围
2.1 项目使命
PikaPython 面向资源受限微控制器提供可裁剪的 Python 运行能力：
- 应用在受控 Flash 和 RAM 预算内运行；
- 应用可以选择足够的 Python 语法、模块和本地扩展能力；
- 运行时性能和确定性与功能范围共同参与设计裁决。
项目采用两条互相隔离、可独立验收的技术路线：
- V2 内核路线：
- 重写 V1 路线的动态 Python 子集内核；
- 从第一版开始以运行时性能、Flash 和 RAM 为核心设计输入；
- 允许语法兼容性弱于 MicroPython；
- 延续并强化 V1 的编译期和构建期裁剪能力；
- 允许以主机侧、阶段性的 V1 parser 适配器引导前端，但长期合同必须是 V2 中性类型化 IR；
- 使用原子 capability、显式依赖图和命名 profile 组织能力，不把语法能力建模为单一直线等级；
- 每个 profile 独立满足语义、性能和资源合同，较大能力闭包不得掩盖最小配置退化。
- 静态加速路线：
- 面向显式静态约束或编译加速场景独立演进；
- 不作为 V2 的依赖、兼容层、发布判定前提或架构前提；
- strict type、LLVM 或其他静态编译技术只能在该路线的独立规格中决策。
2.2 预期终态
PikaPython 应形成一个可持续演进的嵌入式 Python 产品族：
- V1 保持已有用户、语法、模块和板级生态的稳定交付；
- V2 以重新设计的内核显著超越 V1，并在能力等价的代表性运行时负载上相对 MicroPython 形成可解释的 Pareto 优势；
- 静态加速路线面向适合编译期约束的代码提供独立加速能力；
- 两条新路线共享 capability 语义、可比较配置、benchmark 方法和板级接口原则，但不共享必须同步演进的内核架构；
- 所有路线都能对不支持的语法、资源耗尽和运行时错误给出清晰、确定且可测试的结果。
2.3 范围内
- Python 子集的解析、编译、字节码或其他执行表示。
- VM、对象模型、调用约定、内存管理、异常和模块系统。
- C 模块绑定、平台移植和微控制器资源裁剪。
- capability 依赖、命名 profile 和跨实现能力等价比较。
- Linux 功能、性能与资源基线，以及目标架构功能和资源验证。
- V1、V2、MicroPython 和适用静态实现的版本化比较。
2.4 范围外
- 以完整 CPython 兼容性作为嵌入式内核的首要目标。
- 为追求语法数量而牺牲资源边界、错误可见性或可裁剪性。
- 用 QEMU 性能数据替代 Linux 性能裁决。
- 把静态类型、LLVM、JIT 或目标相关 native emitter 设为 V2 必需能力。
- 要求 V2 复用 V1 的内部对象布局、字节码、调用栈或源码架构。
- 把 V1 parser 或 MicroPython fork 设为 V2 目标运行时的长期依赖。
3. 术语表
| 术语 | 定义 |
|---|---|
| V1 | 已交付的 PikaPython 内核和兼容生态。 |
| V2 | 重新设计和实现的动态 Python 子集内核，不表示 V1 内部架构的第二版补丁。 |
| 静态加速 | 依赖显式静态约束或编译期类型事实的独立执行路线。 |
| 可裁剪性 | 在构建期按语法、opcode、对象类型、模块和平台能力移除不需要代码与数据的能力。 |
| 可比较配置 | 为各实现选择相同 workload 所需语义和模块后的最小可运行配置。 |
| capability | 可独立标识、声明依赖、测试语义和报告资源成本的语言或 runtime 能力。 |
| profile | 有稳定名称和产品意图的 capability 根集合，不表示线性兼容等级。 |
| 能力等价配置 | 所需 capability 闭包和被测语义一致，并只启用 workload 必需平台模块的配置。 |
| 代表性 suite | 覆盖产品 profile 真实使用路径的版本化 benchmark 集合；不等同于单一内核上限测试。 |
4. 系统边界和接口
| 边界项 | 内容 |
|---|---|
| 外部使用者 | 嵌入式应用开发者、模块开发者、移植维护者和自动化构建系统。 |
| 外部输入 | Python 源码或预编译产物、C 模块、构建裁剪配置、平台端口和资源预算。 |
| 受控资源 | 解析器、编译器、执行内核、对象与堆、模块注册表、平台抽象和生成产物。 |
| 外部输出 | 可执行固件或库、字节码、运行结果、异常、资源报告和 benchmark 报告。 |
| 用户接口 | Python 子集、C API、模块绑定、构建配置和 workspace CLI。 |
| 系统边界 | PikaPython 负责语言子集和运行时语义，不替代板级操作系统、驱动、工具链或应用资源规划。 |
5. 路线分工与规格索引
| 编号 | 路线 | 规格文档 | 主责边界 | 上游依赖 | 下游支撑 |
|---|---|---|---|---|---|
| PJ2026-0501 | V2内核 | PJ2026-0501 V2内核 | 动态 Python 子集、紧凑 VM、对象模型、资源裁剪和 V1 演进替代能力。 | V1 用户语义、嵌入式平台约束、先进 VM 技术。 | 新应用、V1 迁移、模块与板级生态。 |
| PJ2026-0502 | 静态加速 | PJ2026-0502 静态加速 | 显式静态约束下的独立编译和执行加速。 | 静态语义契约、编译工具链。 | 计算密集且可静态化的函数或模块。 |
5.1 共享规格
| 规格编号 | 短名 | 规格文档 | 适用范围 |
|---|---|---|---|
| PIKA-CAP | 能力配置档 | PikaPython 能力与配置档 | V1、V2、静态加速及后续内核。 |
5.2 目标路线关系
flowchart LR
APP[嵌入式 Python 应用] --> V1[V1 稳定交付]
APP --> V2[V2 动态子集内核]
APP -. 显式选择 .-> S[静态加速路线]
V1 -->|行为经验与迁移需求| V2
V2 -. 不依赖 .-> S
S -. 不约束 .-> V2
V2 --> MCU[微控制器运行面]
S --> MCU
6. 全局原子需求
6.1 PIKA-L0-REQ-001 双路线隔离
| 编号 | 短名 | 主责模块 | 关联模块 |
|---|---|---|---|
| PIKA-L0-REQ-001 | 路线隔离 | PJ2026-0501 V2内核 | PJ2026-0502 静态加速 |
V2 和静态加速必须保持以下隔离：
- 分别声明语言前提、内核架构、性能结论和发布适用范围；
- 任一路线的实验失败不得阻塞另一条路线；
- 任一路线的工具链限制或语法要求不得进入另一条路线。
6.2 PIKA-L0-REQ-002 嵌入式优先
| 编号 | 短名 | 主责模块 | 关联模块 |
|---|---|---|---|
| PIKA-L0-REQ-002 | 嵌入式优先 | PJ2026-0501 V2内核 | PJ2026-0502 静态加速 |
嵌入式优先要求如下：
- 语言能力、数据布局、调度机制和模块边界必须考虑 Flash、RAM 和栈限制；
- 确定性限制必须参与内核结构裁决；
- 新增语法或模块不得默认进入最小配置。
6.3 PIKA-L0-REQ-003 可重复比较
| 编号 | 短名 | 主责模块 | 关联模块 |
|---|---|---|---|
| PIKA-L0-REQ-003 | 版本比较 | PJ2026-0501 V2内核 | PJ2026-0502 静态加速 |
性能主张必须满足以下条件：
- 使用版本固定、配置可见、一次性容器运行的 Linux benchmark；
- Linux 原生执行是快速主裁决环境；涉及 MCU 发布主张时，必须在对应真实 Cortex-M 或 RV32 目标上复核；
- QEMU 只用于功能、Flash 和静态 RAM 验证，不参与性能结论；
- benchmark 必须区分内核上限、动态能力等价、产品代表性和静态加速对照四类 suite；
- benchmark 必须区分 cold-start 与 warm execution：
- cold-start 分别报告 runtime 或 root 创建、解析或编译、首次执行和销毁；
- warm execution 的计时区间只包含已加载或已编译程序的重复执行；
- 无法分离生命周期阶段的结果必须标记为不可与 warm execution 直接比较；
- 同时披露运行时、Flash、静态 RAM、峰值堆、VM 栈、宿主栈和动态分配；
- 同时披露功能配置、样本数、原始样本、离散度和统计方法；
- allocation、峰值堆和栈数据必须来自 instrumentation；无法测量时报告 unavailable 和原因，不得以手工零值代替；
- Viper 或其他静态实现只属于静态加速对照，不得作为 V2 动态路线的产品基线。
6.4 PIKA-L0-REQ-004 错误确定性
| 编号 | 短名 | 主责模块 | 关联模块 |
|---|---|---|---|
| PIKA-L0-REQ-004 | 错误确定性 | PJ2026-0501 V2内核 | PJ2026-0502 静态加速 |
错误确定性要求如下：
- 不支持的语法、非法字节码、类型错误和资源耗尽必须产生明确且可测试的诊断；
- 栈耗尽属于微控制器致命故障时，系统必须先报告清晰原因；
- 报告后进入确定停机状态，不得静默继续、无限解析或未报告崩溃。
6.5 PIKA-L0-REQ-005 能力可比性
| 编号 | 短名 | 主责模块 | 关联模块 |
|---|---|---|---|
| PIKA-L0-REQ-005 | 能力可比性 | PIKA-CAP 能力配置档 | PJ2026-0501、PJ2026-0502 |
路线和实现之间的比较必须以 capability 闭包为基础：
- 每个产物声明所需 capability，runtime 声明提供 capability；
- 比较双方必须使用相同的能力闭包、workload 语义和必要平台模块；
- profile 名称不能替代能力清单，也不能暗示未声明的兼容性；
- 能力差异、模块差异和资源预算差异必须在报告中分别披露。
7. 全局验收合同
- 路线验收：
- V2 不依赖 strict type、LLVM、JIT 或静态加速路线产物即可独立构建、测试和发布；
- 静态加速路线不得改变 V2 的默认语言语义或资源基线。
- 性能验收：
- Linux 原生是快速主裁决，真实 Cortex-M 或 RV32 目标用于对应发布主张的确认；
- 单一 fib、启动时间或 parser 时间只能作为内核上限证据，不能替代动态等价和产品代表性 suite；
- MicroPython 的
+5%吞吐只作为延伸目标； - MicroPython 对照采用能力等价条件下的 Pareto 分析；
- 性能、Flash、峰值 RAM 至少一项明确领先，其余项不得越过本 profile 的资源预算；
- 每项结果必须绑定实现版本、提交、编译器、优化级别和可比较配置。
- 资源验收：
- Flash、静态 RAM、峰值动态 RAM、VM 栈、宿主栈和单次 workload 动态分配必须分别披露；
- 资源补偿可以发生在同一发布范围的其他模块，但总配置不得通过隐藏功能差异制造优势。
8. 过程控制
- V2 内核实现引用
PJ2026-0501 V2内核 v0.2。 - V2 的 capability 和 profile 实现引用
PIKA-CAP v0.1。 - 静态加速实现引用
PJ2026-0502 静态加速 v0.1。 - 稳定需求变化先修改 SPEC，再进入代码或执行 issue。
- 当前状态、阶段 benchmark、PR 和阻塞统一进入 TaskTree、阶段报告或 GitHub issue。
- 新增或修改的手写内核源码应在文件头标注：
- 适用 SPEC 编号；
- 短名；
- 实现引用版本。
- 生成文件、vendored 文件和二进制产物由生成入口追溯 SPEC。