[repo] feat: update features to 0.1.0

.claude/CLAUDE.md

@@ -18,7 +18,8 @@ A RISC-V based DSA (Domain Specific Architecture) framework. Built with Chisel 6
 - `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/lib/bbhw/isa/` — base mem/frontend ISA C macros
+  - `examples/balls/<ball>/workloads/isa/` — ball-specific ISA macros
   - `workloads/src/CTest/` — C test cases
 - `bbdev/` — developer toolchain (Motia workflow backend)
 
@@ -52,10 +53,11 @@ When adding or modifying a balldomain TOML, these must hold:
 
 1. `ballNum` equals `ballIdMappings` length
 2. `ballId` is strictly `0, 1, 2, ...` with no gaps/duplicates
-3. `ballName` / `funct7` / `mnemonic` have no duplicates
+3. `ballName` / `funct7` / `mnemonic` have no duplicates **within that core's ballISA** (cross-core encoding conflicts are allowed)
 4. every `ballISA.bid` exists in `ballIdMappings`, and every ball has at least one ISA entry
 5. relative `config=` paths resolve to existing files (when present)
 6. `inBW` / `outBW` are positive integers
+7. Ball trees (`examples/balls/*/`) must not hardcode `funct7`; encoding comes only from the Core `ballISA` generated into `examples/cores/<core>/isa/ballISA.h`
 
 Use MCP `validate(chip=..., balldomain=...)` or `/check`.
 
@@ -77,11 +79,12 @@ Daily agent path:
 
 ### bbdev API wrappers (automatic server lifecycle + task status)
 All bbdev POST endpoints are exposed as `bbdev_*` tools. Daily path prefers:
-- `bbdev_compiler_build` / `bbdev_workload_{clean,build,tohex}`
+- `bbdev_config_install` / `bbdev_compiler_build` / `bbdev_workload_{clean,build,tohex}`
 - `bbdev_bemu_{sim,batch}`
 - `bbdev_bebop_verilator_{clean,verilog,build,sim,run,batch}` — bebop-accelerated RTL
 - `bbdev_verilator_{clean,verilog,build,sim,run}` — non-bebop Verilator RTL path
-- `bbdev_uvm_{build,run}` / `bbdev_yosys_{run,verilog,synth}`
+- `bbdev_vcs_{clean,verilog,build,sim,run}` — VCS RTL path
+- `bbdev_uvm_{verilog,build,run}` / `bbdev_yosys_{run,verilog,synth}`
 Also: `bbdev_bebop_p2e_*`, `bbdev_firesim_*`, `bbdev_dc_verilog`, `bbdev_kernel_build`
 
 Every `bbdev_*` task submission returns immediately with `accepted=true`,
@@ -90,12 +93,12 @@ Every `bbdev_*` task submission returns immediately with `accepted=true`,
 
 Default Verilator config: `sims.verilator.BuckyballToyVerilatorConfig`
 Pebble: `sims.verilator.BuckyballPebbleVerilatorConfig`
-Workload binary names are `{chip}_{stem}-{platform}`, e.g. `toy_vecunit_matmul_ones-singlecore-baremetal`
+Workload binary names are `{chip}_{stem}-{platform}`, e.g. `toy_vecunit_matmul_ones-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`
-- Simulation logs: `log/<timestamp>-{bemu,verilator,p2e}-<name>/stdout.log`, `disasm.log`
+- Simulation logs: `log/<timestamp>-<chip>-<config>-<tool>-<name>/stdout.log`, `disasm.log`
 - bdb debug log: `log/<timestamp>-*/bdb.ndjson` (or `bdb.log`), with three DPI-C traces:
   - `[ITRACE]` — instruction issue/complete
   - `[MTRACE]` — SRAM reads/writes

.claude/skills/ball-align/SKILL.md

