feat: add Hadamard machine ball for element-wise multiplication

.claude/.gitignore

@@ -0,0 +1,4 @@
+*
+!skills/
+!skills/**/*
+!CLAUDE.md

.claude/CLAUDE.md

@@ -0,0 +1,110 @@
+# Buckyball
+
+A RISC-V based DSA (Domain Specific Architecture) framework. Built with Chisel 6.5.0 and Nix Flake.
+
+## Project Structure
+
+- `arch/src/main/scala/framework/` — framework core
+  - `balldomain/prototype/` — Ball operator implementations (one subdirectory per Ball)
+  - `balldomain/blink/` — Blink protocol definitions (`BlinkIO`, `BankRead/Write`, `BallStatus`)
+  - `balldomain/configs/` — `BallDomainParam` + `default.json` (`ballIdMappings`)
+  - `balldomain/bbus/` — BBus interconnect
+  - `balldomain/rs/` — `BallRsIssue` / `BallRsComplete` (issue/complete interfaces)
+  - `memdomain/backend/banks/` — `SramReadIO` / `SramWriteIO`
+  - `core/bbtile/` — BBTile integration (Rocket core + Buckyball)
+  - `top/` — `GlobalConfig` (top-level parameter aggregation)
+- `arch/src/main/scala/examples/toy/balldomain/` — toy config
+  - `DISA.scala` — instruction opcodes (`funct7` BitPat)
+  - `DomainDecoder.scala` — instruction decode table (`ListLookup`)
+  - `bbus/busRegister.scala` — Ball generator registration (`match case`)
+- `arch/src/main/scala/sims/` — simulation configs
+  - `verilator/` — Verilator config
+- `bb-tests/` — tests
+  - `workloads/lib/bbhw/isa/` — ISA C macros (one `.c` file per instruction)
+  - `workloads/src/CTest/toy/` — C test cases
+  - `sardine/` — pytest test framework
+- `bbdev/` — developer toolchain (Motia workflow backend)
+
+## Blink Protocol
+
+Balls connect to BBus through the Blink protocol. Every Ball implements the `HasBlink` trait.
+
+```
+BlinkIO(b: GlobalConfig, inBW: Int, outBW: Int):
+  cmdReq:    Flipped(Decoupled(BallRsIssue))     // command input (includes BallDecodeCmd + rob_id)
+  cmdResp:   Decoupled(BallRsComplete)           // completion output (includes rob_id)
+  bankRead:  Vec(inBW, Flipped(BankRead))        // SRAM read ports
+  bankWrite: Vec(outBW, Flipped(BankWrite))      // SRAM write ports
+  status:    BallStatus { idle, running }        // status signals
+
+BankRead/BankWrite metadata fields (all Input):
+  bank_id, rob_id, ball_id, group_id
+
+SramReadIO:  req.valid/ready + req.bits.addr  ->  resp.valid + resp.bits.data
+SramWriteIO: req.valid/ready + req.bits(addr, data, mask, wmode)  ->  resp.valid + resp.bits.ok
+```
+
+Key timing rule: SRAM read latency is 1 cycle (`resp.valid` is asserted in the next cycle after `req.fire`).
+
+## Registration Invariants
+
+When adding or modifying Ball registrations, all six conditions below must hold:
+
+1. `ballNum` in `default.json` equals the length of `ballIdMappings`
+2. `ballId` is strictly increasing (`0, 1, 2, ...`) with no gaps
+3. No duplicated `ballId`
+4. No duplicated `funct7` values in `DISA.scala`
+5. Case names in `busRegister.scala` equal `ballName` set in `default.json`
+6. BID values in `DomainDecoder.scala` equal `ballId` set in `default.json`
+
+Use the `/check` skill to validate all invariants and optionally auto-fix issues.
+
+## MCP Tools
+
+The project configures the `buckyball-dev` MCP server with the following tools.
+
+**Important: build, simulation, synthesis, and tests must be invoked via MCP tools. Do not call `bbdev` CLI or `nix develop` directly.**
+`bbdev` CLI is for human developers, while MCP tools are for agents. MCP tools manage bbdev server lifecycle and call it through HTTP APIs.
+
+### Validation
+- `validate` — check all 6 registration invariants
+
+### bbdev API wrappers (with automatic server lifecycle management)
+- `bbdev_workload_build` — build CTests
+- `bbdev_verilator_run(binary, config?, batch?, coverage?)` — full flow: clean -> verilog -> build -> sim
+- `bbdev_verilator_verilog(config)` — generate Verilog; `config` is required
+- `bbdev_verilator_build(jobs?, coverage?)` — build Verilator simulator
+- `bbdev_verilator_sim(binary, batch?, coverage?)` — run simulation (requires prior build)
+- `bbdev_sardine_run(workload?, coverage?)` — run batch tests
+- `bbdev_yosys_synth(top?, config?)` — Yosys synthesis + OpenSTA timing analysis
+
+Default config value: `sims.verilator.BuckyballToyVerilatorConfig`
+Simulation binary naming format: `ctest_<name>_test_singlecore-baremetal`
+
+### Analysis report paths
+- Area reports: `bbdev/api/steps/yosys/log/hierarchy_report.txt` (submodule breakdown), `area_report.txt` (top-level)
+- Timing report: `bbdev/api/steps/yosys/log/timing_report.txt`
+- Coverage report: `bb-tests/sardine/reports/coverage/html/`
+- Simulation logs: `arch/log/<timestamp>/stdout.log`, `disasm.log`
+- bdb debug log: `arch/log/<timestamp>/bdb.log`, with three DPI-C traces:
+  - `[ITRACE]` — instruction issue/complete
+  - `[MTRACE]` — SRAM reads/writes
+  - `[PMCTRACE]` — Ball/Mem performance counters (elapsed cycles)
+
+## Skills
+
+Project skills are under `.claude/skills/`:
+- `/ball` — create a new Ball operator (full flow: implementation -> registration -> ISA -> CTest -> simulation)
+- `/check` — registration consistency check + auto-fix
+- `/verify` — Ball functional verification (build -> simulation -> coverage -> PMC analysis)
+- `/optimize` — RTL area/latency optimization (applies to any module, not only Balls)
+- `/debug` — simulation debugging (log analysis -> waveform -> failure pattern matching)
+- `/waveform` — waveform analysis (`waveform-mcp` usage guide)
+
+## Conventions
+
+- Do not edit registration files while changing Ball implementation; do not edit implementation files while changing registration
+- Chisel version is 6.5.0; do not use 6.6+ APIs
+- Register CTests in CMakeLists via `add_cross_platform_test_target`
+- **Do not call `bbdev` CLI or `nix develop -c bbdev ...` directly**; use MCP tools
+- Ball wrapper class names must match `ballName` in `default.json`

