simdref 0.0.0__tar.gz → 0.0.3__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- {simdref-0.0.0/src/simdref.egg-info → simdref-0.0.3}/PKG-INFO +111 -28
- simdref-0.0.3/README.md +292 -0
- {simdref-0.0.0 → simdref-0.0.3}/pyproject.toml +5 -1
- {simdref-0.0.0 → simdref-0.0.3}/src/simdref/__init__.py +1 -2
- {simdref-0.0.0 → simdref-0.0.3}/src/simdref/__main__.py +0 -1
- {simdref-0.0.0 → simdref-0.0.3}/src/simdref/annotate.py +319 -37
- {simdref-0.0.0 → simdref-0.0.3}/src/simdref/arm_instructions.py +124 -28
- {simdref-0.0.0 → simdref-0.0.3}/src/simdref/cli.py +729 -102
- {simdref-0.0.0 → simdref-0.0.3}/src/simdref/display.py +169 -50
- {simdref-0.0.0 → simdref-0.0.3}/src/simdref/filters.py +70 -21
- {simdref-0.0.0 → simdref-0.0.3}/src/simdref/ingest.py +9 -3
- {simdref-0.0.0 → simdref-0.0.3}/src/simdref/ingest_catalog.py +288 -85
- {simdref-0.0.0 → simdref-0.0.3}/src/simdref/ingest_pdf.py +52 -16
- {simdref-0.0.0 → simdref-0.0.3}/src/simdref/ingest_sources.py +24 -13
- {simdref-0.0.0 → simdref-0.0.3}/src/simdref/lsp.py +29 -6
- {simdref-0.0.0 → simdref-0.0.3}/src/simdref/manpages.py +58 -14
- {simdref-0.0.0 → simdref-0.0.3}/src/simdref/models.py +25 -8
- {simdref-0.0.0 → simdref-0.0.3}/src/simdref/pdfparse/intel.py +48 -28
- {simdref-0.0.0 → simdref-0.0.3}/src/simdref/pdfparse/types.py +11 -7
- {simdref-0.0.0 → simdref-0.0.3}/src/simdref/pdfrefs.py +3 -1
- {simdref-0.0.0 → simdref-0.0.3}/src/simdref/perf.py +21 -0
- simdref-0.0.3/src/simdref/perf_sources/cores.py +386 -0
- {simdref-0.0.0 → simdref-0.0.3}/src/simdref/perf_sources/llvm_scheduling.py +9 -19
- {simdref-0.0.0 → simdref-0.0.3}/src/simdref/perf_sources/merge.py +1 -0
- simdref-0.0.3/src/simdref/profile/__init__.py +25 -0
- simdref-0.0.3/src/simdref/profile/adapters/__init__.py +1 -0
- simdref-0.0.3/src/simdref/profile/adapters/exegesis.py +65 -0
- simdref-0.0.3/src/simdref/profile/adapters/mca.py +84 -0
- simdref-0.0.3/src/simdref/profile/adapters/perf.py +245 -0
- simdref-0.0.3/src/simdref/profile/adapters/uprof.py +89 -0
- simdref-0.0.3/src/simdref/profile/adapters/vtune.py +83 -0
- simdref-0.0.3/src/simdref/profile/adapters/xctrace.py +66 -0
- simdref-0.0.3/src/simdref/profile/hotloop.py +315 -0
- simdref-0.0.3/src/simdref/profile/merge.py +215 -0
- simdref-0.0.3/src/simdref/profile/model.py +129 -0
- simdref-0.0.3/src/simdref/profile/orchestrate.py +303 -0
- simdref-0.0.3/src/simdref/profile/registry.py +62 -0
- {simdref-0.0.0 → simdref-0.0.3}/src/simdref/queries.py +21 -16
- {simdref-0.0.0 → simdref-0.0.3}/src/simdref/riscv.py +40 -13
- {simdref-0.0.0 → simdref-0.0.3}/src/simdref/search.py +62 -12
- {simdref-0.0.0 → simdref-0.0.3}/src/simdref/storage.py +115 -58
- {simdref-0.0.0 → simdref-0.0.3}/src/simdref/templates/app.js +725 -84
- {simdref-0.0.0 → simdref-0.0.3}/src/simdref/templates/index.html +55 -3
- {simdref-0.0.0 → simdref-0.0.3}/src/simdref/templates/style.css +247 -10
- {simdref-0.0.0 → simdref-0.0.3}/src/simdref/tui.py +210 -62
- simdref-0.0.3/src/simdref/ui_labels.py +69 -0
- {simdref-0.0.0 → simdref-0.0.3}/src/simdref/web.py +68 -38
- {simdref-0.0.0 → simdref-0.0.3/src/simdref.egg-info}/PKG-INFO +111 -28
- {simdref-0.0.0 → simdref-0.0.3}/src/simdref.egg-info/SOURCES.txt +20 -0
- {simdref-0.0.0 → simdref-0.0.3}/tests/test_annotate.py +77 -9
- simdref-0.0.3/tests/test_audit_coverage.py +161 -0
- simdref-0.0.3/tests/test_cli_bare_query.py +90 -0
- simdref-0.0.3/tests/test_cli_bootstrap_progress.py +110 -0
- {simdref-0.0.0 → simdref-0.0.3}/tests/test_cli_llm.py +10 -3
- {simdref-0.0.0 → simdref-0.0.3}/tests/test_coverage_parity.py +1 -2
- {simdref-0.0.0 → simdref-0.0.3}/tests/test_display.py +12 -2
- {simdref-0.0.0 → simdref-0.0.3}/tests/test_filters.py +38 -16
- {simdref-0.0.0 → simdref-0.0.3}/tests/test_ingest_sources.py +8 -0
- simdref-0.0.3/tests/test_issue2_fixes.py +159 -0
- {simdref-0.0.0 → simdref-0.0.3}/tests/test_lsp_web.py +32 -13
- {simdref-0.0.0 → simdref-0.0.3}/tests/test_models.py +64 -48
- {simdref-0.0.0 → simdref-0.0.3}/tests/test_pdfparse.py +104 -19
- {simdref-0.0.0 → simdref-0.0.3}/tests/test_perf.py +18 -0
- {simdref-0.0.0 → simdref-0.0.3}/tests/test_perf_sources.py +58 -55
- {simdref-0.0.0 → simdref-0.0.3}/tests/test_presentation.py +18 -4
- simdref-0.0.3/tests/test_preset_persistence.py +117 -0
- {simdref-0.0.0 → simdref-0.0.3}/tests/test_search.py +45 -11
- {simdref-0.0.0 → simdref-0.0.3}/tests/test_search_pushdown.py +8 -4
- {simdref-0.0.0 → simdref-0.0.3}/tests/test_source_kind_filter.py +1 -1
- {simdref-0.0.0 → simdref-0.0.3}/tests/test_source_validation.py +4 -1
- {simdref-0.0.0 → simdref-0.0.3}/tests/test_storage_schema.py +29 -8
- simdref-0.0.3/tests/test_ui_labels_parity.py +121 -0
- {simdref-0.0.0 → simdref-0.0.3}/tests/test_x86_linking.py +6 -2
- simdref-0.0.0/README.md +0 -209
- simdref-0.0.0/src/simdref/perf_sources/cores.py +0 -101
- {simdref-0.0.0 → simdref-0.0.3}/LICENSE +0 -0
- {simdref-0.0.0 → simdref-0.0.3}/setup.cfg +0 -0
- {simdref-0.0.0 → simdref-0.0.3}/src/simdref/pdfparse/__init__.py +0 -0
- {simdref-0.0.0 → simdref-0.0.3}/src/simdref/pdfparse/base.py +0 -0
- {simdref-0.0.0 → simdref-0.0.3}/src/simdref/pdfparse/registry.py +0 -0
- {simdref-0.0.0 → simdref-0.0.3}/src/simdref/perf_sources/__init__.py +0 -0
- {simdref-0.0.0 → simdref-0.0.3}/src/simdref/perf_sources/llvm_mca.py +0 -0
- {simdref-0.0.0 → simdref-0.0.3}/src/simdref/templates/__init__.py +0 -0
- {simdref-0.0.0 → simdref-0.0.3}/src/simdref/templates/favicon.svg +0 -0
- {simdref-0.0.0 → simdref-0.0.3}/src/simdref/templates/logo.svg +0 -0
- {simdref-0.0.0 → simdref-0.0.3}/src/simdref.egg-info/dependency_links.txt +0 -0
- {simdref-0.0.0 → simdref-0.0.3}/src/simdref.egg-info/entry_points.txt +0 -0
- {simdref-0.0.0 → simdref-0.0.3}/src/simdref.egg-info/requires.txt +0 -0
- {simdref-0.0.0 → simdref-0.0.3}/src/simdref.egg-info/top_level.txt +0 -0
- {simdref-0.0.0 → simdref-0.0.3}/tests/test_cli_help.py +0 -0
- {simdref-0.0.0 → simdref-0.0.3}/tests/test_coverage_live.py +0 -0
- {simdref-0.0.0 → simdref-0.0.3}/tests/test_tui.py +0 -0
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: simdref
|
|
3
|
-
Version: 0.0.
|
|
3
|
+
Version: 0.0.3
|
|
4
4
|
Summary: Searchable SIMD intrinsic and instruction reference with CLI, manpages, TUI, LSP, and static web export.
|
|
5
5
|
Author: Marco
|
|
6
6
|
License: GPL-3.0-or-later
|
|
@@ -32,9 +32,8 @@ Dynamic: license-file
|
|
|
32
32
|
# simdref
|
|
33
33
|
|
|
34
34
|
[](https://github.com/DiamonDinoia/simdref/actions/workflows/ci.yml)
|
|
35
|
-
[](https://github.com/DiamonDinoia/simdref/actions/workflows/pages.yml)
|
|
36
35
|
[](https://test.pypi.org/project/simdref/)
|
|
37
|
-
[](https://
|
|
36
|
+
[](https://pypi.org/project/simdref/)
|
|
38
37
|
|
|
39
38
|
A single searchable reference for SIMD intrinsics and instructions across
|
|
40
39
|
**x86 (Intel + uops.info)**, **Arm (ACLE / AARCHMRS)**, and **RISC-V
|
|
@@ -49,11 +48,81 @@ for LLM skills.
|
|
|
49
48
|
|
|
50
49
|
<!-- Screenshots are hosted on the `docs-assets` branch so the main
|
|
51
50
|
branch stays lightweight to clone. -->
|
|
51
|
+
|
|
52
52
|
<p align="center">
|
|
53
53
|
<img alt="simdref TUI" src="https://raw.githubusercontent.com/DiamonDinoia/simdref/docs-assets/img/tui.svg" width="720">
|
|
54
54
|
<br><em>Interactive TUI with ISA filters, ranked results, and measured/modeled performance tables.</em>
|
|
55
55
|
</p>
|
|
56
56
|
|
|
57
|
+
## Install the Claude Code skill
|
|
58
|
+
|
|
59
|
+
`skills/asm-analysis/` ships a Claude Code skill that drives the
|
|
60
|
+
compile → objdump → `simdref annotate` → `simdref profile` → LLM-batch
|
|
61
|
+
pipeline automatically. This repo publishes it as a Claude Code plugin,
|
|
62
|
+
so the one-liner install is:
|
|
63
|
+
|
|
64
|
+
```
|
|
65
|
+
/plugin marketplace add DiamonDinoia/simdref
|
|
66
|
+
/plugin install asm-analysis@simdref
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
Run those at the Claude Code prompt. The marketplace add fetches this
|
|
70
|
+
repo; the install wires up the skill so Claude picks it up automatically
|
|
71
|
+
on performance-oriented prompts like *"why is this loop slow"*,
|
|
72
|
+
*"vectorise this"*, *"look at the asm"*.
|
|
73
|
+
|
|
74
|
+
### Manual install (no marketplace)
|
|
75
|
+
|
|
76
|
+
If you prefer a hand-managed copy:
|
|
77
|
+
|
|
78
|
+
```bash
|
|
79
|
+
# symlink from a checkout — always current with main:
|
|
80
|
+
git clone https://github.com/DiamonDinoia/simdref.git ~/src/simdref
|
|
81
|
+
mkdir -p ~/.claude/skills
|
|
82
|
+
ln -sf ~/src/simdref/skills/asm-analysis ~/.claude/skills/asm-analysis
|
|
83
|
+
|
|
84
|
+
# or pull a one-off snapshot:
|
|
85
|
+
mkdir -p ~/.claude/skills/asm-analysis && \
|
|
86
|
+
curl -fsSL https://raw.githubusercontent.com/DiamonDinoia/simdref/main/skills/asm-analysis/SKILL.md \
|
|
87
|
+
-o ~/.claude/skills/asm-analysis/SKILL.md
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
See [`skills/asm-analysis/SKILL.md`](skills/asm-analysis/SKILL.md) for
|
|
91
|
+
the full trigger list and pipeline stages.
|
|
92
|
+
|
|
93
|
+
## Install the Codex skill
|
|
94
|
+
|
|
95
|
+
This repo also ships the same pipeline as an OpenAI Codex plugin, so
|
|
96
|
+
the one-liner install from a Codex CLI prompt is:
|
|
97
|
+
|
|
98
|
+
```
|
|
99
|
+
codex plugin marketplace add DiamonDinoia/simdref
|
|
100
|
+
/plugins
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
Pick `asm-analysis` in the browser and enable it. Codex picks up the
|
|
104
|
+
skill automatically on performance-oriented prompts (*"why is this
|
|
105
|
+
loop slow"*, *"vectorise this"*, *"look at the asm"*).
|
|
106
|
+
|
|
107
|
+
### Manual install (no marketplace)
|
|
108
|
+
|
|
109
|
+
```bash
|
|
110
|
+
# user-scoped symlink — applies to every repo, always current with main:
|
|
111
|
+
git clone https://github.com/DiamonDinoia/simdref.git ~/src/simdref
|
|
112
|
+
mkdir -p ~/.agents/skills
|
|
113
|
+
ln -sf ~/src/simdref/codex-skills/asm-analysis/skills/asm-analysis \
|
|
114
|
+
~/.agents/skills/asm-analysis
|
|
115
|
+
|
|
116
|
+
# or scope the skill to a single repo:
|
|
117
|
+
mkdir -p .agents/skills
|
|
118
|
+
ln -sf ~/src/simdref/codex-skills/asm-analysis/skills/asm-analysis \
|
|
119
|
+
.agents/skills/asm-analysis
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
See
|
|
123
|
+
[`codex-skills/asm-analysis/skills/asm-analysis/SKILL.md`](codex-skills/asm-analysis/skills/asm-analysis/SKILL.md)
|
|
124
|
+
for the trigger list and pipeline stages.
|
|
125
|
+
|
|
57
126
|
## Install
|
|
58
127
|
|
|
59
128
|
```bash
|
|
@@ -63,6 +132,15 @@ isa doctor # confirm everything is wired up
|
|
|
63
132
|
isa # open the TUI
|
|
64
133
|
```
|
|
65
134
|
|
|
135
|
+
For the bleeding-edge version with the `simdref profile` subcommand
|
|
136
|
+
(runtime-profile → asm-annotation pipeline, Stage 2b of the skill),
|
|
137
|
+
install from `main`:
|
|
138
|
+
|
|
139
|
+
```bash
|
|
140
|
+
pipx install git+https://github.com/DiamonDinoia/simdref.git@main
|
|
141
|
+
# or editable: pip install -e git+https://github.com/DiamonDinoia/simdref.git@main#egg=simdref
|
|
142
|
+
```
|
|
143
|
+
|
|
66
144
|
The package installs two equivalent executables, **`isa`** (short) and
|
|
67
145
|
**`simdref`** (explicit). The rest of this README uses `isa`.
|
|
68
146
|
|
|
@@ -171,37 +249,42 @@ and `ld` still consume it.
|
|
|
171
249
|
|
|
172
250
|
**Commands**
|
|
173
251
|
|
|
174
|
-
| Command
|
|
175
|
-
|
|
176
|
-
| `isa`
|
|
177
|
-
| `isa
|
|
178
|
-
| `isa
|
|
179
|
-
| `isa
|
|
180
|
-
| `isa
|
|
181
|
-
| `isa
|
|
182
|
-
| `isa
|
|
183
|
-
| `isa
|
|
252
|
+
| Command | Description |
|
|
253
|
+
| ----------------------- | ----------------------------------------------------------------------------------------------------------------- |
|
|
254
|
+
| `isa` | Open the TUI |
|
|
255
|
+
| `isa <query>` | Open the TUI pre-filled with the query in a TTY; print ranked records to stdout otherwise |
|
|
256
|
+
| `isa doctor` | Check the installation — pass/fail per component, non-zero exit on failure |
|
|
257
|
+
| `isa update` | Download the pre-built release catalog (no `llvm-mca` required); `--from-release` for the GitHub Release artifact |
|
|
258
|
+
| `isa annotate <file.s>` | Annotate a `.s` assembly file with per-instruction summaries and latency/CPI — writes `<file>.sa` |
|
|
259
|
+
| `isa profile run` | Compile→record→disassemble→annotate→merge in one shot (perf or llvm-mca) |
|
|
260
|
+
| `isa profile ingest` | Convert profiler output (perf / VTune / uProf / xctrace / llvm-mca / exegesis) to normalized samples |
|
|
261
|
+
| `isa profile hotloops` | Detect natural loops in a disassembly and rank them by sample weight |
|
|
262
|
+
| `isa profile merge` | Attach hotness data to the annotated instruction stream |
|
|
263
|
+
| `isa llm query <q>` | Strict lookup → JSON/NDJSON/Markdown (see [docs/LLM.md](docs/LLM.md)) |
|
|
264
|
+
| `isa llm batch` | Resolve many queries from stdin in one invocation (NDJSON out) |
|
|
265
|
+
| `isa llm list` | Dump the `FilterSpec` or stream matching catalog entries |
|
|
266
|
+
| `isa llm schema` | Print the JSON schema for `llm` payloads |
|
|
184
267
|
|
|
185
268
|
**Dev commands**
|
|
186
269
|
|
|
187
|
-
| Command
|
|
188
|
-
|
|
189
|
-
| `isa build`
|
|
190
|
-
| `isa web`
|
|
191
|
-
| `isa serve`
|
|
192
|
-
| `isa completion install [SHELL]` | Install shell completion into the user's profile
|
|
193
|
-
| `isa completion show [SHELL]`
|
|
270
|
+
| Command | Description |
|
|
271
|
+
| -------------------------------- | ----------------------------------------------------------------------------------------------- |
|
|
272
|
+
| `isa build` | Full local rebuild from upstream sources, including Intel SDM parsing (`llvm-mca` 18+ required) |
|
|
273
|
+
| `isa web` | Export the static web app under `web/` |
|
|
274
|
+
| `isa serve` | Serve the exported web app locally (gzip-aware) |
|
|
275
|
+
| `isa completion install [SHELL]` | Install shell completion into the user's profile |
|
|
276
|
+
| `isa completion show [SHELL]` | Print the completion script for a shell |
|
|
194
277
|
|
|
195
278
|
## Data sources
|
|
196
279
|
|
|
197
|
-
| Source
|
|
198
|
-
|
|
199
|
-
| Intel Intrinsics Guide
|
|
200
|
-
| uops.info
|
|
201
|
-
| Arm ACLE (NEON/SVE)
|
|
202
|
-
| Arm AARCHMRS (A64)
|
|
203
|
-
| riscv-rvv-intrinsic-doc | RVV intrinsics with deterministic instruction refs
|
|
204
|
-
| RISC-V unified-db
|
|
280
|
+
| Source | What | Entries¹ |
|
|
281
|
+
| ----------------------- | ------------------------------------------------------ | ------------------- |
|
|
282
|
+
| Intel Intrinsics Guide | Signatures, descriptions, ISA, categories | 7,146 intrinsics |
|
|
283
|
+
| uops.info | Instructions, operands, latency, throughput, ports | 22,276 instructions |
|
|
284
|
+
| Arm ACLE (NEON/SVE) | Intrinsic signatures and descriptions | 10,791 intrinsics |
|
|
285
|
+
| Arm AARCHMRS (A64) | Base instruction forms and operand tables | live-only² |
|
|
286
|
+
| riscv-rvv-intrinsic-doc | RVV intrinsics with deterministic instruction refs | 74,319 intrinsics |
|
|
287
|
+
| RISC-V unified-db | RVV instruction forms, ISA tags, Description/Operation | 2,868 instructions |
|
|
205
288
|
|
|
206
289
|
¹ Counts from the current vendored snapshot. See
|
|
207
290
|
[`docs/coverage/summary.json`](docs/coverage/summary.json) for live
|
simdref-0.0.3/README.md
ADDED
|
@@ -0,0 +1,292 @@
|
|
|
1
|
+
# simdref
|
|
2
|
+
|
|
3
|
+
[](https://github.com/DiamonDinoia/simdref/actions/workflows/ci.yml)
|
|
4
|
+
[](https://test.pypi.org/project/simdref/)
|
|
5
|
+
[](https://pypi.org/project/simdref/)
|
|
6
|
+
|
|
7
|
+
A single searchable reference for SIMD intrinsics and instructions across
|
|
8
|
+
**x86 (Intel + uops.info)**, **Arm (ACLE / AARCHMRS)**, and **RISC-V
|
|
9
|
+
(RVV + unified-db)**. Runs as a CLI, a Textual TUI, an LSP server,
|
|
10
|
+
generated manpages, a static web app, and a structured JSON interface
|
|
11
|
+
for LLM skills.
|
|
12
|
+
|
|
13
|
+
[Web App](https://diamondinoia.github.io/simdref/) ·
|
|
14
|
+
[TestPyPI](https://test.pypi.org/project/simdref/) ·
|
|
15
|
+
[GitHub](https://github.com/DiamonDinoia/simdref) ·
|
|
16
|
+
[Contributing](CONTRIBUTING.md)
|
|
17
|
+
|
|
18
|
+
<!-- Screenshots are hosted on the `docs-assets` branch so the main
|
|
19
|
+
branch stays lightweight to clone. -->
|
|
20
|
+
|
|
21
|
+
<p align="center">
|
|
22
|
+
<img alt="simdref TUI" src="https://raw.githubusercontent.com/DiamonDinoia/simdref/docs-assets/img/tui.svg" width="720">
|
|
23
|
+
<br><em>Interactive TUI with ISA filters, ranked results, and measured/modeled performance tables.</em>
|
|
24
|
+
</p>
|
|
25
|
+
|
|
26
|
+
## Install the Claude Code skill
|
|
27
|
+
|
|
28
|
+
`skills/asm-analysis/` ships a Claude Code skill that drives the
|
|
29
|
+
compile → objdump → `simdref annotate` → `simdref profile` → LLM-batch
|
|
30
|
+
pipeline automatically. This repo publishes it as a Claude Code plugin,
|
|
31
|
+
so the one-liner install is:
|
|
32
|
+
|
|
33
|
+
```
|
|
34
|
+
/plugin marketplace add DiamonDinoia/simdref
|
|
35
|
+
/plugin install asm-analysis@simdref
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
Run those at the Claude Code prompt. The marketplace add fetches this
|
|
39
|
+
repo; the install wires up the skill so Claude picks it up automatically
|
|
40
|
+
on performance-oriented prompts like *"why is this loop slow"*,
|
|
41
|
+
*"vectorise this"*, *"look at the asm"*.
|
|
42
|
+
|
|
43
|
+
### Manual install (no marketplace)
|
|
44
|
+
|
|
45
|
+
If you prefer a hand-managed copy:
|
|
46
|
+
|
|
47
|
+
```bash
|
|
48
|
+
# symlink from a checkout — always current with main:
|
|
49
|
+
git clone https://github.com/DiamonDinoia/simdref.git ~/src/simdref
|
|
50
|
+
mkdir -p ~/.claude/skills
|
|
51
|
+
ln -sf ~/src/simdref/skills/asm-analysis ~/.claude/skills/asm-analysis
|
|
52
|
+
|
|
53
|
+
# or pull a one-off snapshot:
|
|
54
|
+
mkdir -p ~/.claude/skills/asm-analysis && \
|
|
55
|
+
curl -fsSL https://raw.githubusercontent.com/DiamonDinoia/simdref/main/skills/asm-analysis/SKILL.md \
|
|
56
|
+
-o ~/.claude/skills/asm-analysis/SKILL.md
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
See [`skills/asm-analysis/SKILL.md`](skills/asm-analysis/SKILL.md) for
|
|
60
|
+
the full trigger list and pipeline stages.
|
|
61
|
+
|
|
62
|
+
## Install the Codex skill
|
|
63
|
+
|
|
64
|
+
This repo also ships the same pipeline as an OpenAI Codex plugin, so
|
|
65
|
+
the one-liner install from a Codex CLI prompt is:
|
|
66
|
+
|
|
67
|
+
```
|
|
68
|
+
codex plugin marketplace add DiamonDinoia/simdref
|
|
69
|
+
/plugins
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
Pick `asm-analysis` in the browser and enable it. Codex picks up the
|
|
73
|
+
skill automatically on performance-oriented prompts (*"why is this
|
|
74
|
+
loop slow"*, *"vectorise this"*, *"look at the asm"*).
|
|
75
|
+
|
|
76
|
+
### Manual install (no marketplace)
|
|
77
|
+
|
|
78
|
+
```bash
|
|
79
|
+
# user-scoped symlink — applies to every repo, always current with main:
|
|
80
|
+
git clone https://github.com/DiamonDinoia/simdref.git ~/src/simdref
|
|
81
|
+
mkdir -p ~/.agents/skills
|
|
82
|
+
ln -sf ~/src/simdref/codex-skills/asm-analysis/skills/asm-analysis \
|
|
83
|
+
~/.agents/skills/asm-analysis
|
|
84
|
+
|
|
85
|
+
# or scope the skill to a single repo:
|
|
86
|
+
mkdir -p .agents/skills
|
|
87
|
+
ln -sf ~/src/simdref/codex-skills/asm-analysis/skills/asm-analysis \
|
|
88
|
+
.agents/skills/asm-analysis
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
See
|
|
92
|
+
[`codex-skills/asm-analysis/skills/asm-analysis/SKILL.md`](codex-skills/asm-analysis/skills/asm-analysis/SKILL.md)
|
|
93
|
+
for the trigger list and pipeline stages.
|
|
94
|
+
|
|
95
|
+
## Install
|
|
96
|
+
|
|
97
|
+
```bash
|
|
98
|
+
pip install simdref
|
|
99
|
+
isa update # download the pre-built catalog
|
|
100
|
+
isa doctor # confirm everything is wired up
|
|
101
|
+
isa # open the TUI
|
|
102
|
+
```
|
|
103
|
+
|
|
104
|
+
For the bleeding-edge version with the `simdref profile` subcommand
|
|
105
|
+
(runtime-profile → asm-annotation pipeline, Stage 2b of the skill),
|
|
106
|
+
install from `main`:
|
|
107
|
+
|
|
108
|
+
```bash
|
|
109
|
+
pipx install git+https://github.com/DiamonDinoia/simdref.git@main
|
|
110
|
+
# or editable: pip install -e git+https://github.com/DiamonDinoia/simdref.git@main#egg=simdref
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
The package installs two equivalent executables, **`isa`** (short) and
|
|
114
|
+
**`simdref`** (explicit). The rest of this README uses `isa`.
|
|
115
|
+
|
|
116
|
+
`isa update` pulls the combined catalog (x86 measured + Arm/RISC-V
|
|
117
|
+
measured & modeled) from the latest GitHub Release — **no `llvm-mca`
|
|
118
|
+
required**. Only contributors doing a full local rebuild with
|
|
119
|
+
`isa build` need `llvm-mca` 18+ on `PATH`.
|
|
120
|
+
|
|
121
|
+
Pre-release builds live on TestPyPI:
|
|
122
|
+
|
|
123
|
+
```bash
|
|
124
|
+
pip install -i https://test.pypi.org/simple/ \
|
|
125
|
+
--extra-index-url https://pypi.org/simple/ simdref
|
|
126
|
+
```
|
|
127
|
+
|
|
128
|
+
## Quickstart
|
|
129
|
+
|
|
130
|
+
```bash
|
|
131
|
+
isa _mm_add_ps # exact intrinsic -> detailed view
|
|
132
|
+
isa VPADDD # exact instruction -> detailed view
|
|
133
|
+
isa _mm_add # fuzzy -> ranked search results
|
|
134
|
+
isa mm add # tokenized query -> intrinsic-biased search
|
|
135
|
+
isa ADD # mnemonic-like -> instruction-biased search
|
|
136
|
+
isa VADDPS 2 # pick variant #2 from the last result list
|
|
137
|
+
isa # open the interactive TUI
|
|
138
|
+
```
|
|
139
|
+
|
|
140
|
+
## Interfaces
|
|
141
|
+
|
|
142
|
+
**Web app** — a self-contained static SPA with filters and performance
|
|
143
|
+
tables, published to GitHub Pages at
|
|
144
|
+
[diamondinoia.github.io/simdref](https://diamondinoia.github.io/simdref/).
|
|
145
|
+
Export your own copy:
|
|
146
|
+
|
|
147
|
+
```bash
|
|
148
|
+
isa web --web-dir ./web
|
|
149
|
+
isa serve --web-dir ./web # gzip-aware local server
|
|
150
|
+
```
|
|
151
|
+
|
|
152
|
+
The [live demo](https://diamondinoia.github.io/simdref/) hosts the same
|
|
153
|
+
build — search across ~122k entries with ISA filters and per-uarch perf
|
|
154
|
+
tables.
|
|
155
|
+
|
|
156
|
+
**LSP** — hover docs + completion for intrinsic names and instruction
|
|
157
|
+
mnemonics in any LSP-capable editor:
|
|
158
|
+
|
|
159
|
+
```bash
|
|
160
|
+
simdref-lsp # speaks JSON-RPC over stdio
|
|
161
|
+
```
|
|
162
|
+
|
|
163
|
+
```lua
|
|
164
|
+
-- Neovim
|
|
165
|
+
vim.lsp.start({ name = "simdref", cmd = { ".venv/bin/simdref-lsp" } })
|
|
166
|
+
```
|
|
167
|
+
|
|
168
|
+
**LLM interface** — stable JSON / NDJSON for agents and editor skills,
|
|
169
|
+
with meaningful exit codes so tools can distinguish *no match* (2),
|
|
170
|
+
*ambiguous* (3), and *bad flag* (1):
|
|
171
|
+
|
|
172
|
+
```bash
|
|
173
|
+
isa llm query _mm_add_ps --source-kind measured
|
|
174
|
+
echo -e "_mm_add_ps\nVPADDD" | isa llm batch
|
|
175
|
+
isa llm list --pattern "*gather*" --isa Intel
|
|
176
|
+
```
|
|
177
|
+
|
|
178
|
+
See [docs/LLM.md](docs/LLM.md) for the full payload shape and a
|
|
179
|
+
Claude-skill recipe.
|
|
180
|
+
|
|
181
|
+
**Assembly annotator** — turn compiler output into a self-documented
|
|
182
|
+
`.sa` file. Given `hello_simd.s`:
|
|
183
|
+
|
|
184
|
+
```asm
|
|
185
|
+
dot8:
|
|
186
|
+
vmovups (%rdi), %ymm0
|
|
187
|
+
vmovups (%rsi), %ymm1
|
|
188
|
+
vmulps %ymm1, %ymm0, %ymm0
|
|
189
|
+
vaddps %ymm0, %ymm0, %ymm0
|
|
190
|
+
vhaddps %ymm0, %ymm0, %ymm0
|
|
191
|
+
ret
|
|
192
|
+
```
|
|
193
|
+
|
|
194
|
+
```bash
|
|
195
|
+
isa annotate hello_simd.s # writes hello_simd.sa
|
|
196
|
+
isa annotate hello_simd.s --arch skylake-x -o - # to stdout, skylake-x only
|
|
197
|
+
```
|
|
198
|
+
|
|
199
|
+
produces:
|
|
200
|
+
|
|
201
|
+
```asm
|
|
202
|
+
dot8:
|
|
203
|
+
vmovups (%rdi), %ymm0 # Move Unaligned Packed Single Precision FP Values. | lat=10.3c cpi=0.78 [avg of 25 archs, measured]
|
|
204
|
+
vmovups (%rsi), %ymm1 # Move Unaligned Packed Single Precision FP Values. | lat=10.3c cpi=0.78 [avg of 25 archs, measured]
|
|
205
|
+
vmulps %ymm1, %ymm0, %ymm0 # Multiply Packed Single Precision FP Values. | lat=3.8c cpi=0.54 [avg of 25 archs, measured]
|
|
206
|
+
vaddps %ymm0, %ymm0, %ymm0 # Add Packed Single Precision FP Values. | lat=3.1c cpi=0.58 [avg of 25 archs, measured]
|
|
207
|
+
vhaddps %ymm0, %ymm0, %ymm0 # Horizontal Add Packed Single Precision FP. | lat=5.6c cpi=2.22 [avg of 25 archs, measured]
|
|
208
|
+
ret
|
|
209
|
+
```
|
|
210
|
+
|
|
211
|
+
The output is still valid assembly — comments start with `#`, so `as`
|
|
212
|
+
and `ld` still consume it.
|
|
213
|
+
|
|
214
|
+
## Commands
|
|
215
|
+
|
|
216
|
+
`isa --help` groups commands into **Commands** (day-to-day) and
|
|
217
|
+
**Dev commands** (rebuild / export / completion).
|
|
218
|
+
|
|
219
|
+
**Commands**
|
|
220
|
+
|
|
221
|
+
| Command | Description |
|
|
222
|
+
| ----------------------- | ----------------------------------------------------------------------------------------------------------------- |
|
|
223
|
+
| `isa` | Open the TUI |
|
|
224
|
+
| `isa <query>` | Open the TUI pre-filled with the query in a TTY; print ranked records to stdout otherwise |
|
|
225
|
+
| `isa doctor` | Check the installation — pass/fail per component, non-zero exit on failure |
|
|
226
|
+
| `isa update` | Download the pre-built release catalog (no `llvm-mca` required); `--from-release` for the GitHub Release artifact |
|
|
227
|
+
| `isa annotate <file.s>` | Annotate a `.s` assembly file with per-instruction summaries and latency/CPI — writes `<file>.sa` |
|
|
228
|
+
| `isa profile run` | Compile→record→disassemble→annotate→merge in one shot (perf or llvm-mca) |
|
|
229
|
+
| `isa profile ingest` | Convert profiler output (perf / VTune / uProf / xctrace / llvm-mca / exegesis) to normalized samples |
|
|
230
|
+
| `isa profile hotloops` | Detect natural loops in a disassembly and rank them by sample weight |
|
|
231
|
+
| `isa profile merge` | Attach hotness data to the annotated instruction stream |
|
|
232
|
+
| `isa llm query <q>` | Strict lookup → JSON/NDJSON/Markdown (see [docs/LLM.md](docs/LLM.md)) |
|
|
233
|
+
| `isa llm batch` | Resolve many queries from stdin in one invocation (NDJSON out) |
|
|
234
|
+
| `isa llm list` | Dump the `FilterSpec` or stream matching catalog entries |
|
|
235
|
+
| `isa llm schema` | Print the JSON schema for `llm` payloads |
|
|
236
|
+
|
|
237
|
+
**Dev commands**
|
|
238
|
+
|
|
239
|
+
| Command | Description |
|
|
240
|
+
| -------------------------------- | ----------------------------------------------------------------------------------------------- |
|
|
241
|
+
| `isa build` | Full local rebuild from upstream sources, including Intel SDM parsing (`llvm-mca` 18+ required) |
|
|
242
|
+
| `isa web` | Export the static web app under `web/` |
|
|
243
|
+
| `isa serve` | Serve the exported web app locally (gzip-aware) |
|
|
244
|
+
| `isa completion install [SHELL]` | Install shell completion into the user's profile |
|
|
245
|
+
| `isa completion show [SHELL]` | Print the completion script for a shell |
|
|
246
|
+
|
|
247
|
+
## Data sources
|
|
248
|
+
|
|
249
|
+
| Source | What | Entries¹ |
|
|
250
|
+
| ----------------------- | ------------------------------------------------------ | ------------------- |
|
|
251
|
+
| Intel Intrinsics Guide | Signatures, descriptions, ISA, categories | 7,146 intrinsics |
|
|
252
|
+
| uops.info | Instructions, operands, latency, throughput, ports | 22,276 instructions |
|
|
253
|
+
| Arm ACLE (NEON/SVE) | Intrinsic signatures and descriptions | 10,791 intrinsics |
|
|
254
|
+
| Arm AARCHMRS (A64) | Base instruction forms and operand tables | live-only² |
|
|
255
|
+
| riscv-rvv-intrinsic-doc | RVV intrinsics with deterministic instruction refs | 74,319 intrinsics |
|
|
256
|
+
| RISC-V unified-db | RVV instruction forms, ISA tags, Description/Operation | 2,868 instructions |
|
|
257
|
+
|
|
258
|
+
¹ Counts from the current vendored snapshot. See
|
|
259
|
+
[`docs/coverage/summary.json`](docs/coverage/summary.json) for live
|
|
260
|
+
parity against upstream and [`docs/SOURCES.md`](docs/SOURCES.md) for
|
|
261
|
+
licenses and refresh cadence.
|
|
262
|
+
|
|
263
|
+
² The full AARCHMRS A64 spec is only available via live fetch or by
|
|
264
|
+
dropping the tarball under `vendor/arm/`.
|
|
265
|
+
|
|
266
|
+
Every rendered latency / CPI is tagged `(measured, <core>)` or
|
|
267
|
+
`(modeled, <core>)` so measured and modeled numbers never get silently
|
|
268
|
+
mixed.
|
|
269
|
+
|
|
270
|
+
### Scope caveats
|
|
271
|
+
|
|
272
|
+
- Performance data is x86-only in v1.
|
|
273
|
+
- RISC-V coverage is RVV-focused — not full scalar or privileged ISA.
|
|
274
|
+
|
|
275
|
+
## Development
|
|
276
|
+
|
|
277
|
+
```bash
|
|
278
|
+
git clone https://github.com/DiamonDinoia/simdref.git
|
|
279
|
+
cd simdref
|
|
280
|
+
python3 -m venv .venv
|
|
281
|
+
.venv/bin/pip install -e .
|
|
282
|
+
.venv/bin/isa build # requires llvm-mca 18+
|
|
283
|
+
.venv/bin/python -m pytest tests/ -v
|
|
284
|
+
```
|
|
285
|
+
|
|
286
|
+
See [CONTRIBUTING.md](CONTRIBUTING.md) for the full dev flow
|
|
287
|
+
(tests, adding a new source, build stages) and
|
|
288
|
+
[ARCHITECTURE.md](ARCHITECTURE.md) for module layout.
|
|
289
|
+
|
|
290
|
+
## License
|
|
291
|
+
|
|
292
|
+
[GNU General Public License v3.0](LICENSE).
|
|
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
|
|
|
4
4
|
|
|
5
5
|
[project]
|
|
6
6
|
name = "simdref"
|
|
7
|
-
version = "0.0.
|
|
7
|
+
version = "0.0.3"
|
|
8
8
|
description = "Searchable SIMD intrinsic and instruction reference with CLI, manpages, TUI, LSP, and static web export."
|
|
9
9
|
readme = "README.md"
|
|
10
10
|
requires-python = ">=3.11"
|
|
@@ -51,3 +51,7 @@ where = ["src"]
|
|
|
51
51
|
|
|
52
52
|
[tool.setuptools.package-data]
|
|
53
53
|
simdref = ["templates/*"]
|
|
54
|
+
|
|
55
|
+
[tool.ruff]
|
|
56
|
+
line-length = 100
|
|
57
|
+
target-version = "py311"
|