Skip to content

Commit 3eea8be

Browse files
mguthausmguthaus
authored
Merge pull request #119 from VLSIDA/update-results-skill
Add /update-results skill for keeping results.html + figures/ in sync
2 parents 576ef03 + 48465b0 commit 3eea8be

1 file changed

Lines changed: 189 additions & 0 deletions

File tree

‎.claude/skills/update-results/SKILL.md‎

Lines changed: 189 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,189 @@
1+
---
2+
name: update-results
3+
description: Refresh webpage/results.html and webpage/figures/ to reflect each (platform, design) pair's latest cached build. Detects stale rows by comparing a per-row data-commit attribute to the design's most recent commit, refetches the cached 6_report.json via tools/fetch_cache.sh, regenerates the gallery image at <design>_<platform>_<sha>.png, deletes the previous versioned image, and rewrites the table between RESULTS_START / RESULTS_END markers. Also handles the one-time migration from canonical filenames (cnn_asap7.png) to commit-versioned ones. Use after a build sweep lands new artifacts in the remote cache.
4+
argument-hint: "[platform] [design]"
5+
---
6+
7+
# Update results.html and gallery figures
8+
9+
Keeps `webpage/results.html` and `webpage/figures/` in sync with each design's latest cached `6_report.json`. Each row pins a **commit SHA** (the most recent commit touching that design's BUILD/SDC/RTL); the gallery image is named with the same SHA so the row and image cannot drift. Old image files are deleted as new versions land.
10+
11+
The user may have given a `[platform]` and/or `[design]` filter (`$0` / `$1`) — use the same matching semantics as `k8s/run.sh` (positional, with `--design` for design-only). No filter = sweep everything.
12+
13+
**Operates on the `webpage` git worktree**, not whichever branch the user is currently on. Find it with `git worktree list | awk '$3=="[webpage]"{print $1}'`.
14+
15+
## Step 1: Locate the webpage worktree and check it's clean
16+
17+
```bash
18+
WT=$(git worktree list | awk '$3=="[webpage]"{print $1}')
19+
test -n "$WT" || die "no webpage worktree found; create one with 'git worktree add ../webpage webpage'"
20+
git -C "$WT" status --short
21+
```
22+
23+
If the worktree has uncommitted changes (other than the ones you're about to make), warn the user and ask whether to proceed — don't blindly add to a dirty tree.
24+
25+
If `webpage` is behind `origin/webpage`, fast-forward it before doing any work:
26+
27+
```bash
28+
git -C "$WT" pull --ff-only
29+
```
30+
31+
## Step 2: Detect first-time migration
32+
33+
Look for canonical filenames (no SHA component). These predate this skill and need a one-time rename to the new convention:
34+
35+
```bash
36+
ls "$WT"/figures/*.png 2>/dev/null \
37+
| grep -vE '_[0-9a-f]{7,}\.png$' \
38+
| grep -vE '/(HighTideFLOW|lighthouse|final_placement_)' # exclude infra figures, not per-design
39+
```
40+
41+
Anything that comes back is on the canonical-name convention. For each, decode `<design>_<platform>` from the filename, compute the design's current SHA (Step 4 below), then:
42+
43+
```bash
44+
git mv "$WT"/figures/<design>_<platform>.png \
45+
"$WT"/figures/<design>_<platform>_<sha>.png
46+
```
47+
48+
Use `git mv` so the rename history is preserved.
49+
50+
After all migrations, the existing single `<tr>` in results.html (currently a hardcoded lfsr row) should be replaced with a freshly-generated row in Step 6. Don't try to migrate the row in place — just regenerate it.
51+
52+
## Step 3: Determine the design list
53+
54+
```bash
55+
bazel query '//designs/...' 2>/dev/null \
56+
| awk -F: '/_final$/ { sub(":.*", "", $0); print $0 }' \
57+
| sort -u
58+
```
59+
60+
That yields entries like `//designs/asap7/cnn`. Strip the prefix to get `<platform>/<design-path>`. Apply `[platform]` / `[design]` filters if provided.
61+
62+
For each, derive:
63+
- `platform` (first segment)
64+
- `design_dir` (full path under `designs/`)
65+
- `leaf` (last segment of `design_dir`)
66+
- `bazel_target = //designs/<design_dir>:<leaf>_final`
67+
- `gallery_target = //designs/<design_dir>:<leaf>_gallery`
68+
- `report_path = bazel-bin/designs/<design_dir>/logs/<platform>/<top>/base/6_report.json` — `<top>` is whatever the design's `top` is, usually `<leaf>` but not always (e.g. lfsr's top is `lfsr_prbs_gen`). Read it from `bazel query --output=build //designs/<design_dir>:<leaf>_final` if uncertain, or just glob `logs/<platform>/*/base/6_report.json`.
69+
70+
## Step 4: Compute the design SHA
71+
72+
For each (platform, design):
73+
74+
```bash
75+
sha=$(git log -1 --format=%h -- \
76+
"designs/$design_dir/" \
77+
"designs/src/$leaf/" 2>/dev/null)
78+
```
79+
80+
7 chars (default `%h`), matching GitHub's commit-link convention. If the design has no `designs/src/<leaf>/` (no per-design RTL submodule, e.g. lfsr's RTL is in `designs/src/lfsr/` but for designs whose RTL lives elsewhere, just drop the second arg).
81+
82+
## Step 5: Refresh stale designs
83+
84+
Parse `webpage/results.html` for existing rows. Each row is keyed by `data-design` + `data-platform`; its current commit is `data-commit`. A row is **stale** if `data-commit` ≠ the SHA from Step 4, or the row is missing entirely.
85+
86+
For each stale (platform, design):
87+
88+
```bash
89+
# Pull the cached JSON. No local build — if cache miss, log + skip.
90+
./tools/fetch_cache.sh "$platform" "$leaf" || { echo "WARN: $platform/$leaf NOT CACHED, skipping"; continue; }
91+
92+
# Build only this design's gallery target.
93+
bazel build "$gallery_target"
94+
95+
# Copy versioned image, delete the previous one.
96+
new_img="$WT/figures/${leaf}_${platform}_${sha}.png"
97+
old_img=$(ls "$WT"/figures/${leaf}_${platform}_*.png 2>/dev/null | grep -v "_${sha}.png$" | head -1)
98+
cp "bazel-bin/designs/$design_dir/${leaf}_gallery.png" "$new_img"
99+
[[ -n "$old_img" ]] && git -C "$WT" rm -f "$old_img"
100+
git -C "$WT" add "$new_img"
101+
```
102+
103+
Capture QoR from the JSON using the same metric keys `tools/summary.sh` reads:
104+
- `finish__design__die__area`
105+
- `finish__design__core__area`
106+
- `finish__design__instance__area__stdcell`
107+
- `finish__design__instance__utilization` (× 100 for %)
108+
- `finish__design__instance__count__stdcell`
109+
- `finish__design__instance__count__macros`
110+
- `finish__design__io`
111+
- `finish__timing__setup__ws` (WNS)
112+
- `finish__timing__setup__tns` (TNS)
113+
- `finish__timing__fmax` (÷ 1e9 for GHz)
114+
- `finish__power__total` (× 1000 for mW)
115+
- `finish__flow__errors__count` (DRCs)
116+
117+
Format with the same precision as `tools/summary.sh:53-84` (areas / cells / counts: 1 decimal; timing / fmax: 2 decimals; power: 3 decimals; util: 1 decimal).
118+
119+
## Step 6: Rewrite the table between markers
120+
121+
Find `<!-- RESULTS_START -->` and `<!-- RESULTS_END -->` in `webpage/results.html`. Replace everything between them with one `<tr>` per (platform, design) in `(platform, design)` sort order:
122+
123+
```html
124+
<tr data-design="cnn" data-platform="asap7" data-commit="a1b2c3d">
125+
<td><span class="platform-badge badge-asap7">asap7</span></td>
126+
<td>cnn</td>
127+
<td>360000.0</td>
128+
<td>336166.0</td>
129+
<td>23936.7</td>
130+
<td>40.1</td>
131+
<td>212257</td>
132+
<td>65</td>
133+
<td>367</td>
134+
<td>-44.30</td>
135+
<td>-149.87</td>
136+
<td>0.96</td>
137+
<td>456.091</td>
138+
<td>0</td>
139+
<td><a href="https://github.com/VLSIDA/HighTide/commit/a1b2c3d">a1b2c3d</a></td>
140+
</tr>
141+
```
142+
143+
The first time the skill runs the table needs a new `<th>Commit</th>` column at the right end of the `<thead>` row — add it once, idempotent.
144+
145+
If a (platform, design) is currently NOT CACHED (Step 5 skipped it), preserve any existing row in the table (don't drop the design from the page just because the user's local cache is empty). Use `<!-- skipped: not cached on YYYY-MM-DD -->` as a comment marker to make stale-data sources visible.
146+
147+
## Step 7: Update gallery.html thumbnails
148+
149+
`webpage/gallery.html` references the same images. Replace its `<img src="figures/<old>.png">` references to point at the new versioned filenames. Same migration rule applies on first run.
150+
151+
## Step 8: Show the diff and stop
152+
153+
```bash
154+
git -C "$WT" status --short
155+
git -C "$WT" diff --stat
156+
git -C "$WT" diff figures/ -- ':(exclude)*.png' | head # text-only diff for HTML
157+
```
158+
159+
Surface the change set to the user, list any designs that were skipped because the cache was cold, and stop. Don't `git commit` or `git push` — leave that to the user.
160+
161+
## Worked example
162+
163+
```
164+
/update-results
165+
```
166+
167+
(No filter, so sweep everything.)
168+
169+
```
170+
> Locating webpage worktree at /home/mrg/HighTide/webpage … clean (origin/webpage @ 1d9ccec4).
171+
> Migration check: 38 canonical-name PNGs found, renaming to <design>_<platform>_<sha>.png …
172+
> figures/cnn_asap7.png → cnn_asap7_a1b2c3d.png
173+
> figures/coralnpu_asap7.png → coralnpu_asap7_e4f5g6h.png
174+
> …
175+
> Sweep: 56 (platform, design) pairs.
176+
> asap7/cnn a1b2c3d STALE (table commit was canonical-only)
177+
> ./tools/fetch_cache.sh asap7 cnn → cached
178+
> bazel build //designs/asap7/cnn:cnn_gallery → 0.4s, cache hit
179+
> wrote figures/cnn_asap7_a1b2c3d.png (replaces cnn_asap7.png)
180+
> sky130hd/NVDLA/partition_c stale NOT CACHED → skipped
181+
> …
182+
> Rewrote results.html (56 rows, 1 skipped → preserved as comment).
183+
> Rewrote gallery.html (38 image references updated).
184+
> Diff:
185+
> results.html | 412 ++++++++++++++++++++++++++++++++++++++++++--------------
186+
> gallery.html | 84 +++++-----
187+
> figures/ | 38 deletions, 38 creations (renames)
188+
> Run `git -C /home/mrg/HighTide/webpage diff` to review, then commit + push.
189+
```

0 commit comments

Comments
 (0)