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}