diff --git a/docs/v0.4-plan.md b/docs/v0.4-plan.md new file mode 100644 index 0000000..f422e2b --- /dev/null +++ b/docs/v0.4-plan.md @@ -0,0 +1,126 @@ +# Bakelite 0.4 — Remaining Work + +Items to implement after the modernization PR chain (PRs #1–7) lands. +Reference: original PR #10 (`feature/modernization-and-async`). + +## 1. Simplified type system (breaking change) + +The biggest change in 0.4. All `bytes[N]`, `string[N]`, and `T[N]` become +variable-length with max capacity N. No more fixed-length semantics. + +### Wire format + +- `bytes[N]` — 1-byte length prefix + up to N bytes +- `string[N]` — null-terminated, up to N chars (no padding) +- `T[N]` — 1-byte length prefix + up to N elements + +### Grammar changes + +The Lark grammar (`protodef.lark`) needs updating: + +- `bytes[N]` and `string[N]` require a size — no more bare `bytes[]`/`string[]` +- `T[N]` always requires a size +- The `prim_variable` rule becomes `prim_sized` with higher priority + +### Code generator changes + +**Python** — Arrays and bytes use length-prefix encode/decode in the generated +`pack()`/`unpack()` methods. Strings use null-termination helpers. + +**cpptiny** — New `SizedArray` template with vector-like API (`size()`, +`push_back()`, iterators). Strings map to `char[N+1]`. The serializer +(`serializer.h`) gains variable-length read/write helpers. + +**ctiny** — `bytes[N]` and `T[N]` use inline anonymous structs: +`{ T data[N]; uint8_t len; }`. Strings map to `char[N+1]`. + +### Other effects + +- Remove heap parameter from ctiny/cpptiny decode functions +- Structs become self-contained with inline storage +- Parser type representation (`types.py`) needs adjustment — the `size` field + on `ProtoType` becomes the max capacity +- All tests and examples need updating for new wire format + +### New module: `sizes.py` + `bakelite info` command + +A size calculator (`bakelite/generator/sizes.py`) that computes min/max wire +sizes for every struct and protocol-level RAM estimates for embedded targets. + +Key types: +- `SizeInfo(min_size, max_size, kind)` — where kind is `FIXED` or `BOUNDED` +- `StructSizeInfo(name, size)` +- `ProtocolSizeInfo` — protocol-level aggregation including CRC overhead, + COBS framing overhead, and estimated RAM for ctiny/cpptiny + +The `bakelite info -i ` command renders this as a rich table (via `rich`) +or JSON (`--json`). Add `rich` as a dependency. + +## 2. Documentation rewrites + +### Protocol specification (`docs/protocol.md`) + +Full rewrite of the protocol spec: +- Replace HTML tables with Unicode box-drawing diagrams +- Remove unimplemented "Not for V1" sections +- Add quick reference table for all types +- Add formal grammar reference +- Reorganize into: Overview → Types → Structs → Enums → Protocol blocks + +### Python docs (`docs/python.md`) + +- Add async examples using `messages()` iterator +- Document `async_=True` parameter +- Update version requirement to Python 3.13+ +- Add runtime generation steps to quickstart + +### CLAUDE.md + +- Add project purpose, target platforms, architecture overview +- Document project structure including templates, runtimes, examples +- Add 80% code coverage requirement + +## 3. Benchmarking suite + +Cross-architecture benchmarking under `bench/`: + +### Structure + +``` +bench/ + harness/ — C/C++ benchmark programs (one per protocol × language) + protocols/ — .bakelite protocol definitions (simple, framing, serialize, typical) + scripts/ + run_benchmarks.py — orchestrate builds and measurements + download_toolchains.py — auto-download cross-compilers + analyze.py — parse results +``` + +### Targets + +- ARM Cortex-M0 (thumb), Cortex-M3 (thumb2) +- AVR ATmega328P +- RISC-V RV32IMC +- x86-64 + +### Metrics + +- Code size (text, data, bss) +- RAM usage +- Instruction count +- Stack usage (via `-fstack-usage`) +- Generates disassembly for manual analysis + +### Toolchains + +Auto-downloaded to `bench/toolchains/`: +- xPack ARM GCC +- xPack RISC-V GCC +- ZakKemble AVR GCC + +## 4. Copyright / housekeeping + +Already handled in PR #7. If anything was missed: +- License year → 2025 +- Email → emma@emmaponders.com +- Applies to: LICENSE.md, pyproject.toml, template headers, bin/update