🥮 mooncakes.io

    moon-arena-plan

    Static multi-bank buffer planning and independent layout verification

    memory-planning
    tensor
    arena
    embedded
    Download zip
    Author
    Version
    0.1.0
    License
    MIT
    Repository
    Last updated
    1 hour ago
    Downloads
    4

    #MoonArenaPlan

    静态多内存区缓冲区规划库与 CLI。给定缓冲区的大小、存活区间、允许内存区和固定位置，生成可复用的偏移布局，并用独立检查器核验结果。核心实现为 MoonBit，MIT 许可证。

    适用于已知串行执行顺序的张量流水线、采集与处理缓冲区，以及内存预算的 CI 回归检查。使用者需提供准确的字节数、scratch、持久状态、保留输出和设备访问限制。

    #安装与构建

    使用 moonc 0.10.16 或更高；当前验证和 CI 固定 0.10.16+b1a0e846e 及匹配 core。Windows 已有 SDK 可在当前终端执行：

    . ./scripts/use-sdk.ps1 -SdkHome '你的 MoonBit SDK 绝对路径'
moon update
moon check --deny-warn
moon build --release --deny-warn
moon test --deny-warn

    库安装：moon add SongYZZZ/moon-arena-plan。在 moon.pkg 导入 "SongYZZZ/moon-arena-plan" @arena，调用 plan、verify、summarize、lifetimes、c_header。API 见 pkg.generated.mbti，输入契约见 SPEC.md。

    #可复现案例

    moon run cmd/arenaplan -- plan examples/reuse.json
moon run cmd/arenaplan -- plan examples/dma_banks.json
moon run cmd/arenaplan -- plan examples/budget_failure.json

    第三条预期退出 1，报告超预算；不是构建失败。三个 64 字节、生命周期不重叠的缓冲区在第一个例子复用到 64 字节，而逐个独立预留需要 192 字节。第二例把固定采集缓冲区保留在 dma 内存区，把同一时刻存活的特征区放入 fast。第三例在交接步同时保留输入和输出，128 字节需求超出 96 字节预算。

    这些是可执行的工程场景样本，尚无真实设备部署或用户采用记录。项目目标及成熟工具关系见 docs/NECESSITY.md。

    # layout 命令只输出布局，可把 stdout 保存为 layout.json
moon run cmd/arenaplan -- layout examples/reuse.json
moon run cmd/arenaplan -- verify examples/reuse.json layout.json
moon run cmd/arenaplan -- header examples/reuse.json layout.json
moon run cmd/arenaplan -- lifetimes examples/graph.json

    文件读取仅接受最多 4 MiB 的 UTF-8 常规文件；CLI 只写 stdout/stderr，不覆盖输入。退出码 0 表示输入约束满足，1 表示布局/预算问题，2 表示输入、用法或导出失败。

    #验证

    python scripts/verify.py --exe _build/native/release/build/cmd/arenaplan/arenaplan.exe
