Repository navigation
v0.10.0
0.1.0 was a 676-line position-independent assembler and patch-site finder with
26 instruction encodings. 0.10.0 is roughly twenty thousand lines: a decoder
and encoder for essentially the whole Thumb and Thumb-2 instruction set, an
instruction relocator built on it, and a trampoline installer built on that.
The crate went from emitting Thumb to reading it, which is what makes
patching over live code possible rather than only over a known prologue.
Three things that shipped in 0.1.0 break. They are listed first, because they
are the only reason this is not a drop-in upgrade.
Breaking changes
-
DetourError::Installhas been removed. The variant named a failure whose
precondition set is empty:detour's planning phase already proves the site is
in bounds, that the hook branch encodes, and — viaStubOverlapsSite— that
writing the stub cannot touch the site's four bytes. What remained was
install_branch's read-back, and a write to a&mut [u8]followed by a read
cannot disagree under Rust's memory model. The commit is now two infallible
stores and the read-back survives as adebug_assert_eq!post-condition, which
makes the code match what the module's Atomicity section already claimed. -
find_free_spacetakes a requiredalignparameter. The signature is now
find_free_space(image, len, align, start). Alignment has to be accounted for
during the scan, not by rounding up a run that was already found: rounding
the start up moves the start without moving the end, so a run that was exactly
long enough stops being long enough and the caller gets an offset whose tail
overlaps live bytes. Pass4for anything destined forAsm::finish, whose
literal-pool offsets are computed againstAlign(PC, 4); pass1for raw
data, which is the pre-0.10 behaviour. Panics ifalignis 0. -
Needle::FreeRunis a struct variant.Needle::FreeRun(len)is now
Needle::FreeRun { len, align }, for the same reason. Anymatchover
Needlehas to be updated. -
Asm::mov_regno longer writes the condition flags. See Fixed below for
what it used to emit and why that was wrong. Callers that wanted the old
flag-setting behaviour must switch to the newAsm::movs_reg; callers that
wanted a register move need no change and were previously getting a silently
different instruction.
One further shape change affects nobody on crates.io but does affect anyone
tracking dev: isa::Mem stores its offset as an unsigned magnitude plus a
separate add: bool — the architecture's U bit — rather than as a signed
i32, and gained an align: u16 field for Advanced SIMD's [rn:64]
qualifier. AddrMode gained a fourth variant, PostIncrement, for the
[rn]! form of the element and structure transfers. Mem::displacement()
returns the signed byte count for consumers that only want the effective
address.
Added
isa — the decoder, the encoder and the instruction vocabulary
isa::Decoder— anIterator<Item = Insn>that walks a Thumb stream from
a known start and tracksITSTATE. The 1–4 instructions after anIT
carry no condition in their own encoding, so a decoder that ignoresIT
reports them as unconditional — silently, and in the one place where being
wrong changes control flow. Instructions decoded inside an IT block come back
withInsn::condalready filled in.Decoder::atdecodes from an offset that
is not the address;.thumbee(true)selects ThumbEE state;pos,it_state
andskipare there to resynchronise past an undefined encoding.isa::decode_at,decode_at_with,decode_halfwords— decode one
instruction, from an image or straight from a halfword pair.
isa::insn_lenis the whole of Thumb's length rule:hw1[15:11]decides
and nothing else is consulted (ARM DDI 0403E.e A5.1).isa::encode/isa::encode_bytes— the inverse. Dispatch is verified,
not trusted: a mnemonic does not identify an encoding group —addlives in
five of them — soencodeoffers the instruction to each group in turn and
decodes every candidate again, comparing it against the instruction asked
for, before returning it. A mismatch is discarded and the next group gets a
turn. With a bare fallback chain the whole thing would only be as correct as
its least strict member, and a group accepting a neighbour's instruction would
emit the wrong encoding while every module's own tests stayed green.isa::disassemble—countinstructions from an offset as UAL text.isa::insn— the shared vocabulary every group module speaks:Insn
(mnemonic,encoding,addr,width,cond,sets_flags,
explicit_width,operands) withis_branch,is_call,writes_pc,
branch_targetandlen;Operand,Operands(a fixed inline array,
MAX_OPERANDS == 6, so decoding allocates nothing),Mem,AddrMode,Reg,
FpReg,Shift,ShiftKind,ShiftAmountandWidth.Insn,Operand,
RegandWidthare re-exported at the crate root.- Nineteen group modules, one per numbered sub-table of Arm's architecture
reference manual, so a review is one section ofspec/THUMB-ISA.mdbeside one
table of Arm's beside one file of the crate's: the six 16-bit groups of A5.2,
the twelve 32-bit groups of A5.3 (including the coprocessor, floating-point
and Advanced SIMD space), and ThumbEE's re-assigned 16-bit map from
DDI 0406 A9.2.1. - Coverage, counted rather than asserted. Thumb's length rule partitions
every bit pattern a Thumb stream can present into 59,392 single halfwords and
402,653,184(hw1, hw2)pairs, and both are small enough to enumerate, so
spec/THUMB-ISA.md§4 states coverage as an exhaustive count of all
402,712,576 of them rather than as an adjective. 58,233 of the 59,392
16-bit halfwords decode — 98.05% — with the 1,159 exceptions named one at a
time rather than left as a remainder, and 3,840 of ThumbEE's 4,096
re-assigned halfwords. Over half of the wide space decodes; §4.2 has the
module-by-module table, whose rows partition the whole space so the total is
a sum rather than an estimate, together with the distinct-mnemonic and
(mnemonic, encoding)counts. §4.3 explains why the wide-space ratio is not
a coverage grade: most of the 32-bit space is UNDEFINED by construction —
Table A5-9 leaves wholeop2rows unallocated,t32_dp_regrejects fifteen
sixteenths of its space before decoding anything — and a decoder scoring
higher there would be wrong. - One refusal policy, stated once (§4.4):
decodereturnsNoneonly for
an encoding the table does not allocate, for a should-be-zero or should-be-one
bit holding the wrong value —Insnhas nowhere to put it, so decoding would
discard information and re-encode to a different pattern — and for an
UNPREDICTABLE encoding with no representable UAL. The converse is applied just
as uniformly: an UNPREDICTABLE choice of operands is decoded, because
pop.w {lr, pc}is exactly the malformed code a reverse-engineer is hunting
for and refusing it would hide it.
relocate — moving one instruction to a new address
relocate(insn, to),relocate_with(insn, to, widen)and
relocate_bytes— re-site a decoded instruction so it still means the
same thing somewhere else. Thumb has three ways for behaviour to depend on an
instruction's own address: a direct branch's displacement, a pc-relative
literal access based onAlign(PC, 4), and the handful of instructions that
readpcas a value. The decoder has already done the hard half, because an
Operand::Targetis the resolved absolute address, so relocation never
redoes pc arithmetic — it holds the target still and asks whether the new
displacement fits.- The case worth knowing:
Align(PC, 4)does not move linearly. Moving an
instruction two bytes changes a literal displacement by either zero or four,
never by two, so the temptingnew = old - (to - from)is wrong at every
second halfword and wrong in a way that still assembles. Widen::{Never, IfNeeded}— whether a narrow direct branch may be
re-encoded wide when the narrow displacement no longer reaches.relocate
never widens, because widening changes the instruction's length and a caller
laying out a fixed buffer has to be told; the widening form is asked for by
name. Only direct branches widen: a narrowADRorLDR (literal)is refused
rather than widened, because ±4095 is the same "cannot reach a pool from free
space" class as ±1020.RelocateError— eight variants, each naming the instruction and both
addresses, with a stablereason()string, plusmnemonic(),from(),
to()andis_address_dependent(), which is what tells a caller whether
retrying at a different address could possibly help.
detour — the headline verb
tramp(image, site, hook)anddetour(image, site, hook, opts)—
decode the instructions a four-byte hook branch would displace, relocate them
into a stub, branch back, and install the hook. This is the thing that cannot
be written without a decoder, because patching four bytes over an arbitrary
address is four ways wrong and every one of them is silent: it cuts an
instruction in half; it moves an instruction out from under itsIT, so a
conditional instruction runs unconditionally in the stub; it relocates a
pc-relative instruction as a byte copy; and it half-applies.- Refusals are specific and atomic.
DetourErrorhas fifteen variants, each
with a stablereason()—"splits-it-block","site-not-aligned",
"site-in-it-block","no-free-space","site-unreachable",
"hook-unreachable","resume-unreachable","relocate"(wrapping the
RelocateErrorthat says which instruction could not be moved), and the rest.
On any error the image is byte-for-byte unchanged: every fallible step —
decoding, the IT checks, relocating each displaced instruction, encoding all
three branches, the free-space search, every bounds check — happens in a
planning phase that takes&[u8], and only then are the two writes issued.
The stub is written first on purpose, so that even an impossible failure of
the final verification leaves an unreferenced blob in free space and an
untouched site rather than a live branch into free space. Detourreportssite,displaced(always a whole number of
instructions, so 4 or 6, never 5),stub,stub_len,kind, andresume().DetourOptions—kind(BranchKind::Blby default;BWidepreserves
lr, which is what a tail-call site needs),convention,search_start,
stub_atfor a consumer with its own allocator, andscan_from, a known
instruction boundary at or before the site. Withoutscan_fromthe IT state
entering the site is assumed inactive and the site is assumed to be an
instruction boundary, neither of which can be checked from the site alone,
because a Thumb stream cannot be decoded backwards; with it, both are checked.Convention::CallThenContinuecalls the hook and then runs the original;
Convention::HookDecidesjumps to the hook withlruntouched andr12
pointing at the relocated code, so the hook can run the original, return
without running it, or do something else — which is the convention for a gate
whose answer is "deny".
analysis — the derived questions
xrefs(image, target)— every reference to an address, instruction-
accurate, over all four ways a Thumb image names one: a direct call
(XrefKind::Call), a direct branch includingcbz/cbnz
(XrefKind::Branch), a 4-byte data word (XrefKind::LiteralPool), and an
address materialised frompcbyadr(XrefKind::PcRelativeAddress). Each
Xrefcarries the mnemonic that produced it, because the distinction inside a
kind is often the one that matters. This supersedesfind_bl_sites, which
answers a strictly smaller question and answers it unsoundly.function_start— a documented heuristic, with its failure modes written
down rather than implied.literal_value— what anldrliteral actually loads, resolving
Align(PC, 4)through the decoder instead of by hand.nop_fill— blank code withNOPT1, because0x0000ismovs r0, r0
and writes the flags.reachable/Reach— a control-flow walk from an entry point,
reporting what was reached, what could not be followed, an over-approximate
end, and whether the walk itself ran out of road, as four separate facts.veneer— an 8-byteldr.w pc, [pc]plus literal, for a target too far
for any branch encoding.
Image, branch and error surface at the crate root
read_u16— the little-endian halfword read that was missing beside
read_u32/read_u8. A halfword is the unit a Thumb image is made of, and
consumers were open-codingu16::from_le_bytes([image[at], image[at + 1]])at
every signature-scan site.try_read_u8,try_read_u16,try_read_u32—Option-returning
siblings of the panicking reads, for scans that walk to the end of an image.decode_b_cond/CondBranch/encode_b_cond— a generic
conditional-branch codec covering both encodings:B<cond>T1 (16-bit,
1101 cond imm8, A5.2.6) andB<cond>.WT3 (32-bit,S:J2:J1:imm6:imm11,
A5.3.4).decode_b_condreturns the condition, the absolute target and the
instruction width, so a caller can step over either form;encode_b_cond
picks the narrowest encoding that reaches. T3 is not packed likeB.WT4:
it has no I1/I2 inversion and the J bits are in the opposite order, and the
two encodings differ only inhw2[12].- Conditional-branch emitters on
Asmfor all fourteen conditions —bmi,
bpl,bvs,bvc,bls,bge,blt,bgt,blejoin the existing
beq/bne/bhs/bhi/blo, all one-liners over the new generic
Asm::b_cond(cond, label). Asm::movs_reg(rd, rm)—MOV (register)T2, the flag-setting register
move, low registers only. For callers who want the behaviourmov_regused to
have, by its right name.verify_branch,install_branch,BranchKindandInstallMismatch—
framework-agnostic detour installation and verification.install_branch
encodes, writes, then decodes the image back to prove the bytes mean what was
intended;verify_branchis that last step alone. Bit 0 is masked off both
sides before comparing, so either form of an address may be passed.
BranchKind::encode/decodedispatch over the existingencode_bl/
encode_b_wideanddecode_bl/decode_b_widepairs.Cond— the shared condition-code type (bits,from_bits,invert,
suffix,Display), carrying the architectural bit values, with0b1111
rejected rather than treated as a fifteenth condition.thumb_asm::Result<T, E = AsmError>at the crate root, so downstream code
can write-> thumb_asm::Result<Vec<u8>>.
Checked against an implementation nobody here wrote
tests/conformance.rs, a differential harness against LLVM, documented in
docs/CONFORMANCE.md. The round-trip sweeps prove the decoder and the encoder
agree with each other, which a systematic misreading of the manual satisfies
perfectly while still being wrong in both directions. This asks a second
implementation instead: bytes → our decoder → our UAL text → LLVM's assembler
→ bytes, asserting the bytes come back identical. All 59,392 halfwords of
the 16-bit space are swept, and 98% of that space round-trips through LLVM
byte-for-byte — over 99.9% of the patterns this crate claims to decode. The
32-bit space is covered by 669,696 structured probes and 200,000 pseudorandom
ones from a printed seed, reported separately so a gap is visible rather than
averaged away. Every divergence is enumerated in a 21-entry allow-list
(tests/support/divergences.rs), each entry carrying the architectural clause
that justifies it and a budget, set from the measured count, on how many
probes it may absorb; anything not
on the list fails the test. The harness skips and passes with no LLVM
installed, so a contributor without it still gets a greencargo test.
Changed
-
The test suite is now audited by mutation testing. 100% line, region and
function coverage says every line ran, not that any line was checked — and
three real defects in this crate had already lived under it.cargo-mutants
generates 7,475 mutants; 89.0% are caught, or 96.9% once the 588 survivors
that are provably equivalent (|swapped for^across disjoint bit-fields,
which cannot change the value) are set aside. The remaining 206 are recorded
indocs/CONFORMANCE.mdrather than glossed over. Three groups of fixes in
this release came directly out of that run: operand validation on theAsm
emitters, the tests pinning every clause ofInsn::writes_pcand
first_operand_is_source, and a test forprologue_len. -
The conformance harness was assembling its probes as Arm, not Thumb. The
dialect prologues wrote.thumbabove.arch, and.archresets the
assembler to Arm state, so every probe was assembled as a 32-bit Arm
instruction. LLVM 23 happens not to reset and LLVM 18 does, so this passed on
a developer machine and failed the first time CI ran the sweeps: the byte
round-trip fell from 98% to 0.36%. The disassembly comparison went on
agreeing throughout, because it reads the original probe bytes rather than the
assembled ones — which is exactly why the two directions are counted
separately. A second version-dependency went with it: the harness required
the.balignpadding after each probe to be zero, and.balign 16, 0x00in
an executable Thumb section is honoured literally by LLVM 23 and filled with
nopby LLVM 18. The sentinel's position is already the length check, so the
padding requirement is gone. -
The conformance harness now tests the printer the crate actually ships.
renderbuilt its own UAL text rather than callingInsn::Display, so what
the sweeps corroborated was a second printer that existed only in the test
suite — and a rule in the real one, forcingLDR (literal)T1 to print
[pc, #0]instead of the ambiguous[pc], was absent from the copy. The
divergence stayed on the allow-list as a known defect while the fix for it
sat in the shipped code, untested.rendernow delegates and performs only
the one documented substitution (an absoluteTargetbecomes LLVM's
pc-relative immediate); the eight affected probes round-trip byte-for-byte
and the allow-list entry is gone rather than kept as an excuse. -
A width suffix the assembler will not parse is now a test failure. When
LLVM refuses our text the sweep falls back to comparing its disassembly,
and that comparison strips.w/.nbefore matching — so an invalid suffix
was refused by the assembler and then forgiven by a comparison that could not
see it, landing in the bucket labelled "agreed".mul.wsat there across
282,000 probes. A separate check now offers every distinct suffixed form to
LLVM on its own and requires some dialect to accept it. -
The 32-bit probe vectors cover every
Rdand sub-opcode nibble. The
hand-picked second-halfword vectors never putr3,r6orr9inRd, and
reached several instructions only through a pattern namingpcin every
field — and<op> pc, pcis UNPREDICTABLE, which LLVM will not assemble, so
those instructions were corroborated only through the weaker disassembly
path. The structured sweep is now 669,696 probes rather than 282,624. -
Every allow-list budget is set from its measured count. They were round
numbers with up to fourteen times the slack of what they admitted, which
cannot detect a class growing. Each is now the observed count plus a small
margin. -
Fourteen allow-list citations pointed at the wrong section. They had
drifted against the DDI 0403E text inspec/:A7.7.24was cited for both
CPSandBICand is in factCLZ; all six numbers in the saturate/bitfield
entry named different instructions; three Advanced SIMD entries cited the
Armv7-M manual, which does not contain Advanced SIMD at all. Corrected against
the manuals inspec/, and the header comment now names DDI 0406B, which is
the A/R revision actually in the tree. -
Asm::mov_regnow emitsMOV (register)T1 and no longer touches the
flags — see Breaking changes above and Fixed below. It now emits
0x4600 | (d << 7) | (rm << 3) | (rd & 7)withd = (rd >> 3) & 1
(A5.2.3 / A7.7.77), which preserves the flags and additionally reaches
R8–R15, making it the only 16-bit way to mover8–r12,sporlr. -
Asm'sbeq/bne/bhs/bhi/blodelegate toAsm::b_cond; the encodings
are unchanged.b_cond(Cond::Al, label)deliberately emits the
unconditionalbrather than a condition field of0b1110, because in the
16-bit branch space0b1110is the permanently undefinedUDFand0b1111
isSVC. -
find_bl_sitesis superseded byanalysis::xrefsand its documentation says
so. It is still present and still supported; it answers a strictly smaller
question — directBLonly — by scanning every even offset, so it can land
mid-instruction and report a halfword pair that merely looks like aBL. -
Crate-level documentation rewritten to be consumer-neutral: it described one
specific firmware tool's private platform engines, which no longer reflects
how the crate is used. Same four-verb (find / read / modify-insert / create)
framing, no private names. -
CommandTable's documentation reframed: the MT1959 record layout is kept
because it is a genuinely useful worked example of what the geometry fields
mean, but it is now presented as one example rather than as the definition,
and the danglingcrate::engine::Enginedoc link is gone. -
Asm::lsls_immdocuments the A5-2 footnote alias:lsls_imm(rd, rm, 0)is
not a zero-bit shift, it isMOV (register)T2 and disassembles as
movs rd, rm— the same halfwordmovs_regemits. -
AsmError's documentation explains that because it is
std::error::Error + Send + Sync + 'static,anyhowalready accepts it
through its own blanketFromimpl, so a bare?in a function returning
anyhow::Resultworks with no.map_err. It also explains why ananyhow
feature flag is impossible rather than merely unimplemented: such an impl
would overlapanyhow's blanket impl and be rejected for coherence.
Fixed
-
Every
Asmemitter accepted operands no encoding field could hold. Each
one ORs its arguments into a fixed halfword, and none checked them first, so
an out-of-range value did not fail — it overflowed its field and assembled to
a different instruction.push(0x4000)produced0xF400, which is not a
push but the first halfword of a 32-bit instruction, so the two bytes after it
were swallowed as its second halfword and everything downstream decoded from
the wrong offset. The documentation invited exactly that call:push's example
gavepush {lr}as0x4000when the register-list bit forlris0x0100.
Operands are now validated at emit and the first bad one is reported by
[Asm::finish], which is the same channel an out-of-range branch already used
— there is no path that yields the corrupt encoding.Asm::bindon a label
that was never reserved indexed out of bounds and panicked; it is an error now. -
MULT2 printed a.wthat is not valid UAL. A7.7.84 gives the 32-bit
encoding the syntax lineMUL<c> <Rd>,<Rn>,<Rm>and offers no width
qualifier; LLVM rejectsmul.woutright. The two encodings are told apart by
their operands instead — T1 is<Rdm>,<Rn>,<Rdm>and sets flags outside an IT
block. Text this crate emitted forFB0n Fxxxcould not be re-assembled by
any assembler. -
ROR (immediate)was labelled encoding T2. A7.7.116 lists one encoding.
LSL,LSRandASRare T2 in this group because each spends a T1 on its
16-bit form, andRORhas no 16-bit immediate form to spend one on — which is
whyRRX, in the same table, was already correctly T1. -
analysis::reachableignoredITblocks, contrary to its documentation.
It decoded every instruction with IT state off, so an instruction made
conditional only by an enclosing block —bxeq lr, which has no condition
field of its own — was read as an unconditional branch and the walk ended
there. A function returning underITwas reported as stopping at the
conditional return, withcomplete: trueand no indication anything had been
missed. Deciding where a patch may go on that answer would put it on top of
live code.ITSTATEnow travels with each pending offset. -
try_read_u16andtry_read_u32panicked on an offset nearusize::MAX.
Both computedat + 2/at + 4before handing the range toget, so the
addition overflowed: a panic in a debug build, from the one family of functions
whose entire purpose is to be the non-panicking read — and in a release build a
wrapped range that can land back in bounds and silently return the wrong bytes,
which is worse. The offsets these take come from scans over attacker-supplied
firmware, and the triggering value is not hypothetical: a handler pointer read
out of erased flash is0xFFFF_FFFF, which masked to even is0xFFFF_FFFE—
exactly the offset that overflows on a 32-bit target. Both now use
checked_add. -
Asm::mov_regemittedadds rd, rm, #0and clobbered the flags. Through
0.1.0 it emitted0x1C00 | rm << 3 | rd, which is notMOVat all: it is
ADD (immediate)T1 withimm3 == 0, and it writes N, Z, C and V. Any
sequence that moved a register between acmpand itsb<cond>was silently
miscompiled, because the move destroyed the comparison's flags before the
branch read them. The flag-setting move now has to be asked for by name, as
Asm::movs_reg. -
find_bl_sitesmissed aBLoccupying the final four bytes of an image.
The scan bound was0..image.len().saturating_sub(4), which is exclusive of
len - 4— a legal site, and exactly where a trailing thunk or an
end-of-region dispatch table puts one. Nowsaturating_sub(3), so the last
offset examined islen - 4. The regression test was verified red against the
old bound. -
Memfolded the architecturalUbit into a sign, so#0and#-0
collapsed. Seventeen places in DDI 0403E.e say in as many words that
"different instructions are generated for #0 and #-0", and A7.7.51 lists
LDRD<c> <Rt>,<Rt2>,[PC,#-0]as an encoding in its own right. In ani32,
-0 == 0, so a sign-corrected offset destroyedUon decode and had to
invent it on re-encode — breaking exact re-encoding on 874 encodings across
the dual, load, store and coprocessor groups.offsetis now an unsigned
magnitude andaddis theUbit itself, so every bit pattern of the pair
denotes a distinct, legal addressing form. -
Advanced SIMD data processing was implemented but unreachable. The whole
VADD/VAND/VMUL/VSHLgrid lives int32_simd, but both halves of its
space setop2[6], which Table A5-9 gives to the coprocessor arm — so all
33,554,432 of those patterns decoded toNoneno matter how completely they
were implemented. The dispatcher now falls through fromt32_coprocto
t32_simdon both coprocessor arms, which is what makes NEON reachable at
all. -
A
t32_dp_regencoder wroteRdto the wrong nibble. Its second halfword
was built as0xF000 | rd << 12 | op2 << 4 | rm, puttingRdinhw2[15:12]
— the field the group's own first rule requires to be1111— wheredecode
correctly reads it fromhw2[11:8].Rdwas therefore discarded, and only
instructions whose destination wasr0re-encoded: 18,768 of 300,288,
exactly one sixteenth. The module's own sweep could not catch it, because
its test helper repeated the same formula and the two agreed; the
cross-module round trip through the publicisa::encodeis what found it. -
ItState::advanceadvanced only the mask, so the else-arm of everyITE
came back with the un-inverted condition.ITAdvance()(A7.3.2) shifts
ITSTATE<4:0>, andITSTATE<4>is the low bit of the condition, not the
top of the mask — so the shift crosses the cond/mask boundary and each step
pullsmask<3>intocond<0>. That bit is theT/Eselector, and it is
what makes the else-arms of anITE/ITTE/… block run on the inverted
condition. Advancing only the mask looks right and is right for an all-T
block, and hands back a silently wrong answer about control flow for every
Earm.ItState::advanceis now the pseudocode line for line.
Removed
Nothing. Every item that shipped in 0.1.0 is still present under the same name;
the three breaking changes above are signature and behaviour changes, not
removals.