Skip to content
gaulPublic

About

Examine x86-64 machine code to find suboptimal encodings and sequences of instructions

Topics

Resources

Stars

19 stars

Watchers

1 watching

Forks

Repository files navigation

x86lint

x86lint examines x86-64 machine code to find suboptimal encodings and sequences. For example, add eax, 1 can encode with either an 8- or 32-bit immediate:

83C0 01
81C0 01000000

Using the former can result in smaller and faster code. x86lint can help compiler writers generate better code and documents the complexity of x86.

Design and soundness model

x86lint is a peephole analyzer. It walks the machine code in a single linear sweep -- decoding one instruction at a time in 64-bit long mode with Intel XED, with every instruction set XED knows enabled (XED_CHIP_ALL), so a chip-gated encoding like LZCNT decodes as itself rather than as its legacy alias (BSR under a stray REP prefix) -- and matches each decoded instruction against a table of checks, every one recognizing a single suboptimal encoding by its opcode, operands, and immediate. Matching works on XED's decoded form, so aliases and alternate encodings of the same operation are all caught. Most checks inspect a single instruction; a few peepholes match a short window of adjacent instructions -- like its AArch64 sibling armlint -- such as a redundant test folded into the flag-setting ALU before it or a LEA folded into the memory operand after it. The soundness gates below then look a bounded distance forward (and, for the 32-bit identity rewrites, one instruction back) to prove a flag or register value dead.

Linear sweep with resync. Executable sections routinely interleave data with code -- jump tables, alignment islands, GHC info tables, Go's BoringCrypto signature. When XED cannot decode the bytes at the cursor, x86lint skips a single byte and resynchronizes instead of abandoning the rest of the section. Skipped bytes are counted (x86lint_summary_skipped) so that partial coverage of a data-laden region is not mistaken for a clean scan.

A first pass over the same sweep also collects every direct branch and call target. A multi-instruction peephole rewrites a window of instructions, which is sound only if control cannot enter the window's interior -- an incoming edge executes just the tail. The canonical trap is the scan loop mov rbx, rax ; L: add rbx, 1 ; cmp byte [rbx], '-' ; je L (this exact shape appears in bash and git), where folding the pair into lea rbx, [rax + 1] would turn the loop increment into a per-iteration reset. Each multi-instruction finding is therefore suppressed when a collected target lands inside its window; a target on the window's head is fine, since that edge executes the whole pattern. An ENDBR64 is marked as a target too: under IBT it is the only place an indirect branch may land, so it is the binary's own declaration of an incoming edge -- the one indirect edge the sweep can see -- and a window it sits inside is suppressed like any other. Edges the sweep cannot see -- indirect branches in code without landing pads, notrack jump tables, entries from another section -- remain a residual risk of judging raw bytes, accepted and documented here.