@@ -38,11 +38,11 @@ Against `examples/balls/<name>/` and the target chip, list gaps:
 | Small tests | Short shapes, hand vectors, edge/illegal | bemu + Verilator |
 | Bank tests | `iter≈BANK_LINES`, `srand`/`rand`; soft numeric may report LOSS | **bemu only** |
 | Integration tests | Real consumers; must update on contract changes | bemu; small paths may use Verilator |
-| MLIR | Under `examples/balls/<name>/workloads/mlir_tests/`; **not** under chip | FileCheck + optest ELF → bemu regression |
+| MLIR | Under `examples/balls/<name>/workloads/mlir_tests/`; **not** under chip | FileCheck + mlirtest ELF → bemu regression |
 | UVM | Stimulus/scoreboard on the same contract | **After RTL is green** |
 
-- MLIR: keep `bank` Op and lowered `ball` Op separate (see transpose: contract + optest)
-- New ctest / optest → chip **bemu** `workloads-elf.toml` + `workloads-pk.toml`
+- MLIR: keep `bank` Op and lowered `ball` Op separate (see transpose: contract + mlirtest)
+- New ctest / mlirtest → chip **bemu** `workloads-elf.toml` + `workloads-pk.toml`
 - Verilator lists take **small tests only**, not bank tests
 
 ## Phase 2 - One semantics across the stack
@@ -78,7 +78,7 @@ Copy and tick:
 ```
 - [ ] Contract (fields, shapes, illegal table) + validate pass
 - [ ] Small suite bemu green; bank tests bemu green
-- [ ] bank/ball MLIR OpTest + listed in bemu regression
+- [ ] bank/ball MLIRTest + listed in bemu regression
 - [ ] RTL aligned + Verilator small tests green
 - [ ] Integration tests synced; UVM (after RTL)
 ```

.claude/skills/ball/SKILL.md

@@ -12,7 +12,7 @@ description: Create a new Buckyball Ball operator named $ARGUMENTS, covering the
    - usually `examples/chips/<chip>/configs/tiles/cores/balldomains/*.toml`
 2. Check for partial existing implementation (incremental mode):
    - existing directory in `examples/balls/`
-   - existing ISA macro in `bb-tests/workloads/lib/bbhw/isa/`
+   - existing ISA macro in `examples/balls/<name>/workloads/isa/` (or base under `bb-tests/workloads/lib/bbhw/isa/`)
    - existing chip/ball ctests under `examples/` or `bb-tests/workloads/`
 3. Confirm with user:
    - target chip