moon run examples/c_replay
moon test --target js -p SongYZZZ/moon-arena-plan --deny-warn
moon test --target wasm-gc -p SongYZZZ/moon-arena-plan --deny-warn

    Python 黑盒检查器用另一种实现核对随机问题、峰值和输入重排；C 示例使用 CLI 实际生成的头文件读写数组，检查交接步的数据保持。它们验证静态布局合同，不构成神经网络推理或硬件验证。

    #边界

    schema 1 的完整字段及拒绝行为是本版本兼容终点。字节数、容量、对齐和偏移使用十进制字符串，时间步和 schema 使用 JSON 整数；禁止未知字段、重复 JSON 键和小数/指数形式的数值。空固定字段可省略或使用 null。

    规划采用固定位置优先、约束较少的可选 bank 集合优先、大小降序的贪心规则；ID 按 ASCII 排序，bank 列表顺序用于平局选择。结果不保证全局最优；超预算不证明其他布局都不可行。允许 bank 集合来自调用者，不从芯片型号自动推导。硬件地址、缓存一致性、异步 DMA 实际完成时间、栈和运行时开销需另行验证。

    当前不读取 ONNX/TFLite 文件，不执行张量算子，不把外部框架的分配器作为产品实现。标准内存规划技术的公开参考与许可证见 docs/REFERENCES.md。

    PlanError

    source
    pub suberror PlanError {
      PlanError(String, String)
    } derive(
    Debug    )

    Bank

    source
    pub(all) struct Bank {
      id : String
      capacity : Int64
    } derive(Eq, ToJson, 
    Debug    , 
    FromJson    )

    Bank::equal

    source
    fn Bank::equal(Bank, Bank) -> Bool

    Bank::from_json

    source

    Bank::not_equal

    source
    fn Bank::not_equal(x : Bank, y : Bank) -> Bool

    Bank::to_json

    source
    fn Bank::to_json(Bank) -> Json

    Bank::to_repr

    source

    BankUsage

    source
    pub(all) struct BankUsage {
      bank : String
      capacity : Int64
      highwater : Int64
      peak_live_bytes : Int64
      peak_step : Int
      fits : Bool
    } derive(Eq, ToJson, 
    Debug    )

    BankUsage::equal

    source
    fn BankUsage::equal(BankUsage, BankUsage) -> Bool

    BankUsage::not_equal

    source
    fn BankUsage::not_equal(x : BankUsage, y : BankUsage) -> Bool

    BankUsage::to_json

    source
    fn BankUsage::to_json(BankUsage) -> Json

    BankUsage::to_repr

    source

    Buffer

    source
    pub(all) struct Buffer {
      id : String
      bytes : Int64
      first : Int
      last : Int
      alignment : Int64
      banks : Array[String]
      fixed_bank : String?
      fixed_offset : Int64?
    } derive(Eq, ToJson, 
    Debug    , 
    FromJson    )

    Inclusive lifetimes. Access restrictions and byte sizes must be supplied.

    Buffer::equal

    source
    fn Buffer::equal(Buffer, Buffer) -> Bool

    Buffer::from_json

    source

    Buffer::not_equal

    source
    fn Buffer::not_equal(x : Buffer, y : Buffer) -> Bool

    Buffer::to_json

    source
    fn Buffer::to_json(Buffer) -> Json

    Buffer::to_repr

    source

    Finding

    source
    pub(all) struct Finding {
      code : String
      buffer : String
      other : String
      message : String
    } derive(Eq, ToJson, 
    Debug    )

    Finding::equal

    source
    fn Finding::equal(Finding, Finding) -> Bool

    Finding::not_equal

    source
    fn Finding::not_equal(x : Finding, y : Finding) -> Bool

    Finding::to_json

    source
    fn Finding::to_json(Finding) -> Json

    Finding::to_repr

    source

    Graph

    source
    pub(all) struct Graph {
      schema : Int
      banks : Array[Bank]
      tensors : Array[Tensor]
      steps : Array[Step]
    } derive(Eq, ToJson, 
    Debug    , 
    FromJson    )

    Graph::equal

    source
    fn Graph::equal(Graph, Graph) -> Bool

    Graph::from_json

    source

    Graph::not_equal

    source
    fn Graph::not_equal(x : Graph, y : Graph) -> Bool

    Graph::to_json

    source
    fn Graph::to_json(Graph) -> Json

    Graph::to_repr

    source

    Layout

    source
    pub(all) struct Layout {
      schema : Int
      placements : Array[Placement]
    } derive(Eq, ToJson, 
    Debug    , 
    FromJson    )

    Layout::equal

    source
    fn Layout::equal(Layout, Layout) -> Bool

    Layout::from_json

    source

    Layout::not_equal

    source
    fn Layout::not_equal(x : Layout, y : Layout) -> Bool

    Layout::to_json

    source
    fn Layout::to_json(Layout) -> Json

    Layout::to_repr

    source

    Placement

    source
    pub(all) struct Placement {
      id : String
      bank : String
      offset : Int64
    } derive(Eq, ToJson, 
    Debug    , 
    FromJson    )

    Placement::equal

    source
    fn Placement::equal(Placement, Placement) -> Bool

    Placement::from_json

    source

    Placement::not_equal

    source
    fn Placement::not_equal(x : Placement, y : Placement) -> Bool

    Placement::to_json

    source
    fn Placement::to_json(Placement) -> Json

    Placement::to_repr

    source

    Problem

    source
    pub(all) struct Problem {
      schema : Int
      banks : Array[Bank]
      buffers : Array[Buffer]
    } derive(Eq, ToJson, 
    Debug    , 
    FromJson    )

    Problem::equal

    source
    fn Problem::equal(Problem, Problem) -> Bool

    Problem::from_json

    source

    Problem::not_equal

    source
    fn Problem::not_equal(x : Problem, y : Problem) -> Bool

    Problem::to_json

    source
    fn Problem::to_json(Problem) -> Json

    Problem::to_repr

    source

    Step

    source
    pub(all) struct Step {
      id : String
      inputs : Array[String]
      outputs : Array[String]
      scratch : Array[String]
    } derive(Eq, ToJson, 
    Debug    , 
    FromJson    )

    Step::equal

    source
    fn Step::equal(Step, Step) -> Bool

    Step::from_json

    source

    Step::not_equal

    source
    fn Step::not_equal(x : Step, y : Step) -> Bool

    Step::to_json

    source
    fn Step::to_json(Step) -> Json

    Step::to_repr

    source

    Tensor

    source
    pub(all) struct Tensor {
      id : String
      bytes : Int64
      alignment : Int64
      banks : Array[String]
      fixed_bank : String?
      fixed_offset : Int64?
      source : Bool
      retain : Bool
    } derive(Eq, ToJson, 
    Debug    , 
    FromJson    )

    Tensor::equal

    source
    fn Tensor::equal(Tensor, Tensor) -> Bool

    Tensor::from_json

    source

    Tensor::not_equal

    source
    fn Tensor::not_equal(x : Tensor, y : Tensor) -> Bool

    Tensor::to_json

    source
    fn Tensor::to_json(Tensor) -> Json

    Tensor::to_repr

    source

    c_header

    source
    fn c_header(problem : Problem, layout : Layout) -> String raise PlanError

    C11 offset macros only. The caller owns correctly aligned bank storage.

    decode_graph

    source
    fn decode_graph(text : String) -> Graph raise PlanError

    decode_layout

    source
    fn decode_layout(text : String) -> Layout raise PlanError

    decode_problem

    source
    fn decode_problem(text : String) -> Problem raise PlanError

    lifetimes

    source
    fn lifetimes(graph : Graph) -> Problem raise PlanError

    Translate an explicit serial schedule; no shape or operator semantics inferred.

    plan

    source
    fn plan(problem : Problem) -> Layout raise PlanError

    Deterministic greedy planning. An over-budget result is not an infeasibility proof.

    summarize

    source
    fn summarize(problem : Problem, layout : Layout) -> Array[BankUsage] raise PlanError

    Summary is defined for structurally valid layouts, including over-budget plans.

    validate

    source
    fn validate(problem : Problem) -> Unit raise PlanError

    verify

    source
    fn verify(problem : Problem, layout : Layout) -> Array[Finding] raise PlanError

    Does not invoke the planner or trust a layout's size/lifetime metadata.

    Source Files

    Powered by MoonBit

    Site sourceReport issueModulesSkillsBuild queueStatistics

    © 2026 mooncakes.io