.claude/skills/ball/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: ball
+description: Create a new Buckyball Ball operator named $ARGUMENTS, covering the full flow from implementation to verification.
+---
+
+**Important: all build/simulation operations must go through MCP tools (`validate`, `bbdev_workload_build`, `bbdev_verilator_run`, etc.). Do not use bbdev CLI or nix develop directly.**
+
+## Phase 1 - Requirement Collection
+
+1. Inspect registration state and decide `ballId` + `funct7`:
+   - `arch/src/main/scala/framework/balldomain/configs/default.json`
+   - `arch/src/main/scala/examples/toy/balldomain/DISA.scala`
+2. Check for partial existing implementation (incremental mode):
+   - existing directory in `arch/src/main/scala/framework/balldomain/prototype/`
+   - existing ISA macro in `bb-tests/workloads/lib/bbhw/isa/`
+   - existing CTest in `bb-tests/workloads/src/CTest/toy/`
+3. Confirm with user:
+   - operator semantics
+   - `inBW` / `outBW`
+   - whether `op2` is needed
+   - meaning of `iter`
+
+## Phase 2 - Implement the Ball
+
+1. Read references:
+   - simple example: `.../prototype/relu/ReluBall.scala`, `Relu.scala`
+   - complex example: `.../prototype/systolicarray/`
+   - Blink protocol: `.../blink/blink.scala`, `bank.scala`, `status.scala`
+   - SRAM IO: `.../memdomain/backend/banks/SramIO.scala`
+2. Create files under `arch/src/main/scala/framework/balldomain/prototype/<name>/` using templates from `references/`.
+
+### Key constraints
+- SRAM read latency is 1 cycle (`resp.valid` in the cycle after `req.fire`)
+- Latch command fields when `cmdReq.fire`
+- Base FSM pattern: `idle -> read -> compute -> write -> complete -> idle`
+- `status.idle` and `status.running` must map correctly to FSM states
+
+## Phase 3 - Register the Ball
+
+Update files in order:
+1. `.../configs/default.json` - append `ballIdMappings` entry and update `ballNum`
+2. `.../bbus/busRegister.scala` - add import + `match case`
+3. `.../DISA.scala` - add `val XXX = BitPat("bxxxxxxx")`
+4. `.../DomainDecoder.scala` - add decode row (`BID = ballId.U`)
+
+## Phase 4 - Add ISA C Macro
+
+Create `<funct7_decimal>_<name>.c` under `bb-tests/workloads/lib/bbhw/isa/`, then include it in `isa.h`.
+
+## Phase 5 - Add CTest
+
+1. Create `<name>_test.c` under `bb-tests/workloads/src/CTest/toy/`
+2. Register in `bb-tests/workloads/src/CTest/toy/CMakeLists.txt` using `add_cross_platform_test_target`
+3. Append workload entry in `bb-tests/sardine/tests/test_ctest.py` (`ctest_workloads`)
+
+## Phase 6 - Validate, Build, and Simulate
+
+1. Run `validate` and ensure all 6 invariants pass
+2. Run `bbdev_workload_build`
+3. Run `bbdev_verilator_run` for this Ball's CTest binary
+4. Interpret results:
+   - `PASSED` -> done
+   - `FAILED` -> switch to `/debug`