Soundness over recall. For a tool that suggests code changes, a false positive -- flagging an instruction whose replacement would change behavior -- is the worst failure, so every check errs toward false negatives: a missed opportunity is cheaper than a wrong one. Most rewrites are unconditionally equivalent (a shorter immediate, a dropped REX prefix, movaps for movdqa) and need no further proof. But two side effects are invisible in the lone instruction and would make an otherwise-redundant rewrite unsound if a later instruction observed them; each is guarded by a bounded forward scan (up to 16 instructions) starting at the successor.

  • Flag liveness. Some rewrites change which flags an instruction writes: mov eax, 0 -> xor eax, eax saves bytes but clobbers the arithmetic flags mov left untouched, and add [rbx], 1 -> inc [rbx] reproduces every flag except CF, which add writes and inc leaves alone. The rewrite is sound only when the affected flags are dead, so a check declares the flags it perturbs (flag_concerns) and flags_live_after suppresses the finding if any is read before being overwritten. A RET ends the scan as dead -- neither the SysV nor Win64 ABI preserves flags across a call -- while a branch, call, or interrupt whose path the scan cannot follow ends it conservatively live.

    The model covers CF, PF, ZF, SF and OF. AF is deliberately outside it, and three rewrites do diverge there, each replacing an instruction that defines AF with one that leaves it undefined: CMP reg, 0 and ADD reg, 0 to TEST reg, reg, and SUB reg, reg to XOR reg, reg. Nothing gates them, because flag_concerns has no bit for AF and adding one would suppress findings on a flag that 64-bit code cannot read without LAHF or PUSHF and that no compiler emits a dependence on. Recorded rather than assumed: the divergence is real, it runs toward undefined, and it is accepted. The reverse direction is harmless and appears once, in SHL reg, 1 to ADD reg, reg, which gives AF a definition the shift did not have.

  • Register (upper-32) liveness. Writing a 32-bit register zero-extends into the upper half of its 64-bit parent, so a 32-bit identity operation whose rewrite writes nothing -- mov eax, eax removed; add eax, 0, or eax, eax, or and eax, -1 turned into test; shl eax, 0 removed (hardware zero-extends even at count 0, whatever the SDM's count-0 pseudocode suggests) -- is redundant only when that zero-extension is dead. This is not hypothetical: GCC emits and ebx, -1 as a fused zero-extend-and-test whose full 64-bit register is read right after the branch, so the ungated rewrite would corrupt it. A check names the 64-bit register at stake (reg_concern) and reg_upper32_live_after suppresses the finding if bits 63:32 are read -- as an explicit operand or a memory base/index -- before an unconditional 32- or 64-bit write redefines them. Here RET is conservatively live: the value can escape as a return value or in a callee-saved register, which a linear walk cannot rule out. One backward escape reinstates the finding: when the immediately preceding instruction already zero-extended the register, the identity op changes nothing regardless of downstream reads. The escape holds only if every path to the instruction runs through that predecessor, so a direct branch targeting the instruction itself -- arriving with unknown upper bits -- cancels it. The escape is licensed per check, because it is sound only for rewrites that delete the write: narrowing lea rax, [...] to lea eax, [...] (oversized LEA width) still writes the register, swapping the address's upper half for zeros, so a predecessor's zeroing of the destination -- overwritten either way -- proves nothing, and that check runs the forward gate alone. The boundary also parameterizes: the merging narrow move check runs the same walk at bit 8 or 16 (reg_bits_above_live_after), where a high-byte register read observes bits 15:8 and a same-register 32/64-bit XOR or SUB counts as the kill it is rather than the read XED records -- compilers end a value's life with exactly that idiom.

Both scans share one bias: reads count inclusively and redefinitions exclusively, so every uncertainty -- a decode error, an unfollowable branch, running past the 16-instruction window, or the end of the buffer -- resolves toward live, and thus toward suppressing the finding. A branch ends the walk at that conservative answer, so the analysis stays within a basic block: it never suggests a rewrite whose soundness would hinge on a fact about a branch target it cannot see. The one boundary it reads through is a function return, and only for flags -- the ABI guarantees they do not survive it.

Memory accesses: frame slots only. Until November 2026 no finding changed the set of memory accesses a program makes, and the rewrites that would have deleted a load or a store were recorded and left alone (issue #29). riscvlint never drew that line, and x86lint now matches it, with the one restriction that makes it sound: a finding may delete or replace an access only to a frame slot, [RSP + disp] or [RBP + disp] with no index and no segment override. A frame slot is private to its thread and is never device memory, so the access being dropped cannot be an MMIO side effect, cannot race another thread, and cannot be an atomic -- which matters more on x86 than on RISC-V, since x86 spells even a sequentially consistent load as a plain MOV, with no fence for a window to stop at. Everywhere else the old line holds. A plain load that survives -O2 beside its twin is one the source told the compiler not to merge (issue #29 sampled libxul's heap reloads: 14 of 14 were atomics), Go spells a nil check as a compare whose only purpose is the load's fault, and a store through a pointer may be the one a signal handler or another thread reads.

RBP qualifies only where mov rbp, rsp made it the frame pointer, and only in that function, because a build without frame pointers allocates it like any callee-saved register. The scan tracks its role from the prologue, ends it at any other write to RBP and at every function entry it can name (a direct-call target, an ENDBR64, an installed function's start, INT3 padding), and restores it past the epilogue's own transfer, since the blocks laid out after an epilogue are reached from the body. The table those checks share drops a claim at any store that may overlap the slot -- through the same base an overlapping byte range, through any other address anything at all -- and at calls, unconditional transfers, branch targets, LOCK and fences; it keeps its claims across the fall-through of a conditional branch, which is where the compiler leaves most of them. Two residual risks are accepted and named. A volatile local -- the setjmp pattern -- is reloaded on purpose, and nothing in the encoding tells it from a spill reload. And a function reached only indirectly, in a binary with neither symbols nor IBT, whose layout puts an RBP-based access ahead of its own write to RBP, inherits the previous function's frame-pointer state: the same class of edge the sweep cannot see as the one under "Linear sweep with resync".

The model differential. Both scans above rest on claims about what instructions do, and those claims were read out of the SDM by hand and written into a switch: reg_kill_iclass's list of instructions that overwrite a register's upper half unconditionally, and the flag behaviour half the multi-instruction rewrites are gated on -- "LEA writes no flags", "INC and DEC leave CF alone", "a shift by CL writes its flags only conditionally". XED holds the same facts in its own operand and flag records, so the two can be compared, and x86lint_model_check does it over every node of XED's static instruction table. A disagreement means a shipped check is reasoning about an instruction the decoder in the same process describes differently.

This is armlint's ARMLINT_LIVENESS_SWEEP=1 differential in the form x86 admits. There is no enumerable encoding space to sweep -- armlint walks all 2^32 A64 encodings against Capstone -- but there is a table of every iform XED knows, and the oracle is better than a second opinion: it is the decoder the findings are built on. It is also cheap enough (ten thousand nodes, not 2^32) to run on every make check rather than behind an environment variable, and it runs against whatever XED the caller linked rather than the one it was written against. Five properties, over 10,879 iforms and 17 instruction fixtures:

property what it pins
no conditional register write in any iform of a reg_kill_iclass member a conditional write leaves the prior value in place, so it cannot kill the register
every deliberate exclusion is a conditional writer the positive control: without it the property above could hold because XED marks nothing conditional
no flag record at all for the iclasses whose silence a gate relies on a substituted or inserted instruction must not disturb flags something later reads
SETcc and CMOVcc read the condition flags and write none, across all 16 condition codes two checks branch on flags a SETcc is claimed to leave in place
the flag sets a gate names by hand are the sets XED records naming one too small is unsound rather than timid: the gate then proves the wrong flags dead

The exclusions are the interesting half. reg_kill_iclass omits the shifts because the SDM's count-0 pseudocode performs no destination write, and BSF/BSR because the destination is undefined when the source is zero; both arguments were made by hand, and XED independently spells both as conditional writes. The third exclusion, REP-prefixed string writes, is not covered: that conditionality lives in the prefix rather than in the iform, so XED's operand records call MOVSB an unconditional writer and the property cannot speak to it.

What the differential cannot check is the per-check flag_concerns declaration, and the reason is worth stating rather than leaving as a gap. flag_concerns is the symmetric difference between the original instruction's flag effects and the replacement's, and XED knows only the original's: suboptimal MOV zero declares every arithmetic flag while MOV writes none of them, because the concern is what the suggested XOR would clobber. So the differential pins the instruction-level claims the gates are built from, and each check's own declaration stays a matter for its unit fixture.

Implemented analyses

Each row links to its full description -- the encoding or sequence it matches, what the rewrite saves, and the soundness argument that licenses it -- in analyses.md. Candidate checks not yet implemented, with the corpus populations that argue for or against each, live in TODO.md.

Analysis Rewrite
ADD foldable into LEA one LEA carrying the ADD's term, where the result stays within two components
ADD foldable into memory fold the pointer arithmetic into the consumer's base+index*scale+disp
AVX-SSE transition VZEROUPPER after the last 256-bit use, or the VEX spelling of the SSE code
bit-cast routed through a frame slot MOVD/MOVQ between the register files, without the slot
branch to the next instruction delete; control arrives there either way
CAS loop foldable into LOCK op LOCK OR/AND/XOR
constant condition after immediate delete the compare; the Jcc/CMOVcc/SETcc reading it has one outcome
constant condition after zeroing same, the tested register being provably zero at any width
dead compare delete it; nothing reads the flags it sets
dead store to a frame slot delete the first of two stores to the slot
IBT-bypassing NOTRACK call review item: a deliberately untracked forward edge, not a rewrite
LEA foldable into memory fold the address into the consumer's memory operand
length-changing prefix stall 32-bit operands; advisory, and the imm8 narrowing removes it by itself
load foldable into ALU ADD reg, [mem] and the rest of the two-operand forms
load foldable into compare CMP [mem], imm / TEST
load foldable into extend MOVZX/MOVSX reg, byte [mem]
load foldable into vector op fold the load into the SIMD instruction's source operand
load foldable into vector transfer MOVD/MOVQ/CVTSI2SD xmm, [mem]
load of a just-stored value MOV rD, rS from the register the frame slot was stored from
load of a value the register still holds delete the frame-slot load; its destination already holds the bytes
NEG foldable into ADD/SUB SUB/ADD of the original
missing ANDN (only with -m bmi1) ANDN
missing APX NDD (only with -m apx) the EVEX new-data-destination form, dropping the copy
missing APX SETZU (only with -m apx) the zero-upper SETcc, dropping the MOVZX
missing BLSI (only with -m bmi1) BLSI
missing BLSMSK (only with -m bmi1) BLSMSK
missing BLSR (only with -m bmi1) BLSR
missing BZHI (only with -m bmi2) BZHI, when the count is below the width; advisory
missing MOVBE (only with -m movbe) MOVBE
missing MULX (only with -m bmi2) MULX, dropping the move out of the fixed register
missing POPCNT dependency break insert XOR dst, dst ahead of it
missing SSE dependency break insert XORPS dst, dst ahead of it; advisory
stale VEX merge operand name the data source, or a dead register, as the merge operand
merging scalar move MOVAPS; advisory
merging narrow move MOVZX, or MOVSX where the sign is wanted
missing SHLX/SHRX/SARX (only with -m bmi2) SHLX/SHRX/SARX, which write no flags
MOV constant foldable fold the constant into the consumer's immediate
MOV+ADD foldable to LEA one non-destructive LEA
OR foldable into memory (only with -m v8) fold V8's decompressed pointer into the consumer's addressing mode
oversized ADD/SUB 128 the imm8 form of the opposite operation
oversized ADD/SUB one INC/DEC, while CF is dead
oversized branch displacement the rel8 form
oversized displacement the disp8 form
oversized EVEX encoding the VEX encoding of the same operation
oversized immediates the sign-extended imm8 form
oversized LEA width drop the REX.W, while bits 63:32 are dead
oversized MOV encoding the B8+r immediate-to-register form
oversized TEST immediate TEST AL, imm8
oversized VEX encoding the two-byte VEX prefix
oversized XCHG encoding the one-byte 90+r accumulator form
redundant ADD/SUB zero TEST, or remove
redundant CMOVcc reg, reg remove; a conditional move onto itself
redundant AND immediate TEST reg, reg
redundant bit-scan default delete the MOV; needs -t skylake or later
redundant MOV constant delete; the destination already holds it
redundant MOV reg, reg remove
redundant OR/XOR zero TEST, or remove
redundant zero-extension drop it; the producer already zeroed those bits
redundant re-extension remove the second extension
redundant reload MOV rD, rS from the register still holding the frame slot's value
redundant shift/rotate by zero remove
redundant TEST after flags delete the TEST; the ALU before it already set the flags
redundant TEST after SETcc branch on the compare's flags directly
redundant TEST after shift branch on the shift's flags directly
redundant TEST immediate TEST reg, reg
shift pair foldable into extend MOVSX/MOVZX
store of a value the slot already holds delete the frame-slot store; the slot already holds those bytes
rematerialized constant MOV rD, rS; needs -t skylake or -t zen
suboptimal AND immediate MOVZX
suboptimal AND zero XOR reg, reg
suboptimal CMP zero TEST reg, reg
suboptimal CMP one TEST reg, reg with the equality branch
suboptimal IMUL constant LEA, SHL, MOV, NEG or XOR, by the multiplier
suboptimal lane-0 extract MOVD/MOVQ/MOVSS
suboptimal LEA MOV, or ADD while the flags are dead
suboptimal MOV zero XOR reg, reg, while the flags are dead
suboptimal OR/AND reg, reg TEST reg, reg
suboptimal SETcc inversion the complementary SETcc
suboptimal SETcc zero-extension zero the register ahead of the flag-setter; advisory
suboptimal SHL one ADD reg, reg
suboptimal SSE MOV opcode MOVAPS/MOVUPS
suboptimal SSE zero idiom XORPS
suboptimal SUB reg, reg XOR reg, reg, which every core recognizes as independent
suboptimal VEX operand order swap the sources, or the other-direction move, for the two-byte VEX prefix
suboptimal XOR immediate NOT, while the flags are dead
unneeded explicit immediate the implied-operand form
unneeded explicit register the accumulator form
unneeded LOCK prefix on XCHG drop the prefix; XCHG with memory is already atomic
unneeded MOVSX CWDE/CBW
unneeded MOVSXD CDQE
unneeded REP prefix on RET drop the prefix
unneeded REX prefix drop the prefix
unneeded SIB byte the plain modrm form
unneeded zero displacement drop the displacement
suboptimal NOP sequence multiple 90 instead of a single 66 90; never implemented, and sized at about 110 sites rather than the 2,527 the shape suggests -- Go's 2,133 are ginsnop inline marks that the runtime identifies by PC, and every population where merging is sound turns out to be bytes nothing decodes. See #9 and "Suboptimal NOP runs" in TODO.md

Compilation

First install the Intel x86 encoder decoder:

git clone https://github.com/intelxed/xed.git xed
git clone https://github.com/intelxed/mbuild.git mbuild
cd xed
./mfile.py install --install-dir=kits/xed-install

Next build x86lint:

git clone https://github.com/gaul/x86lint.git x86lint
cd x86lint
XED_PATH=/path/to/xed make all

Run the unit suite and the ELF-driver smoke test with XED_PATH=/path/to/xed make check.

The suite has three layers. x86lint_test.c assembles byte sequences and asserts the exact category and total each one produces, which is where a check's soundness gates are pinned. driver_test.sh builds small ELF fixtures with the system toolchain and asserts one stated fact per line about the report: what each flag turns on, which exit code a path returns, what --json must not contain. The same script then snapshots each fixture's whole report into snapshots/, which catches everything the assertions do not name -- column widths, ordering, a stray extra finding, a count on a line nobody wrote a grep for. Values the linker chooses (section index, load address, sample and target addresses) are normalized away so the files are portable. Rewrite them with XED_PATH=/path/to/xed make snapshots and read the diff: a change you can explain is a new check or a deliberate edit, and one you cannot is the regression the layer exists to catch. The script never skips itself; an environment that cannot build the fixtures exits 2, because a skip that exits 0 is indistinguishable from a pass.

On an x86-64 host, XED_PATH=/path/to/xed make rwfuzz-test runs x86lint's advice. tools/rwfuzz generates random programs as assembly text -- ALU, shift, multiply, LEA, extension, CMOVcc, SETcc and SSE instructions, loads and stores to frame slots named through both RSP and RBP and to a scratch buffer, pushes, pointers to the frame, forward branches and calls, and planted shapes for the checks -- assembles them with the host's compiler driver (RWFUZZ_CC, default cc), and runs check_instructions over the bytes. A finding names one instruction and carries no rewrite, so rwfuzz holds a rewriter per finding name that applies the row's rewrite as the table below states it, finding a window's partner the plain way and assuming nothing the check had to prove. Each rewrite is assembled from its own text and run natively against the original from the same random registers, flags and memory; a difference in the general registers, xmm0-xmm7, the defined flags or the scratch memory is a soundness bug, and so is a rewrite the rewriter or the assembler cannot apply. A control arm applies the same rewrites where x86lint refused to and must see some of them change a result. 81 of the rewriting rows run; TODO.md, "rwfuzz coverage", lists the rest and why. RWFUZZ_PROGRAMS (10000) and RWFUZZ_SEED size and vary the run, RWFUZZ_JOBS splits it across worker processes without changing what it prints, and tools/rwfuzz -f NAME MODE narrows one to a single finding over the same programs. CI runs it on every pull request under gcc's assembler and clang's with the default seed, and on pushes to master, weekly and on demand with the run's id as the seed and ten times the programs.

Usage

x86lint is intended to be part of compiler test suites, which should #include "x86lint.h" and link libx86lint.a. Pass the just-emitted machine code to check_instructions; its return value is the number of opportunities found, which a test can assert is zero:

#include "x86lint.h"

// inst/len: the x86-64 bytes to check (e.g. a function the compiler just
// emitted). Returns the opportunity count (0 == clean). An undecodable byte
// is skipped and the scan resyncs rather than failing, since executable input
// can interleave data with code.
int lint(const uint8_t *inst, size_t len)
{
    xed_tables_init();
    return check_instructions(inst, len, /*vaddr=*/0, /*verbose=*/false,
                              /*summary=*/NULL, /*extensions=*/0,
                              /*on_finding=*/NULL, /*ctx=*/NULL);
}

The optional summary accumulates a by-type tally across one or more runs (x86lint_summary_create / _print / _destroy; pass NULL to skip it), and verbose controls whether each opportunity is printed as it is found. x86lint_summary_skipped reports how many undecodable bytes were skipped, so incomplete coverage of a data-laden section is not mistaken for a clean scan. extensions is a bitwise OR of enum x86lint_extensions values (X86LINT_EXT_BMI1, X86LINT_EXT_BMI2) declaring which instruction-set extensions the code's target supports; checks that suggest an instruction from one of those sets run only when its bit is enabled, and 0 keeps the scan to baseline x86-64.

The optional on_finding callback is called once per opportunity, with ctx as its first argument, the finding's name, the absolute address of the offending instruction (the vaddr argument plus the finding's offset), and that instruction's decoded form and raw encoding. Where the summary answers "how many of each kind", the callback answers "which instruction, at what address" -- the form needed to join findings against anything else keyed by address, such as an execution profile that weights each opportunity by how often the instruction it names actually runs. It is independent of both summary and verbose, so a consumer wanting only the per-finding stream passes NULL for the summary and false for verbose. The driver's --json mode is built on it.

x86lint can also read arbitrary 64-bit ELF executables directly:

$ ./x86lint /bin/ls                            # the lint scan
$ ./x86lint --verbose --function main /bin/ls  # each finding, in one function
$ ./x86lint --constants /usr/lib64/libc.so.6   # the constant census

Every option has a long name and a one-letter alias, and x86lint --help prints the table. The letters shared with armlint (-v, -A, -f, -i, -c, -m, -a and --json) mean the same thing in both tools, and so do their long names. A value follows its option as the next argument or joined with = (--function=main).

option effect
-v, --verbose print each finding with its disassembly
-A, --all-bytes scan every byte, not only the sized functions
-f FUNC, --function FUNC scan only the function named FUNC
-e, --endbr also verify the CET IBT landing pads
-i, --isa an ISA census in place of the lint scan
-r, --registers a register census
-c, --constants a constant census
-n, --inlining an inlining census
-j, --jcc a JCC-erratum audit
-s, --thunks a speculation-thunk audit
-p, --properties a build-property audit
--json the findings as a JSON document on stdout
-m EXT, --assume EXT the target has EXT: bmi1, bmi2, movbe or apx; v8 asserts V8's register conventions
-t TARGET, --tune TARGET generic, sandybridge, skylake, icelake, zen or silvermont
-a KIND, --enable KIND also report the advisory, security or all finding classes
-h, --help print this table

The sections below name each mode by its letter, which is how the examples spell it.

When the binary kept its symbol table (.symtab), the scan is restricted to the byte ranges of its function symbols: executable sections routinely interleave non-code that decodes cleanly -- GHC info tables, LLVM's constexpr tables, jump tables -- which linear sweep would otherwise report pseudo-instruction findings from, and which the undecodable-bytes counter cannot flag. Excluded bytes are tallied into that skipped count, and a summary line reports the restriction; pass -A (--all-bytes) to scan every byte anyway. The dynamic symbol table is never used for this -- it survives stripping but lists only exports, and scanning just those would silently miss almost all code -- so stripped binaries scan whole sections exactly as before. An unsized assembly label extends to the next function's start, keeping coverage conservative.

An instruction whose bytes a relocation will rewrite is excluded whatever the symbols say, because its immediate or displacement is not a value. It is zero, or a bare addend, waiting for the linker, and a peephole that reads one is reasoning about a number that will not be there at run time. Two findings on a Fedora kernel module show the stakes: 143 relocated e9 00000000 -- every return in a -mfunction-return=thunk-extern build -- whose rel32 placeholder reads as a displacement that would fit rel8, and 132 mov r64, imm32 carrying R_X86_64_32S, where the shorter encoding the finding asks for cannot express the sign-extended kernel address the linker is about to write. Acting on either corrupts the relocation, which makes these worse than noise; they were 275 of that module's 314 findings, and excluding them leaves 31. The whole instruction goes, not the field, since an opcode with its immediate cut out decodes as something else entirely -- so the exclusion also stops any multi-instruction window from reasoning across a placeholder. A linked binary has no relocations into .text (only .rela.dyn and .rela.plt, neither of which names a target section), so this costs nothing there and the summary line appears only when something was actually excluded.

The dynamic linker's import glue is skipped whatever the symbols say: the ELF .plt, .iplt and .plt.* sections are emitted from a fixed template by ld, so their shape is the dynamic-linking ABI's business and no source change reaches it. The noise this removes is a constant: a lazy-binding PLT entry pushes its relocation index with the 5-byte push imm32, so every entry whose index fits a signed imm8 draws an oversized-immediate finding and the count saturates at exactly 128 -- libstdc++ (1,105 PLT entries), /bin/bash (236) and libcrypto (161) each reported those 128 plus 7 oversized branch displacements from the resolver jumps, 135 apiece regardless of size, none of them fixable and all of them enough to fail the non-zero exit a compiler test suite gates on. The exclusion is by section rather than by symbol because the symbol restriction already hid it wherever .symtab survived (glibc reported none) and could not where it did not, so the noise appeared only on stripped binaries -- which is how a distro library is usually scanned. -A keeps its contract and scans the glue too, for anyone auditing a linker rather than a compiler. The -e verification is a separate pass and deliberately unaffected: PLT entries really are indirect-branch targets under IBT, so whether they carry landing pads is the one thing about them worth checking. armlint excludes the same family, adding Mach-O's __stubs, __stub_helper and __objc_stubs.

By default x86lint prints only a summary -- the opportunities grouped by type and sorted by prevalence -- followed by a total and the number of instructions scanned:

$ ./x86lint /bin/ls
Optimization opportunities by type:
     169  oversized ADD/SUB one
     105  oversized immediate
       8  oversized branch displacement

282 optimization opportunities in 22705 instructions

Pass -v to also print each opportunity -- its one-line disassembly plus the offending encoding -- ahead of the summary:

$ ./x86lint -v /bin/ls
== section 5 .text: vaddr 0x2100, 1077514 bytes ==
oversized immediate at offset: 0x14: push 0x0
  68 00 00 00 00
...

Offsets are relative to the section being scanned, so the banner names each one and gives the address to add to place a finding in a disassembly. A binary can hold several executable sections -- a BOLT-processed library keeps the functions it did not move in .bolt.org.text beside those it moved into .text -- and without the banner their offsets are indistinguishable.

When the binary kept its symbols, findings are also attributed to the function that holds them: each -v line gains a (name+0xoff) suffix that jumps straight to the site in a disassembler, and the summary adds a by-function companion table -- the top ten offenders, the tail summed into a residue line -- so a whole-binary count reads as "and here is where to start":

Optimization opportunities by function:
     356  __strcasecmp_l_sse2
     356  __strncasecmp_l_sse2
     252  __strcmp_sse2
     ...
   49334  in 32480 more functions

Attribution uses sized function symbols only; a finding in code reached through an unsized assembly label lands in an honest outside every function range row rather than the wrong neighbor.

Pass -f NAME (--function NAME) to restrict the scan to the one function named NAME -- "lint just this function". Unlike the default restriction, -f also draws on the dynamic symbol table, so naming an exported function of a stripped library works; every sized symbol spelled NAME is scanned (a versioned export like glibc's two memcpys has several sites), and the count line reflects only their instructions. -f combines with -i for a per-function census; see that section.

Pass -m bmi1, -m bmi2, -m movbe, and/or -m apx (--assume) to declare that the binary's target supports those instruction-set extensions, enabling the checks that suggest replacing a baseline sequence with an instruction from that set (missing ANDN, missing BLSI, missing BLSMSK, missing BLSR, missing BZHI, missing SHLX/SHRX/SARX, missing MOVBE, missing APX NDD, missing APX SETZU). These are opt-in because the finding is only actionable when the target guarantees the extension: a distro binary built for x86-64-v2 could not have used ANDN however clear the opportunity, and inferring availability from the surrounding bytes is unsound for binaries like glibc that keep baseline code and CPU-dispatched BMI-rich variants in the same section. The flags are independent, matching their CPUID feature bits: -m bmi2 does not imply -m bmi1.

-m v8 is a knowledge bit rather than an ISA bit, and is armlint's flag of the same name: it asserts a runtime invariant of the scanned code, that R14 holds V8's pointer-compression cage base, which is 4 GB aligned so its low 32 bits are zero. It enables OR foldable into memory, which is unsound for arbitrary code and stays silent without it. Pass it when scanning V8's JIT output or its embedded builtins; never for an ordinary binary.

Pass -t generic|sandybridge|skylake|icelake|zen|silvermont (--tune) to name the microarchitecture the code is tuned for. This is a different axis from -m: that says whether an encoding exists on the target, where -t says whether a rewrite is worth making there, and several of x86lint's are not worth it everywhere. The default, generic, assumes every documented penalty applies at once, so it reports the rewrites that pay on every core and withholds the ones that only sometimes do.

Four behaviours move with it, and they move in both directions:

  • A three-component LEA costs 3 cycles on port 1 alone from Sandy Bridge through Cascade Lake, where each two-component form is 1 cycle on two ports, so folding a fast LEA and an ADD into a slow one trades a cycle for three or four bytes. Agner Fog's tables give Ice Lake and Tiger Lake no separate row for the three-component form, and Zen 3 through Zen 5 two cycles as two ops, which is what the pair already costs. On libxul, -t icelake takes "ADD foldable into LEA" from 2,678 findings to 28,064: 25,386 sound folds that the default is right to withhold and a modern target is right to want.
  • POPCNT's destination is a phantom input from Sandy Bridge through Cascade Lake and not after, so on icelake and zen the dependency-break check goes silent rather than advising an XOR that is pure cost. That is 6,431 findings on libxul the default reports and Ice Lake does not.
  • The length-changing prefix stall applies to MOV on the Pentium 4 through Nehalem, not on Sandy Bridge through Skylake, and again from Ice Lake. MOV is most of what that check fires on -- 92% of the findings on librustc_driver -- so on a Sandy-Bridge-through-Skylake target the bulk of its output was reporting a cost that is not paid. The arithmetic and logic forms pay on every Intel big core and are never gated.
  • SUB r, r is recognized as a zeroing idiom independent of its input everywhere except the low-power line, where "SUB, SBB and CMP instructions are not recognized in this way" (Agner Fog). The rewrite to XOR therefore fires under generic and silvermont and nowhere else.

sandybridge and skylake currently differ in no gated behaviour and are named separately because they differ on an axis no check reads yet: the bit-scan false dependency ends at Broadwell where POPCNT's runs to Cascade Lake. An unknown name is a usage error rather than a silent fallback to the default, since a typo that quietly changed which findings appear would be worse than a refusal.

Pass -a advisory, -a security or -a all (--enable) to report kinds of finding the default scan withholds. Most checks state a verified byte-level rewrite: the replacement is equivalent, the tool proved the conditions, and applying it is mechanical. Those are the default, and they are what makes a non-zero exit mean "there is something here to fix". Two other kinds do not fit that description and were, until now, reported beside them as though they did.

  • advisory is a real improvement whose fix the tool cannot verify or cannot even see. The SETcc zero-extension's rewrite belongs upstream of the flag-setter, whose surroundings a peephole cannot prove safe; the length-changing prefix stall's clean fix is 32-bit operands, which needs upper-16 liveness this tool does not track. Both said so in their own documentation before they had a class to sit in. A build should not fail on advice the tool cannot check. The two scalar-merge rows, "missing SSE dependency break" and "merging scalar move", joined them on 2026-11-10: their rewrites change a vector register's upper lanes, and they assume rather than prove that nothing reads those lanes past what their walk can see, which tools/rwfuzz showed is not always so.
  • security is not a rewrite at all. The IBT-bypassing NOTRACK call is a review item, since dropping the prefix without padding the target trades the bypass for a #CP fault, so the reader is being asked to look rather than to patch. armlint keeps the same kind behind the same flag, -a pac.

The bits are independent, so advisories can be asked for without review items or the other way round, and an unknown name is a usage error rather than a silent default. Enabling a class makes its findings count like any other, exit status included: you asked for them. On glibc the default scan reports 7,130 findings and -a advisory reports 7,464, the difference being 194 SETcc zero-extensions and 140 prefix stalls.

One finding changes class rather than appearing: under -m apx the SETcc pair is reported as "missing APX SETZU" instead, and that is a verified rewrite -- the zero-upper form replaces the pair in place -- so it stays in the default scan.

Pass --json to replace the human report with the findings as a JSON document, one object per line inside a findings array:

$ ./x86lint --json /bin/ls
{"file": "/bin/ls",
  "findings": [
    {"vaddr": 8468, "check": "oversized immediate", "section": ".text", "length": 5, "bytes": "6800000000", "text": "push 0x0"},
    ...
  ],
  "instructions": 22705,
  "skipped": 0,
  "opportunities": 282
}

vaddr is the offending instruction's absolute address -- not the section-relative offset -v prints -- and is a number rather than a hex string so that it composes with arithmetic. That is the point of the mode: findings become joinable against anything else keyed by address, and the join worth making is an execution profile, which turns a static count of opportunities into a dynamic one. How often a compiler emits a suboptimal encoding is a poor proxy for what it costs; one inside an interpreter dispatch loop outweighs thousands in cold initialization code, and only a profile can tell the two apart. function and function_offset appear when the binary kept symbols to attribute against, and restriction carries what narrowed the scan -- {"symbols": N} by default, {"function": ..., "sites": N, "bytes": N} under -f, and absent under -A -- so that a partial scan is not read as a clean sweep of the whole file.

Findings are written as they are found rather than collected first, so a large binary streams instead of accumulating tens of thousands of objects in memory; the totals close the document because the scan only knows them then. Section and symbol names are copied from the file verbatim, so a binary whose string tables are not UTF-8 yields strings that are not either. The exit status is unchanged, and a file the driver rejects leaves stdout empty rather than half a document. --json describes the peephole scan alone: -v, -i, -r, -c, -n, -e, -j, -s and -p are separate reports whose output would interleave with it, and the driver refuses the combination rather than choosing for the caller.

Pass -e (--endbr) to also verify the binary's CET indirect-branch-tracking landing pads, -i (--isa) to replace the lint scan with an ISA census of the binary, -r (--registers) with a register census, -c (--constants) with a constant census, -n (--inlining) with an inlining census, -j (--jcc) with a JCC-erratum verdict, -s (--thunks) with a speculation-thunk verdict, and -p (--properties) with a per-function build-property audit; see the next sections.

The exit status follows the grep convention -- 0 for a clean scan, 1 when any opportunity is found, 2 on a tool failure (unreadable or malformed input) -- so x86lint can gate a compiler test suite and CI can tell a dirty scan from a broken run. -e findings set the exit status like any other; the -i, -r, -c and -n censuses never set it, the -j audit sets it only under -t skylake (the one target that has the erratum), the -s audit only for a mitigation left incomplete, and the -p audit never.

ENDBR64 (CET IBT) verification (-e, --endbr)

With Intel CET's indirect branch tracking enforced, an indirect JMP or CALL must land on an ENDBR64 instruction or the CPU raises a control-protection fault (#CP). The loader turns enforcement on when the binary's GNU property note (.note.gnu.property) carries the IBT bit, so a binary makes two claims that can drift apart: the note says "every indirect target is padded," and the code either honors that or does not. x86lint -e cross-checks them.

Which addresses an indirect branch can reach is not a property of the instruction stream -- nothing in the bytes distinguishes a landing site from fallthrough code, which is why this is a driver (-e) pass over the ELF metadata rather than an entry in the check table above. A linked binary evidences a checkable subset of its indirect targets:

  • the entry point (e_entry) of a program with a PT_INTERP interpreter -- ld.so transfers to it with an indirect jump (_dl_start_user's jmp *%r12). A kernel-entered binary -- static, static-PIE, ld.so itself -- starts with the tracker idle and owes no pad there, and ld.so's own _start indeed has none, deliberately;
  • .init and .fini (DT_INIT/DT_FINI) -- called through pointers;
  • every .preinit_array/.init_array/.fini_array slot;
  • R_X86_64_JUMP_SLOT and R_X86_64_GLOB_DAT relocations resolving to a definition in the same binary -- the slot's runtime value is that entry;
  • R_X86_64_IRELATIVE -- the loader calls the ifunc resolver indirectly;
  • every defined dynamic function symbol -- a cross-object call always arrives through the caller's PLT or GOT, an indirect branch landing here;
  • absolute-address relocations (R_X86_64_RELATIVE, R_X86_64_64, and the packed SHT_RELR form) whose baked pointer lands in an executable section -- vtables and callback tables.

The last class proves only that the address is taken, not that it is branched to: glibc bakes pointers to bracket labels (__syscall_cancel_arch_start) that are only ever compared against interrupted PCs, and hand-written assembly omits their pads deliberately. Address-relocation evidence therefore counts only when the pointer addresses a function entry known to .symtab or .dynsym -- a compare-only label is NOTYPE and drops out, and a stripped binary loses this one evidence class (the tool's usual trade: a false negative over a false claim). The converse check -- flagging a superfluous ENDBR64 -- is not attempted at all, since a target materialized by a RIP-relative LEA leaves no relocation behind and absence of evidence proves nothing.

Four verdicts, reconciling the pads against the note:

  • IBT declared, all targets padded -- clean;
  • IBT declared, some target bare -- each miss is printed with its address, symbol, and evidence (#CP fault the moment tracking is enforced);
  • IBT not declared, but the targets carry pads -- the compiler emitted CET and the link lost it: the linker ANDs the property across all inputs, so a single object built without -fcf-protection silently disarms enforcement for the whole binary. One finding; -v lists any targets without pads (in a poisoned link, usually the culprit object's);
  • no declaration, no pads -- not an IBT binary; nothing to hold it to, no findings.

The same FEATURE_1_AND word carries the shadow-stack bit, so -e reports it in the same pass: -fcf-protection=full emits both, and an asymmetric declaration earns a line. The asymmetries are real and directional: of 3,203 /usr/lib64 library files, 3,120 declare both bits, none declare IBT alone, and 18 declare SHSTK alone -- all media/JIT libraries (the ffmpeg family, dav1d, x264, libass, LuaJIT) whose hand-written assembly emits an SHSTK-only property note, since its returns stay call-paired but its entry points carry no pads. Under the linker's AND an SHSTK-only output proves every input object declared SHSTK while at least one withheld IBT, so each of the 18 pairs this line with the annotation-lost verdict: the two together read "the C was compiled with full CET, the assembly could claim only the return half, and the AND kept exactly what everything agreed on." The SHSTK line is informational and never sets the exit status, because SHSTK, unlike IBT, leaves nothing in the instruction stream to hold the binary to; even a shadow-stack-incompatible idiom is not statically recognizable -- glibc's own setcontext/swapcontext end in the classic push-and-ret, legitimately, because a runtime branch takes an RSTORSSP-based path first whenever a shadow stack is live, a feature gate no instruction matcher can see. So the declared bit is reported and the instructions are not judged. In the annotation-lost verdict the pads evidence branch protection only -- a lost FEATURE_1_AND takes IBT and SHSTK down together, but whether return protection was ever compiled in is unknowable, so there the line states the bit's absence without claiming a loss.

Verified against a Fedora system where CET is on by default: bash (1,767 evidenced targets), libc.so.6 (2,500), libcrypto.so.3 (5,867, including OpenSSL's perlasm), ld-linux-x86-64.so.2, and git all reconcile cleanly, and a Go binary -- Go does not emit IBT -- produces no noise. The sweep also caught a real specimen of the third verdict: Fedora's libzstd.so.1 ships all 598 evidenced targets padded but its property note carries no FEATURE_1_AND at all -- the hand-written Huffman assembly ate the declaration at link, so the fully padded library runs unenforced. Relocatable objects are rejected: their address-taken evidence dissolves into the final link, so the question is only answerable for executables and shared objects. The library exports the single-site predicate (check_endbr64_target); the evidence collection lives in the driver.

ISA census (-i, --isa)

x86lint -i replaces the lint scan with a census: every instruction in the binary's executable sections, tallied by the XED isa-set it belongs to and mapped onto the x86-64 psABI micro-architecture levels -- x86-64-v2 (CMPXCHG16B, LAHF-SAHF, POPCNT, SSE3, SSSE3, SSE4.1, SSE4.2), x86-64-v3 (adds AVX, AVX2, BMI1, BMI2, F16C, FMA, LZCNT, MOVBE, XSAVE), x86-64-v4 (adds AVX-512 F/BW/CD/DQ/VL). This answers "what was this binary compiled for": a distro package built with -march=x86-64-v3 shows AVX and BMI woven through ordinary functions, while a baseline build shows none.

$ ./x86lint -i /usr/lib64/libc.so.6
ISA census: 356358 instructions, 0 undecodable bytes skipped
  baseline x86-64 (v1): 341217
  x86-64-v2: SSSE3 (315), SSE4.2 (206), SSE4.1 (11)
  x86-64-v3: AVX2 (3368), AVX (3015), BMI1 (532), BMI2 (146), LZCNT (27), MOVBE (16)
  x86-64-v4: AVX512F (2038), AVX512BW (1709), AVX512DQ (3)
  outside the psABI levels: CET (3706), RTM (46), PKU (3)
  x87 legacy FP: 428 (control/env 34, 80-bit operands 124, other 270)
  highest psABI level: x86-64-v4
  code evidence: 9899 function symbols + 3791 .eh_frame FDEs + 0 Go pclntab functions covering 1481413 of 1514109 executable bytes
  GNU property ISA note: needed = x86-64-baseline, used = x86-64-baseline+x86-64-v2+x86-64-v3+x86-64-v4
  IFUNC resolvers defined: 141 (runtime CPU dispatch present)

The census reports presence, not requirement. glibc above runs on any x86-64 CPU: its AVX-512 lives in IFUNC-dispatched memcpy variants selected at load time, which is why the IFUNC resolver count is printed alongside -- a high level plus many resolvers reads as "baseline binary with dispatched fast paths," a high level with none as "compiled wholesale for that level" (or, as in OpenSSL and Go binaries, dispatch by plain branches on a runtime-probed feature word, which no static count can see). Deciding what the binary requires would mean proving which instructions execute unconditionally on the path from entry, which the instruction stream cannot evidence; the census states what the compiler was allowed to emit anywhere, and reports the note that can state requirement when the toolchain recorded one: the GNU property ISA note line prints the GNU_PROPERTY_X86_ISA_1_NEEDED word (authoritative -- the loader refuses to run the binary below that level) and the _USED word (the linker's union of what its inputs were allowed to emit -- the same quantity the census measures from the bytes, and a cross-check on it). glibc above declares needed = baseline: it requires only v1, everything higher being reached through dispatch, exactly as the resolver count suggests.

-f NAME narrows the census to the one named function, which turns "dispatch is present" into "and here is what each target actually uses" -- the per-target level question a whole-binary census cannot answer, one command per IFUNC variant:

$ for fn in __memmove_avx512_unaligned_erms __memmove_avx_unaligned_erms \
            __memmove_sse2_unaligned_erms; do
>   ./x86lint -i -f $fn /usr/lib64/libc.so.6 | grep highest
> done
  highest psABI level: x86-64-v4
  highest psABI level: x86-64-v3
  highest psABI level: baseline x86-64 (v1)

The coverage figure on the code evidence line is clipped to the scanned slices, and the file-level lines (the property note, the resolver count) keep reporting the whole binary they describe.

Extensions outside the levels -- AES-NI, PCLMULQDQ, SHA, ADX, CET, RTM, the post-v4 AVX-512 families (VNNI, VBMI, VAES, ...), APX -- are tallied on their own line and never raise the level verdict, since no -march=x86-64-vN implies them.

The x87 legacy FP line is a cross-cutting annotation, not a level: the x87-family instructions (isa-sets X87, FCMOV, FCOMI, plus SSE3's FISTTP) keep their place in the level counts -- x87 is baseline -- and are additionally split into FPU control/environment instructions (FLDCW, FNSTSW, ..., what ordinary fesetround compiles to), instructions touching an 80-bit tbyte memory operand, and everything else. The split exists because intent is only judgeable per binary, never per instruction: the SysV ABI deliberately keeps long double on x87, and a legitimate long-double function is dominated by bare register-stack arithmetic between its FLDT/FSTPT edges (glibc's own line above reads exactly so: strtold and printf %%Lf machinery). "Other" beside 80-bit traffic is long-double implementation; "other" in a binary with zero 80-bit operands cannot be long double, and reads as -mfpmath=387 leakage or assembly ported from 32-bit habits -- Fedora's libavutil is a live specimen (x87 legacy FP: 19 (control/env 4, 80-bit operands 0, other 15)), and -v's x87 other at ... samples lead straight to the sites. The v4 line folds XED's per-width isa-sets into their CPUID feature (AVX512F_512, AVX512F_128 and the mask ops all count as AVX512F); levels with no hits print none so two censuses diff line-for-line. The census always scans every executable byte (the .symtab restriction does not apply): a handful of hits can be data misdecoded as code, so -v prints up to four sample addresses per extension to check at a disassembler prompt before trusting a small count, and the zero-none shape plus the skipped-bytes counter bound how much could have been misread.

The census also labels every tally against the bytes the toolchain recorded as code -- sized function symbols from .symtab and .dynsym (stripped distro libraries keep the latter), .eh_frame FDE pc-ranges, and Go pclntab function boundaries, the runtime's own table, kept through strip because traceback needs it: a stripped pure-Go binary loses both symbol tables and has no unwind data worth the name, yet keeps every function boundary this way (all four header eras back to Go 1.2 parse; the table is found by section name or by scanning the data sections, and believed only after the whole functab validates against the executable sections and the entry point -- modern linkers store a dead textStart word, so the base is recovered from the section layout, and when external linking makes every candidate wrong the table is honestly dropped) -- because no property of the instruction stream itself can tell a real instruction from a phantom: tools/cohere measured run length, gap adjacency, and self-synchronization consensus all failing at exactly that (a GHC binary's phantom x87 reaches 92% consensus; junk converges onto its own stable decode chain). A family with hits outside all evidence prints as FAM (n, u unevidenced), and the code evidence line reports what backed the labels. The semantics are deliberately asymmetric: inside evidence lends trust -- OpenSSL's XOP (88) carries no annotation because every hit sits in a real function, and they are indeed its Bulldozer SHA-1 paths -- while unevidenced means only "no toolchain claim", never "phantom": GHC emits no FDEs for Haskell code, so a shellcheck census flags all 30864 x87 hits (correctly: they are info tables), but real Haskell code is equally unlabeled there. Evidence quality varies by build; when a binary has none at all, nothing is labeled and the line says so.

Register census (-r, --registers)

x86lint -r replaces the lint scan with a census of registers: which architectural registers the code names, in what role and at what width, and how many encoding bytes the choice of register number cost. It sweeps the same bytes as -i, carries the same evidence labels, and combines with it (-i -r prints both from one sweep) and with -f.

$ ./x86lint -r /usr/lib64/libc.so.6
register census: 355921 instructions, 0 undecodable bytes skipped
  general-purpose registers: references by role, register operands by width
    reg      insns   share   operand      base     index    hidden     64-bit    32-bit    16-bit     8-bit    high 8   sole REX    unevid.
    rax      94641   26.6%     78262     25147     12443      1252      37308     37466       483      4111       146                  4075
    ...
    rsp      38425   10.8%      5456      1774         0     31201      36657         0         0         0                               0
    ...
    r12      14797    4.2%     12659      2803       235         0       9614      2869         7       169                 5135          0
    r13      12086    3.4%     10529      2104       227         0       7883      2444         7       195                 3984          0
    ...
  vector registers: references by width
    ...
  rarely used registers: high-byte register 500, vector register 16-31 2697, mask register 1907, x87 stack register 394
    high bytes: ah 146, ch 202, dh 176, bh 17
    masks: k0 893, k1 576, k2 344, k3 79, k4 83, k5 98, k6 92, k7 0
  addressing: 11688 RIP-relative, 4500 FS-relative, 0 GS-relative
  encoding cost of register numbering: 34424 bytes
    legacy REX: 160354 (129988 with REX.W, so no cost; 0 selecting nothing)
    REX only for a register numbered 8-15: 29492
    REX only for SPL/BPL/SIL/DIL: 874
    APX REX2 prefix: 0
    three-byte VEX only for a high r/m or index register: 886
    R12 base without an index (SIB byte): 2447 (rsp, no alternative: 1704)
    R13 base with zero displacement (disp8): 725 (rbp, no alternative: 32)
    VEX: 5987 two-byte, 1382 three-byte; EVEX: 2970, 2697 of them naming a vector register 16-31
  code evidence: 9899 function symbols + 3791 .eh_frame FDEs + 0 Go pclntab functions covering 1481418 of 1512109 executable bytes

References are counted per operand, so add rax, rax names RAX twice; the insns column counts each instruction once. An operand is a register the disassembly shows, including one the opcode fixes (CL in shl eax, cl, EAX in add eax, imm32); base and index are a memory or LEA operand's address registers; hidden is a register the instruction uses without showing it -- RSP under PUSH, CALL and RET, RDX:RAX under MUL, RSI and RDI under the string instructions. Widths count register operands (not addresses), and high 8 is AH, CH, DH and BH. Flags, RIP and XED's pseudo-registers are not counted, and neither is an EVEX write-mask of k0, which is the encoding of "no masking" rather than a use of k0. Vector rows and APX's R16-R31 print only when used.

The cost section is the reason the census exists. x86-64 numbers registers with a three-bit ModRM field and takes the fourth bit from a prefix, so the upper half of each file costs more than the lower, and each line counts one way that cost was paid:

  • REX only for a register numbered 8-15: a legacy instruction whose REX sets R, X or B but not W, so the byte exists for the register number alone. With REX.W already present for a 64-bit operand, a high register is free, and those REX bytes are counted apart. The sole REX column attributes each such instruction to the high registers it names.
  • REX only for SPL/BPL/SIL/DIL: a bare REX, needed because without it those byte-register encodings mean AH, CH, DH and BH.
  • APX REX2: two bytes, or one when W is set and a REX.W was due anyway.
  • three-byte VEX only for a high r/m or index register: opcode map 0F with VEX.W clear fits the two-byte C5 form except for VEX.B and VEX.X, so the third byte was spent on the number of the register in the r/m or index field. For a commutative operation, swapping the two sources removes it, as does the other-direction opcode for a register copy; the suboptimal VEX operand order check reports those sites.
  • R12 base without an index takes a SIB byte, because R12 shares RSP's r/m encoding, and R13 base with zero displacement takes a disp8 of 0, because R13 shares RBP's. The RSP and RBP counts sit beside them because they pay the same byte and have no alternative.

The total is what register numbering cost, not what a better allocation would save: most high registers are in use because the low ones were occupied. Across the corpora measured on 2026-11-01 it is 2.2-2.9% of code bytes in compiled code (libxul 2.2%, librustc_driver 2.3%, the clang-built libLLVM and libclang-cpp 2.8-2.9%), about 85% of it REX bytes for R8-R15.

The rarely used registers -- high bytes, R16-R31, vector registers 16-31, mask, MMX, x87, control and debug registers, segment registers as operands -- are listed with their unevidenced share, and -v prints up to four sample sites for each and for each cost. Phantom decodes of data are likelier than a compiler to name an odd register: libxul's 37451 instructions naming vector registers 16-31 are 84% unevidenced. The asymmetry from the ISA census holds as well. libLLVM's 740 such instructions are all unevidenced and all real -- LLVM's bundled BLAKE3 AVX-512 assembly, which has no symbols or CFI -- while glibc's 2697 are all evidenced and all inside its *_evex and *_avx512 string and memory functions, which use YMM16-YMM31 because those registers need no VZEROUPPER.

Constant census (-c, --constants)

x86lint -c replaces the lint scan with a census of constants: which immediates the code carries, what they cost in encoding bytes, and which a function carries more than once. It is the x86 counterpart of armlint's -c report on MOVZ/MOVK chains, under the same letter. It sweeps the same bytes as -i and -r, carries the same evidence labels, and combines with them and with -f.

$ ./x86lint -c /usr/lib64/libc.so.6
constant census: 359838 instructions, 0 undecodable bytes skipped
  immediates by encoded width: imm8 33983, imm16 139, imm32 19990, imm64 532; 118477 bytes, 7.75% of the 1528109 bytes swept
  wide immediates (imm32 and imm64): 20522 carrying 1447 distinct values, 84216 bytes (5.51%)
    materialized into a register by MOV: 10533 (44260 bytes)
    stored by MOV or PUSH: 4980 (19920 bytes)
    consumed in place by an operation: 5009 (20036 bytes)
    imm32 fitting a sign-extended imm8: 13004; MOV carries 12935 (8130 into a register, 4805 to memory) and TEST 69, and neither has an imm8 form
    a one-byte form for them would save 39012 bytes (2.55% of the bytes swept); the other 0 are ALU, PUSH and IMUL, which have one
    imm64, which MOVABS alone carries: 532 building 148 distinct values, 4256 bytes (0.28%)
  repeats within a function: 8811 in 1060 of 3897 functions, 35900 bytes (42.63% of the wide-immediate bytes); 1 wide immediate in no function
  how often a function carries a value it repeats: twice 1720, 3 times 559, 4 times 236, 5 or more times 545
  most bytes spent on one value:
        bytes    sites      mov    store    imm64  value
        10620     2655     2161      494        0  32-bit 0x1
         6436     1609        1     1608        0  64-bit 0x0
         4844     1211      976      235        0  32-bit 0xffffffff
         4324     1081      144      937        0  32-bit 0x0
    ...
    (1427 more distinct values)
  most bytes spent repeating one value within a function:
        bytes  repeats functions  value
         6396     1599       410  32-bit 0x1
         3920      980       324  64-bit 0x0
    ...
    (421 more distinct values)
  functions: 3897 sized from .symtab
  code evidence: 9896 function symbols + 3799 .eh_frame FDEs + 0 Go pclntab functions covering 1497314 of 1528109 executable bytes

x86 has no constant chains: a constant is one immediate field, and the field's width is what it costs. A value in -128..127 rides in one byte on almost any instruction, a wider one costs four, and a 64-bit value that does not sign-extend from 32 bits costs eight and is carried by MOV alone (MOVABS), so a comparison against it or a mask by it has to materialize it into a register first. The census tallies every immediate by encoded width and keys the wide ones -- imm32 and imm64 -- by value, so the top of the table is the binary's signature constants: hash multipliers, error codes, tag masks, field offsets. Values are keyed at the effective operand width, as the register would hold them: mov eax, 0xffffffff and mov rax, -1 are two values, while mov rax, -1 (imm32, sign-extended) and movabs rax, -1 (imm64) are one, and the imm64 column says how many of a value's sites took the eight-byte encoding. The mov and store columns split a value's sites into materializations into a register and stores to memory (MOV mem, imm and PUSH imm); the remainder are operations consuming the value in place.

Two lines are the reason the census exists:

  • imm32 fitting a sign-extended imm8. Every ALU instruction has a byte form for a small immediate, which is why compilers never emit add eax, 0x00000001 and the oversized-immediate check finds so little. MOV has none, for a register or for memory, and neither does TEST above a byte operand: mov eax, 1 is five bytes and mov qword [rsp+0x28], 0 eight, four of them an immediate whose value fits one. Those sites are two thirds of a C++ binary's imm32s, and a one-byte form would save 2.0-3.4% of code bytes across the corpora measured on 2026-11-05 -- the size of the register-numbering cost, and more uniform across compilers, because it is the instruction set's cost rather than the compiler's. The line also says what the top of every value table is made of: libxul's commonest wide constant is 64-bit 0x0, 224,602 sites of mov qword [mem], 0.
  • Repeats within a function. A repeat is a wide immediate whose value an earlier instruction of the same function already carried, in address order; neither dominance nor liveness is checked. It bounds what keeping the value in a register could save -- the second MOVABS of a value is ten bytes a register copy would make three -- and does not measure it: an imm32 consumed in place is the idiom x86 offers for free, and a rebuild after a call can be cheaper than a spill. The functions are the sized symbols of .symtab, or the exports of .dynsym when .symtab is stripped, and the functions: line says which. A stripped distro library's exports bound little of its code (Fedora's libxul exports 2 functions), so the count then covers almost nothing and the report says how many wide immediates fell in no function. The driver does not read MiniDebugInfo; the mining tools do.

The imm64 line is the chain census proper, and it finds what armlint's finds on AArch64: libLLVM materializes splitmix64's multiplier 0xbf58476d1ce4e5b9 -- DenseMap's pointer hash -- 19,151 times (153 KB), 1,218 of them in one function, and libxul's clang build carries SpiderMonkey's UndefinedValue tag 0xfff9800000000000 15,046 times and the header words of an empty nsString and nsAutoString 24,390 times between them. Fedora's GCC build of the same source has none of the tag in its top twenty and 15,209 mov eax, 0x1fff3 instead: 15,178 of them are followed by shl rax, 47, GCC's nine-byte spelling of the ten-byte MOVABS, and this census keys that pair by its parts -- x86's one chain, and the piece of armlint's chain tracking a port turns out to want. GCC emits the pair only where it optimizes for size (-Os, or code its profile calls cold: 13,463 of the Fedora pairs sit in the PGO cold partition, against 2,059 MOVABS in the hot one) and only into rax-rdi, where mov r32, imm32 has no REX prefix and the pair is actually the shorter spelling.

-v adds each value's first three sites and, for a repeated value, the function that carries it most often with its first sites there. Immediates a relocation will rewrite are masked out as the lint scan masks them, so a kernel module's mov r64, imm32 placeholders do not count as the value 0. imm8 and imm16 are counted and costed but not keyed by value. The measurements and their reading are in TODO.md ("Constant census").

Inlining census (-n, --inlining)

x86lint -n replaces the lint scan with a census of what the compiler left as a call: where every direct call goes, and how many go to functions so small that the call is most of what the caller pays for.

$ ./x86lint -n /usr/lib64/libc.so.6
inlining census: 359838 instructions, 0 undecodable bytes skipped
  calls: 12887 direct (call rel32), 550 indirect (through a register or memory)
    direct calls to a function start: 9676; into a function elsewhere than its start: 1; to a linker stub (PLT): 3210; to no sized function: 0
  tail jumps: 629 to another function's start, 96 to a linker stub; 63 jumps to a .cold fragment stay with their function
  callees by body bytes (the function's size less a leading ENDBR64, a frame-pointer frame and a trailing RET):
        body  functions      calls  tail jumps  share of direct calls
           0          2          2           0  0.02%
         1-8         31        177           3  1.37%
        9-16         52       1266          29  9.82%
       17-32        118        936          68  7.26%
       33-64        170        936          51  7.26%
      65-128        254       2059          69  15.98%
     129-256        377       2084         129  16.17%
        257+        633       2216         280  17.20%
  calls to functions of at most 16 body bytes: 1445 (11.21% of direct calls) to 81 functions
    of the functions: 60 exported in .dynsym (1406 calls), 49 forwarding with a final jump (322 calls), 2 empty (2 calls), 0 recursive
    replacing each call with its callee's body would add 13247 bytes before anything the inliner then simplifies; 12 of the calls have a body under the call's five bytes
  the functions of at most 16 body bytes most called:
       calls   tail  body  size  function
         896      0    16    20  <__stack_chk_fail> (exported)
         117     15    15    19  <__GI___dcgettext> (exported, forwarder)
          66      0    16    20  <__GI___chk_fail> (exported)
          51      0     7    12  <__GI___close_nocancel_nostatus> (exported)
          32      2    10    14  <__GI___pthread_mutex_unlock> (exported, forwarder)
    ...
    (61 more functions)
  functions: 3897 sized from .symtab
  code evidence: 9896 function symbols + 3799 .eh_frame FDEs + 0 Go pclntab functions covering 1497314 of 1528109 executable bytes

Every direct near call is placed against the binary's function ranges: on a function's start, inside a function elsewhere than its start, in a linker stub (the PLT and its variants, so an import reads as one rather than as a call to nothing), or on no sized function. Unconditional jumps that leave their function for another's start are tail calls and are counted beside the calls; a jump to a .cold fragment is its function continuing and is counted apart. Function ranges come from .symtab, or from the exports of .dynsym when .symtab is stripped, and the functions: line says which: a stripped distro library's exports place only the calls to exported functions, and the line counts the rest as calls to no sized function. A relocatable object's calls are resolved by relocations and are not placed. Under -f the call sites come from the named function and every function stays a callee.

A callee is measured by its body: the symbol's size less a leading ENDBR64 (four bytes a CET build spends in every function), a frame-pointer frame (push rbp ; mov rbp, rsp at the start and pop rbp before the return, five bytes a frame-pointer build spends in every function) and a trailing RET, so a function that returns a constant measures as the bytes that compute it, an empty one measures 0, and a Fedora build's 20-byte symbol measures as the 10 bytes it does work in. The headline is the calls to functions of at most 16 body bytes, with three kinds told apart: a forwarder ends in a jump to the function that does the work, so a call to it is a call that could have gone there directly; an empty function has a body of 0 bytes; and an exported one is interposable from outside the object, which is why GCC under -fPIC leaves its calls alone. The size counterfactual is the plain one -- each call replaced by its callee's body, nothing simplified -- so it mostly says that tiny functions cost dynamically (a call/return pair, a return-predictor entry, the calling convention) rather than in bytes, except for the calls whose callee's body is under the call's own five bytes, which it counts.

Measured on 2026-11-05 (see TODO.md, "Inlining census"), the tiny callees are mostly there on purpose -- Go's stack-growth and write-barrier stubs are 98.7% of its 22.6%, glibc's __stack_chk_fail is 62% of its 11.2%, and Rust's handle_alloc_error leads libxul's -- and the real misses are the empty and near-empty functions a cross-translation-unit call reaches in a build without LTO: an empty debug hook called 3,837 times in libxul, 92 empty exported functions with 1,105 calls in libLLVM. The controls behind that reading: two translation units at -O2 leave 92% (GCC) and 96% (clang) of their calls to tiny functions in place and -flto removes every one; a shared object under GCC's -fPIC sends its calls to its own exported functions through the PLT rather than leaving them as direct calls, so GCC's semantic-interposition cost hides in the to a linker stub count, not in this census's headline.

-v adds each ranked function's first three call sites. -i, -r, -c and -n share one sweep and may be combined.

JCC erratum audit (-j, --jcc)

Skylake-derived cores cannot cache a jump in the decoded-icache when the jump's bytes cross a 32-byte boundary or its last byte is the last byte of one; fetch falls back to legacy decode, and the cost is paid per execution, so a hot loop pays it every iteration. x86lint -j reports whether a binary was built with the assembler padding that avoids it.

This is the one report here that is a verdict rather than a finding. Every check in the table above reads an instruction and says its bytes could have been better; here the bytes are fine and what is wrong is where they landed, so the fix is padding something earlier -- one build flag, not a rewrite -- and no single one of the 10-13% of jumps that touch a boundary is individually at fault.

$ ./x86lint -j /bin/bash
JCC erratum audit: 254073 instructions, 0 undecodable bytes skipped
  Jcc 30799 + JMP 12442: 5458 touch a 32-byte boundary (12.6%), 5688.50 expected unpadded
  verdict: mitigation absent (witnesses at the rate chance predicts)
  not in the verdict's scope: 29266 fused compare+Jcc pairs (6428 touching), 19612 CALL (3018), 3032 RET (92)
  informational: the erratum is Skylake through Comet Lake, Cascade Lake included; pass -t skylake to count it

What makes the verdict sound without a calibrated threshold is that unmitigated code is exactly uniform with respect to the boundary. A jump of length L occupies [s, s+L-1] and touches a boundary precisely when s mod 32 >= 32 - L, which is L of the 32 residues, so each jump contributes L/32 expected witnesses and the expectation for a whole scan is its jump bytes over 32. That is arithmetic, not a fit, and the corpus lands on it: bash, glibc, libcrypto, ld.so and libxul report 10.7-12.9% of their Jcc and JMP on a boundary, every one of them within 5% of its own expectation. An object assembled with cc -Wa,-mbranches-within-32B-boundaries reports 0 of 2,366, for 2.6% more text.

The evidence is asymmetric, and the four verdicts say so. One witness is proof that whatever produced the code holding it did not pad, so mitigation absent needs no minimum sample; the absence of witnesses means nothing until enough jumps have been seen for chance to have produced one, so mitigation present requires a scan expecting at least eight. Between them, partially mitigated is a real configuration rather than a hedge -- a mixed link, or a toolchain that pads compiler output and not hand-written assembly, which is exactly what Go's own binaries are:

$ ./x86lint -j /bin/go | sed -n '2,3p'
  Jcc 113255 + JMP 52098: 92 touch a 32-byte boundary (0.1%), 16581.65 expected unpadded
  verdict: partially mitigated (witnesses far below chance -- mixed objects, or a toolchain that pads compiler output and not hand-written assembly)

Go pads what its compiler emits and not what its runtime hand-writes (padJump and isJump in src/cmd/internal/obj/x86/asm6.go, which makePjcCtx turns off for ctxt.IsAsm), and those 92 are the hand-written half. Its scope is also wider than gas's: CALL and RET come out at 55 of 104,059 and 8 of 28,022, where gas's -malign-branch=jcc+fused+jmp leaves both alone. Reading the out-of-scope line beside the verdict is what identifies which toolchain was at work, which is why those classes are printed and why they never decide the verdict -- that and the fact that whether a given compare and Jcc really macro-fuse depends on the core and on operand shape, so an approximate predicate must not be allowed to manufacture a witness.

Only -t skylake makes a missing mitigation a finding (exit 1); every other target, the conservative -t generic default included, leaves the report informational. The erratum is one named group of cores -- V8 enumerates the affected models and steppings in src/base/cpu/cpu-x86.cc -- so unlike every other per-core question here, the pessimistic reading is not the safe one: applied by default it would fail every binary on a system that may never run on an affected core.

The audit needs the address each jump will run at, which is why a relocatable object is judged only when the section holding it is at least 32-byte aligned. That is not a formality: gas raises .text to 32-byte alignment precisely when it pads, so that the padding it just inserted is not undone by a linker placing the section at 16 mod 32. Sections below that are counted and reported as skipped rather than guessed at. Sections with a real address -- a linked executable's, or the JIT addresses tools/jitdump2elf.py records -- are judged exactly.

The JIT case is the one this cannot be measured any other way. V8 implements the mitigation (Assembler::AlignForJCCErratum) and SpiderMonkey implements nothing, but V8's is gated on the host CPU actually having the erratum, so a dump's verdict describes the machine that produced it and not the engine: on an AMD host a V8 corpus reports mitigation absent, correctly, because nothing there needed padding.

Speculation thunk audit (-s, --thunks)

A retpoline replaces an indirect branch with a call to a thunk that returns to the intended target, so the branch predictor never sees an indirect transfer to mistrain; a return thunk does the same for RET, which is what Retbleed and SRSO attack. x86lint -s reports whether a binary was built that way -- -mindirect-branch=thunk[-extern] and -mfunction-return=thunk[-extern] in GCC, -mretpoline in clang.

Like the JCC audit this is a verdict: the transformation is not an encoding a peephole could suggest, no one unrouted return is at fault, and per site it would be one finding per return in the binary. The signal is about as close to binary as this tool gets, and it is positive on both sides rather than inferred from absence -- a routed build names the thunk, in its relocations while it is still an object and in its symbol table once linked, and contains none of the instruction the thunk replaces.

$ xzcat /lib/modules/$(uname -r)/kernel/drivers/net/amt.ko.xz > amt.ko
$ ./x86lint -s amt.ko
speculation thunk audit: 8441 instructions, 0 undecodable bytes skipped
  returns: 0 bare, 75 routed through a thunk -- routed (the image names a return thunk and holds no RET)
  indirect branches: 0 bare -- none in this image

$ ./x86lint -s /bin/bash | sed -n '2,3p'
  returns: 3032 bare -- not routed (the image names no return thunk)
  indirect branches: 239 bare -- not routed (the image names no indirect thunk)

Fedora's own kernel is the proof that this is worth checking: across 60 shipped modules, 59 report routed and one has no returns at all to judge. Not one reports a hole, which is the calibration -- a verdict that fired spuriously on real input would be useless for the audit it exists for.

The one thing reported as a finding is a hole, not an absence. A bare RET in an image that names a return thunk means the build asked for the mitigation and something escaped it -- hand-written assembly the conversion missed is exactly how that happens -- so that exits 1. A binary that names no thunk never opted in, and saying so is describing a build rather than judging one: these are kernel and hypervisor mitigations, userspace does not use them, and unlike the JCC erratum there is no -t value that would change the answer, because what decides is what the binary is and not which CPU runs it.

A thunk's own body is excluded, and it has to be. The trampoline GCC emits ends in the very RET it exists to replace, and a retpoline's ends in a RET that jumps to the target it pushed. Without excluding those bodies, an image that defines its thunks rather than importing them would always report a hole, and the hole it reported would be the mitigation itself. GCC also emits both symbols with st_size 0, so the extent comes from the next symbol in the section -- the same rule the scan applies to an unsized assembly label.

Two limits worth stating. The routed count is exact only while the object is relocatable, since a linked image has resolved those branches into ordinary direct ones; there the symbol's presence carries the verdict and the count reads zero. And a linked image is judged whole, passengers included: a retpoline-built program linked against an ordinary libc reports INCOMPLETE because libc's returns really are unrouted, which is accurate but says more about the link than about the code. A kernel module has no such passengers, which is why it is the case with clean semantics.

Build-property audit (-p, --properties)

x86lint -p reports build properties that a function's own code reveals, as fractions of the functions rather than facts about the image. That makes the symbol table part of the measurement rather than an optimization: a stripped binary has no denominator, which is the one contract this shares with nothing else here.

It answers two questions so far: what fraction of functions carry a stack canary, and what fraction keep a frame pointer.

$ ./x86lint -p /bin/go | sed -n '2,4p'
  stack protector: 0 of 14862 functions (0.0%) -- no stack protector
  frame pointers: 12490 of 14862 functions (84.0%) -- kept (-fno-omit-frame-pointer; leaves that need no frame have none)
  measured over the function symbols in .symtab

Stack protector

The fraction is the point. checksec and hardening-check read the symbol table and report whether __stack_chk_fail is present, which is a yes or no; counting the functions that actually load the guard separates none from some from every one, which is what distinguishes the three flag settings. Verified against all three: 0% with no flag, 25% under -fstack-protector-strong for the one function of four with an escaping array, 100% under -fstack-protector-all.

$ ./x86lint -p /usr/lib64/libc.so.6 | sed -n '2,3p'
  stack protector: 1513 of 6943 functions (21.8%) -- -fstack-protector or -strong
  measured over the function symbols in .symtab

$ ./x86lint -p /usr/lib64/ld-linux-x86-64.so.2 | sed -n '2p'
  stack protector: 1 of 474 functions (0.2%) -- no stack protector (the guard is read but no handler is named, so this is where it gets set up)

The loader is why the verdict rests on two signals and not one. Reading the guard is not being protected by it: ld.so touches %fs:0x28 in exactly one function, that being where the guard is established for everyone else, and it names no __stack_chk_fail at all. An earlier version called that binary -fstack-protector on the strength of one initializer. A protected function must be able to fail, so with no handler named anywhere the verdict is no stack protector however many functions touch the slot.

The converse is a verdict of its own. A handler named with no examined function reading the guard means the protected functions are outside the sample, not that there are none: Firefox 160's libfreeblpriv3.so exports two functions, neither reads the guard, and the code .dynsym does not list holds 536 guard loads. An earlier version called that no stack protector too, on a sample of two. The report now says the protection is in code the sample does not cover, and names the handler as the reason it knows.

Which functions -strong protects is not decidable from the bytes -- it turns on having a local array or an address-taken local -- so the partial verdict names both flags and does not choose between them. The audit is informational and never sets the exit status: coverage is a policy choice rather than a defect at any level, and partial coverage is precisely what -strong means.

Two things to know about the denominator. .symtab is preferred; where it has been stripped -- most distro binaries -- the audit measures over .dynsym instead and says so, because exported functions are a biased sample of a library's but a biased fraction still answers the question where no sample answers nothing. And the guard load is not a prologue-only phenomenon: GCC schedules it wherever the register pressure allows, and the first version of this measured only the first dozen instructions of each function, which undercounted /bin/bash by 35%.

Frame pointers

A push rbp immediately followed by mov rbp, rsp, near enough the entry to be the prologue. Both halves are required and the pairing is most of the work: 1,031 of bash's functions open with push rbp and only 753 follow it with the mov (counted together over one disassembly), the other 278 using rbp as an ordinary callee-saved register.

"Near enough" is four instructions rather than zero, which is the other half of the work. A CET binary opens every address-taken function with endbr64, and Go opens most functions with a two- or three-instruction stack-growth check before the identical pair -- allowing for that moved /bin/go from 4.8% to 84.0%, so a window of zero would have reported a language whose runtime maintains frame pointers throughout as having none. An assignment to rbp before the pair disqualifies it, since a pair following one is not establishing a frame.

The reading is a nonzero share against a zero one, not a high one: a leaf that needs no frame does not get one even under -fno-omit-frame-pointer, so no real build reaches 100%. Fedora's binaries report 26-46%, /bin/go 84%, and an ordinary -O2 object none at all. This is why the finding population x86lint reports on libxul includes 34,930 mov rbp, rsp writes killed by a later pop rbp: that is a build-flag artifact rather than dead code, and this line is what says so.

Mining tools

tools/ holds the research utilities that feed x86lint's check backlog, built separately with XED_PATH=/path/to/xed make tools (which also builds tools/rwfuzz, the execution test described under Compilation):

  • tools/shapescan sizes a named candidate with the rewrite's own conditions applied, and says what refused the rest. Where pairscan ranks shapes to find what is frequent, a TODO row turns on whether a specific rewrite is available at a site, and measuring that ad hoc is what this exists to stop: the 2026-09 armlint port was sized four times with throwaway scripts and was wrong four times, three of them overstating the rewrite by 20x or more because a condition went unapplied. Candidates are therefore C predicates rather than patterns -- each needed operand-role matching, branch arithmetic, encodability through XED or a liveness walk -- and the file includes x86lint.c to call the shipped checks themselves, so a shipped candidate is measured by the code that realizes it and an unshipped one is a draft check that moves rather than being rewritten. Each reports three things: how often the pattern matched, how often the rewrite was available, and which gate refused the difference. The third is the point -- "18,236 sites become 583" is a puzzle, while "9,126 read the loaded register again and 5,743 have no memory form in that operand slot" is an answer. -e NAME prints example sites
  • tools/pairscan counts adjacent-instruction pairs by normalized shape across the executable sections of an ELF binary, surfacing frequent patterns worth a new check. Registers collapse to a class and width (with RAX, RCX, RDX, RSP, and RBP kept distinct), immediates to #0/#1/#-1/#i, memory to [base+index*scale+disp]:width, and the Jcc, SETcc, and CMOVcc families to one token each. Every pair is tagged with how the two instructions couple: dep and waw on registers, fdep and fdead on the flags -- the last being the gate that decides whether a flag-disturbing rewrite is legal. -e SUBSTR prints example sites for matching shapes.
  • tools/defuse profiles block-local def-to-use distances -- how far a value's sole consumer sits from its producer, bucketed so a window can be sized against it -- and the multi-instruction redundancies no pair statistic can see: dead definitions, redundant reloads of one address, re-materialized constants, and zero compares of a value whose producer already set the flags.
  • tools/cohere measured whether cheap per-instruction "coherence" signals -- run length between undecodable gaps, gap adjacency, and three-walk self-synchronization consensus -- can separate real instructions from phantom decodes of data-in-text, toward gating the census. All three fail on ground truth (a GHC binary's phantom x87 reaches 92% consensus: self-sync is a decoder property, and junk converges onto its own stable chain); what separates every tested case instead is toolchain evidence, .symtab ranges and .eh_frame FDEs. The tool's header records the measurements; the census's evidence labeling (the unevidenced annotations and code evidence line) is what they argued into existence.
  • tools/split.py splits a mixed C++/Rust binary's findings by language. It takes x86lint -v or tools/shapescan output and attributes each finding to the function containing it, and the function to C++ or Rust by its mangling. Unmangled C and #[no_mangle] functions take their neighbors' language in address order. A stripped binary's functions come from its .gnu_debugdata MiniDebugInfo. It prints per-million rates for each side, plus two compiler fingerprints that check the split. --cold-below reports how much of each C++ count sits in GCC's size-optimized cold partition. The libxul split in TODO.md is its output.
  • tools/framescan sizes the frame-layout counterfactual: of the bytes a binary pays for 32-bit displacements on its stack-slot accesses -- three per access past 127 bytes from the base register, a cost no instruction check can see because every access is correctly encoded for the offset the compiler gave it -- how many a frequency-aware slot order would recover. It is the register census's question asked of the frame: a whole-function cost, split into what a different allocation saves and what is structural. Each .symtab function's explicit RSP-based accesses (and RBP-based ones under a frame pointer, by -p's prologue rule) are keyed to slots relative to the return address, with RSP's depth tracked through pushes, frame allocation and stack-clash probe loops; the slots divide into incoming arguments (the ABI's), pushed registers (the prologue's) and locals (the layout's), and a 0/1 knapsack per base asks which locals fitting in the 128-byte disp8 window -- less the pushes, below RBP -- cover the most accesses. Three bytes times the accesses that gains over today is the bound. It weighs accesses statically and treats slots as independent, so it is an upper bound, and -f NAME dumps a function's slot table to check against objdump; -m dumps the functions behind its own contradiction counter. Code the build has marked profile-cold weighs nothing in the bound: .cold fragments by name, and under -c ADDR every function below that address, which is how GCC's hot/cold split lays a PGO binary out (the end of its highest .cold fragment is the boundary; tools/split.py --cold-below is the same knob). Measured in TODO.md, "Frame layout": 4.1-4.9% of code bytes in GCC output and 7.7% in Go, of which 18-76% is recoverable by the bound, the low end being Fedora's PGO libxul once its cold partition is weighed as the profile says.

All of them restrict the scan to the symbol table's function ranges and skip the dynamic linker's import glue exactly as the driver does, so no pair or distance spans two functions, none is mined from the non-code that executable sections interleave, and none counts the PLT's one fixed template as though a compiler had emitted it; -A scans every byte (framescan has no -A: without function boundaries there is no frame). A binary whose .symtab was stripped but that kept MiniDebugInfo -- the xz-compressed symbol tables Fedora leaves in .gnu_debugdata for gdb -- gets its ranges and names from there, which is what makes a distro library a per-function corpus; the tools link liblzma (xz-devel) for it, and the linter does not. Two functions that abut with no padding between them are two ranges: until 2026-11 the loader merged them, which the pair and distance tools barely noticed and a per-function tool could not survive. The workflow behind several current checks: run pairscan over a representative corpus, classify the top shapes as by-design or foldable, then use defuse to decide whether a candidate needs adjacency only or a liveness window -- the measurement APX_NDD_WINDOW's default rests on.

Both lean on XED's operand model, which is exact about the compare aliases where Capstone is not, but reports CMOVcc as a plain write to its destination. That is right about the encoding and wrong about the dataflow -- the prior value survives a not-taken move -- so the tools add a conditional writer's destination to its read set, the same correction reg_kill_iclass embodies in x86lint.c.

JIT output

A JIT has no object file: its code lives in an anonymous mapping that disappears with the process, which is why every measurement in this project's backlog that mentions a JavaScript engine was made by reading disassembly text rather than by running the tool. tools/ converts what an engine can be made to hand over into an ELF object x86lint scans like any other, so the whole check table applies to JIT output:

  • tools/v8dump2elf.py reads a V8 --print-opt-code listing, which already carries the encoding bytes, so nothing has to be patched. d8 --print-opt-code bench.js | python3 tools/v8dump2elf.py - -o v8.elf and then ./x86lint -m v8 v8.elf; the -m v8 flag is what tells the linter that R13 holds a 4 GB-aligned pointer-compression cage base, which is the invariant the OR-into-address fold rests on.
  • tools/jitdump2elf.py reads a container of raw code blobs -- "X86J" | u64 address | u32 code size | u32 name size | name | code, concatenated with no file header, so a dump from a process that was killed still parses up to its truncation. tools/spidermonkey-jitdump.patch adds the writer to jit::Linker::newCode, which every JS blob passes through -- Ion, Baseline, RegExp and the trampolines -- and a second call in wasm::CodeBlock::initialize, which every wasm block reaches once it is linked, so both wasm tiers and their stubs are recorded too. Each process writes <path>.<pid>, which is what lets a whole Firefox be dumped rather than only a shell: the parent and every content process link JIT code, and one shared file would be truncated by each of them. JavaScriptCore's LinkBuffer takes the same few lines, and the record is the whole interface. --raw reads a bare blob, which is what SpiderMonkey's disnative(f, "file") writes for one function with nothing patched at all. Both converters leave a blob's inline pointers -- its switch tables and the targets of its extended jump table -- outside the symbol ranges x86lint scans, because eight bytes of code pointer decode into whatever the heap address spells and none of it shows in the undecodable-byte count; in a browser that was 17.5% of the raw figure.
  • tools/jetstream3/run-browser.sh runs JetStream 3 in a headless Firefox built with the patch, serving the checkout on loopback and taking the driver's own POST /report as the end, and leaves one dump per process; run-shell.sh does the same in the js shell. tools/jitdumpstats.py turns the dumps into the per-process, per-tier and per-check tables the write-up below is made of, streaming -v text because a browser tab's findings do not fit in --json.

Both write one section per code object at the address the engine compiled it to, so a finding cross-references straight back into the dump, and separate sections stop a window peephole from walking off one code object into the next. Each section gets an STT_FUNC symbol naming the tier and, where the engine reveals it, the JS function -- so the by-function table is a per-tier breakdown and -v names the holder.

What they found, over Octane 9 and ARES-6 on both engines -- 10.4M instructions of JIT output, against the same engines' own compiled code -- is written up as "JIT corpora" in TODO.md. The headline is that JIT code carries six to nine times the findings per instruction that AOT code does, and that one check is nearly all of the difference: oversized branch displacement runs 33-59 per thousand instructions against 0.12-0.42 in compiled binaries. Every one of those 464,860 findings is a forward branch and none is backward, because both assemblers shorten a jump to an already-bound label and neither can know the distance to one that is not yet bound. Take that class out and JIT and AOT code are within a factor of two of each other, which is the reassuring half: the check table needs no JIT dialect. A whole headless Firefox on JetStream 3 -- 383 MB of code in the benchmark tab, both wasm tiers included -- gave the same picture at 35 times the size ("JetStream 3 in Firefox" in TODO.md), and two things a shell cannot show: a tab is 2,082 copies of the runtime's trampolines, one per Worker, and the three classes the engine writes on purpose and a linter reads as waste -- movabs patch placeholders, or r14, 0 slow-call markers and jmp -1 far-jump slots -- are 6-7% of the findings and account for every "backward" branch.

References

License

Copyright (C) 2018 Andrew Gaul

Licensed under the Apache License, Version 2.0

About

Examine x86-64 machine code to find suboptimal encodings and sequences of instructions

Topics

Resources

Stars

19 stars

Watchers

1 watching

Forks

Releases

Contributors

Languages