A language server for GNU as (GAS) x86 assembly in AT&T syntax. Written for
the cpp-preprocessed .S files in airies-boot (falcon-bios real mode,
protected mode and long mode code), but it knows nothing project-specific and
works on any GAS x86 source.
What it does:
- Hover on mnemonics, registers, directives, prefixes, labels and numbers.
Short and to the point: summary, operand forms, ISA set and x86-64 level
(
x86-64-v3 (BMI2)), privilege (CPL 0), mode restrictions (64-bit only) and flags read/written. AT&T size suffixes resolve (movw=mov+w) without mis-splitting real mnemonics (setb,movsb,cwtl). A#defined constant shows its definition and, when it is a constant expression over numbers and other macros, its value in hex and decimal (SEL_CODE32->0x8), plus the header it comes from. - Semantic highlighting: mnemonic vs. size suffix, prefixes, registers,
immediates, label definitions and references, directives, cpp directives
and macros (including those from included headers, once the toolchain has
run). Privileged (CPL 0) instructions carry the
defaultLibrarymodifier; instructions and registers invalid in the current.code16/32/64mode carrydeprecated. - Diagnostics: instructions and registers invalid in the current mode,
instruction forms above a target x86-64 level (
-march=x86-64-v3, afalcon-asm: level=v3comment, or the editor setting), and the real assembler's errors and warnings from the project's own compiler, run on open and save in the background. Errors inside included files are reported on those files too.#if 0bodies are faded. - Listing hints: after each instruction or data line, its offset in the
section and its encoded bytes (
+0x1a3 b8 01 24); on.organd. = exprlines, how many bytes the move pads (pads 70 bytes), which is the space left in a boot sector at. = _start + 510. - Navigation: go to definition, find references and rename for labels,
.set/.equsymbols,.macroand#definenames, across open files, their#includes and the.S/.sfiles of the workspace; local1f/1blabels resolve the way gas does. Outline and folding ranges. - Completion: registers valid in the current mode after
%, directives after., mnemonics and prefixes at statement start, labels and macros in operands. - Inline asm in C/C++: hover inside
asmstatements (instructions and registers in the template,%0/%[name]operands, constraints such as"=r", clobbers) and mode/level diagnostics using the C file's own compile flags. Everything else in C files is left to clangd. - Full coverage of the system instructions a boot loader lives on (
lgdt,ljmp,iret,inb/outb,rdmsr,rep movsb, ...), which general purpose x86 tooling tends to miss.
The toolchain features read compile_commands.json (at the workspace root,
in build/, or found walking up from the file) for each file's compiler and
flags. Without a database, or without the compiler installed, they are
silently off and everything else still works.
It is a single static binary with no runtime dependencies and speaks LSP over
stdio, so any LSP client can drive it. A thin VS Code client lives in
editors/vscode.
Requires Go (see go.mod for the version). The module is stdlib-only.
make # build/bin/falcon-asm
make test # go test -race ./...
make coverage # coverage profile + 80% statement gate
make analyze # go vet, gofmt check, golangci-lint if installed
make check # ascii-check over the tree
make bench # Go microbenchmarks into build/bench/bench.txt
make lspbench # end-to-end LSP benchmark into build/bench/lspbench.{txt,json}
make rules-doc # regenerate docs/RULES.md from the rule registry (a test checks it)
make install # installs falcon-asm into ~/.local/bin (PREFIX=... to change)make VARIANT=debug builds without stripping or -trimpath. The version
string is release_version plus build stamp and variant, e.g.
0.1.0_20261003.0518.release; falcon-asm --version prints it.
make lspbench starts the built server and drives it over stdio the way an
editor does (tools/lspbench): the falcon-bios fixtures, typing into 20k-
and 100k-line files, a 500-file workspace and process cold start, with
per-request p50/p95/p99/max and peak memory; the linter's paths
(edit-to-diagnostics latency, code actions, code lenses, register hints,
hardware hovers and their length, workspace symbols, the call hierarchy);
and falcon-asm lint wall time and peak memory. -root adds a real
project with the toolchain on; -json and -compare old.json new.json
track changes. make bench runs the Go microbenchmarks. The method,
scenarios, the before and after numbers of the performance pass and of the
linter pass, and the remaining hot spots are in
docs/BENCHMARKS.md.
The same binary lints without an editor, for CI and pre-commit hooks:
falcon-asm lint # everything under ., gcc-style output
falcon-asm lint --format sarif src # SARIF 2.1.0 for code scanning
falcon-asm lint --fix # apply quick fixes in place
falcon-asm lint --changed # only files changed against git HEAD
falcon-asm lint --no-toolchain # rules only, no assembler runs
falcon-asm rules [code] # the rule list, or one rule's documentation
falcon-asm help [lint|rules] # every mode and flag, with examplesThe assembler runs by default. Some rules (alignment, size budgets, boot
layout, branch encoding) need gas's listing, so each assembly file with a
compile_commands.json entry (its own, else the nearest one, as in the
editor) is assembled with that entry's compiler, which also reports gas's
own diagnostics. A file with no entry, a compiler that is not installed, a
file that fails to assemble, or --no-toolchain leaves those rules
unable to run. The run then says so instead of reading clean:
note: 12 listing rules skipped on 1 file (no assembler listing: 1 without a compile command): boot/mbr.S; give them a compile_commands.json entry (--compile-commands); see falcon-asm lint --help
40 files linted, no problems (12 listing rules skipped on 1 file)
--format json stays a plain array of findings; --format json-full
wraps it as {"findings", "skipped", "files"}, and SARIF output reports
each skipped file as a tool execution notification
(listing-rules-skipped). Skipped rules never change the exit status.
--toolchain is still accepted and is the default.
Exit status is 0 when nothing at or above --severity (default warning)
was found, 1 when something was, 2 on a usage or configuration error. Rules
are configured per project and per path in .falcon-asm.json and silenced
in the source with falcon-asm: ignore=<code> comments; the editor and the
CLI read the same file and report the same findings. Every rule is
documented, with examples, in docs/RULES.md.
Suppression comments work in any comment (/* */, #, //; in C,
// and /* */ silence inline asm findings). Each takes one code or a
comma-separated list, all for every rule, and an optional reason after
a colon:
loop 1b /* falcon-asm: ignore=slow-loop: 32 passes, once, at boot */
/* falcon-asm: ignore-next=self-modifying-code: patched before paging is on */
/* falcon-asm: ignore-file=unused-define: shared header, users are elsewhere */
/* falcon-asm: ignore-begin=unused-label: a table walked by offset */
...
/* falcon-asm: ignore-end=unused-label */ignore= covers findings starting on its own line, ignore-next= the
next line holding code, ignore-file= the whole file, and
ignore-begin=/ignore-end= the lines between them, inclusive. The
marker and the item must be on one line. unused-suppression reports a
suppression that no longer matches anything; ignore-without-reason,
off by default, reports one without a reason once a project enables it
("rules": {"ignore-without-reason": "info"}).
Some findings are better answered with an annotation than an ignore:
falcon-asm: reached=offset|sequence|external on (or directly above) a
label tells unused-label it is entered by offset, walked in sequence
from an earlier label, or entered from outside the sources, and a label
directly after .org <constant> is presumed reachable on its own.
Calling-convention annotations (falcon-asm: args=si clobbers=ax,cx preserves=all) imply cc=custom when the lists are given.
{
"rules": { "level-outside": "off", "mode-register": "error" },
"overrides": [ { "paths": ["legacy/**"], "target": { "mode": 16 } } ],
"target": { "level": "v3" }
}The server must be on PATH (make install) or configured by absolute path.
make vscode # npm ci, tests, packages editors/vscode/falcon-asm-*.vsix
code --install-extension editors/vscode/falcon-asm-*.vsixThe extension registers the falcon-asm language for .S and .s files.
If another assembly extension also claims those extensions, pin the
association in settings:
"files.associations": { "*.S": "falcon-asm", "*.s": "falcon-asm" }Settings: falcon-asm.serverPath (default falcon-asm, resolved via PATH),
falcon-asm.toolchain.enabled (run the compiler on open/save),
falcon-asm.inlayHints.listing (offset/bytes hints),
falcon-asm.inlayHints.registers (tracked register values, off by default), falcon-asm.level
(target level override, v1..v4), falcon-asm.compileCommands (explicit
database path), falcon-asm.inlineAsm.enabled (serve C/C++ files for inline
asm) and falcon-asm.trace.server (off, messages, verbose). Changing
any but the last restarts the server. Command: falcon-asm: Restart Server.
See editors/vscode/README.md.
The server reads its options once, from initializationOptions. Every key
is optional:
{ "toolchain": true, "listingHints": true, "registerHints": false, "level": "", "compileCommands": "" }level is "" (use the file comment or -march) or v1..v4;
compileCommands is a path to a compile_commands.json (or a directory
holding one), relative paths resolving against the workspace root.
Semantic tokens are registered with a document selector for the
falcon-asm language id only, so C files keep their own highlighting. A
client that honours static registration selectors must therefore open
assembly files with that language id (the CLion mapping below does); one
that ignores them gets tokens for any assembly file, and an empty stream for
C files.
Install the LSP4IJ plugin, then Settings > Languages & Frameworks > Language Servers > +:
- Name:
falcon-asm - Command:
falcon-asm(or the absolute path) - Mappings > File name patterns:
*.S,*.s, language idfalcon-asm
Every feature works through LSP4IJ; the options described above go in the server's initialization options as JSON.
vim.lsp.config('falcon_asm', {
cmd = { 'falcon-asm' },
filetypes = { 'asm' },
root_markers = { '.git' },
})
vim.lsp.enable('falcon_asm')Neovim maps .S/.s to the asm filetype by default.
cmd/falcon-asm/ entry point: the server, `lint` and `rules`
internal/jsonrpc/ Content-Length framing and connection
internal/protocol/ the LSP types in use
internal/docstore/ open documents, incremental sync, UTF-16 positions
internal/lexer/ GAS + cpp tokenizer
internal/isa/ instruction, register and directive tables, mnemonic resolution
internal/analysis/ mode tracking, mode and level diagnostics, document symbols
internal/symbols/ workspace symbol index: definition, references, rename, outline, folding
internal/toolchain/ compile database, gcc -dM macros, assembling with a listing
internal/inlineasm/ asm statements in C: template extraction and mapping, operand hover
internal/completion/ completion items
internal/constexpr/ integer constant expressions for macro values
internal/hover/ hover content
internal/semtok/ semantic tokens
internal/lint/ rule registry, .falcon-asm.json, suppression comments, the runner
internal/rules/ the lint rules, one package per roadmap area; rules/all imports them
internal/project/ shared by server and CLI: file target resolution, linting a document
internal/engine/ per-document state, configuration, toolchain runs, feature wiring
internal/server/ method dispatch and lifecycle
internal/benchdata/ shared benchmark inputs built from the fixtures
tools/xedgen/ generator for internal/isa/data/xed.json
tools/lspbench/ end-to-end LSP benchmark driving the server binary
editors/vscode/ VS Code client, base TextMate grammar, inline asm injection grammar
testdata/falcon-bios real .S fixtures from airies-boot
docs/DESIGN.md has the package contracts and the reasoning behind them.
internal/isa/data/system.json is hand written and covers the system,
privileged, I/O, string and control-transfer instructions; it wins over the
generated data for any name in both. internal/isa/data/xed.json is
generated by tools/xedgen from Intel XED and asm-lsp's x86 data and is
committed, so a normal build needs neither upstream. To regenerate, see
tools/xedgen/README.md and run make xed-data. Attribution is in NOTICE.
GPL-3.0-or-later. See LICENSE. Third-party data attribution in NOTICE.