.claude/skills/check/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: check
+description: Staticaly validate Buckyball Ball registration consistency and optionally auto-fix mismatches. Use this skill when users ask to inspect registration status, validate Ball configuration, troubleshoot registration issues, or verify consistency after registration edits.
+---
+
+## Validation Flow
+
+Call MCP tool `validate` to check these 6 invariants:
+1. `ballNum` equals `ballIdMappings` array length
+2. `ballId` is strictly increasing (`0, 1, 2, ...`) with no gaps
+3. no duplicated `ballId`
+4. no duplicated `funct7` in `DISA.scala`
+5. case names in `busRegister.scala` match `ballName` in `default.json`
+6. BID values in `DomainDecoder.scala` match `ballId` in `default.json`
+
+Report pass/fail for each item.
+
+## Registration Summary
+
+After validation, generate a summary table for all Ball registrations. Data sources:
+
+- `arch/src/main/scala/framework/balldomain/configs/default.json` — `ballId`, `ballName`, `inBW`, `outBW`
+- `arch/src/main/scala/examples/toy/balldomain/DISA.scala` — `funct7` values
+- `arch/src/main/scala/examples/toy/balldomain/DomainDecoder.scala` — BID in decode rows
+
+Table format:
+
+| ballId | ballName | funct7 | inBW | outBW | DISA | busReg | Decoder |
+|--------|----------|--------|------|-------|------|--------|---------|
+| 0      | VecBall  | 32     | 2    | 4     | ok   | ok     | ok      |
+| ...    | ...      | ...    | ...  | ...   | ...  | ...    | ...     |
+
+## Auto Fix
+
+If validation finds inconsistencies and they are deterministic to fix, ask whether to auto-fix:
+
+1. **`ballNum` mismatch** — update `ballNum` to `ballIdMappings` length
+2. **non-contiguous `ballId`** — renumber to `0, 1, 2, ...` (and sync BID in `DomainDecoder.scala`)
+3. **missing cases in `busRegister.scala`** — list missing Balls and provide required imports and `match case` entries
+4. **BID mismatch in `DomainDecoder.scala`** — update BID values to match `default.json`
+
+For non-auto-fixable issues (for example, `funct7` conflicts), provide root-cause analysis and manual fix guidance.

.claude/skills/debug/SKILL.md

