simdref

simdref is a SIMD intrinsic and instruction reference for x86 (Intel + uops.info), Arm (ACLE, AARCHMRS), and RISC-V (RVV + unified-db). It runs as a CLI, a TUI, an LSP server, and an on-demand manpage renderer.

Web app · TestPyPI · GitHub · Contributing

Install the Claude Code and Codex skill

The asm-analysis skill 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     # check the install
isa            # open the TUI

The package installs two equivalent executables, isa and simdref. The catalog download does not use llvm-mca. Only isa build uses 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 TUI

Interfaces

The web app at simdref.diamondinoia.com reads the JSON site data this repo exports:

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

The LSP server speaks JSON-RPC on stdio:

simdref-lsp

Editor clients, one for each editor:

• Zed: zed-asm-intrinsics
• VS Code: vscode-simdref
• JetBrains: jetbrains-simdref
• Neovim: nvim-simdref

Each client shows a one-line brief at the end of each instruction line and the full manpage on hover, from the local catalog.

The LLM interface writes JSON and NDJSON with exit codes 0 (match), 1 (bad flag), 2 (no match), 3 (ambiguous):

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 payload shape.

The annotator turns compiler .s output into an annotated .sa file.

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

The annotator adds a trailing comment with the summary, latency, and CPI to each instruction line. The output stays valid assembly.

Commands

isa --help groups commands into Commands and Dev commands.

Commands

Dev commands

Data sources

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

² The full AARCHMRS A64 spec needs a live fetch or a tarball under vendor/arm/.

Each perf row carries a (measured, <core>) or (modeled, <core>) tag.

Scope

• Performance data is x86-only.
• RISC-V coverage is RVV only, not 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          # needs llvm-mca 18+
.venv/bin/python -m pytest tests/ -v

See CONTRIBUTING.md and ARCHITECTURE.md.

License

GNU General Public License v3.0.