simdref 0.0.4

Searchable SIMD intrinsic and instruction reference with CLI, manpages, TUI, LSP, and static web export.

simdref

A single searchable reference for SIMD intrinsics and instructions across x86 (Intel + uops.info), Arm (ACLE / AARCHMRS), and RISC-V (RVV + unified-db). Runs as a CLI, a Textual TUI, an LSP server, generated manpages, a static web app, and a structured JSON interface for LLM skills.

Web App · TestPyPI · GitHub · Contributing

Interactive TUI with ISA filters, ranked results, and measured/modeled performance tables.

Install the Claude Code skill

skills/asm-analysis/ ships a Claude Code skill that drives the compile → objdump → simdref annotate → simdref profile → LLM-batch pipeline automatically. This repo publishes it as a Claude Code plugin, so the one-liner install is:

/plugin marketplace add DiamonDinoia/simdref
/plugin install asm-analysis@simdref

Run those at the Claude Code prompt. The marketplace add fetches this repo; the install wires up the skill so Claude picks it up automatically on performance-oriented prompts like "why is this loop slow", "vectorise this", "look at the asm".

Manual install (no marketplace)

If you prefer a hand-managed copy:

# symlink from a checkout — always current with main:
git clone https://github.com/DiamonDinoia/simdref.git ~/src/simdref
mkdir -p ~/.claude/skills
ln -sf ~/src/simdref/skills/asm-analysis ~/.claude/skills/asm-analysis

# or pull a one-off snapshot:
mkdir -p ~/.claude/skills/asm-analysis && \
  curl -fsSL https://raw.githubusercontent.com/DiamonDinoia/simdref/main/skills/asm-analysis/SKILL.md \
  -o ~/.claude/skills/asm-analysis/SKILL.md

See skills/asm-analysis/SKILL.md for the full trigger list and pipeline stages.

Install the Codex skill

This repo also ships the same pipeline as an OpenAI Codex plugin, so the one-liner install from a Codex CLI prompt is:

codex plugin marketplace add DiamonDinoia/simdref
/plugins

Pick asm-analysis in the browser and enable it. Codex picks up the skill automatically on performance-oriented prompts ("why is this loop slow", "vectorise this", "look at the asm").

Manual install (no marketplace)

# user-scoped symlink — applies to every repo, always current with main:
git clone https://github.com/DiamonDinoia/simdref.git ~/src/simdref
mkdir -p ~/.agents/skills
ln -sf ~/src/simdref/codex-skills/asm-analysis/skills/asm-analysis \
       ~/.agents/skills/asm-analysis

# or scope the skill to a single repo:
mkdir -p .agents/skills
ln -sf ~/src/simdref/codex-skills/asm-analysis/skills/asm-analysis \
       .agents/skills/asm-analysis

See codex-skills/asm-analysis/skills/asm-analysis/SKILL.md for the trigger list and pipeline stages.

Install

pip install simdref
isa update     # download the pre-built catalog
isa doctor     # confirm everything is wired up
isa            # open the TUI

For the bleeding-edge version with the simdref profile subcommand (runtime-profile → asm-annotation pipeline, Stage 2b of the skill), install from main:

pipx install git+https://github.com/DiamonDinoia/simdref.git@main
# or editable: pip install -e git+https://github.com/DiamonDinoia/simdref.git@main#egg=simdref

The package installs two equivalent executables, isa (short) and simdref (explicit). The rest of this README uses isa.

isa update pulls the combined catalog (x86 measured + Arm/RISC-V measured & modeled) from the latest GitHub Release — no llvm-mca required. Only contributors doing a full local rebuild with isa build need llvm-mca 18+ on PATH.

Pre-release builds live on TestPyPI:

pip install -i https://test.pypi.org/simple/ \
            --extra-index-url https://pypi.org/simple/ simdref

Quickstart

isa _mm_add_ps       # exact intrinsic  -> detailed view
isa VPADDD           # exact instruction -> detailed view
isa _mm_add          # fuzzy -> ranked search results
isa mm add           # tokenized query -> intrinsic-biased search
isa ADD              # mnemonic-like -> instruction-biased search
isa VADDPS 2         # pick variant #2 from the last result list
isa                  # open the interactive TUI

Interfaces

Web app — a self-contained static SPA with filters and performance tables, published to GitHub Pages at diamondinoia.github.io/simdref. Export your own copy:

isa web --web-dir ./web
isa serve --web-dir ./web       # gzip-aware local server

The live demo hosts the same build — search across ~122k entries with ISA filters and per-uarch perf tables.

LSP — hover docs + completion for intrinsic names and instruction mnemonics in any LSP-capable editor:

simdref-lsp                      # speaks JSON-RPC over stdio

-- Neovim
vim.lsp.start({ name = "simdref", cmd = { ".venv/bin/simdref-lsp" } })

LLM interface — stable JSON / NDJSON for agents and editor skills, with meaningful exit codes so tools can distinguish no match (2), ambiguous (3), and bad flag (1):

