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, on-demand manpages (simdref man — or run simdref install-manpages so plain man vpaddd works), a JSON site-data export for simdref-web, 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 and Codex skill

The asm-analysis skill for Claude Code and OpenAI Codex lives in simd-labs/simdref-skill. Follow the install steps in that repo.

Install

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

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 simdref.diamondinoia.com and built from the simdref-web repo. This repo exports the JSON data it consumes:

isa export --out-dir ./site-data

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

Dev commands

Data sources

¹ 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/simd-labs/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.