Bitloom

Rust 嵌入式 RTL HDL：设计是可执行生成器。cargo bitloom build 在本机 elaborate 得到冻结电路图（FrozenHir），再降到 Yosys 友好的 Verilog，并可在 cargo test 里做周期精确 tick。

身份与发布（请先读）

本仓库与 samitbasu/rhdl 无关。 那是另一个独立项目。

	本项目
Git 仓库名	可以叫 `rhdl`
公开产品名	Bitloom
crates.io 发布名	`bitloom`（CLI 二进制 `cargo-bitloom` → `cargo bitloom`）
禁止发布	`rhdl`、`rhdl-bits`（名称已被占用或保留）

文档、徽章与发布说明不得暗示本工具链以 crates.io 包名 rhdl 发布。

快速开始（真独立；不必 clone）

rustup toolchain install 1.97.1
cargo install bitloom
cargo bitloom new blink
cargo bitloom build --package blink --manifest-dir blink --out-dir out

设计 crate 只依赖 bitloom-prelude（不要把 CLI 包 bitloom 加进 [dependencies]）。与 bitbloom 等无关拼写无关；与 samitbasu/rhdl 无关。

工具链： rust-toolchain.toml 钉死 rustc 1.97.1 / edition 2024
测试（贡献者）： just test（或 cargo test --workspace）

贡献者：在 monorepo 里跑示例

git clone https://github.com/TangCan/bitloom.git
cd bitloom
cargo run -p bitloom -- build --package counter_ports --out-dir /tmp/bitloom-out --manifest-dir .

多包发布与 Trusted Publishing：见 docs/crates-io-publish-bitloom.md。

可选：独立仿真（`bitloom-sim`）

设计 crate 的 [dependencies] 仍只有 bitloom-prelude。需要 tick / VCD 时：

cargo add bitloom-sim --dev

在 cargo test 里 use bitloom_sim::Sim; 对 FrozenHir 做周期步进。勿把 sim 放进 [dependencies]。

文档在哪

文档	路径
阶段一产品合同	`_agile-output/specs/spec-rhdl/SPEC.md`
阶段二需求（FR21–FR40）	`_agile-output/planning-artifacts/prds/prd-rhdl-2026-08-19/prd.md`
架构脊柱（AD-1…AD-26）	`_agile-output/planning-artifacts/architecture/architecture-rhdl-2026-08-18/ARCHITECTURE-SPINE.md`
Epic / Story	`_agile-output/planning-artifacts/epics.md`
Sprint 状态	`_agile-output/implementation-artifacts/sprint-status.yaml`
HIR→源码再生（仅调试）	`docs/hir-to-source-debug-only.md`
手写 bridge / abstraction / both	`docs/fr29-bridge-abstraction-both.md`
双视图等价检查	`docs/fr30-dual-view-equiv.md`
可选 FST	`docs/fr31-optional-fst.md`
tick 引擎	`docs/fr32-tick-engines.md`
C ABI cdylib	`docs/fr33-c-abi.md`
仿真覆盖率	`docs/fr34-sim-coverage.md`
Chisel 尽力生成	`docs/fr28-chisel-best-effort.md`
HLS（Bambu）	`docs/fr35-hls.md`
Formal/SVA	`docs/fr39-formal-sva.md`
Analog/InOut	`docs/fr27-analog-inout.md`
rhdl-float	`docs/fr36-rhdl-float.md`
IP / 黑盒	`docs/fr37-ip-box.md`
HIR HTML / LSP	`docs/fr38-viz-lsp.md`
额外 CLI	`docs/fr40-cli-verbs.md`
多平台 firtool	`docs/nfr11-firtool-platforms.md`
MSRV 1.97.1 (NFR13)	`docs/nfr13-msrv-1.97.1.md`

firtool（NFR3）

默认不信任 PATH 上的 firtool。CLI 钉死 firtool-1.155.0（firrtl-bin-linux-x64.tar.gz + .sha256）：

cargo run -p bitloom -- firtool info
cargo run -p bitloom -- firtool ensure   # 下载/校验/缓存并打印二进制路径

覆盖：RHDL_FIRTOOL_PATH 指向含 firtool 的目录；缓存根可用 RHDL_FIRTOOL_CACHE。

工具链 crate：MIT OR Apache-2.0（见各 crate 的 Cargo.toml）。

状态与 deferred（诚实声明）

当前为 0.x。已交付：生成器 elaborate → FrozenHir → .v / FIRRTL 互转 / tick、firtool 钉死、Mem/CDC 等阶段二能力（见 epics.md）。

明确 deferred / 未承诺为产品完整面：

完整 LSP hover/goto（FR38 部分）
部分 CLI 动词（check / import / visualize / wave / doc / build-sim）
自研 HLS 调度器（永不；仅外挂）
crates.io 名 rhdl / rhdl-bits（禁止）

详见 docs/semver-0x-policy.md 与 docs/crates-io-publish-bitloom.md。

bitloom-sim 0.1.2