@@ -0,0 +1,116 @@
+---
+name: debug
+description: Systematically debug Buckyball simulation failures. Use this skill when simulation returns FAILED, CTest fails, Chisel compilation errors appear, or users report abnormal Ball behavior. It covers log analysis, waveform analysis, and common failure pattern matching.
+---
+
+**Important: build and simulation operations must be called through MCP tools. Do not use bbdev CLI or nix develop directly.**
+
+## Step 1 - Locate Logs
+
+1. Find the log directory:
+   - MCP tool JSON output includes `log_dir`
+   - If absent, use `ls -t arch/log/ | head -5` to find recent log dirs
+2. Confirm key log files exist:
+   - `stdout.log` - program stdout (`PASSED`/`FAILED`, `printf`)
+   - `disasm.log` - disassembled instruction stream
+   - `bdb.log` - Buckyball hardware debug log (most important)
+   - `bbdev/server.log` - bbdev server log (compilation errors usually appear here)
+
+## Step 2 - Layered Analysis
+
+Analyze from high level to low level, ruling out simple issues first.
+
+### Level 1: Compilation errors (`bbdev/server.log`)
+
+If MCP tools return HTTP 500 or `returncode=1`, inspect `server.log` first:
+- Chisel compile errors (type mismatch, missing registration, etc.)
+- mill build errors (dependency issues)
+- CTest compile errors (C syntax/link errors)
+
+### Level 2: Program output (`stdout.log`)
+
+- Search for `PASSED` / `FAILED` to confirm test results
+- Search for `printf` outputs and compare actual vs expected values
+- Search for `panic` / `abort` / `trap` to detect exceptions
+
+### Level 3: Instruction stream (`disasm.log`)
+
+- Confirm custom Ball instructions were executed (search `custom3`)
+- Check instruction order (`mvin -> ball_op -> mvout -> fence`)
+- Check for traps or exceptions
+
+### Level 4: Hardware tracing (`bdb.log`)
+
+This is the most important log for Ball logic bugs. It contains three traces:
+
+**[ITRACE] instruction trace:**
+- `ISSUE rob_id=X domain=Y funct=0xZZ` - instruction issued
+- `COMPLETE rob_id=X` - instruction completed
+- Check: issued? completed? completion order correct?
+
+**[MTRACE] memory trace:**
+- `READ ch=X vbank=Y group=Z addr=0xAA` - SRAM read
+- `WRITE ch=X vbank=Y group=Z addr=0xAA data=0x...` - SRAM write
+- Check: addresses correct? data correct? `bank_id` matches?
+
+**[PMCTRACE] performance trace:**
+- `BALL ball_id=X rob_id=Y elapsed=Z` - Ball operation latency
+- `LOAD/STORE rob_id=X elapsed=Y` - memory operation latency
+- Check: elapsed reasonable? any unusually long operations?
+
+### Level 5: Waveform analysis (`waveform-mcp`)
+
+If logs are not enough, use waveform-mcp for cycle-level analysis. See `/waveform` skill.
+
+## Step 3 - Common Failure Patterns
+
+### 1. Ball not responding (`cmdResp` never fires)
+**Symptoms:** timeout or deadlock; `bdb.log` has `ISSUE` but no `COMPLETE`
+**Causes:**
+- FSM stuck in a state (check transition conditions)
+- `SRAM resp.valid` not consumed (for example, missing `resp.ready := true.B`)
+- `cmdResp.valid` never asserted
+
+### 2. All-zero output data
+**Symptoms:** CTest FAILED; output matrix is all zeros
+**Causes:**
+- write address bug (`waddr` not incremented)
+- write mask all zero (for example, forgot `mask := 1`)
+- wrong `bank_id` (writes into wrong bank)
+
+### 3. Output unchanged (`output == input`)
+**Symptoms:** CTest FAILED; output equals input
+**Causes:**
+- compute logic not executed (compute state skipped)
+- read data written back without processing
+
+### 4. Partial data errors
+**Symptoms:** CTest FAILED; some rows correct, others wrong
+**Causes:**
+- `iter` count miscalculated (missing reads/writes for some rows)
+- address offset bug (row stride error)
+- boundary condition bug
+
+### 5. SRAM timing error
+**Symptoms:** data appears shifted by one row
+**Causes:**
+- SRAM read latency is 1 cycle, but code reads `resp.bits.data` in the same cycle as `req.fire`
+- Correct behavior: wait one cycle and read when `resp.valid` is high
+
+### 6. `bank_id` conflict
+**Symptoms:** assertion failure or corrupted data
+**Causes:**
+- `op1_bank` and `wr_bank` use the same bank (read/write conflict)
+- multiple Balls access the same bank concurrently
+
+### 7. `rob_id` mismatch
+**Symptoms:** completion order looks incorrect
+**Causes:**
+- `cmdResp.bits.rob_id` is wrong
+- `rob_id` was not latched on `cmdReq.fire`
+
+## Step 4 - Fix and Verify
+
+1. Modify Chisel source code based on issues found in logs/waveforms
+2. Rebuild and rerun simulation through MCP tools to verify fixes
+3. If new failures appear, return to Step 2 and reanalyze