From d77d025c59b5c8aa6de5187cbc2e5c160ebe9d0e Mon Sep 17 00:00:00 2001 From: bowei Date: Wed, 12 Aug 2026 02:25:30 +0800 Subject: [PATCH] sync: SHANGHAI-U9 2026-08-12 --- sim-rtl-flow/SKILL.md | 27 ++++++++++++++++++--------- 1 file changed, 18 insertions(+), 9 deletions(-) diff --git a/sim-rtl-flow/SKILL.md b/sim-rtl-flow/SKILL.md index bb7f3fb..bd9aead 100644 --- a/sim-rtl-flow/SKILL.md +++ b/sim-rtl-flow/SKILL.md @@ -82,7 +82,7 @@ graph skip work: | metadata field | effect if `false` / listed | |---|---| -| `redo_fixed_point` | `false` → the `-q` stage is skipped entirely | +| `redo_fixed_point` | `false` → the `-q` stage is skipped entirely. Before answering `false`, re-check the historic `-q` against the **current** word-length rule — widths that violate it, or a history doc that never recorded widths, mean `true` | | `redo_partition` + `partition_review_required` | both `false` → the **`functional_partition` human checkpoint is skipped** | | `reuse_modules` | listed module → its `native:M` + `ip_replace:M` are skipped; result recorded as `stage: history_reuse` | | `redo_modules` | listed module always re-runs, even if also in `reuse_modules` | @@ -138,26 +138,34 @@ From `Notes/PR01.md` and `Notes/PR01-2.md`; the graph routes on these. 1. **sim-golden is the only acceptance criterion.** `-q`, the partition, and every `-E` version must match the `-x` sim. If it doesn't, record `gate_passed: false` — never record a pass you didn't verify. -2. **One `-E.slx` per RTL submodule**, saved separately (`_A-E.slx`, …). Do not +2. **The fixed-point word-length rule ranks alongside sim-golden.** Only multiplies and + adds of 16bit or less — after a 16×16 product, truncate back to 16bit before anything + downstream; widths must not accumulate stage by stage. The one exception is loop + accumulation: the accumulator is at least 32bit, and its result is truncated before it + feeds the rest of the design. `fixed_point#n` fails on a violation even when the + performance matches sim-golden, and `native:*`, `modify_e:*`, `sync_sim:*` may not + widen anything back. The rule and its machine-readable form arrive in every affected + task as `context.wordlength_rule` / `context.wordlength_limits`. +3. **One `-E.slx` per RTL submodule**, saved separately (`_A-E.slx`, …). Do not nativize all submodules in one Simulink model. -3. **Never hand-edit MATLAB-generated RTL.** If IP replacement, Vivado timing, or HIL +4. **Never hand-edit MATLAB-generated RTL.** If IP replacement, Vivado timing, or HIL needs a change there, return `change_scope: "simulink_module"` + `affected_modules`. The graph then forces `modify_e:* → sync_sim:*` before any RTL is regenerated. -4. **Editing a `-E` model obliges you to sync the `-x`/`-q` model.** `modify_e:*` edits +5. **Editing a `-E` model obliges you to sync the `-x`/`-q` model.** `modify_e:*` edits only the `-E`; the follow-up `sync_sim:*` uses **`simulink-rtl-redev`** to carry the same change into the simulation model and re-verify against sim-golden. The derivation script does *not* translate native-core edits into the m implementation, so changing one side alone means the RTL moved while the simulation still validates the old behaviour. If they don't align, the graph goes back to `modify_e:*` — it will **not** let you regenerate RTL. -5. **Timing fixes change the RTL, not the constraints.** Prefer adding pipeline/delay +6. **Timing fixes change the RTL, not the constraints.** Prefer adding pipeline/delay stages. Only touch timing constraints when the constraint itself is plainly wrong, and say why in `notes`. -6. **HIL is strictly read-only.** `hil:*` arrives with `allow_code_changes=false`. Run +7. **HIL is strictly read-only.** `hil:*` arrives with `allow_code_changes=false`. Run `fpga-imx6-flow` / `zynq-imx6-flow` for *diagnosis only*; the moment a code change is needed, stop that sub-flow and report it back here — the fix happens in the sim-rtl-flow main graph, then re-enters Vivado and HIL. -7. **Skipping a step needs written evidence, and every run leaves some.** The only +8. **Skipping a step needs written evidence, and every run leaves some.** The only grounds for not executing a stage are a history doc that records it as verified and unaffected. Every run ends by writing the next `sim-rtl-flow-.md`; anything you could not verify goes in as *not verified*, so the next run redoes it. @@ -239,7 +247,7 @@ keys with a default success — rehearsal only, and it refuses review keys. | `history_review#n` | read `sim-rtl-flow-.md` + the requirement doc, decide what may be reused; verdict in `metadata` (**first task of every run that has a history doc**) | inline — read the files, don't guess | | `simulink_x#n` | build/revise the `-x` sim, document the performance envelope | MATLAB MCP + `model-based-design-core:building-simulink-models`, `simulating-simulink-models` | | `review:sim_performance#n` | **ask the user** to sign off on sim-golden | — (relay to user) | -| `fixed_point#n` | `-q` fixed-point, compare to `-x` | same MATLAB skills | +| `fixed_point#n` | `-q` fixed-point, compare to `-x`, **and hold the word-length rule** (mult/add ≤16bit with truncation after the product; loop accumulators ≥32bit then truncated). Report `metadata.{wordlength_compliant, wordlength_violations, wordlengths}` — a violation fails the gate even when the performance matches sim-golden | same MATLAB skills | | `partition#n` | pure-sim / RTL / SoC split, must not degrade sim-golden | same | | `interfaces#n` | RTL↔SoC interface doc — register-config or data-stream only | write the doc under `work_dir` | | `review:functional_partition#n` | **ask the user** to sign off on the split + interfaces | — (relay to user) | @@ -252,7 +260,7 @@ keys with a default success — rehearsal only, and it refuses review keys. | `hil:fpga-imx6-flow#n` / `hil:zynq-imx6-flow#n` | HIL debug, **read-only** | `fpga-imx6-flow` / `zynq-imx6-flow` | | `timing_rework#n` | fix non-Simulink RTL / SoC / project timing | inline | | `hil_rework#n` | apply the code change HIL asked for | inline | -| `design_summary#n` | write `/sim-rtl-flow-.md` (path handed to you in `context.target_path`) covering every `-x`/`-q`/`-E` version, the partition, per-module status, Vivado/HIL verdicts, what was reused and what is still open; return the real path in `artifacts` (**last task of every run, success or failure**) | inline | +| `design_summary#n` | write `/sim-rtl-flow-.md` (path handed to you in `context.target_path`) covering every `-x`/`-q`/`-E` version, **the `-q` word lengths (multiplier/adder widths, truncation points, loop-accumulator widths) and whether they satisfy the word-length rule** — unrecorded widths force the next run to redo `-q` — the partition, per-module status, Vivado/HIL verdicts, what was reused and what is still open; return the real path in `artifacts` (**last task of every run, success or failure**) | inline | `#n` is the n-th time that key has been requested this run — retries and rework produce `#2`, `#3`, … @@ -272,6 +280,7 @@ review: {"approved": true, "notes": "", "metadata": {}} |---|---| | `success` + `gate_passed` | every design node — `false` → retry, then `failed` after 10 attempts | | `artifacts` | `simulink_x`'s first artifact **becomes sim-golden**; `vivado`'s go to HIL as the bitstream | +| `metadata.wordlength_compliant` + `wordlength_violations` + `wordlengths` | `fixed_point` — a violation (or a bare `wordlength_compliant: false`) fails the gate on its own; `wordlengths` is what the history doc records | | `timing_met` | `vivado` only | | `hil_passed` | `hil:*` only | | `needs_code_change` + `change_scope` + `affected_modules` | `vivado` and `hil:*` — the rework router |