isa llm query _mm_add_ps --source-kind measured
echo -e "_mm_add_ps\nVPADDD" | isa llm batch
isa llm list --pattern "*gather*" --isa Intel

See docs/LLM.md for the full payload shape and a Claude-skill recipe.

Assembly annotator — turn compiler output into a self-documented .sa file. Given hello_simd.s:

dot8:
    vmovups (%rdi), %ymm0
    vmovups (%rsi), %ymm1
    vmulps  %ymm1, %ymm0, %ymm0
    vaddps  %ymm0, %ymm0, %ymm0
    vhaddps %ymm0, %ymm0, %ymm0
    ret

isa annotate hello_simd.s           # writes hello_simd.sa
isa annotate hello_simd.s --arch skylake-x -o -   # to stdout, skylake-x only

produces:

dot8:
    vmovups (%rdi), %ymm0   # Move Unaligned Packed Single Precision FP Values. | lat=10.3c cpi=0.78 [avg of 25 archs, measured]
    vmovups (%rsi), %ymm1   # Move Unaligned Packed Single Precision FP Values. | lat=10.3c cpi=0.78 [avg of 25 archs, measured]
    vmulps  %ymm1, %ymm0, %ymm0   # Multiply Packed Single Precision FP Values. | lat=3.8c cpi=0.54 [avg of 25 archs, measured]
    vaddps  %ymm0, %ymm0, %ymm0   # Add Packed Single Precision FP Values.      | lat=3.1c cpi=0.58 [avg of 25 archs, measured]
    vhaddps %ymm0, %ymm0, %ymm0   # Horizontal Add Packed Single Precision FP.  | lat=5.6c cpi=2.22 [avg of 25 archs, measured]
    ret

The output is still valid assembly — comments start with #, so as and ld still consume it.

Commands

isa --help groups commands into Commands (day-to-day) and Dev commands (rebuild / export / completion).

Commands

Command	Description
isa	Open the TUI
isa <query>	Open the TUI pre-filled with the query in a TTY; print ranked records to stdout otherwise
isa doctor	Check the installation — pass/fail per component, non-zero exit on failure
isa update	Download the pre-built release catalog (no llvm-mca required); --from-release for the GitHub Release artifact
isa annotate <file.s>	Annotate a .s assembly file with per-instruction summaries and latency/CPI — writes <file>.sa
isa profile run	Compile→record→disassemble→annotate→merge in one shot (perf or llvm-mca)
isa profile ingest	Convert profiler output (perf / VTune / uProf / xctrace / llvm-mca / exegesis) to normalized samples
isa profile hotloops	Detect natural loops in a disassembly and rank them by sample weight
isa profile merge	Attach hotness data to the annotated instruction stream
isa llm query <q>	Strict lookup → JSON/NDJSON/Markdown (see docs/LLM.md)
isa llm batch	Resolve many queries from stdin in one invocation (NDJSON out)
isa llm list	Dump the FilterSpec or stream matching catalog entries
isa llm schema	Print the JSON schema for llm payloads

Dev commands

Command	Description
isa build	Full local rebuild from upstream sources, including Intel SDM parsing (llvm-mca 18+ required)
isa web	Export the static web app under web/
isa serve	Serve the exported web app locally (gzip-aware)
isa completion install [SHELL]	Install shell completion into the user's profile
isa completion show [SHELL]	Print the completion script for a shell

Data sources

Source	What	Entries¹
Intel Intrinsics Guide	Signatures, descriptions, ISA, categories	7,146 intrinsics
uops.info	Instructions, operands, latency, throughput, ports	22,276 instructions
Arm ACLE (NEON/SVE)	Intrinsic signatures and descriptions	10,791 intrinsics
Arm AARCHMRS (A64)	Base instruction forms and operand tables	live-only²
riscv-rvv-intrinsic-doc	RVV intrinsics with deterministic instruction refs	74,319 intrinsics
RISC-V unified-db	RVV instruction forms, ISA tags, Description/Operation	2,868 instructions

¹ Counts from the current vendored snapshot. See docs/coverage/summary.json for live parity against upstream and docs/SOURCES.md for licenses and refresh cadence.

² The full AARCHMRS A64 spec is only available via live fetch or by dropping the tarball under vendor/arm/.

Every rendered latency / CPI is tagged (measured, <core>) or (modeled, <core>) so measured and modeled numbers never get silently mixed.

Scope caveats

• Performance data is x86-only in v1.
• RISC-V coverage is RVV-focused — not full scalar or privileged ISA.

Development

git clone https://github.com/DiamonDinoia/simdref.git
cd simdref
python3 -m venv .venv
.venv/bin/pip install -e .
.venv/bin/isa build          # requires llvm-mca 18+
.venv/bin/python -m pytest tests/ -v

See CONTRIBUTING.md for the full dev flow (tests, adding a new source, build stages) and ARCHITECTURE.md for module layout.

License

GNU General Public License v3.0.