Skip to main content

thumb_asm/
lib.rs

1//! Generic, platform-neutral toolkit for reading, patching and generating
2//! ARM-Thumb code inside a flat binary image.
3//!
4//! Whatever the image is — a drive firmware dump, a boot ROM, a stripped
5//! `.bin` carved out of an update package — the work reduces to four verbs:
6//!
7//! * **find**  — locate something (a byte pattern, a word, a run of free space,
8//!   a call site). ONE primitive, [`find`], expressed over a [`Needle`]; every
9//!   named finder ([`find_free_space`], …) is a thin overload of it. Because
10//!   [`find`] takes a `start` and returns the match offset, finds compose by
11//!   nesting: `find(y, find(x, find(a, 0)))`.
12//! * **read**  — read a value at a found location: [`read_u32`], [`read_u16`],
13//!   [`read_u8`] for offsets already known to be in bounds, and the
14//!   `Option`-returning [`try_read_u32`], [`try_read_u16`], [`try_read_u8`] for
15//!   scans that walk to the end of the image. Instruction-level reads are
16//!   [`decode_bl`], [`decode_b_wide`] and [`decode_b_cond`].
17//! * **modify / insert** — [`write()`] bytes at an offset (repoint a record,
18//!   patch a field) or [`insert`] a code blob into free space, returning its
19//!   address. [`install_branch`] does the whole detour-installation pattern —
20//!   encode, write, decode back to confirm — in one call.
21//! * **create** — [`Asm`], a small position-independent Thumb assembler with a
22//!   literal pool and data blobs, plus the standalone encoders [`encode_bl`],
23//!   [`encode_b_wide`] and [`encode_b_cond`].
24//!
25//! The crate deliberately knows nothing about any particular firmware, vendor
26//! or tool. The *knowledge* — which needle to look for, where it lives, what to
27//! assemble in its place — belongs to the caller; this crate supplies only the
28//! verbs, so supporting a new platform never means new toolkit logic.
29//!
30//! Every encoding claim in this file cites its section in Arm's architecture
31//! reference manuals (`A5.*`/`A7.*` = ARM DDI 0403E.e, Armv7-M; `A6.*` =
32//! ARM DDI 0406B, Armv7-A/R).
33
34#![forbid(unsafe_code)]
35#![deny(missing_docs)]
36
37pub mod analysis;
38mod cond;
39pub mod detour;
40pub mod flags;
41pub mod isa;
42pub mod relocate;
43
44pub use cond::Cond;
45pub use isa::{Insn, Operand, Reg, Width};
46
47/// The crate's `Result`, defaulted to [`AsmError`] so downstream code can write
48/// `-> thumb_asm::Result<Vec<u8>>` and mean "or an assembler error".
49///
50/// The second parameter is still free, so the fallible image operations that
51/// report a different failure keep their own error type without a second alias:
52/// [`verify_branch`] returns `Result<(), InstallMismatch>`.
53///
54/// ```
55/// fn build() -> thumb_asm::Result<Vec<u8>> {
56///     let mut a = thumb_asm::Asm::new();
57///     a.movs_imm(0, 1);
58///     a.bx(0);
59///     a.finish()
60/// }
61/// assert_eq!(build().unwrap(), vec![0x01, 0x20, 0x00, 0x47]);
62/// ```
63pub type Result<T, E = AsmError> = core::result::Result<T, E>;
64
65/// A thing [`find`] can search for. Add a variant here to teach every caller a
66/// new kind of search without touching caller code.
67///
68/// `#[non_exhaustive]`: a `match` on this in a downstream crate must carry a
69/// `_` arm, so a future search kind is an addition rather than a breaking
70/// change. That was not true before 0.11.0, and adding [`Needle::Masked`] is
71/// what cost the minor bump.
72#[derive(Debug, Clone, Copy)]
73#[non_exhaustive]
74pub enum Needle<'a> {
75    /// An exact byte pattern.
76    Bytes(&'a [u8]),
77    /// A little-endian 32-bit word (e.g. an absolute address embedded as a
78    /// Thumb literal, or a handler pointer).
79    Word(u32),
80    /// A run of at least `len` erased-flash bytes (`0xFF`) — i.e. free space —
81    /// whose *start offset* is a multiple of `align`.
82    ///
83    /// The alignment belongs in the needle rather than in a round-up afterwards.
84    /// [`Asm::finish`] documents that its output assumes a 4-byte-aligned load
85    /// address, because its literal-pool offsets are computed against
86    /// `Align(PC, 4)` relative to the buffer start — and rounding a found run's
87    /// start up moves the start without extending the end, so a run that was
88    /// exactly long enough stops being long enough and the caller gets an offset
89    /// whose tail overlaps live bytes. Accounting for alignment *during* the scan
90    /// is the only form of the question with a correct answer. `align: 1` is the
91    /// pre-0.10 behaviour.
92    FreeRun {
93        /// How many free bytes are needed.
94        len: usize,
95        /// Required alignment of the run's start offset, in bytes. Must be >= 1.
96        align: usize,
97    },
98    /// An instruction pattern with don't-care bits: a slice of
99    /// `(value, mask)` halfword pairs, matching where
100    /// `halfword & mask == value & mask` for every pair in order.
101    ///
102    /// This is how a signature is actually written. "Any `BL`" is
103    /// `(0xF000, 0xF800)` — the five bits that identify the encoding fixed and
104    /// the eleven displacement bits ignored — and searching for it with
105    /// [`Needle::Bytes`] is not possible at all, because the bytes differ at
106    /// every call site.
107    ///
108    /// **Matches are halfword-aligned.** Thumb instructions are 2-aligned, so
109    /// a match at an odd offset is not an instruction; scanning every byte
110    /// offset would report plausible-looking hits straddling two real
111    /// instructions. The scan starts at the first even offset at or after
112    /// `start`.
113    ///
114    /// An empty pattern matches nothing rather than matching everywhere: a
115    /// needle that is satisfied by any position is a mistake in the caller,
116    /// and returning the start offset would hide it.
117    ///
118    /// ```
119    /// use thumb_asm::{find, Needle};
120    ///
121    /// // `bl` to somewhere, preceded by `movs r0, #1`.
122    /// let image = [0x01, 0x20, 0xFF, 0xF7, 0xFE, 0xFF];
123    /// let any_bl = [(0xF000u16, 0xF800u16), (0xD000, 0xD000)];
124    /// assert_eq!(find(&image, Needle::Masked(&any_bl), 0), Some(2));
125    /// ```
126    Masked(&'a [(u16, u16)]),
127}
128
129/// The one search primitive. Find `needle` at or after byte offset `start`;
130/// return the offset of the match, or `None`. Every named finder below is a
131/// thin overload of this call.
132pub fn find(image: &[u8], needle: Needle, start: usize) -> Option<usize> {
133    match needle {
134        Needle::Bytes(pat) => find_bytes(image, pat, start),
135        Needle::Word(w) => find_bytes(image, &w.to_le_bytes(), start),
136        Needle::FreeRun { len, align } => find_free_run(image, len, align, start),
137        Needle::Masked(pat) => find_masked(image, pat, start),
138    }
139}
140
141/// [`find`], confined to a window of the image.
142///
143/// Scoping a search is not a convenience, it is how an otherwise-ambiguous
144/// signature becomes usable. A pattern that matches three places in a whole
145/// image may match exactly once inside the region you care about, and without
146/// a bound [`find_one`] can only be used where the pattern happens to be
147/// unique across everything — which is the case that never needed it.
148///
149/// The match must lie **entirely** within `range`: a signature half outside
150/// the window is not in the window.
151///
152/// `range` is half-open (`0x90000..0xb0000` excludes `0xb0000`) and is in
153/// **image coordinates**. That matters, and is why this exists rather than
154/// leaving callers to slice: alignment is measured from the image origin, so
155/// [`Needle::Masked`]'s halfword boundaries and [`Needle::FreeRun`]'s `align`
156/// mean the same thing inside a window as outside one. Slicing the image at an
157/// odd or unaligned offset and searching the slice silently moves that origin.
158///
159/// ```
160/// use thumb_asm::{find, find_in, Needle};
161///
162/// // The same two bytes twice; the window is what tells them apart.
163/// let image = [0x01, 0x20, 0x70, 0x47, 0x01, 0x20];
164/// assert_eq!(find(&image, Needle::Bytes(&[0x01, 0x20]), 0), Some(0));
165/// assert_eq!(find_in(&image, Needle::Bytes(&[0x01, 0x20]), 2..6), Some(4));
166///
167/// // Entirely within: a match starting at 4 does not fit in `0..5`.
168/// assert_eq!(find_in(&image, Needle::Bytes(&[0x01, 0x20]), 4..5), None);
169/// ```
170pub fn find_in(image: &[u8], needle: Needle, range: core::ops::Range<usize>) -> Option<usize> {
171    let (lo, hi) = (range.start, range.end.min(image.len()));
172    if lo >= hi {
173        return None;
174    }
175    match needle {
176        Needle::Bytes(pat) => find_bytes_in(image, pat, lo, hi),
177        Needle::Word(w) => find_bytes_in(image, &w.to_le_bytes(), lo, hi),
178        Needle::FreeRun { len, align } => find_free_run_in(image, len, align, lo, hi),
179        Needle::Masked(pat) => find_masked_in(image, pat, lo, hi),
180    }
181}
182
183/// How many bytes one occurrence of `needle` spans, for advancing past a match.
184fn needle_len(needle: Needle) -> usize {
185    match needle {
186        Needle::Bytes(pat) => pat.len(),
187        Needle::Word(_) => 4,
188        Needle::FreeRun { len, .. } => len,
189        Needle::Masked(pat) => pat.len() * 2,
190    }
191}
192
193/// Why [`find_one`] did not return an offset.
194#[derive(Debug, Clone, Copy, PartialEq, Eq)]
195#[non_exhaustive]
196pub enum FindError {
197    /// Nothing matched.
198    NotFound,
199    /// More than one thing matched.
200    Ambiguous {
201        /// How many non-overlapping occurrences were found.
202        count: usize,
203        /// The offset of the first, for diagnostics — so a message can say
204        /// *where* the search became ambiguous rather than only that it did.
205        first: usize,
206    },
207}
208
209impl FindError {
210    /// A stable, machine-readable reason: `"not-found"` or `"ambiguous"`.
211    ///
212    /// Every error type in this crate carries one, so a caller can branch on
213    /// the cause without matching variants it would have to update when a new
214    /// one appears (these enums are `#[non_exhaustive]` precisely so that new
215    /// ones can appear).
216    ///
217    /// # Labelling a failure
218    ///
219    /// There is deliberately no `context` or `label` on this type. A
220    /// `&'static str` would not take a label built at run time, and a `String`
221    /// would make the error allocate on a path that is often in a loop. Both
222    /// fields a caller needs to write its own message are public, so the
223    /// wrapper this replaces is one line:
224    ///
225    /// ```
226    /// use thumb_asm::{find_one, FindError, Needle};
227    ///
228    /// let image = [0u8; 8];
229    /// let what = "cmac table";
230    /// let msg = match find_one(&image, Needle::Word(0xdead_beef)) {
231    ///     Ok(at) => format!("{what} at {at:#x}"),
232    ///     Err(e @ FindError::Ambiguous { count, .. }) => {
233    ///         format!("{what} signature matched {count} times ({e})")
234    ///     }
235    ///     Err(e) => format!("{what}: {e}"),
236    /// };
237    /// assert_eq!(msg, "cmac table: no match");
238    /// ```
239    pub fn reason(&self) -> &'static str {
240        match self {
241            FindError::NotFound => "not-found",
242            FindError::Ambiguous { .. } => "ambiguous",
243        }
244    }
245}
246
247impl core::fmt::Display for FindError {
248    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
249        match self {
250            FindError::NotFound => f.write_str("no match"),
251            FindError::Ambiguous { count, first } => {
252                write!(f, "{count} matches, first at {first:#x}")
253            }
254        }
255    }
256}
257
258impl std::error::Error for FindError {}
259
260/// Find `needle` and require that it occurs exactly once.
261///
262/// [`find`] returns the first match, which is the right answer when you are
263/// scanning. It is the wrong answer when you are *identifying* something: a
264/// signature that matches three places in a firmware image has not found the
265/// function you meant, it has told you the signature is too weak. Taking the
266/// first one and patching it is how a device gets bricked by a tool that
267/// reported success.
268///
269/// So this refuses to choose. `Err(FindError::Ambiguous { count, first })`
270/// carries both the count and the first offset, so a caller can say what
271/// happened without repeating the search.
272///
273/// Occurrences are counted **non-overlapping**: after a match the scan resumes
274/// one needle-length later. For [`Needle::FreeRun`] that makes the count the
275/// number of disjoint free windows, which is rarely a useful question — use
276/// [`find_free_space_in`] to place something instead.
277///
278/// ```
279/// use thumb_asm::{find_one, FindError, Needle};
280///
281/// let image = [0x01, 0x20, 0x01, 0x20];
282/// assert_eq!(
283///     find_one(&image, Needle::Bytes(&[0x01, 0x20])),
284///     Err(FindError::Ambiguous { count: 2, first: 0 })
285/// );
286/// assert_eq!(find_one(&image, Needle::Bytes(&[0x70, 0x47])), Err(FindError::NotFound));
287/// assert_eq!(find_one(&image, Needle::Word(0x2001_2001)), Ok(0));
288/// ```
289pub fn find_one(image: &[u8], needle: Needle) -> Result<usize, FindError> {
290    find_one_in(image, needle, 0..image.len())
291}
292
293/// [`find_one`], confined to a window of the image.
294///
295/// This is the pairing that makes either function useful on real firmware.
296/// Uniqueness is a property of a signature *and a region*, not of a signature
297/// alone: scoping to the range you already know the function lives in is what
298/// turns a pattern that matches three times across the image into one that
299/// matches once where it matters. Requiring global uniqueness would restrict
300/// this to signatures strong enough not to need checking.
301///
302/// `range` is half-open and in image coordinates, with the same reasoning as
303/// [`find_in`]; matches must lie entirely inside it.
304///
305/// ```
306/// use thumb_asm::{find_one, find_one_in, FindError, Needle};
307///
308/// let image = [0x01, 0x20, 0x70, 0x47, 0x01, 0x20];
309/// let movs = Needle::Bytes(&[0x01, 0x20]);
310///
311/// // Ambiguous across the whole image...
312/// assert_eq!(find_one(&image, movs), Err(FindError::Ambiguous { count: 2, first: 0 }));
313/// // ...and unique inside the window you meant.
314/// assert_eq!(find_one_in(&image, movs, 2..6), Ok(4));
315/// ```
316pub fn find_one_in(
317    image: &[u8],
318    needle: Needle,
319    range: core::ops::Range<usize>,
320) -> Result<usize, FindError> {
321    let step = needle_len(needle).max(1);
322    let hi = range.end.min(image.len());
323    let first = match find_in(image, needle, range.start..hi) {
324        Some(p) => p,
325        None => return Err(FindError::NotFound),
326    };
327    let mut count = 1;
328    let mut at = first;
329    while let Some(next) = at
330        .checked_add(step)
331        .and_then(|from| find_in(image, needle, from..hi))
332    {
333        count += 1;
334        at = next;
335    }
336    if count == 1 {
337        Ok(first)
338    } else {
339        Err(FindError::Ambiguous { count, first })
340    }
341}
342
343/// Overload: the first run of `>= len` free (`0xFF`) bytes at or after `start`
344/// whose start offset is a multiple of `align`.
345/// `find_free_space(image, len, align, start) ==
346/// find(image, Needle::FreeRun { len, align }, start)`.
347///
348/// `align` is required rather than defaulted because there is no safe default.
349/// Anything destined for [`Asm::finish`] needs 4, and an unaligned placement is
350/// not diagnosed anywhere — the assembled code simply runs against the wrong
351/// constants, because its pool offsets were computed for an aligned base. Pass
352/// `1` to mean "raw data, alignment is irrelevant to me".
353///
354/// # Panics
355///
356/// Panics if `align` is 0.
357pub fn find_free_space(image: &[u8], len: usize, align: usize, start: usize) -> Option<usize> {
358    find(image, Needle::FreeRun { len, align }, start)
359}
360
361/// Read the little-endian u32 at `at` (e.g. a record's handler pointer).
362pub fn read_u32(image: &[u8], at: usize) -> u32 {
363    u32::from_le_bytes([image[at], image[at + 1], image[at + 2], image[at + 3]])
364}
365
366/// Read the byte at `at`.
367pub fn read_u8(image: &[u8], at: usize) -> u8 {
368    image[at]
369}
370
371/// Read the little-endian u16 at `at`.
372///
373/// Present because a halfword is the unit a Thumb image is actually made of:
374/// signature scans and instruction classification both want one, and without
375/// this they open-code `u16::from_le_bytes([image[at], image[at + 1]])` at every
376/// site. Panics on a short slice, exactly like [`read_u32`] and [`read_u8`];
377/// use [`try_read_u16`] when the offset comes from a scan rather than from a
378/// bounds-checked structure.
379///
380/// ```
381/// let img = [0x34u8, 0x12];
382/// assert_eq!(thumb_asm::read_u16(&img, 0), 0x1234);
383/// ```
384pub fn read_u16(image: &[u8], at: usize) -> u16 {
385    u16::from_le_bytes([image[at], image[at + 1]])
386}
387
388/// [`read_u8`] without the panic: `None` when `at` is past the end.
389///
390/// The three `try_read_*` functions exist for the scan-to-the-end case, where
391/// the last legal offset is `len - size` and getting that bound wrong silently
392/// drops the final match — which was a real bug in this crate's own
393/// [`find_bl_sites`] before 0.2.0. Reaching for a checked read instead of
394/// hand-rolling the bound is the fix that generalises.
395///
396/// ```
397/// let img = [0xAAu8];
398/// assert_eq!(thumb_asm::try_read_u8(&img, 0), Some(0xAA));
399/// assert_eq!(thumb_asm::try_read_u8(&img, 1), None);
400/// ```
401pub fn try_read_u8(image: &[u8], at: usize) -> Option<u8> {
402    image.get(at).copied()
403}
404
405/// [`read_u16`] without the panic: `None` unless all 2 bytes are in bounds.
406///
407/// ```
408/// let img = [0x34u8, 0x12];
409/// assert_eq!(thumb_asm::try_read_u16(&img, 0), Some(0x1234));
410/// assert_eq!(thumb_asm::try_read_u16(&img, 1), None); // would run past the end
411/// ```
412pub fn try_read_u16(image: &[u8], at: usize) -> Option<u16> {
413    // `checked_add`, not `at + 2`: the addition happens *before* `get` sees
414    // it, so a near-`usize::MAX` offset overflows — a panic in debug, and in
415    // release a wrapped range that can land back in bounds and silently return
416    // the wrong bytes. The offsets here come from scans over attacker-supplied
417    // firmware: a handler pointer read out of erased flash is `0xFFFF_FFFF`,
418    // which masked to even is `0xFFFF_FFFE`, and on a 32-bit target that is
419    // exactly the value that overflows. Not panicking is this function's whole
420    // reason to exist.
421    let b = image.get(at..at.checked_add(2)?)?;
422    Some(u16::from_le_bytes([b[0], b[1]]))
423}
424
425/// [`read_u32`] without the panic: `None` unless all 4 bytes are in bounds.
426///
427/// ```
428/// let img = [0x78u8, 0x56, 0x34, 0x12];
429/// assert_eq!(thumb_asm::try_read_u32(&img, 0), Some(0x1234_5678));
430/// assert_eq!(thumb_asm::try_read_u32(&img, 1), None);
431/// ```
432pub fn try_read_u32(image: &[u8], at: usize) -> Option<u32> {
433    // `checked_add`, not `at + 4`: the addition happens *before* `get` sees
434    // it, so a near-`usize::MAX` offset overflows — a panic in debug, and in
435    // release a wrapped range that can land back in bounds and silently return
436    // the wrong bytes. The offsets here come from scans over attacker-supplied
437    // firmware: a handler pointer read out of erased flash is `0xFFFF_FFFF`,
438    // which masked to even is `0xFFFF_FFFE`, and on a 32-bit target that is
439    // exactly the value that overflows. Not panicking is this function's whole
440    // reason to exist.
441    let b = image.get(at..at.checked_add(4)?)?;
442    Some(u32::from_le_bytes([b[0], b[1], b[2], b[3]]))
443}
444
445/// Modify: overwrite `image[at..at+bytes.len()]` with `bytes`.
446pub fn write(image: &mut [u8], at: usize, bytes: &[u8]) {
447    image[at..at + bytes.len()].copy_from_slice(bytes);
448}
449
450/// Insert: copy `code` into free space at `free_off`, returning the image
451/// address it now lives at (offset == load address on this flat mapping).
452pub fn insert(image: &mut [u8], free_off: usize, code: &[u8]) -> u32 {
453    write(image, free_off, code);
454    free_off as u32
455}
456
457/// An opcode-dispatch table: an array of fixed-size records that firmware scans
458/// by key until it finds a handler pointer to call. The shape recurs across
459/// unrelated devices (SCSI/ATA command tables, vendor-command tables, ioctl and
460/// AT-command jump tables), so this type stores only the *geometry* — where the
461/// records start, how wide they are, and which byte of a record holds the
462/// opcode, the flags and the handler pointer. The caller supplies those
463/// numbers; [`CommandTable::find`], [`CommandTable::walk`] and
464/// [`CommandTable::replace`] are generic over them.
465///
466/// **One worked example**, given because it makes the fields concrete rather
467/// than because the crate assumes it: an MT1959 optical-drive scanner does
468/// `ldrb [rec + opcode_off]` to match, then `ldr [rec + handler_off]; blx` to
469/// dispatch, over records laid out `[opcode(1) | flags(1) | resv(2) |
470/// handler(4 LE)]`. That table is described by `stride: 8`, `opcode_off: 0`,
471/// `flags_off: 1`, `handler_off: 4`, and `term_flag: 0x03` for the record that
472/// ends the scan. A different firmware with, say, 12-byte records and the
473/// handler first is the same type with different numbers.
474#[derive(Debug, Clone, Copy)]
475pub struct CommandTable {
476    /// File offset of the first record.
477    pub base: usize,
478    /// Bytes per record.
479    pub stride: usize,
480    /// Byte offset of the opcode within a record.
481    pub opcode_off: usize,
482    /// Byte offset of the flags byte within a record.
483    pub flags_off: usize,
484    /// Byte offset of the 4-byte LE handler pointer within a record.
485    pub handler_off: usize,
486    /// Flags value that marks the terminator record (scan stops here).
487    pub term_flag: u8,
488    /// Max records to scan before giving up (guards a corrupt/missing terminator).
489    pub max_records: usize,
490}
491
492/// One resolved dispatch record.
493#[derive(Debug, Clone, Copy, PartialEq, Eq)]
494pub struct CommandRecord {
495    /// File offset of the record.
496    pub off: usize,
497    /// The opcode it dispatches.
498    pub opcode: u8,
499    /// The record's flags byte.
500    pub flags: u8,
501    /// The handler pointer (Thumb bit as-stored; 0 = null / no handler).
502    pub handler: u32,
503}
504
505impl CommandTable {
506    /// `find(opcode)` — the record dispatching `opcode`, or `None` if absent
507    /// (scan stops at the terminator, exactly like the drive's scanner).
508    pub fn find(&self, image: &[u8], opcode: u8) -> Option<CommandRecord> {
509        let mut off = self.base;
510        for _ in 0..self.max_records {
511            // `checked_add`, not `off + self.stride`: `base` and `stride` are
512            // the caller's, so their sum can overflow. In debug that panics;
513            // in release it wraps to a small number that passes the `>` test,
514            // and the indexing below then reads from an offset the check was
515            // supposed to have refused. `walk` below has always used
516            // `checked_add` — this is the same guard, which `find` was
517            // missing.
518            let end = off.checked_add(self.stride)?;
519            if end > image.len() {
520                return None;
521            }
522            let flags = image[off + self.flags_off];
523            if flags == self.term_flag {
524                return None; // reached terminator without a match
525            }
526            if image[off + self.opcode_off] == opcode {
527                return Some(CommandRecord {
528                    off,
529                    opcode,
530                    flags,
531                    handler: read_u32(image, off + self.handler_off),
532                });
533            }
534            off += self.stride;
535        }
536        None
537    }
538
539    /// `replace(record, newHandler)` — overwrite a record's handler pointer (and,
540    /// if `flags` is `Some`, its flags byte). This is the hijack: point an
541    /// existing opcode's dispatch at injected code. Prefer a record whose
542    /// current handler is null (nothing runs today); repointing a live handler
543    /// is allowed but the caller should warn.
544    /// # Panics
545    ///
546    /// Panics if either field lies outside `image`. Both are checked *before*
547    /// either is written, so a record too close to the end of a truncated image
548    /// leaves the table untouched rather than half-repointed: the flags byte and
549    /// the handler pointer are one logical edit, and a table whose flags say
550    /// "live handler" while the pointer still says "null" is worse than one that
551    /// was never touched. This mirrors the atomicity `detour` guarantees.
552    pub fn replace(&self, image: &mut [u8], rec: &CommandRecord, handler: u32, flags: Option<u8>) {
553        let flags_at = flags.map(|_| {
554            rec.off
555                .checked_add(self.flags_off)
556                .expect("flags offset overflows")
557        });
558        let handler_at = rec
559            .off
560            .checked_add(self.handler_off)
561            .expect("handler offset overflows");
562        let handler_end = handler_at.checked_add(4).expect("handler field overflows");
563        // `len` bound before the assertion rather than passed as a format
564        // argument: an argument is only evaluated when the assertion fails, so
565        // it is a branch no passing run can take.
566        let len = image.len();
567        assert!(
568            handler_end <= len && flags_at.map_or(true, |a| a < len),
569            "CommandTable::replace: record at {:#x} does not fit in a {len}-byte image",
570            rec.off
571        );
572        if let (Some(f), Some(at)) = (flags, flags_at) {
573            image[at] = f;
574        }
575        write(image, handler_at, &handler.to_le_bytes());
576    }
577}
578
579impl CommandTable {
580    /// Walk the table exactly as the firmware's own scanner does — following
581    /// chain records (`flags == chain_flag`) to successor segments and stopping
582    /// at the first terminator (`flags == term_flag`) — collecting every
583    /// dispatch record. A chain record is one whose `flags` equal `chain_flag`
584    /// and whose `handler` field is not a handler at all but the file offset of
585    /// the next segment; that is how a table too big for one contiguous run is
586    /// spelled (the MT1959 example above uses `chain_flag == 4`). Pass a
587    /// `chain_flag` that no real record uses if the table has no segments.
588    ///
589    /// A `BTreeSet` of visited bases guards against a chain that loops back on
590    /// itself, so a corrupt image costs a wasted scan rather than a hang.
591    ///
592    /// Returns the records in scan order. This is the grounded basis for
593    /// [`CommandTable::find`]-style lookups when a table spans chained segments.
594    pub fn walk(&self, image: &[u8], chain_flag: u8) -> Vec<CommandRecord> {
595        let mut out = Vec::new();
596        let mut base = self.base;
597        let mut seen = std::collections::BTreeSet::new();
598        // One budget for the whole walk, not one per segment. `max_records` is
599        // documented as the number of records to scan before giving up, and a
600        // cap applied separately to the outer chain and to each segment would
601        // make the real bound its *square*: a crafted image that never presents
602        // the terminator and chains through `max_records` distinct segments, each
603        // holding `max_records` records, yields that many pushes. At a caller's
604        // entirely reasonable `max_records` of 100_000 that is 10^10 records.
605        let mut budget = self.max_records;
606        for _ in 0..self.max_records {
607            if !seen.insert(base) {
608                break; // chain loop guard
609            }
610            let mut off = base;
611            loop {
612                if budget == 0 {
613                    return out;
614                }
615                budget -= 1;
616                // `checked_add`: `off` comes from a handler word read out of the
617                // image, so it is attacker-controlled up to `u32::MAX`, and on a
618                // 32-bit target `off + stride` can wrap back into bounds.
619                match off.checked_add(self.stride) {
620                    Some(end) if end <= image.len() => {}
621                    _ => return out,
622                }
623                let flags = image[off + self.flags_off];
624                if flags == self.term_flag {
625                    return out;
626                }
627                let handler = read_u32(image, off + self.handler_off);
628                if flags == chain_flag {
629                    base = handler as usize; // next segment base
630                    break;
631                }
632                out.push(CommandRecord {
633                    off,
634                    opcode: image[off + self.opcode_off],
635                    flags,
636                    handler,
637                });
638                off += self.stride;
639            }
640            // Reaching here means the inner loop hit a chain record and set the
641            // next `base`; every other way out of it returns. The old
642            // `advanced` flag existed because that loop could also fall through
643            // by exhausting a per-segment counter — which the shared budget now
644            // handles by returning, so the flag could no longer ever be false.
645        }
646        out
647    }
648}
649
650/// Whether the Thumb code at file offset `off` begins with a `push {..., lr}`
651/// (`0xB5xx`, A5.2.5) within the first `window` halfwords — a cheap "this is a
652/// real function entry" cross-check. Used to reject a coincidental byte match
653/// when resolving a handler pointer: a scan over every even offset can land
654/// mid-instruction, and a plausible-looking hit that is not preceded by a
655/// prologue usually is one of those.
656pub fn prologue_is_push_lr(image: &[u8], off: usize, window: usize) -> bool {
657    (0..window).any(|k| {
658        let p = off + k * 2;
659        p + 2 <= image.len() && (u16::from_le_bytes([image[p], image[p + 1]]) & 0xFF00) == 0xB500
660    })
661}
662
663/// Error returned by [`Asm::finish`] when an encoded branch, `ldr` literal, or
664/// `adr` falls outside what its Thumb encoding can represent, or when a label
665/// was referenced but never bound.
666///
667/// # Using this with `anyhow`
668///
669/// `AsmError` is `Send + Sync + 'static` and implements [`std::error::Error`],
670/// which is exactly the bound on `anyhow`'s own blanket
671/// `impl<E: Error + Send + Sync + 'static> From<E> for anyhow::Error`. A bare
672/// `?` on an `Asm::finish()` inside a function returning `anyhow::Result<_>`
673/// therefore already compiles — no `.map_err(anyhow::Error::from)`, no wrapper
674/// type, nothing to opt into.
675///
676/// That is also why this crate has no `anyhow` feature and cannot grow one: a
677/// hand-written `impl From<AsmError> for anyhow::Error` would overlap `anyhow`'s
678/// blanket impl and be rejected for coherence. The feature is not withheld, it
679/// is unrepresentable — and unnecessary. The same holds for
680/// [`InstallMismatch`].
681#[derive(Debug, Clone, PartialEq, Eq)]
682#[non_exhaustive]
683pub enum AsmError {
684    /// An operand the requested encoding cannot hold: a low-register field
685    /// with a high register in it, an immediate outside the encoding's
686    /// range, a `blx` with `pc` as its argument, and so on. Reported at
687    /// [`Asm::finish`] with the byte position of the emitter that failed.
688    Operand {
689        /// Byte position in the code buffer where the emitter tried to write.
690        at: usize,
691        /// Human-readable diagnostic naming the operand and the limit.
692        msg: String,
693    },
694    /// The encoding an emitter produces is not defined on the assembler's
695    /// [`isa::Target`]. Introduced in 0.14.0 alongside `Asm::with_target`;
696    /// the only in-crate emitter that raises it today is `sdiv`/`udiv`
697    /// under [`Target::V7A`](isa::Target::V7A) or
698    /// [`Target::V7AR`](isa::Target::V7AR), plus `raw16` and `raw32` over
699    /// bytes their target's decoder does not accept.
700    Unsupported {
701        /// Byte position in the code buffer where the refused emit happened.
702        at: usize,
703        /// Static mnemonic the emitter identifies as, e.g. `"sdiv"`.
704        mnemonic: &'static str,
705        /// The target the assembler was built for.
706        target: isa::Target,
707    },
708    /// A layout-time failure: an unbound or never-reserved label, a branch
709    /// whose displacement is out of range for its encoding, a literal-pool
710    /// entry too far away for `ldr pc-relative`'s 8-bit immediate, or an
711    /// `adr` whose blob sits before it. These are the diagnostics
712    /// [`Asm::finish`] can only report after every emitter has run — the
713    /// mistake is not a bad operand, it is a missing (or geometrically
714    /// impossible) call the caller has to add or move.
715    Layout {
716        /// Byte position of the emitter whose fix-up could not be resolved
717        /// (for branches / `adr` / `ldr` literals). Zero for
718        /// never-reserved-label diagnostics that have no code position.
719        at: usize,
720        /// Human-readable diagnostic naming what went wrong.
721        msg: String,
722    },
723}
724
725impl AsmError {
726    /// A stable, machine-readable reason: `"operand"`, `"unsupported"`, or
727    /// `"layout"`. Consumers branch on this to distinguish "the operand is
728    /// wrong" (fixable at the emitter's arguments) from "the encoding is not
729    /// legal on this target" (fixable by changing the target or the
730    /// emitter) from "the layout does not close" (fixable at the caller's
731    /// label / branch / pool geometry).
732    pub fn reason(&self) -> &'static str {
733        match self {
734            AsmError::Operand { .. } => "operand",
735            AsmError::Unsupported { .. } => "unsupported",
736            AsmError::Layout { .. } => "layout",
737        }
738    }
739
740    /// Byte position in the code buffer this error refers to. Zero for
741    /// never-reserved-label diagnostics that have no code position.
742    pub fn at(&self) -> usize {
743        match self {
744            AsmError::Operand { at, .. }
745            | AsmError::Unsupported { at, .. }
746            | AsmError::Layout { at, .. } => *at,
747        }
748    }
749}
750
751impl core::fmt::Display for AsmError {
752    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
753        match self {
754            AsmError::Operand { msg, .. } => f.write_str(msg),
755            AsmError::Unsupported {
756                mnemonic, target, ..
757            } => write!(
758                f,
759                "{mnemonic}: not defined on {target:?} (encoder-side legality \
760                 gate refused it)"
761            ),
762            AsmError::Layout { msg, .. } => f.write_str(msg),
763        }
764    }
765}
766
767impl std::error::Error for AsmError {}
768
769/// A tiny position-independent Thumb assembler with a trailing 4-byte-aligned
770/// literal pool — the "create" verb. It is *dumb*: it emits exactly the
771/// instructions asked for and lays out `ldr rt, [pc, #imm]` literals in
772/// first-reference order. An engine composes it; the toolkit never decides what
773/// to assemble.
774///
775/// Placement invariant: the returned bytes assume a 4-byte-aligned load address
776/// (so `Align(PC, 4)` for the pool matches the buffer-relative layout). Callers
777/// must place the code at a 4-aligned offset.
778#[derive(Default)]
779pub struct Asm {
780    code: Vec<u8>,
781    ldrs: Vec<(usize, u32, u16)>,    // (insn byte pos, value, rt)
782    fixups: Vec<(usize, u16, bool)>, // (insn pos, label, is_unconditional) branch
783    adrs: Vec<(usize, u16)>,         // (insn pos, blob label) for `adr rd, blob`
784    blobs: Vec<(u16, Vec<u8>)>,      // (label, data) appended after the pool
785    labels: Vec<Option<usize>>,      // label id -> byte pos
786    err: Option<AsmError>,           // first invalid operand; surfaced by finish()
787    target: isa::Target,             // profile this buffer is being built for
788}
789
790impl Asm {
791    /// A fresh, empty assembler targeting [`isa::Target::Union`] — the historical
792    /// default, which accepts every profile's encodings.
793    ///
794    /// For a chip-specific buffer where the encoder must refuse instructions the
795    /// target does not define, use [`Asm::with_target`].
796    pub fn new() -> Self {
797        Self::default()
798    }
799
800    /// Build for a specific ISA target. Emitters whose encoding is not defined on
801    /// `target` fail at the call site — the resulting `Err` surfaces from
802    /// [`Asm::finish`] with the exact mnemonic and byte position of the refused
803    /// emitter, and the buffer up to that point is discarded on the next
804    /// [`Asm::finish`] because the assembler resets itself.
805    ///
806    /// The default [`Asm::new`] is `with_target(Target::Union)`, which is the
807    /// crate's historical byte-for-byte behaviour.
808    ///
809    /// ```
810    /// use thumb_asm::{Asm, isa::Target};
811    /// // A V8M buffer emitting a Security Gateway pattern via raw32 — accepted.
812    /// let mut a = Asm::with_target(Target::V8M);
813    /// a.raw32(0xE97F, 0xE97F);
814    /// assert!(a.finish().is_ok());
815    /// ```
816    pub fn with_target(target: isa::Target) -> Self {
817        Self {
818            target,
819            ..Self::default()
820        }
821    }
822
823    /// The [`isa::Target`] this buffer is being built for.
824    pub fn target(&self) -> isa::Target {
825        self.target
826    }
827
828    /// Current byte position (also a branch target).
829    pub fn pos(&self) -> usize {
830        self.code.len()
831    }
832
833    /// Record the first invalid operand. Later ones are dropped: the first is
834    /// the one the caller has to fix, and a cascade of consequences obscures it.
835    fn fail(&mut self, msg: String) {
836        if self.err.is_none() {
837            self.err = Some(AsmError::Operand {
838                at: self.code.len(),
839                msg,
840            });
841        }
842    }
843
844    /// Record the first target-legality failure. Same first-wins semantics as
845    /// [`Asm::fail`] — one class of error, one report.
846    fn fail_target(&mut self, mnemonic: &'static str) {
847        let at = self.code.len();
848        let target = self.target;
849        self.err.get_or_insert(AsmError::Unsupported {
850            at,
851            mnemonic,
852            target,
853        });
854    }
855
856    /// Consult the per-profile legality table for `(mnemonic, form)` and
857    /// record an [`AsmError::Unsupported`] on this assembler if the target
858    /// does not accept it. Under [`Target::Union`](isa::Target::Union) this
859    /// is a no-op (Union is permissive by design); every other target routes
860    /// through [`isa::legality::defined_on`].
861    ///
862    /// Call **after** every operand check (`lo`/`reg`/`imm`/…) and after
863    /// cond validation, so an operand or condition error still surfaces as
864    /// the primary cause rather than being masked by a downstream
865    /// "not defined on target" that the caller cannot act on.
866    fn check_target(
867        &mut self,
868        mnemonic: &'static str,
869        form: isa::legality::EncForm,
870        extra: isa::legality::OpExtra,
871    ) {
872        if self.target == isa::Target::Union {
873            return;
874        }
875        if !isa::legality::defined_on(mnemonic, form, self.target, extra) {
876            self.fail_target(mnemonic);
877        }
878    }
879
880    /// `r` must be R0–R7. Most 16-bit Thumb encodings carry 3-bit register
881    /// fields; a wider value silently overflows into the opcode and assembles
882    /// to a different instruction.
883    fn lo(&mut self, what: &str, field: &str, r: u16) {
884        if r > 7 {
885            self.fail(format!(
886                "{what}: {field} must be a low register R0-R7, got r{r}"
887            ));
888        }
889    }
890
891    /// `r` must name some register, R0–R15.
892    fn reg(&mut self, what: &str, field: &str, r: u16) {
893        if r > 15 {
894            self.fail(format!("{what}: {field} must be R0-R15, got r{r}"));
895        }
896    }
897
898    /// `v` must be in `0..=max` and a multiple of `step` — the immediate is
899    /// stored scaled, so an unaligned value loses its low bits and an oversized
900    /// one runs into the neighbouring field.
901    fn imm(&mut self, what: &str, v: u16, max: u16, step: u16) {
902        if v > max {
903            self.fail(format!("{what}: immediate {v} exceeds maximum {max}"));
904        // mutant-equivalent: `step > 1` → `step >= 1` — with `step == 1`, `v % 1`
905        // is always `0`, so the second conjunct is always `false` and the branch
906        // is unreachable under either operator.
907        } else if step > 1 && v % step != 0 {
908            self.fail(format!("{what}: immediate {v} is not a multiple of {step}"));
909        }
910    }
911
912    /// A 16-bit `push`/`pop` register list: R0–R7 plus the one extra bit, and
913    /// never empty (an empty list is UNPREDICTABLE, A7.7.99).
914    fn reglist(&mut self, what: &str, extra: &str, list: u16) {
915        if list == 0 {
916            self.fail(format!("{what}: register list is empty"));
917        } else if list > 0x1FF {
918            self.fail(format!(
919                "{what}: register list {list:#06x} has bits outside R0-R7 and {extra} (bit 8)"
920            ));
921        }
922    }
923
924    /// Reserve a label id; bind it later with [`Asm::bind`].
925    pub fn label(&mut self) -> u16 {
926        self.labels.push(None);
927        (self.labels.len() - 1) as u16
928    }
929
930    /// Bind `label` to the current position.
931    pub fn bind(&mut self, label: u16) -> &mut Self {
932        match self.labels.get_mut(label as usize) {
933            Some(slot) => *slot = Some(self.code.len()),
934            None => self.fail(format!("bind: label {label} was never reserved")),
935        }
936        self
937    }
938
939    /// The internal 16-bit writer. Every emitter appends here; this is the one
940    /// choke point that consumes the operand-formed halfword and stops it being
941    /// second-guessed downstream. Public [`Asm::raw16`] delegates to this after
942    /// running the target-legality gate for non-`Union` targets.
943    fn emit16(&mut self, insn: u16) {
944        self.code.extend_from_slice(&insn.to_le_bytes());
945    }
946
947    /// The internal 32-bit writer for wide (Thumb-2) encodings — halfword-order
948    /// `hw1` then `hw2`, each little-endian, matching [`encode_bl`]'s byte layout.
949    fn emit32(&mut self, hw1: u16, hw2: u16) {
950        self.code.extend_from_slice(&hw1.to_le_bytes());
951        self.code.extend_from_slice(&hw2.to_le_bytes());
952    }
953
954    /// Emit a raw 16-bit Thumb instruction (little-endian).
955    ///
956    /// # Under [`Target::Union`](isa::Target::Union)
957    ///
958    /// Byte-for-byte unchanged from pre-0.14: any halfword goes in the
959    /// buffer. This is the historical contract callers depended on.
960    ///
961    /// # Under any non-`Union` target
962    ///
963    /// The rule is *bytes as this chip reads them*. The decoder itself is
964    /// authoritative for what a target's CPU makes of the halfword — Armv8-M
965    /// CMSE and ThumbEE state both reassign patterns Armv7 uses for
966    /// something else — so `raw16` runs [`isa::decode_at_with`] under
967    /// `self.target` on the two-byte slice and, if the decoder returns
968    /// `Some(insn)`, consults the crate-private legality table with the
969    /// recovered `(mnemonic, encoding form)` pair.
970    ///
971    /// - `insn_len(insn) == 4` (a wide-instruction prefix) is refused
972    ///   distinctly, pointing at [`Asm::raw32`] or
973    ///   [`Asm::raw16_unchecked`]. This is the isolated
974    ///   `raw16(0xF400)`-style case: the second halfword is missing, so
975    ///   the target decoder cannot recover the mnemonic.
976    /// - `decode_at_with` returns `None` (the halfword is UNDEFINED on
977    ///   this target) → `AsmError::Unsupported { mnemonic: "raw16", .. }`.
978    /// - Otherwise the halfword is written.
979    ///
980    /// The 0.14.0 legality table has no *narrow* restricted mnemonic (only
981    /// the wide `sdiv`/`udiv` are gated), so the "decoded but refused by the
982    /// legality table" arm on the narrow path cannot fire today. When
983    /// narrow-restricted emitters land in 0.14.x/0.15.0 (e.g. CMSE narrow
984    /// forms, ThumbEE `hb` variants), this call site will grow that arm.
985    /// The wide-side twin lives in [`Asm::raw32`] and *is* exercised by
986    /// the sdiv/udiv-via-`raw32` test today.
987    ///
988    /// Use [`Asm::raw16_unchecked`] to bypass every check.
989    pub fn raw16(&mut self, insn: u16) -> &mut Self {
990        if self.target == isa::Target::Union {
991            self.emit16(insn);
992            return self;
993        }
994        if isa::insn_len(insn) == 4 {
995            self.fail_target("raw16");
996            // Emit the byte anyway to keep pos() consistent for later
997            // fixups; finish() will still refuse to hand back bytes.
998            self.emit16(insn);
999            return self;
1000        }
1001        let bytes = insn.to_le_bytes();
1002        if isa::decode_at_with(&bytes, 0, 0, self.target).is_none() {
1003            self.fail_target("raw16");
1004        }
1005        self.emit16(insn);
1006        self
1007    }
1008
1009    /// Emit two halfwords of a wide Thumb-2 instruction (`hw1` then `hw2`,
1010    /// little-endian each).
1011    ///
1012    /// Same rule as [`Asm::raw16`] under non-Union: decode under
1013    /// `self.target`, then look the recovered mnemonic up in the legality
1014    /// table. Under [`Target::Union`](isa::Target::Union) the bytes are
1015    /// written unchanged.
1016    ///
1017    /// # Example: SG on V8M
1018    ///
1019    /// ```
1020    /// use thumb_asm::{Asm, isa::Target};
1021    /// // Security Gateway T1 (ARM ARM CMSE) — halfwords 0xE97F 0xE97F.
1022    /// // Accepted under V8M because the V8M decoder recovers `sg`, which
1023    /// // the legality table accepts; refused under V7A because that
1024    /// // decoder recovers `ldrd`, which the legality table does accept
1025    /// // there — this is the "bytes as this chip reads them" contract.
1026    /// let mut a = Asm::with_target(Target::V8M);
1027    /// a.raw32(0xE97F, 0xE97F);
1028    /// assert!(a.finish().is_ok());
1029    /// ```
1030    pub fn raw32(&mut self, hw1: u16, hw2: u16) -> &mut Self {
1031        if self.target == isa::Target::Union {
1032            self.emit32(hw1, hw2);
1033            return self;
1034        }
1035        // `to_le_bytes` on each halfword rather than hand-masking with `& 0xFF`
1036        // and `>> 8`: the manual form generated four provably-equivalent mutants
1037        // (`&`→`|`, `>>`→`<<`) whose effect on the decoded mnemonic is only
1038        // observable through operand-discriminated legality, which the table
1039        // does not yet consult (OpExtra::Plain everywhere in 0.14.0). This
1040        // spelling has no mutant surface for those bit ops.
1041        let hw1_le = hw1.to_le_bytes();
1042        let hw2_le = hw2.to_le_bytes();
1043        let bytes = [hw1_le[0], hw1_le[1], hw2_le[0], hw2_le[1]];
1044        match isa::decode_at_with(&bytes, 0, 0, self.target) {
1045            Some(decoded) => {
1046                let form = isa::legality::EncForm::from(decoded.encoding);
1047                // A Thumb-1 target (ARMv4T/ARMv5TE) has no 32-bit Thumb-2
1048                // instructions at all — only the BL/BLX branch pair, which is
1049                // emitted via the branch path, not raw32. So any wide encoding
1050                // reaching raw32 is refused outright on such a target.
1051                let legal = self.target.supports_thumb2()
1052                    && isa::legality::defined_on(
1053                        decoded.mnemonic,
1054                        form,
1055                        self.target,
1056                        isa::legality::OpExtra::Plain,
1057                    );
1058                if legal {
1059                    self.emit32(hw1, hw2);
1060                } else {
1061                    self.fail_target(decoded.mnemonic);
1062                    self.emit32(hw1, hw2);
1063                }
1064            }
1065            None => {
1066                self.fail_target("raw32");
1067                self.emit32(hw1, hw2);
1068            }
1069        }
1070        self
1071    }
1072
1073    /// Emit any 16-bit halfword, bypassing every legality check. The explicit
1074    /// escape hatch for hand-encoded CMSE / ThumbEE / new-Cortex-M patterns that
1075    /// this crate has no emitter for yet — the caller has taken responsibility
1076    /// for the bytes.
1077    pub fn raw16_unchecked(&mut self, insn: u16) -> &mut Self {
1078        self.emit16(insn);
1079        self
1080    }
1081
1082    /// `ldr rt, [pc, #imm]` loading `value` from the pool (dedup, first-ref order).
1083    pub fn ldr_lit(&mut self, rt: u16, value: u32) -> &mut Self {
1084        self.lo("ldr_lit", "rt", rt);
1085        let pos = self.code.len();
1086        self.emit16(0x4800 | (rt << 8)); // patched in finish()
1087        self.ldrs.push((pos, value, rt));
1088        self
1089    }
1090
1091    /// `str rt, [sp, #offset]`, with an aligned byte offset in 0..=1020.
1092    pub fn str_sp(&mut self, rt: u16, offset: u16) -> &mut Self {
1093        self.lo("str_sp", "rt", rt);
1094        self.imm("str_sp", offset, 1020, 4);
1095        self.emit16(0x9000 | (rt << 8) | (offset >> 2));
1096        self
1097    }
1098
1099    /// `ldrh rt, [rn, rm]`, using three low registers.
1100    pub fn ldrh_reg(&mut self, rt: u16, rn: u16, rm: u16) -> &mut Self {
1101        self.lo("ldrh_reg", "rt", rt);
1102        self.lo("ldrh_reg", "rn", rn);
1103        self.lo("ldrh_reg", "rm", rm);
1104        self.emit16(0x5a00 | (rm << 6) | (rn << 3) | rt);
1105        self
1106    }
1107
1108    /// `add sp, #offset`, with an aligned byte offset in 0..=508.
1109    pub fn add_sp(&mut self, offset: u16) -> &mut Self {
1110        self.imm("add_sp", offset, 508, 4);
1111        self.emit16(0xb000 | (offset >> 2));
1112        self
1113    }
1114
1115    /// `ands rd, rm`, updating N/Z and preserving C/V.
1116    pub fn ands(&mut self, rd: u16, rm: u16) -> &mut Self {
1117        self.lo("ands", "rd", rd);
1118        self.lo("ands", "rm", rm);
1119        self.emit16(0x4000 | (rm << 3) | rd);
1120        self
1121    }
1122
1123    /// Decode and re-encode position-independent native instructions.
1124    /// PC-relative operations, branches, conditional instructions and incomplete
1125    /// encodings are refused; use the relocator for address-dependent code.
1126    pub fn replay(&mut self, bytes: &[u8]) -> &mut Self {
1127        let mut offset = 0;
1128        while offset < bytes.len() {
1129            let ins = match isa::decode_at_with(bytes, offset, offset as u32, self.target) {
1130                Some(ins) => ins,
1131                None => {
1132                    self.fail("replay: invalid or incomplete instruction".into());
1133                    break;
1134                }
1135            };
1136            let dependent = ins.is_branch()
1137                || ins.writes_pc()
1138                || ins.cond.is_some()
1139                || ins.mnemonic == "it"
1140                || ins.operands.as_slice().any(|operand| match operand {
1141                    isa::Operand::Reg(isa::Reg::PC)
1142                    | isa::Operand::RegShifted(isa::Reg::PC, _)
1143                    | isa::Operand::Target(_) => true,
1144                    isa::Operand::Mem(memory) => {
1145                        memory.base == isa::Reg::PC
1146                            || memory.index.map_or(false, |(reg, _)| reg == isa::Reg::PC)
1147                    }
1148                    _ => false,
1149                });
1150            if dependent {
1151                self.fail(
1152                    "replay: instruction depends on its original address or control flow".into(),
1153                );
1154                break;
1155            }
1156            match isa::encode(&ins) {
1157                Some((low, high)) => {
1158                    if ins.len() == 2 {
1159                        self.raw16(low);
1160                    } else {
1161                        self.raw32(low, high);
1162                    }
1163                }
1164                None => {
1165                    self.fail("replay: instruction cannot be re-encoded".into());
1166                    break;
1167                }
1168            }
1169            offset += ins.len();
1170        }
1171        self
1172    }
1173
1174    /// `ldrb rt, [rn, #imm5]` (byte load, offset 0..31).
1175    pub fn ldrb_imm(&mut self, rt: u16, rn: u16, imm5: u16) -> &mut Self {
1176        self.lo("ldrb_imm", "rt", rt);
1177        self.lo("ldrb_imm", "rn", rn);
1178        self.imm("ldrb_imm", imm5, 31, 1);
1179        self.emit16(0x7800 | (imm5 << 6) | (rn << 3) | rt);
1180        self
1181    }
1182
1183    /// `ldr rt, [rn, #imm]` (word load; `imm` must be a multiple of 4, 0..124).
1184    pub fn ldr_imm(&mut self, rt: u16, rn: u16, imm: u16) -> &mut Self {
1185        self.lo("ldr_imm", "rt", rt);
1186        self.lo("ldr_imm", "rn", rn);
1187        self.imm("ldr_imm", imm, 124, 4);
1188        self.emit16(0x6800 | ((imm >> 2) << 6) | (rn << 3) | rt);
1189        self
1190    }
1191
1192    /// `strh rt, [rn, #imm]` (halfword store; `imm` must be even, 0..62).
1193    pub fn strh_imm(&mut self, rt: u16, rn: u16, imm: u16) -> &mut Self {
1194        self.lo("strh_imm", "rt", rt);
1195        self.lo("strh_imm", "rn", rn);
1196        self.imm("strh_imm", imm, 62, 2);
1197        self.emit16(0x8000 | ((imm >> 1) << 6) | (rn << 3) | rt);
1198        self
1199    }
1200
1201    /// `str rt, [rn, #imm]` (word store; `imm` must be a multiple of 4, 0..124).
1202    pub fn str_imm(&mut self, rt: u16, rn: u16, imm: u16) -> &mut Self {
1203        self.lo("str_imm", "rt", rt);
1204        self.lo("str_imm", "rn", rn);
1205        self.imm("str_imm", imm, 124, 4);
1206        self.emit16(0x6000 | ((imm >> 2) << 6) | (rn << 3) | rt);
1207        self
1208    }
1209
1210    /// `bics rd, rm` (bit-clear: `rd &= ~rm`).
1211    pub fn bics(&mut self, rd: u16, rm: u16) -> &mut Self {
1212        self.lo("bics", "rd", rd);
1213        self.lo("bics", "rm", rm);
1214        self.emit16(0x4380 | (rm << 3) | rd);
1215        self
1216    }
1217
1218    /// `orrs rd, rm` (`rd |= rm`).
1219    pub fn orrs(&mut self, rd: u16, rm: u16) -> &mut Self {
1220        self.lo("orrs", "rd", rd);
1221        self.lo("orrs", "rm", rm);
1222        self.emit16(0x4300 | (rm << 3) | rd);
1223        self
1224    }
1225
1226    /// `strb rt, [rn, #imm5]` (byte store, offset 0..31).
1227    pub fn strb_imm(&mut self, rt: u16, rn: u16, imm5: u16) -> &mut Self {
1228        self.lo("strb_imm", "rt", rt);
1229        self.lo("strb_imm", "rn", rn);
1230        self.imm("strb_imm", imm5, 31, 1);
1231        self.emit16(0x7000 | (imm5 << 6) | (rn << 3) | rt);
1232        self
1233    }
1234
1235    /// `cmp rn, #imm8`.
1236    pub fn cmp_imm(&mut self, rn: u16, imm8: u8) -> &mut Self {
1237        self.lo("cmp_imm", "rn", rn);
1238        self.emit16(0x2800 | (rn << 8) | imm8 as u16);
1239        self
1240    }
1241
1242    /// `cmp rn, rm` (low registers, data-processing form).
1243    pub fn cmp_reg(&mut self, rn: u16, rm: u16) -> &mut Self {
1244        self.lo("cmp_reg", "rn", rn);
1245        self.lo("cmp_reg", "rm", rm);
1246        self.emit16(0x4280 | (rm << 3) | rn);
1247        self
1248    }
1249
1250    /// `movs rt, #imm8`.
1251    pub fn movs_imm(&mut self, rt: u16, imm8: u8) -> &mut Self {
1252        self.lo("movs_imm", "rt", rt);
1253        self.emit16(0x2000 | (rt << 8) | imm8 as u16);
1254        self
1255    }
1256
1257    /// `push {reglist}` (bit 8 = lr). e.g. `push {lr}` = `0x0100`,
1258    /// `push {r0, r1, lr}` = `0x0103`. Must be non-empty and within R0-R7 + lr;
1259    /// anything else is an [`AsmError`] from [`Asm::finish`].
1260    pub fn push(&mut self, reglist: u16) -> &mut Self {
1261        self.reglist("push", "lr", reglist);
1262        self.emit16(0xB400 | reglist);
1263        self
1264    }
1265
1266    /// `pop {reglist}` (bit 8 = pc). e.g. `pop {pc}` = `0x0100`,
1267    /// `pop {r0, r1, pc}` = `0x0103`. Must be non-empty and within R0-R7 + pc;
1268    /// anything else is an [`AsmError`] from [`Asm::finish`].
1269    pub fn pop(&mut self, reglist: u16) -> &mut Self {
1270        self.reglist("pop", "pc", reglist);
1271        self.emit16(0xBC00 | reglist);
1272        self
1273    }
1274
1275    /// `blx rm`.
1276    pub fn blx(&mut self, rm: u16) -> &mut Self {
1277        self.reg("blx", "rm", rm);
1278        if rm == 15 {
1279            self.fail("blx: rm must not be pc (UNPREDICTABLE, A7.7.20)".to_string());
1280        }
1281        self.emit16(0x4780 | (rm << 3));
1282        self
1283    }
1284
1285    /// `bx rm`.
1286    pub fn bx(&mut self, rm: u16) -> &mut Self {
1287        self.reg("bx", "rm", rm);
1288        self.emit16(0x4700 | (rm << 3));
1289        self
1290    }
1291
1292    /// `b<cond> label` — the generic conditional branch (`B` T1, `1101 cond
1293    /// imm8`, A5.2.6), patched to a relative offset at [`Asm::finish`]. Range
1294    /// ±254 bytes from the branch; out of range is an [`AsmError`], never a
1295    /// truncated offset.
1296    ///
1297    /// [`Cond::Al`] is deliberately *not* encoded as `0b1110` here — in this
1298    /// encoding space `0b1110` is the permanently-undefined `UDF` and `0b1111`
1299    /// is `SVC`. `b_cond(Cond::Al, l)` emits the unconditional [`Asm::b`]
1300    /// instead, which is both what "branch always" means and what an assembler
1301    /// does with `bal`. As a bonus it gets the wider ±2046-byte range.
1302    ///
1303    /// The fourteen named wrappers ([`Asm::beq`], [`Asm::bne`], …) are one-line
1304    /// calls to this; use whichever reads better at the call site.
1305    pub fn b_cond(&mut self, cond: Cond, label: u16) -> &mut Self {
1306        match cond {
1307            Cond::Al => self.b(label),
1308            c => {
1309                let pos = self.code.len();
1310                self.emit16(0xD000 | ((c.bits() as u16) << 8));
1311                self.fixups.push((pos, label, false));
1312                self
1313            }
1314        }
1315    }
1316
1317    /// `beq label` — equal, `Z == 1`.
1318    pub fn beq(&mut self, label: u16) -> &mut Self {
1319        self.b_cond(Cond::Eq, label)
1320    }
1321
1322    /// `bne label` — not equal, `Z == 0`.
1323    pub fn bne(&mut self, label: u16) -> &mut Self {
1324        self.b_cond(Cond::Ne, label)
1325    }
1326
1327    /// `bhs label` / `bcs` — unsigned ≥, `C == 1`.
1328    pub fn bhs(&mut self, label: u16) -> &mut Self {
1329        self.b_cond(Cond::Hs, label)
1330    }
1331
1332    /// `blo label` / `bcc` — unsigned <, `C == 0`.
1333    pub fn blo(&mut self, label: u16) -> &mut Self {
1334        self.b_cond(Cond::Lo, label)
1335    }
1336
1337    /// `bmi label` — negative, `N == 1`.
1338    pub fn bmi(&mut self, label: u16) -> &mut Self {
1339        self.b_cond(Cond::Mi, label)
1340    }
1341
1342    /// `bpl label` — positive or zero, `N == 0`.
1343    pub fn bpl(&mut self, label: u16) -> &mut Self {
1344        self.b_cond(Cond::Pl, label)
1345    }
1346
1347    /// `bvs label` — overflow set, `V == 1`.
1348    pub fn bvs(&mut self, label: u16) -> &mut Self {
1349        self.b_cond(Cond::Vs, label)
1350    }
1351
1352    /// `bvc label` — overflow clear, `V == 0`.
1353    pub fn bvc(&mut self, label: u16) -> &mut Self {
1354        self.b_cond(Cond::Vc, label)
1355    }
1356
1357    /// `bhi label` — unsigned >, `C == 1 && Z == 0`.
1358    pub fn bhi(&mut self, label: u16) -> &mut Self {
1359        self.b_cond(Cond::Hi, label)
1360    }
1361
1362    /// `bls label` — unsigned ≤, `C == 0 || Z == 1`.
1363    pub fn bls(&mut self, label: u16) -> &mut Self {
1364        self.b_cond(Cond::Ls, label)
1365    }
1366
1367    /// `bge label` — signed ≥, `N == V`.
1368    pub fn bge(&mut self, label: u16) -> &mut Self {
1369        self.b_cond(Cond::Ge, label)
1370    }
1371
1372    /// `blt label` — signed <, `N != V`.
1373    pub fn blt(&mut self, label: u16) -> &mut Self {
1374        self.b_cond(Cond::Lt, label)
1375    }
1376
1377    /// `bgt label` — signed >, `Z == 0 && N == V`.
1378    pub fn bgt(&mut self, label: u16) -> &mut Self {
1379        self.b_cond(Cond::Gt, label)
1380    }
1381
1382    /// `ble label` — signed ≤, `Z == 1 || N != V`.
1383    pub fn ble(&mut self, label: u16) -> &mut Self {
1384        self.b_cond(Cond::Le, label)
1385    }
1386
1387    /// `b label` (unconditional, 11-bit offset; `B` T2, A7.7.12). Range
1388    /// ±2046 bytes.
1389    pub fn b(&mut self, label: u16) -> &mut Self {
1390        let pos = self.code.len();
1391        self.emit16(0xE000);
1392        self.fixups.push((pos, label, true));
1393        self
1394    }
1395
1396    /// `ldrb rt, [rn, rm]` (register-offset byte load).
1397    pub fn ldrb_reg(&mut self, rt: u16, rn: u16, rm: u16) -> &mut Self {
1398        self.lo("ldrb_reg", "rt", rt);
1399        self.lo("ldrb_reg", "rn", rn);
1400        self.lo("ldrb_reg", "rm", rm);
1401        self.emit16(0x5C00 | (rm << 6) | (rn << 3) | rt);
1402        self
1403    }
1404
1405    /// `adds rt, #imm8`.
1406    pub fn adds_imm(&mut self, rt: u16, imm8: u8) -> &mut Self {
1407        self.lo("adds_imm", "rt", rt);
1408        self.emit16(0x3000 | (rt << 8) | imm8 as u16);
1409        self
1410    }
1411
1412    /// `subs rt, #imm8`.
1413    pub fn subs_imm(&mut self, rt: u16, imm8: u8) -> &mut Self {
1414        self.lo("subs_imm", "rt", rt);
1415        self.emit16(0x3800 | (rt << 8) | imm8 as u16);
1416        self
1417    }
1418
1419    /// `lsls rd, rm, #imm5` — `LSL (immediate)` T1, `0000 0 imm5 Rm Rd`
1420    /// (A5.2.1).
1421    ///
1422    /// Note the alias in the A5-2 footnote: `imm5 == 0` is *not* a zero-bit
1423    /// shift, it **is** `MOV (register)` T2 — `lsls_imm(rd, rm, 0)` assembles to
1424    /// the same halfword as [`Asm::movs_reg`]`(rd, rm)` and disassembles as
1425    /// `movs rd, rm`. Both set N/Z. Callers who mean the move should write the
1426    /// move.
1427    pub fn lsls_imm(&mut self, rd: u16, rm: u16, imm5: u16) -> &mut Self {
1428        self.lo("lsls_imm", "rd", rd);
1429        self.lo("lsls_imm", "rm", rm);
1430        self.imm("lsls_imm", imm5, 31, 1);
1431        self.emit16((imm5 << 6) | (rm << 3) | rd);
1432        self
1433    }
1434
1435    /// `lsrs rd, rm, #imm5` (logical shift right). `imm5` is 0..=31, where
1436    /// `0` is not a zero-bit shift but encodes a shift of **32** (A7.7.71
1437    /// `DecodeImmShift`), leaving `rd` zeroed and C set from `rm`'s bit 31.
1438    pub fn lsrs_imm(&mut self, rd: u16, rm: u16, imm5: u16) -> &mut Self {
1439        self.lo("lsrs_imm", "rd", rd);
1440        self.lo("lsrs_imm", "rm", rm);
1441        self.imm("lsrs_imm", imm5, 31, 1);
1442        self.emit16(0x0800 | (imm5 << 6) | (rm << 3) | rd);
1443        self
1444    }
1445
1446    /// `adds rd, rn, rm` (register).
1447    pub fn adds_reg(&mut self, rd: u16, rn: u16, rm: u16) -> &mut Self {
1448        self.lo("adds_reg", "rd", rd);
1449        self.lo("adds_reg", "rn", rn);
1450        self.lo("adds_reg", "rm", rm);
1451        self.emit16(0x1800 | (rm << 6) | (rn << 3) | rd);
1452        self
1453    }
1454
1455    /// `mov rd, rm` — `MOV (register)` T1, `0100 0110 D Rm(4) Rd(3)`
1456    /// (A5.2.3 / A7.7.77), encoded `0x4600 | (d << 7) | (rm << 3) | (rd & 7)`
1457    /// where `d = (rd >> 3) & 1`.
1458    ///
1459    /// # Behaviour change in 0.2.0
1460    ///
1461    /// Through 0.1.0 this emitted `0x1C00 | rm << 3 | rd`, which is not `MOV` at
1462    /// all: it is `ADD (immediate)` T1 with `imm3 == 0` — i.e. `adds rd, rm, #0`
1463    /// — and **it writes N, Z, C and V**. Any sequence that moved a register
1464    /// between a `cmp` and its `b<cond>` was silently miscompiled, because the
1465    /// move destroyed the comparison's flags. T1 `MOV (register)` leaves the
1466    /// flags untouched, which is what a register move is expected to do.
1467    ///
1468    /// The new encoding also reaches the high registers: `rd` may be 0–15 (the
1469    /// `D` bit is `rd`'s bit 3), and `rm` is a full 4-bit field, so this is the
1470    /// only 16-bit way to move R8–R12, SP or LR. `mov pc, rm` (`rd == 15`) is a
1471    /// branch; the architecture permits it, and this helper will encode it, but
1472    /// prefer [`Asm::bx`] where a branch is what is meant.
1473    ///
1474    /// For the old flag-setting behaviour, ask for it by name: [`Asm::movs_reg`].
1475    pub fn mov_reg(&mut self, rd: u16, rm: u16) -> &mut Self {
1476        self.reg("mov_reg", "rd", rd);
1477        self.reg("mov_reg", "rm", rm);
1478        self.emit16(0x4600 | ((rd & 8) << 4) | ((rm & 0xF) << 3) | (rd & 7));
1479        self
1480    }
1481
1482    /// `movs rd, rm` — `MOV (register)` T2, `0000 0000 00 Rm Rd` (A5.2.1 /
1483    /// A7.7.77), encoded `0x0000 | rm << 3 | rd`. Low registers only (R0–R7).
1484    ///
1485    /// Sets N and Z from the moved value and leaves C and V alone, per T2's
1486    /// `setflags = TRUE` pseudocode. This is the form 0.1.0's `mov_reg` was
1487    /// *reaching* for — a flag-setting register move — though it got there by a
1488    /// different instruction (`adds rd, rm, #0`, which also writes C and V).
1489    /// T2 is not permitted inside an IT block.
1490    ///
1491    /// Identical in encoding to `lsls rd, rm, #0`; see [`Asm::lsls_imm`].
1492    pub fn movs_reg(&mut self, rd: u16, rm: u16) -> &mut Self {
1493        self.lo("movs_reg", "rd", rd);
1494        self.lo("movs_reg", "rm", rm);
1495        self.emit16((rm << 3) | rd);
1496        self
1497    }
1498
1499    /// `sdiv rd, rn, rm` — signed integer divide, `SDIV` T1
1500    /// (ARM ARM A8.8.165). Wide (32-bit) Thumb-2 encoding.
1501    ///
1502    /// # Target legality
1503    ///
1504    /// `SDIV` is UNDEFINED on Armv7-A but mandatory on Armv7-R and every
1505    /// Armv7-M / Armv7E-M / Armv8-M profile. Under
1506    /// [`Target::V7A`](isa::Target::V7A) or
1507    /// [`Target::V7AR`](isa::Target::V7AR) (the strict intersection),
1508    /// [`Asm::finish`] returns `AsmError::Unsupported { mnemonic: "sdiv", .. }`.
1509    /// Under [`Target::Union`](isa::Target::Union) — the default — it emits
1510    /// unconditionally, matching the crate's pre-0.14 behaviour.
1511    ///
1512    /// # Operands
1513    ///
1514    /// `Rd`, `Rn`, `Rm` are 4-bit register fields. `PC` (r15) is
1515    /// UNPREDICTABLE and `SP` (r13) is refused for the same reason as
1516    /// [`Asm::blx`]'s guard on r15 — a decoder can accept them, but the
1517    /// hardware behaviour is unspecified. This helper reports either as
1518    /// [`AsmError::Operand`].
1519    pub fn sdiv(&mut self, rd: u16, rn: u16, rm: u16) -> &mut Self {
1520        self.divmod_wide("sdiv", 0xFB90, rd, rn, rm);
1521        self
1522    }
1523
1524    /// `udiv rd, rn, rm` — unsigned integer divide, `UDIV` T1
1525    /// (ARM ARM A8.8.267). Same encoding shape and same target legality
1526    /// story as [`Asm::sdiv`].
1527    pub fn udiv(&mut self, rd: u16, rn: u16, rm: u16) -> &mut Self {
1528        self.divmod_wide("udiv", 0xFBB0, rd, rn, rm);
1529        self
1530    }
1531
1532    /// Shared body of `sdiv`/`udiv` — same operand-validation, same target
1533    /// check, same 4-byte encoding shape, only the base of `hw1` changes
1534    /// (`0xFB90` for signed, `0xFBB0` for unsigned; both keep the `0xF0F0 |
1535    /// (Rd << 8) | Rm` layout for `hw2`).
1536    fn divmod_wide(&mut self, mnemonic: &'static str, hw1_base: u16, rd: u16, rn: u16, rm: u16) {
1537        self.reg(mnemonic, "rd", rd);
1538        self.reg(mnemonic, "rn", rn);
1539        self.reg(mnemonic, "rm", rm);
1540        for (field, r) in [("rd", rd), ("rn", rn), ("rm", rm)] {
1541            if r == 13 || r == 15 {
1542                self.fail(format!(
1543                    "{mnemonic}: {field} = r{r} is UNPREDICTABLE (SP/PC), refuse rather than emit"
1544                ));
1545            }
1546        }
1547        self.check_target(
1548            mnemonic,
1549            isa::legality::EncForm::T1,
1550            isa::legality::OpExtra::Plain,
1551        );
1552        let hw1 = hw1_base | (rn & 0xF);
1553        let hw2 = 0xF0F0 | ((rd & 0xF) << 8) | (rm & 0xF);
1554        self.emit32(hw1, hw2);
1555    }
1556
1557    /// `adr rd, blob` — position-independent load of a data blob's address
1558    /// (`add rd, pc, #imm`). The blob is declared with [`Asm::data_blob`].
1559    pub fn adr(&mut self, rd: u16, blob_label: u16) -> &mut Self {
1560        self.lo("adr", "rd", rd);
1561        let pos = self.code.len();
1562        self.emit16(0xA000 | (rd << 8));
1563        self.adrs.push((pos, blob_label));
1564        self
1565    }
1566
1567    /// Declare a read-only data blob appended after the code+pool; returns a
1568    /// label usable with [`Asm::adr`]. Blobs are laid out 4-byte aligned.
1569    pub fn data_blob(&mut self, bytes: Vec<u8>) -> u16 {
1570        let label = self.label();
1571        self.blobs.push((label, bytes));
1572        label
1573    }
1574
1575    /// Lay out the pool (4-aligned) then data blobs, and back-patch every branch,
1576    /// `ldr` literal, and `adr`. Returns the assembled bytes.
1577    ///
1578    /// # Reuse
1579    ///
1580    /// `finish` takes `&mut self` and, on every path (`Ok` or `Err`), leaves
1581    /// `self` as a **fresh, empty assembler with the same target** — the
1582    /// half-consumed intermediate state (fixups, literal pool, labels, code
1583    /// buffer) is taken out of `self` before any layout work runs, so a caller
1584    /// can call `finish` twice in a row (the second returns `Ok(vec![])`), and
1585    /// a stale label from the previous buffer used after `finish` decodes as
1586    /// "never reserved" — never as a silent branch into the previous buffer's
1587    /// address space. See the reuse tests in `src/lib.rs::asm_reuse_tests`.
1588    pub fn finish(&mut self) -> Result<Vec<u8>, AsmError> {
1589        // Reading `self.target` while `self` is also `&mut`-borrowed as the
1590        // first argument of `mem::replace` trips E0503; the two-phase borrow
1591        // rules cover method-call autoref, not an explicit `&mut` in argument
1592        // position. Copy the field out first, then let `mem::replace` take
1593        // exclusive ownership.
1594        let target = self.target;
1595        let mut this = core::mem::replace(self, Asm::with_target(target));
1596
1597        // 0. any operand rejected during emit. Reported before layout so the
1598        //    caller sees the cause, not a downstream symptom of the bad bytes.
1599        if let Some(e) = this.err.take() {
1600            return Err(e);
1601        }
1602        // 1. code-position branches (targets already bound during emit).
1603        for (pos, label, uncond) in core::mem::take(&mut this.fixups) {
1604            // `get`, not `this.labels[..]`. The id is the caller's: `bind`
1605            // validates it through `get_mut` and reports "never reserved" as
1606            // an error, but the emitters that push fixups — `b`, `b_cond`,
1607            // `adr` — do not, so an id that was never handed out by `label()`
1608            // arrives here unchecked. Indexing raw turns a would-be
1609            // `AsmError` into a panic, which contradicts this type's whole
1610            // contract that a bad operand is an error.
1611            //
1612            // The two failures are distinguished because they are different
1613            // mistakes: an id nobody reserved is a bug at the call site, and
1614            // a reserved id never bound is a missing `bind`.
1615            let target = match this.labels.get(label as usize) {
1616                Some(Some(t)) => *t,
1617                Some(None) => {
1618                    return Err(AsmError::Layout {
1619                        at: pos,
1620                        msg: format!("unbound label {label}"),
1621                    })
1622                }
1623                None => {
1624                    return Err(AsmError::Layout {
1625                        at: pos,
1626                        msg: format!("label {label} was never reserved by `label()`"),
1627                    })
1628                }
1629            };
1630            let off = (target as i32 - (pos as i32 + 4)) / 2;
1631            let enc = if uncond {
1632                if !(-1024..=1023).contains(&off) {
1633                    return Err(AsmError::Layout {
1634                        at: pos,
1635                        msg: format!("branch out of range ({off} halfwords)"),
1636                    });
1637                }
1638                0xE000u16 | (off as u16 & 0x07FF)
1639            } else {
1640                if !(-128..=127).contains(&off) {
1641                    return Err(AsmError::Layout {
1642                        at: pos,
1643                        msg: format!("conditional branch out of range ({off} halfwords)"),
1644                    });
1645                }
1646                let base = u16::from_le_bytes([this.code[pos], this.code[pos + 1]]) & 0xFF00;
1647                base | (off as i8 as u8 as u16)
1648            };
1649            this.code[pos..pos + 2].copy_from_slice(&enc.to_le_bytes());
1650        }
1651        // 2. literal pool (4-aligned), patch ldr.
1652        while this.code.len() % 4 != 0 {
1653            this.code.push(0x00);
1654        }
1655        let mut placed: Vec<(u32, u32)> = Vec::new();
1656        for (pos, value, rt) in core::mem::take(&mut this.ldrs) {
1657            // Linear scan is deliberate. The pool is laid out in first-reference
1658            // order, which this `Vec` is what preserves, and a realistic stub holds
1659            // a handful of distinct literals — the `Asm` type is documented as a
1660            // deliberately dumb assembler for trampolines, not a code generator.
1661            // It is O(n^2) in the number of *distinct* literals and would want an
1662            // index beside the `Vec` if that ever reached the thousands.
1663            let off = match placed.iter().find(|(v, _)| *v == value) {
1664                Some(&(_, o)) => o,
1665                None => {
1666                    let o = this.code.len() as u32;
1667                    this.code.extend_from_slice(&value.to_le_bytes());
1668                    placed.push((value, o));
1669                    o
1670                }
1671            };
1672            let pc = (pos as u32 + 4) & !3;
1673            let imm8 = (off - pc) / 4;
1674            if imm8 > 0xFF {
1675                return Err(AsmError::Layout {
1676                    at: pos,
1677                    msg: format!("ldr literal out of range (imm8 = {imm8})"),
1678                });
1679            }
1680            let enc = 0x4800u16 | (rt << 8) | imm8 as u16;
1681            this.code[pos..pos + 2].copy_from_slice(&enc.to_le_bytes());
1682        }
1683        // 3. data blobs (each 4-aligned); bind their labels.
1684        for (label, bytes) in core::mem::take(&mut this.blobs) {
1685            while this.code.len() % 4 != 0 {
1686                this.code.push(0x00);
1687            }
1688            // Indexed directly, unlike the fixup loops above, and safely so:
1689            // `this.blobs` has exactly one producer, `data_blob`, which calls
1690            // `label()` itself and returns that id. So a blob's label is
1691            // always one this `Asm` reserved. The *reader* below is different
1692            // — `adr` takes the id from the caller — and is guarded.
1693            this.labels[label as usize] = Some(this.code.len());
1694            this.code.extend_from_slice(&bytes);
1695        }
1696        // 4. adr fixups (blob labels now bound).
1697        for (pos, label) in core::mem::take(&mut this.adrs) {
1698            let target = match this.labels.get(label as usize) {
1699                Some(Some(t)) => *t,
1700                Some(None) => {
1701                    return Err(AsmError::Layout {
1702                        at: pos,
1703                        msg: format!("unbound blob label {label}"),
1704                    })
1705                }
1706                None => {
1707                    return Err(AsmError::Layout {
1708                        at: pos,
1709                        msg: format!("blob label {label} was never reserved by `label()`"),
1710                    })
1711                }
1712            };
1713            let base = (pos as u32 + 4) & !3;
1714            let imm = target as u32;
1715            if imm < base || (imm - base) % 4 != 0 || (imm - base) / 4 > 0xFF {
1716                return Err(AsmError::Layout {
1717                    at: pos,
1718                    msg: format!("adr target out of range (pos=0x{pos:x} target=0x{target:x})"),
1719                });
1720            }
1721            let enc = 0xA000u16
1722                | ((u16::from_le_bytes([this.code[pos], this.code[pos + 1]]) >> 8 & 7) << 8)
1723                | ((imm - base) / 4) as u16;
1724            this.code[pos..pos + 2].copy_from_slice(&enc.to_le_bytes());
1725        }
1726        Ok(this.code)
1727    }
1728}
1729
1730/// Decode a Thumb `BL` at file offset `off` → its absolute target VA (Thumb bit
1731/// cleared). `None` if the 4 bytes at `off` are not a `BL`.
1732pub fn decode_bl(image: &[u8], off: usize) -> Option<u32> {
1733    let b = image.get(off..off.checked_add(4)?)?;
1734    let hw1 = u16::from_le_bytes([b[0], b[1]]);
1735    let hw2 = u16::from_le_bytes([b[2], b[3]]);
1736    if (hw1 & 0xF800) != 0xF000 || (hw2 & 0xD000) != 0xD000 {
1737        return None;
1738    }
1739    let s = ((hw1 >> 10) & 1) as u32;
1740    let imm10 = (hw1 & 0x3FF) as u32;
1741    let j1 = ((hw2 >> 13) & 1) as u32;
1742    let j2 = ((hw2 >> 11) & 1) as u32;
1743    let imm11 = (hw2 & 0x7FF) as u32;
1744    let i1 = (!(j1 ^ s)) & 1;
1745    let i2 = (!(j2 ^ s)) & 1;
1746    let mut imm = (imm11 | (imm10 << 11) | (i2 << 21) | (i1 << 22) | (s << 23)) << 1;
1747    if imm & (1 << 24) != 0 {
1748        imm |= !0u32 << 25;
1749    }
1750    Some((off as u32).wrapping_add(4).wrapping_add(imm))
1751}
1752
1753/// Encode a Thumb `BL` at file offset `site` that calls absolute target `target`
1754/// (Thumb bit is implicit; pass the even entry address). Returns the 4 bytes, or
1755/// `None` if `target` is out of `BL` range (±16 MiB).
1756pub fn encode_bl(site: usize, target: u32) -> Option<[u8; 4]> {
1757    let pc = (site as u32).wrapping_add(4);
1758    let off = (target.wrapping_sub(pc)) as i32;
1759    if !(-(1 << 24)..(1 << 24)).contains(&off) || off & 1 != 0 {
1760        return None;
1761    }
1762    let imm = (off >> 1) as u32 & 0x00ff_ffff;
1763    let s = (imm >> 23) & 1;
1764    let i1 = (imm >> 22) & 1;
1765    let i2 = (imm >> 21) & 1;
1766    let imm10 = (imm >> 11) & 0x3ff;
1767    let imm11 = imm & 0x7ff;
1768    let j1 = (!(i1 ^ s)) & 1;
1769    let j2 = (!(i2 ^ s)) & 1;
1770    let hw1 = 0xF000 | (s << 10) as u16 | imm10 as u16;
1771    let hw2 = 0xD000 | (j1 << 13) as u16 | (j2 << 11) as u16 | imm11 as u16;
1772    let mut out = [0u8; 4];
1773    out[0..2].copy_from_slice(&hw1.to_le_bytes());
1774    out[2..4].copy_from_slice(&hw2.to_le_bytes());
1775    Some(out)
1776}
1777
1778/// Encode a Thumb-2 **wide unconditional branch** (`B.W`, T4 encoding) at file
1779/// offset `site` that jumps to absolute target `target` (Thumb bit implicit;
1780/// pass the even entry address). Same 4-byte width and same imm packing as
1781/// [`encode_bl`] — the only difference is `hw2`'s base (`0x9000` for `B.W`
1782/// instead of `0xD000` for `BL`, i.e. bit 14 cleared). Same ±16 MiB range.
1783///
1784/// Use this over `encode_bl` when the site being patched sits at a **tail-call
1785/// idiom** (OEM `b <shared_leaf>` returned to the OUTER function's caller via
1786/// the shared leaf's `bx lr`). A `bl` install would clobber the outer function's
1787/// `lr` with `site+4`, so the shared leaf's `bx lr` would land inside the outer
1788/// function instead of at its caller — running code the OEM never reaches on
1789/// that path. `B.W` preserves `lr` unchanged, so the tail-call semantics are
1790/// exact.
1791pub fn encode_b_wide(site: usize, target: u32) -> Option<[u8; 4]> {
1792    let pc = (site as u32).wrapping_add(4);
1793    let off = (target.wrapping_sub(pc)) as i32;
1794    if !(-(1 << 24)..(1 << 24)).contains(&off) || off & 1 != 0 {
1795        return None;
1796    }
1797    let imm = (off >> 1) as u32 & 0x00ff_ffff;
1798    let s = (imm >> 23) & 1;
1799    let i1 = (imm >> 22) & 1;
1800    let i2 = (imm >> 21) & 1;
1801    let imm10 = (imm >> 11) & 0x3ff;
1802    let imm11 = imm & 0x7ff;
1803    let j1 = (!(i1 ^ s)) & 1;
1804    let j2 = (!(i2 ^ s)) & 1;
1805    let hw1 = 0xF000 | (s << 10) as u16 | imm10 as u16;
1806    let hw2 = 0x9000 | (j1 << 13) as u16 | (j2 << 11) as u16 | imm11 as u16;
1807    let mut out = [0u8; 4];
1808    out[0..2].copy_from_slice(&hw1.to_le_bytes());
1809    out[2..4].copy_from_slice(&hw2.to_le_bytes());
1810    Some(out)
1811}
1812
1813/// Decode a Thumb-2 `B.W` (T4) at `off` and return its absolute target (Thumb
1814/// bit cleared), or `None` if the two halfwords there are not a `B.W`. Mirror
1815/// of [`decode_bl`] but discriminates on the `hw2` bit-12=1 && bit-14=0 pattern
1816/// (`B.W`) vs bit-12=1 && bit-14=1 (`BL`).
1817pub fn decode_b_wide(image: &[u8], at: usize) -> Option<u32> {
1818    // `checked_add`, not `at + 4`: `at` is routinely a scan offset derived from
1819    // image content, and on a 32-bit target the sum can wrap back into bounds
1820    // and read the wrong four bytes. Same rule as `try_read_u32`.
1821    if at.checked_add(4).map_or(true, |end| end > image.len()) {
1822        return None;
1823    }
1824    let hw1 = u16::from_le_bytes([image[at], image[at + 1]]);
1825    let hw2 = u16::from_le_bytes([image[at + 2], image[at + 3]]);
1826    // `hw1 = 11110 S imm10` and `hw2 = 10 J1 0 J2 imm11` (B.W T4).
1827    if (hw1 & 0xF800) != 0xF000 || (hw2 & 0xD000) != 0x9000 {
1828        return None;
1829    }
1830    let s = ((hw1 >> 10) & 1) as u32;
1831    let imm10 = (hw1 & 0x3FF) as u32;
1832    let j1 = ((hw2 >> 13) & 1) as u32;
1833    let j2 = ((hw2 >> 11) & 1) as u32;
1834    let imm11 = (hw2 & 0x7FF) as u32;
1835    let i1 = (!(j1 ^ s)) & 1;
1836    let i2 = (!(j2 ^ s)) & 1;
1837    let mut imm = (imm11 | (imm10 << 11) | (i2 << 21) | (i1 << 22) | (s << 23)) << 1;
1838    if imm & (1 << 24) != 0 {
1839        imm |= !0u32 << 25;
1840    }
1841    Some((at as u32).wrapping_add(4).wrapping_add(imm))
1842}
1843
1844/// Every file offset holding a Thumb `BL` whose target is `target` (Thumb bit
1845/// ignored). These are the direct call sites that reach a handler — the thing to
1846/// redirect when a firmware dispatches by hardcoded call rather than a table.
1847///
1848/// The scan is every even offset with room for four bytes, so the last site
1849/// considered is `len - 4`. (Through 0.1.0 the bound was
1850/// `len.saturating_sub(4)` used *exclusively*, which stopped one site short and
1851/// missed a `BL` occupying the final four bytes of an image — the case where a
1852/// dispatch table or trailing thunk sits right at the end.)
1853///
1854/// Being a blind even-offset scan, it can in principle match four bytes that
1855/// are really the tail of some other instruction; corroborate a hit with
1856/// [`prologue_is_push_lr`] on its target when that matters.
1857pub fn find_bl_sites(image: &[u8], target: u32) -> Vec<usize> {
1858    let want = target & !1;
1859    (0..image.len().saturating_sub(3))
1860        .step_by(2)
1861        .filter(|&off| decode_bl(image, off).map(|t| t & !1) == Some(want))
1862        .collect()
1863}
1864
1865/// A decoded conditional branch: which condition, where it goes, and how wide
1866/// the instruction was.
1867///
1868/// Produced by [`decode_b_cond`], which resolves both the 16-bit T1 and the
1869/// 32-bit T3 encodings into this one shape so a caller can step over the
1870/// instruction (`at + len`) without caring which it found.
1871#[derive(Debug, Clone, Copy, PartialEq, Eq)]
1872pub struct CondBranch {
1873    /// The branch condition.
1874    pub cond: Cond,
1875    /// Absolute target offset in the image (`at + 4 + imm32`), Thumb bit not
1876    /// set — this is a file offset in the same flat space as `at`.
1877    pub target: u32,
1878    /// Instruction width in bytes: 2 for T1, 4 for T3.
1879    pub len: usize,
1880}
1881
1882/// Decode the conditional branch at `at`, in either encoding, or `None` if the
1883/// bytes there are not one.
1884///
1885/// # T1 — 16-bit, `1101 cond imm8` (A5.2.6, A7.7.12)
1886///
1887/// `target = at + 4 + SignExtend(imm8:'0')`, so ±254 bytes.
1888///
1889/// **`0b1101xxxx` is not all branches.** Per Table A5-8, `cond == 0b1110` is
1890/// the permanently UNDEFINED `UDF` (A7.7.194) and `cond == 0b1111` is `SVC`
1891/// (A7.7.175) — a supervisor call, which transfers control somewhere entirely
1892/// unrelated to any `imm8`-relative target. Neither is a branch, so this
1893/// function returns `None` for `0xDE**` and `0xDF**`. Code that treats
1894/// `0xD0xx..=0xDFxx` as the conditional-branch range is wrong for exactly those
1895/// two sixteenths of it, and will read an `SVC #n` as a branch to `at + 4 + 2n`.
1896/// The correct range is `0xD0xx..=0xDDxx`.
1897///
1898/// # T3 — 32-bit, `hw1 = 11110 S cond imm6`, `hw2 = 10 J1 0 J2 imm11` (A5.3.4)
1899///
1900/// Matched by `(hw1 & 0xF800) == 0xF000 && (hw2 & 0xD000) == 0x8000`, with
1901/// `target = at + 4 + SignExtend(S:J2:J1:imm6:imm11:'0')` — ±1 MB.
1902///
1903/// Mind the packing: T3 is **not** the `BL`/`B.W` scheme. Those pack
1904/// `S:I1:I2:imm10:imm11` with `I1 = NOT(J1 EOR S)` and `I2 = NOT(J2 EOR S)`;
1905/// T3 packs `S:J2:J1:imm6:imm11` — J2 and J1 in the opposite order, used
1906/// directly with no inversion, over a 6-bit rather than 10-bit high field.
1907/// Reusing [`decode_bl`]'s arithmetic here produces a plausible, wrong target.
1908/// (Verified against ARM DDI 0403E.e A7.7.12 and DDI 0406B A8.6.16.)
1909///
1910/// `cond<3:1> == 0b111` in T3 is "see Related encodings" — `MSR`/`MRS`, hints,
1911/// `UDF.W`, `BL` — so, as in T1, both `0b1110` and `0b1111` decode as `None`.
1912///
1913/// ```
1914/// use thumb_asm::{decode_b_cond, Cond};
1915///
1916/// // `bmi` T1 at offset 0, reaching 0x20: 0xD40E.
1917/// let b = decode_b_cond(&[0x0E, 0xD4], 0).unwrap();
1918/// assert_eq!((b.cond, b.target, b.len), (Cond::Mi, 0x20, 2));
1919///
1920/// // `UDF` and `SVC` share the space but are not branches.
1921/// assert!(decode_b_cond(&[0x00, 0xDE], 0).is_none());
1922/// assert!(decode_b_cond(&[0x00, 0xDF], 0).is_none());
1923/// ```
1924pub fn decode_b_cond(image: &[u8], at: usize) -> Option<CondBranch> {
1925    let hw1 = try_read_u16(image, at)?;
1926
1927    // T1: 1101 cond imm8.
1928    if (hw1 & 0xF000) == 0xD000 {
1929        // 0xDE** is UDF and 0xDF** is SVC: `Cond::from_bits` rejects 0b1111
1930        // outright, and 0b1110 comes back as `Al`, which this space cannot
1931        // encode. Both are "not a branch".
1932        let cond = match Cond::from_bits(((hw1 >> 8) & 0xF) as u8) {
1933            Some(c) if c != Cond::Al => c,
1934            _ => return None,
1935        };
1936        let imm = ((hw1 & 0xFF) as u8 as i8 as i32) * 2;
1937        return Some(CondBranch {
1938            cond,
1939            target: (at as u32).wrapping_add(4).wrapping_add(imm as u32),
1940            len: 2,
1941        });
1942    }
1943
1944    // T3: hw1 = 11110 S cond imm6, hw2 = 10 J1 0 J2 imm11.
1945    let hw2 = try_read_u16(image, at + 2)?;
1946    if (hw1 & 0xF800) != 0xF000 || (hw2 & 0xD000) != 0x8000 {
1947        return None;
1948    }
1949    // `cond<3:1> == 0b111` is "see Related encodings" — MSR/MRS, hints, UDF.W,
1950    // BL — so again neither 0b1110 (`Al`) nor 0b1111 is a branch here.
1951    let cond = match Cond::from_bits(((hw1 >> 6) & 0xF) as u8) {
1952        Some(c) if c != Cond::Al => c,
1953        _ => return None,
1954    };
1955    let s = ((hw1 >> 10) & 1) as u32;
1956    let imm6 = (hw1 & 0x3F) as u32;
1957    let j1 = ((hw2 >> 13) & 1) as u32;
1958    let j2 = ((hw2 >> 11) & 1) as u32;
1959    let imm11 = (hw2 & 0x7FF) as u32;
1960    let mut imm = (imm11 | (imm6 << 11) | (j1 << 17) | (j2 << 18) | (s << 19)) << 1;
1961    if imm & (1 << 20) != 0 {
1962        imm |= !0u32 << 21;
1963    }
1964    Some(CondBranch {
1965        cond,
1966        target: (at as u32).wrapping_add(4).wrapping_add(imm),
1967        len: 4,
1968    })
1969}
1970
1971/// Encode a conditional branch at file offset `site` to absolute `target`,
1972/// choosing the narrowest encoding that reaches: 2 bytes (T1, ±254) if it fits,
1973/// else 4 bytes (T3, ±1 MB), else `None`.
1974///
1975/// `None` also for an odd displacement (Thumb instructions are halfword
1976/// aligned) and for [`Cond::Al`], which **has no conditional-branch encoding**:
1977/// `0b1110` is `UDF` in T1 and a different instruction class in T3 (see
1978/// [`decode_b_cond`]). Emit [`encode_b_wide`] — or a 16-bit `B` T2 — for an
1979/// unconditional branch.
1980///
1981/// Round-trips with [`decode_b_cond`] for every value it accepts.
1982///
1983/// ```
1984/// use thumb_asm::{encode_b_cond, Cond};
1985///
1986/// assert_eq!(encode_b_cond(0, Cond::Mi, 0x20), Some(vec![0x0E, 0xD4]));
1987/// // Too far for T1, so T3: `bmi.w` +0x10000.
1988/// assert_eq!(
1989///     encode_b_cond(0x1000, Cond::Mi, 0x1_1004),
1990///     Some(vec![0x10, 0xF1, 0x00, 0x80])
1991/// );
1992/// assert_eq!(encode_b_cond(0, Cond::Al, 0x20), None); // no such encoding
1993/// ```
1994pub fn encode_b_cond(site: usize, cond: Cond, target: u32) -> Option<Vec<u8>> {
1995    if cond == Cond::Al {
1996        return None;
1997    }
1998    let bits = cond.bits() as u16;
1999    let pc = (site as u32).wrapping_add(4);
2000    let off = target.wrapping_sub(pc) as i32;
2001    if off & 1 != 0 {
2002        return None;
2003    }
2004    // T1: 1101 cond imm8, offsets -256..=254 (A7.7.12).
2005    if (-256..=254).contains(&off) {
2006        let hw = 0xD000u16 | (bits << 8) | ((off >> 1) as i8 as u8 as u16);
2007        return Some(hw.to_le_bytes().to_vec());
2008    }
2009    // T3: S:J2:J1:imm6:imm11, offsets -1048576..=1048574 (A7.7.12).
2010    if !(-1_048_576..=1_048_574).contains(&off) {
2011        return None;
2012    }
2013    let imm = (off >> 1) as u32 & 0xF_FFFF;
2014    let s = (imm >> 19) & 1;
2015    let j2 = (imm >> 18) & 1;
2016    let j1 = (imm >> 17) & 1;
2017    let imm6 = (imm >> 11) & 0x3F;
2018    let imm11 = imm & 0x7FF;
2019    let hw1 = 0xF000u16 | (s as u16) << 10 | (bits << 6) | imm6 as u16;
2020    let hw2 = 0x8000u16 | (j1 as u16) << 13 | (j2 as u16) << 11 | imm11 as u16;
2021    let mut out = Vec::with_capacity(4);
2022    out.extend_from_slice(&hw1.to_le_bytes());
2023    out.extend_from_slice(&hw2.to_le_bytes());
2024    Some(out)
2025}
2026
2027/// Which 4-byte branch a detour site is patched with.
2028///
2029/// Both members are 32-bit and ±16 MB, and differ only in whether `lr` is
2030/// written; see [`encode_b_wide`] for when that distinction decides a patch.
2031#[derive(Debug, Clone, Copy, PartialEq, Eq)]
2032#[non_exhaustive]
2033pub enum BranchKind {
2034    /// `BL` (T1) — a call: sets `lr` to `site + 4`, so the callee returns here.
2035    Bl,
2036    /// `B.W` (T4) — a jump: leaves `lr` untouched, so the callee returns to
2037    /// whatever called *this* function. The right choice at a tail call.
2038    BWide,
2039}
2040
2041impl BranchKind {
2042    /// Encode a branch of this kind at `site` to `target`, or `None` if the
2043    /// displacement is out of range or odd. Thin dispatch over [`encode_bl`]
2044    /// and [`encode_b_wide`].
2045    pub fn encode(self, site: usize, target: u32) -> Option<[u8; 4]> {
2046        match self {
2047            BranchKind::Bl => encode_bl(site, target),
2048            BranchKind::BWide => encode_b_wide(site, target),
2049        }
2050    }
2051
2052    /// Decode a branch of this kind at `at` to its absolute target, or `None`
2053    /// if the four bytes there are not one. Thin dispatch over [`decode_bl`]
2054    /// and [`decode_b_wide`].
2055    pub fn decode(self, image: &[u8], at: usize) -> Option<u32> {
2056        match self {
2057            BranchKind::Bl => decode_bl(image, at),
2058            BranchKind::BWide => decode_b_wide(image, at),
2059        }
2060    }
2061}
2062
2063impl core::fmt::Display for BranchKind {
2064    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
2065        f.write_str(match self {
2066            BranchKind::Bl => "bl",
2067            BranchKind::BWide => "b.w",
2068        })
2069    }
2070}
2071
2072/// The four bytes at a detour site do not branch where they were meant to.
2073///
2074/// Returned by [`verify_branch`] and [`install_branch`]. `expected` and `found`
2075/// are both stored with bit 0 cleared, so a caller can print or compare them
2076/// without re-deriving the Thumb-bit convention (see [`verify_branch`]).
2077#[derive(Debug, Clone, Copy, PartialEq, Eq)]
2078#[non_exhaustive]
2079pub struct InstallMismatch {
2080    /// File offset that was checked.
2081    pub site: usize,
2082    /// The branch kind that was expected there.
2083    pub kind: BranchKind,
2084    /// The intended target, Thumb bit masked off.
2085    pub expected: u32,
2086    /// What actually decodes there, Thumb bit masked off — or `None` if the
2087    /// bytes are not a branch of that kind at all (which is also what
2088    /// [`install_branch`] reports when `expected` was out of range and so
2089    /// nothing was written).
2090    pub found: Option<u32>,
2091}
2092
2093impl InstallMismatch {
2094    /// A stable, machine-readable reason: `"not-a-branch"` when nothing of the
2095    /// expected kind decodes at the site, `"wrong-target"` when one does but
2096    /// points elsewhere.
2097    ///
2098    /// The distinction matters and is otherwise only recoverable by inspecting
2099    /// [`found`](Self::found): a `None` there means the write did not happen
2100    /// or was overwritten, while a `Some` means it happened and landed wrong.
2101    pub fn reason(&self) -> &'static str {
2102        match self.found {
2103            None => "not-a-branch",
2104            Some(_) => "wrong-target",
2105        }
2106    }
2107}
2108
2109impl core::fmt::Display for InstallMismatch {
2110    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
2111        let Self {
2112            site,
2113            kind,
2114            expected,
2115            found,
2116        } = self;
2117        match found {
2118            Some(got) => write!(
2119                f,
2120                "{kind} at 0x{site:x}: expected target 0x{expected:08x}, found 0x{got:08x}"
2121            ),
2122            None => write!(
2123                f,
2124                "{kind} at 0x{site:x}: expected target 0x{expected:08x}, \
2125                 but no {kind} decodes there"
2126            ),
2127        }
2128    }
2129}
2130
2131impl std::error::Error for InstallMismatch {}
2132
2133/// What is already at a patch site. Returned by [`classify_branch`].
2134#[derive(Debug, Clone, Copy, PartialEq, Eq)]
2135#[non_exhaustive]
2136pub enum BranchAt {
2137    /// Nothing decoded there, or what decoded is not a branch.
2138    NotABranch,
2139    /// A branch whose destination is fixed in the encoding.
2140    Direct {
2141        /// Which installable kind this is, or `None` for a direct branch that
2142        /// [`install_branch`] cannot write — a 16-bit `b`, a `cbz`, a `blx`
2143        /// to an Arm-state label. `None` is the interesting answer: it means
2144        /// the site holds a branch you cannot replace in place without
2145        /// thinking about width.
2146        kind: Option<BranchKind>,
2147        /// How many bytes it occupies: 2 or 4. **This is the field that
2148        /// matters.** Writing a 4-byte branch over a 2-byte one does not just
2149        /// change the branch, it overwrites the instruction after it.
2150        width: u8,
2151        /// Where it goes, with the Thumb bit already cleared.
2152        target: u32,
2153    },
2154    /// A branch whose destination is computed — `bx`/`blx` on a register,
2155    /// `ldr pc, [..]`, `tbb`/`tbh`. There is no target to compare against.
2156    Indirect {
2157        /// How many bytes it occupies: 2 or 4.
2158        width: u8,
2159    },
2160}
2161
2162/// Why [`can_install`] says a site cannot take a branch.
2163#[derive(Debug, Clone, Copy, PartialEq, Eq)]
2164#[non_exhaustive]
2165pub enum InstallHazard {
2166    /// The four bytes do not fit: `site + 4` is past the end of the image.
2167    OutOfBounds {
2168        /// The site asked about.
2169        site: usize,
2170        /// How many bytes the image actually has.
2171        image_len: usize,
2172    },
2173    /// Nothing at `site` decodes as an instruction, so what a branch would
2174    /// overwrite is unknown. Either the offset is wrong or it is mid-
2175    /// instruction — both are reasons not to write.
2176    NotAnInstruction {
2177        /// The site asked about.
2178        site: usize,
2179    },
2180    /// The four bytes end in the middle of an instruction.
2181    ///
2182    /// This is the hazard [`classify_branch`]'s `width` hints at, stated
2183    /// outright. A 16-bit instruction followed by a 32-bit one spans six
2184    /// bytes, so a four-byte branch leaves the last two halves of a wide
2185    /// instruction behind, to be executed as whatever they happen to encode.
2186    SplitsInstruction {
2187        /// Where the straddled instruction starts.
2188        at: usize,
2189        /// How many bytes whole instructions actually occupy from the site —
2190        /// always more than 4. Displacing that many is what a detour does;
2191        /// see [`crate::detour::detour`], which relocates them rather than
2192        /// leaving them cut.
2193        displaced: usize,
2194    },
2195}
2196
2197impl InstallHazard {
2198    /// A stable, machine-readable reason: `"out-of-bounds"`,
2199    /// `"not-an-instruction"` or `"splits-instruction"`.
2200    ///
2201    /// Matches the convention every other error type in this crate follows,
2202    /// so a caller can log or branch on the cause without matching variants —
2203    /// which matters here because this enum is `#[non_exhaustive]` and will
2204    /// grow as more pre-flight hazards become checkable.
2205    pub fn reason(&self) -> &'static str {
2206        match self {
2207            InstallHazard::OutOfBounds { .. } => "out-of-bounds",
2208            InstallHazard::NotAnInstruction { .. } => "not-an-instruction",
2209            InstallHazard::SplitsInstruction { .. } => "splits-instruction",
2210        }
2211    }
2212}
2213
2214impl core::fmt::Display for InstallHazard {
2215    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
2216        match self {
2217            InstallHazard::OutOfBounds { site, image_len } => write!(
2218                f,
2219                "a 4-byte branch at {site:#x} runs past the end of a {image_len:#x}-byte image"
2220            ),
2221            InstallHazard::NotAnInstruction { site } => {
2222                write!(f, "nothing decodes at {site:#x}")
2223            }
2224            InstallHazard::SplitsInstruction { at, displaced } => write!(
2225                f,
2226                "a 4-byte branch at this site cuts the instruction at {at:#x} in half; \
2227                 whole instructions occupy {displaced} bytes"
2228            ),
2229        }
2230    }
2231}
2232
2233impl std::error::Error for InstallHazard {}
2234
2235/// Would installing a 4-byte branch here overwrite whole instructions?
2236///
2237/// [`classify_branch`] reports the width of what is at a site; this answers
2238/// the question that width was being consulted for. Leaving callers to do the
2239/// arithmetic themselves is leaving them to do the reasoning that goes wrong:
2240/// every branch this crate installs is four bytes, and four bytes only land
2241/// cleanly when the instructions at the site add up to exactly four.
2242///
2243/// The hazard is more general than "the site holds a 16-bit branch". Any
2244/// 2-byte instruction followed by a 4-byte one spans six, and cutting it
2245/// leaves two bytes that will be executed as whatever they encode. That is
2246/// the case this catches and a `width` check alone does not.
2247///
2248/// `kind` is accepted so the signature reads at the call site and so a future
2249/// narrow branch kind does not change it; both current kinds are four bytes,
2250/// so it does not currently affect the answer.
2251///
2252/// An `Ok` here does **not** mean the patch is a good idea — only that it
2253/// destroys whole instructions rather than half of one. Use
2254/// [`crate::detour::detour`] when the displaced instructions still need to
2255/// run.
2256///
2257/// ```
2258/// use thumb_asm::{can_install, BranchKind, InstallHazard};
2259///
2260/// // `movs r0, #1` · `movs r1, #2` — two 16-bit instructions, exactly 4 bytes.
2261/// assert!(can_install(&[0x01, 0x20, 0x02, 0x21], 0, BranchKind::Bl).is_ok());
2262///
2263/// // `movs r0, #1` · `bl +0` — 2 + 4 bytes. A 4-byte branch cuts the `bl`.
2264/// let image = [0x01, 0x20, 0xFF, 0xF7, 0xFE, 0xFF];
2265/// assert_eq!(
2266///     can_install(&image, 0, BranchKind::Bl),
2267///     Err(InstallHazard::SplitsInstruction { at: 2, displaced: 6 })
2268/// );
2269/// ```
2270pub fn can_install(image: &[u8], site: usize, kind: BranchKind) -> Result<(), InstallHazard> {
2271    can_install_with(isa::Target::Union, image, site, kind)
2272}
2273
2274/// Same as [`can_install`] but for a caller who knows the image's ISA
2275/// [`isa::Target`]. This is the load-bearing surface for the 0.14.0 detour
2276/// path: under `Target::Union` an Armv8-M `SG` at the hook site decodes as
2277/// a plain `LDRD` (the whole reason [`isa::Target`] exists — 0.12.0), so
2278/// `can_install` silently green-lights overwriting the Security Gateway.
2279/// A caller who passes `Target::V8M` gets the honest answer, which is
2280/// still `Ok(())` today because `SG` is a legal instruction on that target,
2281/// but sets the stage for follow-on hazards
2282/// (`InstallHazard::SecureGateway`, planned for 0.14.x) to fire from this
2283/// path.
2284pub fn can_install_with(
2285    target: isa::Target,
2286    image: &[u8],
2287    site: usize,
2288    kind: BranchKind,
2289) -> Result<(), InstallHazard> {
2290    let _ = kind; // every kind this crate installs is four bytes.
2291    if site.checked_add(4).map_or(true, |end| end > image.len()) {
2292        return Err(InstallHazard::OutOfBounds {
2293            site,
2294            image_len: image.len(),
2295        });
2296    }
2297    let mut at = site;
2298    while at < site + 4 {
2299        let insn = match isa::decode_at_with(image, at, at as u32, target) {
2300            Some(i) => i,
2301            None => return Err(InstallHazard::NotAnInstruction { site: at }),
2302        };
2303        let next = at + insn.len();
2304        if next > site + 4 {
2305            return Err(InstallHazard::SplitsInstruction {
2306                at,
2307                displaced: next - site,
2308            });
2309        }
2310        at = next;
2311    }
2312    Ok(())
2313}
2314
2315/// Ask what branch is already at `at`, before overwriting it.
2316///
2317/// [`verify_branch`] checks an *assertion*: you say which kind and target you
2318/// expect and it agrees or disagrees. That cannot catch the case where the
2319/// expectation itself is wrong — which is the interesting failure, because a
2320/// patcher that believes the site holds a `BL` when it holds a `B` will
2321/// happily install the wrong one and report success.
2322///
2323/// This asks the question instead of asserting the answer. The decoder already
2324/// knows; this only puts it in the same vocabulary [`install_branch`] takes.
2325///
2326/// # The width is the dangerous part
2327///
2328/// A 16-bit `b` at the site is [`BranchAt::Direct`] with `kind: None` and
2329/// `width: 2`. [`install_branch`] only writes 4-byte branches, so patching
2330/// over it silently consumes the two bytes of whatever follows. Checking
2331/// `width` before installing turns that from a field-reported brick into a
2332/// refusal:
2333///
2334/// ```
2335/// use thumb_asm::{classify_branch, BranchAt, BranchKind};
2336///
2337/// // `b.n +0` — a 16-bit unconditional branch.
2338/// let image = [0xFE, 0xE7];
2339/// match classify_branch(&image, 0) {
2340///     BranchAt::Direct { kind, width, .. } => {
2341///         assert_eq!(kind, None, "not a kind install_branch can write");
2342///         assert_eq!(width, 2, "installing a 4-byte branch here eats the next instruction");
2343///     }
2344///     other => panic!("expected a direct branch, got {other:?}"),
2345/// }
2346///
2347/// // `bl +0` — 4 bytes, and installable.
2348/// let image = [0xFF, 0xF7, 0xFE, 0xFF];
2349/// assert!(matches!(
2350///     classify_branch(&image, 0),
2351///     BranchAt::Direct { kind: Some(BranchKind::Bl), width: 4, .. }
2352/// ));
2353/// ```
2354pub fn classify_branch(image: &[u8], at: usize) -> BranchAt {
2355    classify_branch_with(isa::Target::Union, image, at)
2356}
2357
2358/// Same as [`classify_branch`] but for a caller who knows the image's ISA
2359/// [`isa::Target`]. Under `Target::V8M` this is what lets a hook-site check
2360/// see a CMSE gateway (`SG`) as `NotABranch` — since `SG` is not a
2361/// branch — rather than as a fake pc-relative `LDRD` whose displacement
2362/// then gets followed as a "branch target that carries a literal
2363/// address". See [`can_install_with`] for the parallel argument on the
2364/// install side.
2365pub fn classify_branch_with(target: isa::Target, image: &[u8], at: usize) -> BranchAt {
2366    let insn = match isa::decode_at_with(image, at, at as u32, target) {
2367        Some(i) => i,
2368        None => return BranchAt::NotABranch,
2369    };
2370    if !insn.is_branch() {
2371        return BranchAt::NotABranch;
2372    }
2373    let width = insn.len() as u8;
2374    // A `Target` alongside a `Mem` is the address of a literal-pool word, not
2375    // a destination — the same overload `analysis::reachable` documents, and
2376    // the shape of `ldr pc, [pc, #imm]`, which is emphatically indirect.
2377    let has_mem = insn
2378        .operands
2379        .as_slice()
2380        .any(|o| matches!(o, isa::Operand::Mem(_)));
2381    match insn.branch_target() {
2382        Some(target) if !has_mem => {
2383            let kind = match (insn.mnemonic, insn.len()) {
2384                ("bl", 4) => Some(BranchKind::Bl),
2385                ("b", 4) => Some(BranchKind::BWide),
2386                _ => None,
2387            };
2388            BranchAt::Direct {
2389                kind,
2390                width,
2391                target: target & !1,
2392            }
2393        }
2394        _ => BranchAt::Indirect { width },
2395    }
2396}
2397
2398/// Confirm that the four bytes at `site` are a `kind` branch to `expected`.
2399///
2400/// This is the check every consumer of this crate ends up writing by hand after
2401/// patching a detour site: encode, write, then *decode the image back* and
2402/// prove the bytes now mean what was intended. Decoding back is what catches a
2403/// truncated displacement, a half-written patch, or a site that was never four
2404/// bytes of branch to begin with — none of which the encoder can see.
2405///
2406/// # The Thumb bit
2407///
2408/// Branch targets in a Thumb image are routinely carried with bit 0 set, since
2409/// that is the form `bx`/`blx` and a function pointer need. The *encoded*
2410/// displacement has no room for it: `BL` and `B.W` targets are halfword
2411/// aligned, so bit 0 is always zero on the way out of a decoder. This function
2412/// therefore masks bit 0 off **both** sides before comparing, and `expected`
2413/// may be passed in either form. If a caller needs to distinguish `0x1234` from
2414/// `0x1235` it is not asking about a branch target.
2415pub fn verify_branch(
2416    image: &[u8],
2417    site: usize,
2418    kind: BranchKind,
2419    expected: u32,
2420) -> Result<(), InstallMismatch> {
2421    let expected = expected & !1;
2422    let found = kind.decode(image, site).map(|t| t & !1);
2423    if found == Some(expected) {
2424        Ok(())
2425    } else {
2426        Err(InstallMismatch {
2427            site,
2428            kind,
2429            expected,
2430            found,
2431        })
2432    }
2433}
2434
2435/// Encode a `kind` branch from `site` to `target`, write it into `image`, and
2436/// verify by decoding it back — the whole install-a-detour pattern in one call.
2437///
2438/// Fails, writing nothing, when the displacement is out of range for `kind`,
2439/// when it is odd, or when `site` has fewer than four bytes after it; the
2440/// returned [`InstallMismatch`] has `found: None` in each case. Bit 0 of
2441/// `target` is masked off, so a Thumb-bit-carrying address may be passed
2442/// directly — see [`verify_branch`].
2443///
2444/// The trailing verification is not paranoia about this crate's own encoder: it
2445/// is what makes the operation *self-checking at the byte level*, so a caller
2446/// that later re-runs it over an already-patched image, or over an image some
2447/// other tool touched, gets a definite answer rather than a silent overwrite.
2448///
2449/// ```
2450/// use thumb_asm::{decode_bl, install_branch, verify_branch, BranchKind};
2451///
2452/// let mut image = vec![0u8; 0x100];
2453/// install_branch(&mut image, 0x10, BranchKind::Bl, 0x81).unwrap(); // Thumb bit ok
2454/// assert_eq!(decode_bl(&image, 0x10), Some(0x80));
2455/// assert!(verify_branch(&image, 0x10, BranchKind::Bl, 0x80).is_ok());
2456///
2457/// // Wrong kind at the same site: a `bl` is not a `b.w`.
2458/// let err = verify_branch(&image, 0x10, BranchKind::BWide, 0x80).unwrap_err();
2459/// assert_eq!(err.found, None);
2460/// ```
2461pub fn install_branch(
2462    image: &mut [u8],
2463    site: usize,
2464    kind: BranchKind,
2465    target: u32,
2466) -> Result<(), InstallMismatch> {
2467    let target = target & !1;
2468    let fail = || InstallMismatch {
2469        site,
2470        kind,
2471        expected: target,
2472        found: None,
2473    };
2474    if site.checked_add(4).map_or(true, |end| end > image.len()) {
2475        return Err(fail());
2476    }
2477    let bytes = kind.encode(site, target).ok_or_else(fail)?;
2478    write(image, site, &bytes);
2479    verify_branch(image, site, kind, target)
2480}
2481
2482// --- internal matchers (the actual scans behind `find`) ---
2483
2484fn find_bytes(image: &[u8], pat: &[u8], start: usize) -> Option<usize> {
2485    find_bytes_in(image, pat, start, image.len())
2486}
2487
2488/// `find_bytes`, bounded above: the match must lie entirely within
2489/// `[start, end)`.
2490fn find_bytes_in(image: &[u8], pat: &[u8], start: usize, end: usize) -> Option<usize> {
2491    let end = end.min(image.len());
2492    if pat.is_empty() || start >= end || pat.len() > end - start {
2493        return None;
2494    }
2495    image[start..end]
2496        .windows(pat.len())
2497        .position(|w| w == pat)
2498        .map(|p| p + start)
2499}
2500
2501fn find_free_run(image: &[u8], len: usize, align: usize, start: usize) -> Option<usize> {
2502    find_free_run_in(image, len, align, start, image.len())
2503}
2504
2505/// `find_free_run`, bounded above. Alignment is still measured from the image
2506/// origin, not from `start` — that is the whole reason this takes a window
2507/// rather than the caller slicing and searching the slice.
2508fn find_free_run_in(
2509    image: &[u8],
2510    len: usize,
2511    align: usize,
2512    start: usize,
2513    end: usize,
2514) -> Option<usize> {
2515    assert!(align != 0, "alignment must be at least 1 byte");
2516    let end = end.min(image.len());
2517    let mut p = round_up(start.min(end), align);
2518    loop {
2519        // `checked_add`, because `len` is the caller's and may be enormous;
2520        // a saturated `p` fails this test too, which is why `round_up` can
2521        // saturate rather than report.
2522        if p.checked_add(len).map_or(true, |stop| stop > end) {
2523            return None;
2524        }
2525        // Test the whole window at an aligned start, rather than finding a run
2526        // and aligning after the fact: aligning afterwards moves the start
2527        // without moving the end, so it can reject a run that had the room.
2528        match image[p..p + len].iter().position(|&b| b != 0xFF) {
2529            None => return Some(p),
2530            // The byte at `p + k` is live, so no window starting at or before it
2531            // can work; resume at the first aligned offset past it.
2532            Some(k) => p = round_up(p + k + 1, align),
2533        }
2534    }
2535}
2536
2537/// Halfword-aligned masked search. See [`Needle::Masked`].
2538fn find_masked(image: &[u8], pat: &[(u16, u16)], start: usize) -> Option<usize> {
2539    find_masked_in(image, pat, start, image.len())
2540}
2541
2542/// `find_masked`, bounded above. Halfword alignment is measured from the image
2543/// origin: a window starting at an odd offset does not shift what counts as an
2544/// instruction boundary.
2545fn find_masked_in(image: &[u8], pat: &[(u16, u16)], start: usize, end: usize) -> Option<usize> {
2546    // An empty pattern is satisfied by every position; reporting `start` would
2547    // be technically true and useless. See the variant's documentation.
2548    if pat.is_empty() {
2549        return None;
2550    }
2551    // `* 2`, not `checked_mul`: `pat` is a real slice of 4-byte elements, so
2552    // its length is at most `usize::MAX / 4` and the product cannot overflow.
2553    // A `checked_mul` here would add an arm no input can reach.
2554    let need = pat.len() * 2;
2555    let end = end.min(image.len());
2556    let mut p = round_up(start.min(end), 2);
2557    while p.checked_add(need).map_or(false, |stop| stop <= end) {
2558        let hit = pat.iter().enumerate().all(|(i, &(value, mask))| {
2559            let at = p + i * 2;
2560            u16::from_le_bytes([image[at], image[at + 1]]) & mask == value & mask
2561        });
2562        if hit {
2563            return Some(p);
2564        }
2565        p += 2;
2566    }
2567    None
2568}
2569
2570/// Which free run to choose when more than one will do. See
2571/// [`find_free_space_in`].
2572#[derive(Debug, Clone, Copy, PartialEq, Eq)]
2573#[non_exhaustive]
2574pub enum Fit {
2575    /// The lowest usable offset in the image, and what [`find_free_space`]
2576    /// does.
2577    ///
2578    /// "Lowest" means lowest *address*, not first encountered: the order the
2579    /// regions are passed in does not change the answer.
2580    First,
2581    /// The usable offset inside the longest free run. Prefer this when placing
2582    /// several stubs: first-fit takes the first hole big enough and leaves the
2583    /// large one fragmented, whereas this keeps the big hole for the things
2584    /// that need it.
2585    ///
2586    /// Ties are broken on the lowest address, so this too is independent of
2587    /// the order the regions are passed in.
2588    Largest,
2589}
2590
2591/// Free space, restricted to regions the caller says are writable.
2592///
2593/// [`find_free_space`] scans the whole image, which assumes every erased byte
2594/// is fair game. In a real firmware image it is not: a region may be covered
2595/// by an integrity check, reserved by the vendor, or outside the erase block
2596/// the caller intends to rewrite. Only the caller knows which, and there is no
2597/// safe way to express it from outside — **slicing the image and searching
2598/// that is wrong**, because slicing at an unaligned offset moves the alignment
2599/// origin, so a result that looks 4-aligned within the slice is not 4-aligned
2600/// within the image. That is the same failure the `align` parameter exists to
2601/// prevent, reintroduced one layer up.
2602///
2603/// `within` is in *image* coordinates, and each range is **half-open**:
2604/// `0x90000..0xb0000` includes `0x90000` and excludes `0xb0000`, as every
2605/// `Range` in Rust does. `a..=b` is deliberately not accepted, so porting from
2606/// an inclusive convention is a compile error rather than an off-by-one.
2607///
2608/// Ranges are clipped to the image, need not be disjoint, and **may be given
2609/// in any order without changing the answer** — both [`Fit`] policies resolve
2610/// to an address, not to whichever region was looked at first. Two callers
2611/// with the same intent get the same offset, which anyone producing
2612/// byte-reproducible images depends on. An empty slice finds nothing.
2613///
2614/// A free run that extends past a region's end is **clipped** to the region,
2615/// not rejected: the offset returned is always one where `len` bytes fit
2616/// entirely inside a region you named. If you need the stronger rule — refuse
2617/// a run that straddles a boundary at all, because your erase granularity is
2618/// coarser than your regions — use [`FreeSpace`] with [`Straddle::Reject`].
2619///
2620/// # Panics
2621///
2622/// Panics if `align` is 0, as [`find_free_space`] does.
2623///
2624/// ```
2625/// use thumb_asm::{find_free_space_in, Fit};
2626///
2627/// //          0..4 live        4..12 free       12..16 live    16..32 free
2628/// let mut image = vec![0x00; 4];
2629/// image.extend(std::iter::repeat(0xFF).take(8));
2630/// image.extend(std::iter::repeat(0x00).take(4));
2631/// image.extend(std::iter::repeat(0xFF).take(16));
2632///
2633/// // First fit takes the 8-byte hole; largest fit keeps to the 16-byte one.
2634/// assert_eq!(find_free_space_in(&image, 4, 4, &[0..image.len()], Fit::First), Some(4));
2635/// assert_eq!(find_free_space_in(&image, 4, 4, &[0..image.len()], Fit::Largest), Some(16));
2636///
2637/// // Restricted to the first region, the big hole is not a candidate at all.
2638/// assert_eq!(find_free_space_in(&image, 4, 4, &[0..12], Fit::Largest), Some(4));
2639/// ```
2640pub fn find_free_space_in(
2641    image: &[u8],
2642    len: usize,
2643    align: usize,
2644    within: &[core::ops::Range<usize>],
2645    fit: Fit,
2646) -> Option<usize> {
2647    assert!(align != 0, "alignment must be at least 1 byte");
2648    // `best` is compared, never short-circuited, so the result is a function
2649    // of the regions rather than of the order they arrived in. Returning early
2650    // on the first hit — which this did until 0.11.1 — makes `Fit::First`
2651    // report whichever region was listed first, so the same two regions in the
2652    // other order produce a different address and a byte-reproducible build
2653    // stops being reproducible with nothing to show for it.
2654    let mut best: Option<(usize, usize)> = None; // (usable bytes, offset)
2655    for region in within {
2656        let lo = region.start.min(image.len());
2657        let hi = region.end.min(image.len());
2658        let mut p = lo;
2659        while p < hi {
2660            // Skip live bytes, then measure the free run that follows.
2661            if image[p] != 0xFF {
2662                p += 1;
2663                continue;
2664            }
2665            let run_start = p;
2666            while p < hi && image[p] == 0xFF {
2667                p += 1;
2668            }
2669            // Alignment is applied inside the run, not to the run's start, so
2670            // a run whose start is unaligned still counts the bytes it can
2671            // actually offer.
2672            let at = round_up(run_start, align);
2673            if at.checked_add(len).map_or(false, |end| end <= p) {
2674                let usable = p - at;
2675                let better = match (fit, best) {
2676                    (_, None) => true,
2677                    // Lowest address wins outright.
2678                    (Fit::First, Some((_, b_at))) => at < b_at,
2679                    // Largest run wins; equal runs fall back to the lowest
2680                    // address so the answer is still total rather than
2681                    // dependent on which was seen first.
2682                    (Fit::Largest, Some((b_len, b_at))) => {
2683                        usable > b_len || (usable == b_len && at < b_at)
2684                    }
2685                };
2686                if better {
2687                    best = Some((usable, at));
2688                }
2689            }
2690        }
2691    }
2692    best.map(|(_, at)| at)
2693}
2694
2695/// What to do with a free run that crosses out of the regions it was found in.
2696///
2697/// The two are different safety decisions, not two spellings of one, so this
2698/// is explicit rather than defaulted in a way that suits one caller.
2699///
2700/// # Which regions
2701///
2702/// **The ones you passed, and nothing else.** This is worth stating outright
2703/// because the wording below invites the other reading:
2704/// [`Reject`](Straddle::Reject)'s rationale mentions erase granularity, which
2705/// sounds as though the crate consults an erase-block map. It does not, and
2706/// cannot — it is handed a `&[u8]` with no device geometry, no flash
2707/// controller, and no idea what a page is on your part.
2708///
2709/// So a "region" is whatever *you* meant it to be: an integrity-covered span,
2710/// a CMAC-protected table, an erase block, a linker-script section. The two
2711/// variants differ only in whether a run may be offered when it extends past
2712/// one of them.
2713///
2714/// Erase granularity is a reason you might *choose* `Reject`, not something
2715/// this crate detects. If a page on your part is coarser than the regions you
2716/// are passing, that is a fact about the part which has to be reflected in the
2717/// regions themselves; nothing here can discover it.
2718///
2719/// Every "region" in this crate works this way — [`find_free_space_in`],
2720/// [`FreeSpace`], and [`detour_in`](crate::detour::detour_in) all take the
2721/// caller's declaration and never infer one.
2722#[derive(Debug, Clone, Copy, PartialEq, Eq)]
2723#[non_exhaustive]
2724pub enum Straddle {
2725    /// Truncate the run to the region. The offset handed back always has its
2726    /// `len` bytes inside a region you named, so the *placement* is safe even
2727    /// though the erased run it came from was not entirely covered.
2728    Clip,
2729    /// Do not offer a run that extends past the region at all.
2730    ///
2731    /// Use this when writing near a boundary is unsafe even if the bytes
2732    /// written are inside it — most often because erase granularity is coarser
2733    /// than the regions, so programming a page that straddles the boundary
2734    /// disturbs bytes outside it. Clipping cannot protect against that,
2735    /// because the hazard is the write, not the placement.
2736    Reject,
2737}
2738
2739/// An allocator over the erased space in an image.
2740///
2741/// [`find_free_space_in`] answers "where could this go?" once. Placing several
2742/// stubs needs a different question — "where does the *next* one go?" — and
2743/// repeating the search does not answer it: nothing has been written yet, so
2744/// every call returns the same offset. Writing each stub before searching for
2745/// the next works, but only by accident of the bytes changing, and it forces
2746/// the whole layout to be interleaved with the writing.
2747///
2748/// This tracks what it has handed out, so allocations pack contiguously and
2749/// none is ever returned twice:
2750///
2751/// ```
2752/// use thumb_asm::{FreeSpace, Straddle};
2753///
2754/// let mut image = vec![0u8; 16];
2755/// image.extend(std::iter::repeat(0xFF).take(64));   // free: 16..80
2756///
2757/// let mut space = FreeSpace::new(&image, &[0..image.len()], 4, Straddle::Clip);
2758/// assert_eq!(space.alloc(12), Some(16));
2759/// assert_eq!(space.alloc(8),  Some(28));   // packed, nothing written yet
2760/// assert_eq!(space.alloc(4),  Some(36));
2761/// ```
2762///
2763/// Regions are half-open, may be given in any order and may overlap: they are
2764/// normalised to a sorted, merged set first, so the sequence of offsets is a
2765/// function of the region *set* and not of the order they were listed in.
2766/// Anyone producing byte-reproducible images depends on that.
2767#[derive(Debug, Clone)]
2768pub struct FreeSpace<'a> {
2769    image: &'a [u8],
2770    /// Usable runs, ascending and disjoint.
2771    runs: Vec<core::ops::Range<usize>>,
2772    align: usize,
2773    /// Index into `runs` of the run being handed out of.
2774    at: usize,
2775    /// Next unallocated offset within `runs[at]`.
2776    cursor: usize,
2777}
2778
2779impl<'a> FreeSpace<'a> {
2780    /// Collect the erased runs inside `within` that may be allocated from.
2781    ///
2782    /// # Panics
2783    ///
2784    /// Panics if `align` is 0, as [`find_free_space`] does.
2785    pub fn new(
2786        image: &'a [u8],
2787        within: &[core::ops::Range<usize>],
2788        align: usize,
2789        straddle: Straddle,
2790    ) -> Self {
2791        assert!(align != 0, "alignment must be at least 1 byte");
2792
2793        // Normalise the regions first — sorted, clipped, and merged where they
2794        // touch — so everything below is a function of the set rather than of
2795        // the argument order.
2796        let mut regions: Vec<core::ops::Range<usize>> = within
2797            .iter()
2798            .map(|r| r.start.min(image.len())..r.end.min(image.len()))
2799            .filter(|r| r.start < r.end)
2800            .collect();
2801        regions.sort_by_key(|r| r.start);
2802        let mut merged: Vec<core::ops::Range<usize>> = Vec::with_capacity(regions.len());
2803        for r in regions {
2804            match merged.last_mut() {
2805                Some(last) if r.start <= last.end => last.end = last.end.max(r.end),
2806                _ => merged.push(r),
2807            }
2808        }
2809
2810        let mut runs = Vec::new();
2811        for region in &merged {
2812            let mut p = region.start;
2813            while p < region.end {
2814                if image[p] != 0xFF {
2815                    p += 1;
2816                    continue;
2817                }
2818                let start = p;
2819                while p < region.end && image[p] == 0xFF {
2820                    p += 1;
2821                }
2822                // Does the erased run continue outside the region? Looking at
2823                // the image rather than the region is the whole point: the run
2824                // was clipped by the loop bound above, so its extent here says
2825                // nothing about how far the erased bytes actually go.
2826                let runs_off_the_front =
2827                    start > 0 && start == region.start && image[start - 1] == 0xFF;
2828                let runs_off_the_back = p < image.len() && p == region.end && image[p] == 0xFF;
2829                if straddle == Straddle::Reject && (runs_off_the_front || runs_off_the_back) {
2830                    continue;
2831                }
2832                runs.push(start..p);
2833            }
2834        }
2835        let cursor = runs.first().map_or(0, |r| r.start);
2836        FreeSpace {
2837            image,
2838            runs,
2839            align,
2840            at: 0,
2841            cursor,
2842        }
2843    }
2844
2845    /// Hand out `len` bytes, aligned, from the lowest place they still fit.
2846    ///
2847    /// Returns the offset, or `None` when no run has room left. Successive
2848    /// calls never overlap, and never revisit a run once one has been
2849    /// allocated from a later one, so the sequence is monotonically
2850    /// increasing.
2851    ///
2852    /// **A failed allocation changes nothing.** Asking for more than is left
2853    /// returns `None` and leaves the allocator exactly as it was, so a caller
2854    /// can ask for something smaller afterwards and still get it.
2855    pub fn alloc(&mut self, len: usize) -> Option<usize> {
2856        // Committed only on success. Advancing the cursor while searching
2857        // would mean a request too large for what is left consumes every
2858        // remaining run on its way to returning `None` — so one oversized
2859        // allocation would silently destroy the capacity for all the small
2860        // ones after it, and `remaining` would report zero with the bytes
2861        // still there.
2862        let mut at = self.at;
2863        let mut cursor = self.cursor;
2864        while at < self.runs.len() {
2865            let run = &self.runs[at];
2866            let start = round_up(cursor.max(run.start), self.align);
2867            if start.checked_add(len).map_or(false, |end| end <= run.end) {
2868                self.at = at;
2869                self.cursor = start + len;
2870                return Some(start);
2871            }
2872            at += 1;
2873            cursor = self.runs.get(at).map_or(0, |r| r.start);
2874        }
2875        None
2876    }
2877
2878    /// How many bytes remain unallocated, across every run.
2879    ///
2880    /// A budget check, not a promise: alignment and the shape of what is asked
2881    /// for mean a caller cannot necessarily allocate all of it.
2882    pub fn remaining(&self) -> usize {
2883        self.runs
2884            .iter()
2885            .enumerate()
2886            .map(|(i, r)| match i.cmp(&self.at) {
2887                core::cmp::Ordering::Less => 0,
2888                core::cmp::Ordering::Equal => r.end.saturating_sub(self.cursor.max(r.start)),
2889                core::cmp::Ordering::Greater => r.end - r.start,
2890            })
2891            .sum()
2892    }
2893
2894    /// The runs this allocator will draw from, ascending and disjoint.
2895    ///
2896    /// Exposed because the straddle decision is one a caller may want to audit
2897    /// rather than trust: under [`Straddle::Reject`] the runs that were
2898    /// dropped simply are not here.
2899    pub fn runs(&self) -> &[core::ops::Range<usize>] {
2900        &self.runs
2901    }
2902
2903    /// The image this was built over.
2904    pub fn image(&self) -> &'a [u8] {
2905        self.image
2906    }
2907}
2908
2909/// `v` rounded up to the next multiple of `align`, saturating.
2910///
2911/// Saturation rather than an `Option` because the overflow it would report
2912/// cannot happen here and the caller does not need it to: `v` is always bounded
2913/// by the image length, and for `v < align` the result is exactly `align`,
2914/// while `v >= align` would need an `align` near `usize::MAX` *and* an image of
2915/// comparable size. Were it ever to saturate anyway, the `p + len > image.len()`
2916/// test at the only call site rejects the result, so the failure mode is
2917/// "no free space found" rather than a wrong offset.
2918fn round_up(v: usize, align: usize) -> usize {
2919    match v % align {
2920        0 => v,
2921        r => v.saturating_add(align - r),
2922    }
2923}
2924
2925#[cfg(test)]
2926#[path = "thumb_tests.rs"]
2927mod tests;
2928
2929#[cfg(test)]
2930mod unreserved_label_tests {
2931    use super::*;
2932
2933    /// A label id that was never handed out by `label()` is an error, not a
2934    /// panic — on every path that accepts one.
2935    ///
2936    /// `bind` has always validated the id through `get_mut`, and
2937    /// `thumb_tests::binding_a_label_that_was_never_reserved_is_an_error_not_a_panic`
2938    /// pins that. The emitters that record a fixup — `b`, `b_cond`, `adr`,
2939    /// `blob` — did not, and `finish` then indexed `self.labels` raw, so the
2940    /// same bad id aborted the process instead of returning `AsmError`. The
2941    /// existing unbound-label tests all call `label()` first, so they
2942    /// exercised reserved-but-unbound and never never-reserved.
2943    #[test]
2944    fn a_label_never_reserved_is_refused_by_every_path_that_takes_one() {
2945        // A conditional branch to an id nobody reserved.
2946        let mut a = Asm::new();
2947        a.b_cond(Cond::Eq, 7);
2948        let err = a.finish().expect_err("an unreserved label must not panic");
2949        // Bound before asserting: a format argument is only evaluated when
2950        // the assertion fails, so inline it is dead on every passing run.
2951        let msg = err.to_string();
2952        assert!(msg.contains("never reserved"), "{msg}");
2953
2954        // An unconditional branch, which takes a different fixup path.
2955        let mut a = Asm::new();
2956        a.b(9);
2957        let err = a.finish().expect_err("an unreserved label must not panic");
2958        assert!(err.to_string().contains("never reserved"));
2959
2960        // `adr` to a blob label nobody reserved.
2961        let mut a = Asm::new();
2962        a.adr(0, 3);
2963        let err = a
2964            .finish()
2965            .expect_err("an unreserved blob label must not panic");
2966        assert!(err.to_string().contains("never reserved"));
2967
2968        // Note there is deliberately no case here for a *blob* recorded
2969        // against an unreserved label: `data_blob` reserves its own id and is
2970        // the only producer, so that path cannot be reached from the public
2971        // API and guarding it would be an unreachable branch.
2972    }
2973
2974    /// Reserved-but-never-bound stays distinguishable from never-reserved:
2975    /// they are different mistakes and deserve different messages.
2976    #[test]
2977    fn a_reserved_but_unbound_label_reports_separately() {
2978        let mut a = Asm::new();
2979        let l = a.label();
2980        a.b_cond(Cond::Eq, l);
2981        let err = a.finish().expect_err("never bound");
2982        let msg = err.to_string();
2983        assert!(msg.contains("unbound label"), "{msg}");
2984        assert!(!msg.contains("never reserved"));
2985    }
2986}
2987
2988#[cfg(test)]
2989mod command_table_overflow_tests {
2990    use super::*;
2991
2992    /// `find`'s bounds check must not overflow on a caller-supplied `base`
2993    /// and `stride`.
2994    ///
2995    /// Both come from the caller describing a table in their own image, so
2996    /// their sum is not bounded by anything. Computed as `off + stride` this
2997    /// panics in a debug build and, worse, *wraps* in a release build to a
2998    /// small number that passes the `> image.len()` test — after which the
2999    /// indexing below reads from an offset the check was meant to refuse.
3000    /// `walk` has always used `checked_add`; `find` did not.
3001    #[test]
3002    fn a_table_whose_base_plus_stride_overflows_is_refused_not_wrapped() {
3003        let image = vec![0u8; 100];
3004        let table = CommandTable {
3005            base: usize::MAX - 10,
3006            stride: 20,
3007            opcode_off: 0,
3008            flags_off: 1,
3009            handler_off: 4,
3010            term_flag: 0xFF,
3011            max_records: 5,
3012        };
3013        assert_eq!(
3014            table.find(&image, 0x42),
3015            None,
3016            "an overflowing base+stride must be refused, not wrapped into range"
3017        );
3018        // `walk` is the sibling that already did this correctly; it must
3019        // agree, so the two cannot drift apart again.
3020        assert!(
3021            table.walk(&image, 0x01).is_empty(),
3022            "walk must refuse the same table"
3023        );
3024    }
3025}
3026
3027#[cfg(test)]
3028mod error_reason_tests {
3029    use super::*;
3030
3031    /// Every error type in this crate answers `reason()` with a stable token.
3032    ///
3033    /// These are part of the public contract: consumers log them, branch on
3034    /// them, and put them in their own error messages. Pinning them as string
3035    /// literals here is what makes a rename a failing test rather than a
3036    /// silent break in somebody else's matching.
3037    #[test]
3038    fn every_error_type_reports_a_stable_machine_readable_reason() {
3039        assert_eq!(FindError::NotFound.reason(), "not-found");
3040        assert_eq!(
3041            FindError::Ambiguous {
3042                count: 3,
3043                first: 0x10
3044            }
3045            .reason(),
3046            "ambiguous"
3047        );
3048
3049        assert_eq!(
3050            InstallHazard::OutOfBounds {
3051                site: 0,
3052                image_len: 2
3053            }
3054            .reason(),
3055            "out-of-bounds"
3056        );
3057        assert_eq!(
3058            InstallHazard::NotAnInstruction { site: 0 }.reason(),
3059            "not-an-instruction"
3060        );
3061
3062        // `found: None` and `found: Some` are genuinely different outcomes —
3063        // nothing was written, versus something was written and landed wrong.
3064        let nothing = InstallMismatch {
3065            site: 0,
3066            kind: BranchKind::Bl,
3067            expected: 0x1000,
3068            found: None,
3069        };
3070        assert_eq!(nothing.reason(), "not-a-branch");
3071        let wrong = InstallMismatch {
3072            found: Some(0x2000),
3073            ..nothing
3074        };
3075        assert_eq!(wrong.reason(), "wrong-target");
3076    }
3077
3078    /// `SplitsInstruction` is reachable only through `can_install`, so it is
3079    /// built the way a caller would meet it rather than by hand.
3080    #[test]
3081    fn the_split_instruction_hazard_reports_its_reason() {
3082        // A two-byte `nop` followed by a four-byte `bl`: the four bytes a
3083        // branch needs at offset 0 cover the `nop` and only the first half of
3084        // the `bl`, which is the hazard — the site itself decodes fine.
3085        let image = [0x00, 0xBF, 0x00, 0xF0, 0x00, 0xF8, 0x00, 0xBF];
3086        let hazard =
3087            can_install(&image, 0, BranchKind::Bl).expect_err("site splits an instruction");
3088        assert_eq!(hazard.reason(), "splits-instruction");
3089    }
3090
3091    /// `AsmError` reports a constant reason and exposes its message.
3092    #[test]
3093    fn an_assembler_error_reports_its_reason_and_message() {
3094        // The immediate is a `u8`, so it cannot overflow by construction —
3095        // the reachable failure is a register outside the low bank, which
3096        // `MOVS` (immediate) T1 encodes in three bits.
3097        let mut asm = Asm::new();
3098        asm.movs_imm(8, 0);
3099        let err = asm.finish().expect_err("a high register must fail");
3100        assert_eq!(err.reason(), "operand");
3101        // Bound before the assert: a format argument is only evaluated when
3102        // the assertion fails, so inline it would never be covered.
3103        let msg = err.to_string();
3104        assert!(
3105            msg.contains("movs"),
3106            "the message should name the instruction, got: {msg}"
3107        );
3108    }
3109}
3110
3111#[cfg(test)]
3112mod asm_reuse_tests {
3113    //! `finish` is `&mut self` (not `self`), so an `Asm` survives it — this
3114    //! module pins the two invariants of the reuse contract: successive
3115    //! `finish()`es on the same builder do not carry state between them, and
3116    //! a label id from a previous buffer used after `finish` decodes as
3117    //! "never reserved" rather than as a silent branch to the previous
3118    //! buffer's byte offset.
3119    use super::*;
3120    use crate::isa::Target;
3121    /// A stub the assembler will accept without any pool or fixups, so the
3122    /// second `finish()` sees an assembler that is genuinely empty and
3123    /// returns exactly zero bytes rather than a residual pool from the first
3124    /// buffer.
3125    #[test]
3126    fn a_second_finish_on_the_same_assembler_produces_the_empty_buffer() {
3127        let mut a = Asm::with_target(Target::Union);
3128        a.push(0x0100); // 2 bytes, no fixups, no pool needed.
3129        let first = a.finish().expect("push assembles");
3130        assert_eq!(
3131            first.len(),
3132            4,
3133            "one halfword padded to the 4-byte pool align"
3134        );
3135        let second = a.finish().expect("a reset assembler still finishes");
3136        assert!(
3137            second.is_empty(),
3138            "a fresh assembler after finish must produce no bytes, got {second:02x?}"
3139        );
3140    }
3141
3142    /// The reuse hazard round 4 of the audit named: a label reserved on the
3143    /// old buffer must not silently bind to any offset in the new one. After
3144    /// `finish`, the labels vector is gone — a stale id is "never reserved",
3145    /// which is what the next `finish` reports.
3146    #[test]
3147    fn a_label_from_a_previous_finish_is_refused_by_the_next_one() {
3148        let mut a = Asm::new();
3149        let stale = a.label();
3150        a.bind(stale);
3151        let _ = a.finish().expect("empty buffer assembles");
3152        // `stale` is a `u16` the caller kept, but the reset assembler has an
3153        // empty labels vector, so referencing it is a use-of-unreserved id.
3154        a.b(stale);
3155        let err = a
3156            .finish()
3157            .expect_err("stale label must not silently branch into the previous buffer");
3158        assert!(
3159            err.to_string().contains("was never reserved"),
3160            "expected an unreserved-label diagnostic, got: {err}"
3161        );
3162    }
3163
3164    /// `finish` also preserves the target across resets. A caller who set up a
3165    /// V8M builder and finishes it does not silently lose the V8M gate on the
3166    /// next round of emits.
3167    #[test]
3168    fn a_reset_assembler_keeps_the_original_target() {
3169        let mut a = Asm::with_target(Target::V8M);
3170        let _ = a.finish().expect("empty buffer");
3171        assert_eq!(
3172            a.target(),
3173            Target::V8M,
3174            "target must survive the reset in finish"
3175        );
3176    }
3177}
3178
3179#[cfg(test)]
3180mod asm_target_gate_tests {
3181    //! End-to-end tests for the [`Asm::with_target`] gate: the `sdiv`/`udiv`
3182    //! demonstration emitters and the `raw16`/`raw32` decode-under-target
3183    //! recovery path. This module covers the observable behaviour a consumer
3184    //! would test; the pin-set / whole-target-variant / EncForm mutation
3185    //! tripwires live in [`crate::isa::legality::tests`].
3186    use super::*;
3187    use crate::isa::Target;
3188
3189    /// `sdiv` under Armv7-A is UNDEFINED (see `Asm::sdiv` docstring). The
3190    /// gate reports it as [`AsmError::Unsupported`] with the exact mnemonic
3191    /// and byte position of the emit.
3192    #[test]
3193    fn sdiv_is_refused_under_v7a() {
3194        let mut a = Asm::with_target(Target::V7A);
3195        a.sdiv(0, 1, 2);
3196        let err = a.finish().expect_err("sdiv is UNDEFINED on Armv7-A");
3197        assert!(matches!(
3198            &err,
3199            AsmError::Unsupported {
3200                mnemonic: "sdiv",
3201                target: Target::V7A,
3202                at: 0
3203            }
3204        ));
3205    }
3206
3207    /// V7R accepts `sdiv` — it is mandatory on Armv7-R. The bytes match the
3208    /// hand-computed encoding from ARM ARM A8.8.165.
3209    #[test]
3210    fn sdiv_is_accepted_under_v7r_and_encodes_correctly() {
3211        let mut a = Asm::with_target(Target::V7R);
3212        a.sdiv(0, 1, 2);
3213        let bytes = a.finish().expect("sdiv is mandatory on Armv7-R");
3214        // hw1 = 0xFB90 | Rn(=1); hw2 = 0xF0F0 | (Rd=0 << 8) | Rm(=2).
3215        assert_eq!(
3216            &bytes[..4],
3217            &[0x91, 0xFB, 0xF2, 0xF0],
3218            "sdiv r0, r1, r2 encoding"
3219        );
3220    }
3221
3222    /// V7AR is the strict intersection of V7A and V7R — `sdiv` is refused
3223    /// because V7A refuses it. The point Fable's round-4 audit named:
3224    /// V7AR is strictly stricter than V7R.
3225    #[test]
3226    fn v7ar_is_strictly_stricter_than_v7r() {
3227        let mut a = Asm::with_target(Target::V7AR);
3228        a.sdiv(0, 1, 2);
3229        let err = a
3230            .finish()
3231            .expect_err("V7AR must refuse anything V7A refuses");
3232        assert!(matches!(
3233            err,
3234            AsmError::Unsupported {
3235                mnemonic: "sdiv",
3236                target: Target::V7AR,
3237                ..
3238            }
3239        ));
3240    }
3241
3242    /// `raw16` under a non-Union target with a wide-instruction prefix
3243    /// halfword (e.g. `0xF400`) is refused distinctly, pointing at
3244    /// `raw32`/`raw16_unchecked`. Under Union the same call is accepted —
3245    /// the pre-0.14 byte-for-byte contract.
3246    #[test]
3247    fn raw16_refuses_a_wide_prefix_under_non_union() {
3248        let mut a = Asm::with_target(Target::V7A);
3249        a.raw16(0xF400);
3250        let err = a
3251            .finish()
3252            .expect_err("wide prefix via raw16 has no second halfword to decode");
3253        assert!(matches!(
3254            err,
3255            AsmError::Unsupported {
3256                mnemonic: "raw16",
3257                target: Target::V7A,
3258                ..
3259            }
3260        ));
3261
3262        // Same call under Union: accepted, byte-for-byte.
3263        let mut u = Asm::with_target(Target::Union);
3264        u.raw16(0xF400);
3265        let bytes = u.finish().expect("Union is permissive");
3266        assert_eq!(
3267            &bytes[..2],
3268            &[0x00, 0xF4],
3269            "Union writes 0xF400 little-endian"
3270        );
3271    }
3272
3273    /// A Thumb-1 (ARMv4T/ARMv5TE) target has no 32-bit Thumb-2 instructions, so
3274    /// any wide encoding reaching `raw32` is refused — here `ldr.w pc,[pc,#0]`
3275    /// (`0xF8DF 0xF000`), the exact pattern that faulted a Thumb-1 core as a
3276    /// breadcrumb return trampoline. Plain Thumb-1 16-bit ops still assemble.
3277    #[test]
3278    fn thumb1_refuses_wide_thumb2_but_accepts_thumb1() {
3279        let mut a = Asm::with_target(Target::Thumb1);
3280        a.raw32(0xF8DF, 0xF000); // ldr.w pc,[pc,#0] — Thumb-2, undefined on Thumb-1
3281        assert!(
3282            a.finish().is_err(),
3283            "Thumb1 must refuse a wide Thumb-2 encoding"
3284        );
3285
3286        let mut b = Asm::with_target(Target::Thumb1);
3287        b.push(0b1); // push {r0}
3288        b.pop(0b1); // pop  {r0}
3289        assert!(
3290            b.finish().is_ok(),
3291            "Thumb1 must accept Thumb-1 base 16-bit ops"
3292        );
3293    }
3294
3295    /// A ThumbEE-only halfword outside the legal `0xC000..=0xCFFF` reassignment
3296    /// slice — `0xC100` decodes as UNDEFINED in the ThumbEE table. `raw16`
3297    /// under `Target::ThumbEE` therefore refuses.
3298    #[test]
3299    fn raw16_refuses_thumbee_undefined_pattern() {
3300        let mut a = Asm::with_target(Target::ThumbEE);
3301        a.raw16(0xC100);
3302        let err = a
3303            .finish()
3304            .expect_err("0xC1xx is UNDEFINED in ThumbEE (Table A9-2)");
3305        assert_eq!(err.reason(), "unsupported");
3306    }
3307
3308    /// The Security Gateway pattern is `0xE97F 0xE97F`. On `V8M` the decoder
3309    /// recovers `sg` (accepted), on `V7A` it recovers `ldrd` (also accepted
3310    /// there — the "bytes as this chip reads them" contract), so both
3311    /// targets emit. Only the pattern-does-not-decode-on-target case
3312    /// refuses.
3313    #[test]
3314    fn raw32_accepts_the_v8m_sg_pattern() {
3315        let mut a = Asm::with_target(Target::V8M);
3316        a.raw32(0xE97F, 0xE97F);
3317        let bytes = a.finish().expect("V8M decoder recovers this as sg");
3318        assert_eq!(
3319            &bytes[..4],
3320            &[0x7F, 0xE9, 0x7F, 0xE9],
3321            "SG bytes emitted in little-endian order"
3322        );
3323    }
3324
3325    /// `raw32` with an `sdiv` pattern under `V7A` refuses — the V7A decoder
3326    /// recovers `sdiv` and the legality table rejects it there.
3327    #[test]
3328    fn raw32_refuses_sdiv_pattern_under_v7a() {
3329        // sdiv r2, r1, r3: hw1 = 0xFB91, hw2 = 0xF2F3.
3330        let mut a = Asm::with_target(Target::V7A);
3331        a.raw32(0xFB91, 0xF2F3);
3332        let err = a.finish().expect_err("sdiv via raw32 is UNDEFINED on V7A");
3333        assert!(matches!(
3334            err,
3335            AsmError::Unsupported {
3336                mnemonic: "sdiv",
3337                target: Target::V7A,
3338                ..
3339            }
3340        ));
3341    }
3342
3343    /// `raw16_unchecked` is the escape hatch: nothing gated, ever. The
3344    /// caller has taken responsibility for the bytes.
3345    #[test]
3346    fn raw16_unchecked_bypasses_the_gate() {
3347        let mut a = Asm::with_target(Target::V7A);
3348        a.raw16_unchecked(0xF400); // wide prefix, gated on raw16.
3349        let bytes = a
3350            .finish()
3351            .expect("raw16_unchecked bypasses every legality check");
3352        assert_eq!(&bytes[..2], &[0x00, 0xF4]);
3353    }
3354
3355    /// The install-side `_with` overload accepts the same bytes as
3356    /// `can_install` for baseline patterns — the target axis is here for
3357    /// V8M/ThumbEE cases, not to change the answer for shared encodings.
3358    #[test]
3359    fn can_install_with_agrees_with_can_install_on_baseline_bytes() {
3360        // `nop; nop`: two 2-byte instructions, no split, accepted under any
3361        // target because `nop` is baseline everywhere.
3362        let image = [0x00, 0xBF, 0x00, 0xBF];
3363        for t in [
3364            Target::Union,
3365            Target::V7M,
3366            Target::V7A,
3367            Target::V7R,
3368            Target::V7AR,
3369            Target::V7EM,
3370            Target::V8M,
3371        ] {
3372            assert!(
3373                can_install_with(t, &image, 0, BranchKind::Bl).is_ok(),
3374                "can_install_with({t:?}) must accept a baseline site"
3375            );
3376        }
3377    }
3378
3379    /// `udiv` bytes must match ARM ARM A8.8.267 exactly, and the encoding must
3380    /// use a non-zero `Rd` so the `Rd << 8` mutant (a survivor in the 0.14.0
3381    /// baseline sweep) cannot masquerade as identity.
3382    ///
3383    /// `udiv r3, r4, r5`: hw1 = 0xFBB0 | Rn(=4) = 0xFBB4; hw2 = 0xF0F0 |
3384    /// (Rd=3 << 8) | Rm(=5) = 0xF3F5. Bytes: `[0xB4, 0xFB, 0xF5, 0xF3]`.
3385    #[test]
3386    fn udiv_encodes_exactly_with_nonzero_rd() {
3387        let mut a = Asm::new();
3388        a.udiv(3, 4, 5);
3389        let bytes = a.finish().expect("udiv is legal under Union");
3390        assert_eq!(&bytes[..4], &[0xB4, 0xFB, 0xF5, 0xF3], "udiv r3, r4, r5");
3391    }
3392
3393    /// `udiv` under `Target::V7R` — the acceptance path proves the target
3394    /// gate does not accidentally reject udiv on a profile where it is
3395    /// mandatory.
3396    #[test]
3397    fn udiv_is_accepted_under_v7r() {
3398        let mut a = Asm::with_target(Target::V7R);
3399        a.udiv(0, 1, 2);
3400        let bytes = a.finish().expect("udiv is mandatory on Armv7-R (spec:874)");
3401        assert_eq!(&bytes[..4], &[0xB1, 0xFB, 0xF2, 0xF0]);
3402    }
3403
3404    /// `udiv` and `sdiv` share `divmod_wide`; the SP/PC operand check is
3405    /// `r == 13 || r == 15`. The `||` → `&&` mutant would neuter the check
3406    /// (no register is BOTH 13 AND 15), so a test using only r=13 kills it.
3407    #[test]
3408    fn divmod_wide_refuses_rn_equal_sp() {
3409        let mut a = Asm::new();
3410        a.sdiv(0, 13, 2);
3411        let err = a.finish().expect_err("Rn=SP is UNPREDICTABLE for sdiv");
3412        assert_eq!(err.reason(), "operand");
3413    }
3414
3415    /// The other half of the SP/PC check — r=15 (PC) is separately refused.
3416    /// Testing both endpoints (13 and 15) rules out any partial `||`/`&&`
3417    /// mutation.
3418    #[test]
3419    fn divmod_wide_refuses_rm_equal_pc() {
3420        let mut a = Asm::new();
3421        a.udiv(0, 1, 15);
3422        let err = a.finish().expect_err("Rm=PC is UNPREDICTABLE for udiv");
3423        assert_eq!(err.reason(), "operand");
3424    }
3425
3426    /// Every variant of `AsmError` reports the reason string the accessor
3427    /// documents. Killers for both `at() -> 0/1` body-replace mutants live
3428    /// alongside; the Layout variant is exercised by an out-of-range
3429    /// `ldr_lit`.
3430    #[test]
3431    fn asm_error_reason_and_at_cover_every_variant() {
3432        // Operand: any bad register field.
3433        let mut a = Asm::new();
3434        a.push(0); // empty reglist -> Operand.
3435        let err = a.finish().expect_err("empty reglist is refused");
3436        assert_eq!(err.reason(), "operand");
3437        // Also exercise `.at()` on the Operand variant so every arm of
3438        // the at() match is covered.
3439        assert_eq!(err.at(), 0);
3440
3441        // Unsupported: sdiv under V7A.
3442        let mut a = Asm::with_target(Target::V7A);
3443        a.sdiv(0, 1, 2);
3444        let err = a.finish().expect_err("sdiv on V7A is refused");
3445        assert_eq!(err.reason(), "unsupported");
3446        // Display: names the mnemonic and target explicitly.
3447        let text = format!("{err}");
3448        assert!(text.contains("sdiv"), "Display must name the mnemonic");
3449        assert!(text.contains("V7A"), "Display must name the target");
3450
3451        // Layout: an ldr_lit whose pool word cannot be reached. Padding
3452        // must push the pool past 1020 bytes from the ldr (imm8 > 0xFF).
3453        let mut a = Asm::new();
3454        a.ldr_lit(0, 0xDEAD_BEEF);
3455        for _ in 0..600 {
3456            a.raw16_unchecked(0xBF00);
3457        }
3458        let err = a.finish().expect_err("literal is out of range");
3459        assert_eq!(err.reason(), "layout");
3460        // .at() for Layout returns the emit position, not zero.
3461        assert_eq!(err.at(), 0, "the failed ldr_lit sits at offset 0");
3462    }
3463
3464    /// `raw32` under `Target::Union` is byte-for-byte, no decode path taken.
3465    /// This is the pre-0.14 escape hatch.
3466    #[test]
3467    fn raw32_under_union_is_byte_for_byte() {
3468        let mut a = Asm::with_target(Target::Union);
3469        a.raw32(0xE97F, 0xE97F);
3470        let bytes = a.finish().expect("Union permits any halfword pair");
3471        assert_eq!(&bytes[..4], &[0x7F, 0xE9, 0x7F, 0xE9]);
3472    }
3473
3474    /// `raw32` where the target decoder returns `None` — the halfword
3475    /// pair is UNDEFINED on this profile — reports `Unsupported` with
3476    /// `mnemonic: "raw32"`. Verified via `isa::decode_at_with` locally
3477    /// against several candidates; `hw1 = 0xF7F0`, `hw2 = 0x0000` is a
3478    /// stable choice: it hits the `t32_branch_misc` group's "UNDEFINED"
3479    /// row under every target.
3480    #[test]
3481    fn raw32_reports_raw32_when_the_pair_is_undecodable() {
3482        let mut a = Asm::with_target(Target::V7A);
3483        a.raw32(0xF7F0, 0x0000);
3484        let err = a.finish().expect_err("this pair is UNDEFINED");
3485        assert!(matches!(
3486            &err,
3487            AsmError::Unsupported {
3488                mnemonic: "raw32",
3489                ..
3490            }
3491        ));
3492    }
3493
3494    /// `DetourOptions::with_target` records the target on the builder — the
3495    /// consumer-facing knob that Fable's audit named as the load-bearing
3496    /// detour fix.
3497    #[test]
3498    fn detour_options_with_target_records_the_target() {
3499        let opts = crate::detour::DetourOptions::default().with_target(Target::V8M);
3500        assert_eq!(opts.target, Target::V8M);
3501    }
3502
3503    /// `raw16` under a non-Union target discriminates on `insn_len(insn) == 4`:
3504    /// wide-prefix halfwords are refused with `mnemonic: "raw16"`, narrow
3505    /// halfwords go through the decode-under-target legality path. The `==`
3506    /// → `!=` mutant swaps the two paths, so a narrow accept (this test)
3507    /// under a non-Union target is what distinguishes them: correct code
3508    /// emits bytes, mutant code refuses.
3509    #[test]
3510    fn raw16_accepts_a_narrow_defined_pattern_under_non_union() {
3511        // 0xBF00 is `nop` T1 — narrow (`insn_len == 2`), defined on every
3512        // target the crate knows.
3513        let mut a = Asm::with_target(Target::V7A);
3514        a.raw16(0xBF00);
3515        let bytes = a.finish().expect("nop is baseline everywhere");
3516        assert_eq!(&bytes[..2], &[0x00, 0xBF]);
3517    }
3518
3519    /// `AsmError::at()` must return the actual byte position, not a constant.
3520    /// The mutants that replace the body with `0` or `1` are killed by a
3521    /// scenario where `at` is neither: emit a couple of instructions first,
3522    /// then fail. Uses `sdiv` under V7A (guaranteed Unsupported at pos > 0).
3523    #[test]
3524    fn asm_error_at_returns_the_actual_byte_position() {
3525        let mut a = Asm::with_target(Target::V7A);
3526        a.raw16_unchecked(0xBF00); // 2 bytes: NOP.
3527        a.raw16_unchecked(0xBF00); // 2 more: cursor at 4.
3528        a.sdiv(0, 1, 2); // refused here at position 4.
3529        let err = a.finish().expect_err("sdiv is UNDEFINED on V7A");
3530        assert_eq!(
3531            err.at(),
3532            4,
3533            "at() must return the actual position (4), not 0 or 1"
3534        );
3535    }
3536}