@@ -47,7 +47,9 @@ Edit the chip balldomain TOML (the one selected by `cores/default.toml`, or the
 
 ## Phase 4 - Add ISA C Macro
 
-Create `<funct7_decimal>_<name>.c` under `bb-tests/workloads/lib/bbhw/isa/`, then include it in `isa.h`.
+Create `examples/balls/<name>/workloads/isa/<name>.h` (include `<bbhw/isa/isa.h>`),
+then `#include <isa/<name>.h>` from the ball's ctests. Do **not** add ball ISA to
+central `bb-tests/workloads/lib/bbhw/isa/isa.h` (base mem/frontend only).
 
 ## Phase 5 - Add CTest
 

.claude/skills/check/SKILL.md

@@ -16,9 +16,10 @@ Checks on that TOML:
 1. `ballNum` equals `ballIdMappings` length
 2. `ballId` is strictly increasing (`0, 1, 2, ...`) with no gaps
 3. no duplicated `ballId` / `ballName`
-4. no duplicated `funct7` / `mnemonic` in `ballISA`
+4. no duplicated `funct7` / `mnemonic` in `ballISA` (scope = this single balldomain / core; other cores may reuse the same funct7)
 5. every `ballISA.bid` exists in mappings; every ball has ≥1 ISA entry
 6. relative `config=` paths exist; `inBW`/`outBW` are positive
+7. ball ISA headers / MLIR must not hardcode ball `funct7` (encoding is generated from this TOML into `examples/cores/<core>/isa/ballISA.h`)
 
 Report pass/fail for each item.
 

.claude/skills/chip-designer/SKILL.md

@@ -54,7 +54,7 @@ Do **not** require full-model green before the cut.
 
 Create `examples/chips/<chip>/`:
 
-- `chip.toml` (`topology`, `compilerCore`, `runtime.*`)
+- `chip.toml` (only `[chip]` mill class: `verilatorConfig` / `p2eConfig`)
 - `configs/` tile with `sharedMem` + `[[cores]]` includes into `examples/cores/<name>/`
 - `arch/.../CustomConfigs.scala` + `sims/{verilator,p2e}/TargetConfigs.scala`
 - `workloads/` (contracts + later binaries), `regression/batch/{bemu,verilator,p2e}/`, optional `kernel/`

.claude/skills/verify/SKILL.md

@@ -10,15 +10,15 @@ description: Verify functional correctness of the Ball named $ARGUMENTS. Use thi
 Use `/check` logic to validate registration consistency, then ensure all required artifacts exist and fill missing pieces:
 1. Ball implementation: `examples/balls/<name>/arch/src/main/scala/`
 2. Registration entry in chip balldomain TOML under `examples/chips/<chip>/configs/tiles/cores/balldomains/`
-3. ISA macro file in `bb-tests/workloads/lib/bbhw/isa/`
+3. ISA macro file in `examples/balls/<ball>/workloads/isa/` (base ISA under `bb-tests/workloads/lib/bbhw/isa/`)
 4. CTest for that ball/chip
 
 ## Phase 2 - Build and Simulate
 
 1. Run `bbdev_workload_build(chip=...)` to build CTests
 2. Run `bbdev_bemu_sim(chip=..., binary=...)` first
 3. Run `bbdev_bebop_verilator_run(binary=..., config=...)` for RTL
-   - binary is `{chip}_{stem}-{platform}`, e.g. `toy_transpose_test-singlecore-baremetal`
+   - binary is `{chip}_{stem}-{platform}`, e.g. `toy_transpose_test-baremetal`
    - config is required, e.g. `sims.verilator.BuckyballToyVerilatorConfig`
 4. If build/simulation fails, switch to `/debug` flow
 

.claude/skills/waveform/SKILL.md

@@ -17,7 +17,7 @@ The project uses `waveform-mcp` with these tools:
 ## Waveform File Locations
 
 Waveforms generated by simulation are usually in:
-- `log/<timestamp>-verilator-<binary>/waveform/`
+- `log/<timestamp>-<chip>-<config>-verilator-<binary>/waveform/`
 - format: `.vcd` or `.fst`
 - use `find log -name "*.vcd" -o -name "*.fst" | head -5` to locate files
 

.github/scripts/ci_repo_lock.sh

@@ -0,0 +1,104 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+LOCK_DIR=/tmp/buckyball-ci
+LOCK_FILE="${LOCK_DIR}/lock"
+ACTIVE_SHA_FILE="${LOCK_DIR}/active_sha"
+REFCOUNT_FILE="${LOCK_DIR}/refcount"
+
+usage() {
+  echo "usage: $0 prepare|enter|exit <sha> <repo> <git-ref>" >&2
+  exit 1
+}
+
+[[ $# -eq 4 ]] || usage
+
+cmd="$1"
+want_sha="$2"
+repo="${3/#\~/$HOME}"
+git_ref="$4"
+
+mkdir -p "${LOCK_DIR}"
+exec 9>"${LOCK_FILE}"
+
+repo_reset() {
+  cd "${repo}"
+  git fetch --force --prune origin "${git_ref}"
+  git checkout --detach FETCH_HEAD
+  git reset --hard FETCH_HEAD
+  git clean -ffd
+  git submodule sync
+  git submodule update --init --force
+  for submodule in bbdev bebop compiler/thirdparty/buddy-mlir; do
+    git -C "${repo}/${submodule}" reset --hard
+    git -C "${repo}/${submodule}" clean -ffd
+  done
+  have_sha="$(git rev-parse HEAD)"
+  if [[ "${have_sha}" != "${want_sha}" ]]; then
+    echo "ERROR: checkout is ${have_sha}, expected ${want_sha}" >&2
+    exit 1
+  fi
+}
+
+repo_prepare() {
+  flock 9
+  repo_reset
+  echo "${want_sha}" > "${ACTIVE_SHA_FILE}"
+  echo 0 > "${REFCOUNT_FILE}"
+  flock -u 9
+}
+
+repo_enter() {
+  while true; do
+    flock 9
+    active_sha="$(cat "${ACTIVE_SHA_FILE}" 2>/dev/null || true)"
+    refcount="$(cat "${REFCOUNT_FILE}" 2>/dev/null || echo 0)"
+    have_sha="$(git -C "${repo}" rev-parse HEAD)"
+    if [[ "${have_sha}" == "${want_sha}" ]]; then
+      echo "${want_sha}" > "${ACTIVE_SHA_FILE}"
+      echo $((refcount + 1)) > "${REFCOUNT_FILE}"
+      flock -u 9
+      return 0
+    fi
+    if [[ "${active_sha}" == "${want_sha}" ]]; then
+      echo $((refcount + 1)) > "${REFCOUNT_FILE}"
+      flock -u 9
+      return 0
+    fi
+    if [[ "${refcount}" == "0" ]]; then
+      repo_reset
+      echo "${want_sha}" > "${ACTIVE_SHA_FILE}"
+      echo 1 > "${REFCOUNT_FILE}"
+      flock -u 9
+      return 0
+    fi
+    flock -u 9
+    echo "waiting: active=${active_sha} refcount=${refcount} want=${want_sha}"
+    sleep 10
+  done
+}
+
+repo_exit() {
+  flock 9
+  active_sha="$(cat "${ACTIVE_SHA_FILE}" 2>/dev/null || true)"
+  refcount="$(cat "${REFCOUNT_FILE}" 2>/dev/null || echo 0)"
+  if [[ "${active_sha}" != "${want_sha}" ]]; then
+    echo "ERROR: active sha ${active_sha} != job sha ${want_sha}" >&2
+    flock -u 9
+    exit 1
+  fi
+  if [[ "${refcount}" -le 0 ]]; then
+    echo "ERROR: refcount underflow (${refcount})" >&2
+    flock -u 9
+    exit 1
+  fi
+  echo $((refcount - 1)) > "${REFCOUNT_FILE}"
+  flock -u 9
+}
+
+case "${cmd}" in
+  prepare) repo_prepare ;;
+  enter) repo_enter ;;
+  exit) repo_exit ;;
+  *) usage ;;
+esac

.github/scripts/setproxy.sh

@@ -0,0 +1 @@
+export ALL_PROXY=http://127.0.0.1:7890

.github/workflows/README.zh.md

@@ -1,5 +1,8 @@
 # CI 说明
 
-CI目前分为两大类：
-- 第一类是仓库功能check，确保代码合并后功能正确不会对仓库主线造成影响，触发方式为自动执行。部署的服务器组为 buckyball-cpu-server，服务器label为 cpu-server
-- 第二类是PPA性能回归，定期执行检查优化后设计在目标workload上的表现和RTL的面积和功耗表现，生成性能分析报告，触发方式为手动分配。配置的服务器组为 buckyball-ppa-regression，服务器label为 cpu-server-tapeout
+push/PR 到 `main` 只触发 `ci.yml`：
+
+1. **pre-commit**：拉代码 + 校验一次
+2. **chip-check**：通过后，matrix 并行跑各 chip（共享 `~/Code/buckyball`，`ci_repo_lock.sh` 协调）
+
+手动只跑 pre-commit：Actions 里触发 `pre-commit.yml`。