#![forbid(unsafe_code)]
#![deny(missing_docs)]
pub mod analysis;
mod cond;
pub mod detour;
pub mod flags;
pub mod isa;
pub mod relocate;
pub use cond::Cond;
pub use isa::{Insn, Operand, Reg, Width};
pub type Result<T, E = AsmError> = core::result::Result<T, E>;
#[derive(Debug, Clone, Copy)]
#[non_exhaustive]
pub enum Needle<'a> {
Bytes(&'a [u8]),
Word(u32),
FreeRun {
len: usize,
align: usize,
},
Masked(&'a [(u16, u16)]),
}
pub fn find(image: &[u8], needle: Needle, start: usize) -> Option<usize> {
match needle {
Needle::Bytes(pat) => find_bytes(image, pat, start),
Needle::Word(w) => find_bytes(image, &w.to_le_bytes(), start),
Needle::FreeRun { len, align } => find_free_run(image, len, align, start),
Needle::Masked(pat) => find_masked(image, pat, start),
}
}
pub fn find_in(image: &[u8], needle: Needle, range: core::ops::Range<usize>) -> Option<usize> {
let (lo, hi) = (range.start, range.end.min(image.len()));
if lo >= hi {
return None;
}
match needle {
Needle::Bytes(pat) => find_bytes_in(image, pat, lo, hi),
Needle::Word(w) => find_bytes_in(image, &w.to_le_bytes(), lo, hi),
Needle::FreeRun { len, align } => find_free_run_in(image, len, align, lo, hi),
Needle::Masked(pat) => find_masked_in(image, pat, lo, hi),
}
}
fn needle_len(needle: Needle) -> usize {
match needle {
Needle::Bytes(pat) => pat.len(),
Needle::Word(_) => 4,
Needle::FreeRun { len, .. } => len,
Needle::Masked(pat) => pat.len() * 2,
}
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[non_exhaustive]
pub enum FindError {
NotFound,
Ambiguous {
count: usize,
first: usize,
},
}
impl FindError {
pub fn reason(&self) -> &'static str {
match self {
FindError::NotFound => "not-found",
FindError::Ambiguous { .. } => "ambiguous",
}
}
}
impl core::fmt::Display for FindError {
fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
match self {
FindError::NotFound => f.write_str("no match"),
FindError::Ambiguous { count, first } => {
write!(f, "{count} matches, first at {first:#x}")
}
}
}
}
impl std::error::Error for FindError {}
pub fn find_one(image: &[u8], needle: Needle) -> Result<usize, FindError> {
find_one_in(image, needle, 0..image.len())
}
pub fn find_one_in(
image: &[u8],
needle: Needle,
range: core::ops::Range<usize>,
) -> Result<usize, FindError> {
let step = needle_len(needle).max(1);
let hi = range.end.min(image.len());
let first = match find_in(image, needle, range.start..hi) {
Some(p) => p,
None => return Err(FindError::NotFound),
};
let mut count = 1;
let mut at = first;
while let Some(next) = at
.checked_add(step)
.and_then(|from| find_in(image, needle, from..hi))
{
count += 1;
at = next;
}
if count == 1 {
Ok(first)
} else {
Err(FindError::Ambiguous { count, first })
}
}
pub fn find_free_space(image: &[u8], len: usize, align: usize, start: usize) -> Option<usize> {
find(image, Needle::FreeRun { len, align }, start)
}
pub fn read_u32(image: &[u8], at: usize) -> u32 {
u32::from_le_bytes([image[at], image[at + 1], image[at + 2], image[at + 3]])
}
pub fn read_u8(image: &[u8], at: usize) -> u8 {
image[at]
}
pub fn read_u16(image: &[u8], at: usize) -> u16 {
u16::from_le_bytes([image[at], image[at + 1]])
}
pub fn try_read_u8(image: &[u8], at: usize) -> Option<u8> {
image.get(at).copied()
}
pub fn try_read_u16(image: &[u8], at: usize) -> Option<u16> {
let b = image.get(at..at.checked_add(2)?)?;
Some(u16::from_le_bytes([b[0], b[1]]))
}
pub fn try_read_u32(image: &[u8], at: usize) -> Option<u32> {
let b = image.get(at..at.checked_add(4)?)?;
Some(u32::from_le_bytes([b[0], b[1], b[2], b[3]]))
}
pub fn write(image: &mut [u8], at: usize, bytes: &[u8]) {
image[at..at + bytes.len()].copy_from_slice(bytes);
}
pub fn insert(image: &mut [u8], free_off: usize, code: &[u8]) -> u32 {
write(image, free_off, code);
free_off as u32
}
#[derive(Debug, Clone, Copy)]
pub struct CommandTable {
pub base: usize,
pub stride: usize,
pub opcode_off: usize,
pub flags_off: usize,
pub handler_off: usize,
pub term_flag: u8,
pub max_records: usize,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct CommandRecord {
pub off: usize,
pub opcode: u8,
pub flags: u8,
pub handler: u32,
}
impl CommandTable {
pub fn find(&self, image: &[u8], opcode: u8) -> Option<CommandRecord> {
let mut off = self.base;
for _ in 0..self.max_records {
let end = off.checked_add(self.stride)?;
if end > image.len() {
return None;
}
let flags = image[off + self.flags_off];
if flags == self.term_flag {
return None; }
if image[off + self.opcode_off] == opcode {
return Some(CommandRecord {
off,
opcode,
flags,
handler: read_u32(image, off + self.handler_off),
});
}
off += self.stride;
}
None
}
pub fn replace(&self, image: &mut [u8], rec: &CommandRecord, handler: u32, flags: Option<u8>) {
let flags_at = flags.map(|_| {
rec.off
.checked_add(self.flags_off)
.expect("flags offset overflows")
});
let handler_at = rec
.off
.checked_add(self.handler_off)
.expect("handler offset overflows");
let handler_end = handler_at.checked_add(4).expect("handler field overflows");
let len = image.len();
assert!(
handler_end <= len && flags_at.map_or(true, |a| a < len),
"CommandTable::replace: record at {:#x} does not fit in a {len}-byte image",
rec.off
);
if let (Some(f), Some(at)) = (flags, flags_at) {
image[at] = f;
}
write(image, handler_at, &handler.to_le_bytes());
}
}
impl CommandTable {
pub fn walk(&self, image: &[u8], chain_flag: u8) -> Vec<CommandRecord> {
let mut out = Vec::new();
let mut base = self.base;
let mut seen = std::collections::BTreeSet::new();
let mut budget = self.max_records;
for _ in 0..self.max_records {
if !seen.insert(base) {
break; }
let mut off = base;
loop {
if budget == 0 {
return out;
}
budget -= 1;
match off.checked_add(self.stride) {
Some(end) if end <= image.len() => {}
_ => return out,
}
let flags = image[off + self.flags_off];
if flags == self.term_flag {
return out;
}
let handler = read_u32(image, off + self.handler_off);
if flags == chain_flag {
base = handler as usize; break;
}
out.push(CommandRecord {
off,
opcode: image[off + self.opcode_off],
flags,
handler,
});
off += self.stride;
}
}
out
}
}
pub fn prologue_is_push_lr(image: &[u8], off: usize, window: usize) -> bool {
(0..window).any(|k| {
let p = off + k * 2;
p + 2 <= image.len() && (u16::from_le_bytes([image[p], image[p + 1]]) & 0xFF00) == 0xB500
})
}
#[derive(Debug, Clone, PartialEq, Eq)]
#[non_exhaustive]
pub enum AsmError {
Operand {
at: usize,
msg: String,
},
Unsupported {
at: usize,
mnemonic: &'static str,
target: isa::Target,
},
Layout {
at: usize,
msg: String,
},
}
impl AsmError {
pub fn reason(&self) -> &'static str {
match self {
AsmError::Operand { .. } => "operand",
AsmError::Unsupported { .. } => "unsupported",
AsmError::Layout { .. } => "layout",
}
}
pub fn at(&self) -> usize {
match self {
AsmError::Operand { at, .. }
| AsmError::Unsupported { at, .. }
| AsmError::Layout { at, .. } => *at,
}
}
}
impl core::fmt::Display for AsmError {
fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
match self {
AsmError::Operand { msg, .. } => f.write_str(msg),
AsmError::Unsupported {
mnemonic, target, ..
} => write!(
f,
"{mnemonic}: not defined on {target:?} (encoder-side legality \
gate refused it)"
),
AsmError::Layout { msg, .. } => f.write_str(msg),
}
}
}
impl std::error::Error for AsmError {}
#[derive(Default)]
pub struct Asm {
code: Vec<u8>,
ldrs: Vec<(usize, u32, u16)>, fixups: Vec<(usize, u16, bool)>, adrs: Vec<(usize, u16)>, blobs: Vec<(u16, Vec<u8>)>, labels: Vec<Option<usize>>, err: Option<AsmError>, target: isa::Target, }
impl Asm {
pub fn new() -> Self {
Self::default()
}
pub fn with_target(target: isa::Target) -> Self {
Self {
target,
..Self::default()
}
}
pub fn target(&self) -> isa::Target {
self.target
}
pub fn pos(&self) -> usize {
self.code.len()
}
fn fail(&mut self, msg: String) {
if self.err.is_none() {
self.err = Some(AsmError::Operand {
at: self.code.len(),
msg,
});
}
}
fn fail_target(&mut self, mnemonic: &'static str) {
let at = self.code.len();
let target = self.target;
self.err.get_or_insert(AsmError::Unsupported {
at,
mnemonic,
target,
});
}
fn check_target(
&mut self,
mnemonic: &'static str,
form: isa::legality::EncForm,
extra: isa::legality::OpExtra,
) {
if self.target == isa::Target::Union {
return;
}
if !isa::legality::defined_on(mnemonic, form, self.target, extra) {
self.fail_target(mnemonic);
}
}
fn lo(&mut self, what: &str, field: &str, r: u16) {
if r > 7 {
self.fail(format!(
"{what}: {field} must be a low register R0-R7, got r{r}"
));
}
}
fn reg(&mut self, what: &str, field: &str, r: u16) {
if r > 15 {
self.fail(format!("{what}: {field} must be R0-R15, got r{r}"));
}
}
fn imm(&mut self, what: &str, v: u16, max: u16, step: u16) {
if v > max {
self.fail(format!("{what}: immediate {v} exceeds maximum {max}"));
} else if step > 1 && v % step != 0 {
self.fail(format!("{what}: immediate {v} is not a multiple of {step}"));
}
}
fn reglist(&mut self, what: &str, extra: &str, list: u16) {
if list == 0 {
self.fail(format!("{what}: register list is empty"));
} else if list > 0x1FF {
self.fail(format!(
"{what}: register list {list:#06x} has bits outside R0-R7 and {extra} (bit 8)"
));
}
}
pub fn label(&mut self) -> u16 {
self.labels.push(None);
(self.labels.len() - 1) as u16
}
pub fn bind(&mut self, label: u16) -> &mut Self {
match self.labels.get_mut(label as usize) {
Some(slot) => *slot = Some(self.code.len()),
None => self.fail(format!("bind: label {label} was never reserved")),
}
self
}
fn emit16(&mut self, insn: u16) {
self.code.extend_from_slice(&insn.to_le_bytes());
}
fn emit32(&mut self, hw1: u16, hw2: u16) {
self.code.extend_from_slice(&hw1.to_le_bytes());
self.code.extend_from_slice(&hw2.to_le_bytes());
}
pub fn raw16(&mut self, insn: u16) -> &mut Self {
if self.target == isa::Target::Union {
self.emit16(insn);
return self;
}
if isa::insn_len(insn) == 4 {
self.fail_target("raw16");
self.emit16(insn);
return self;
}
let bytes = insn.to_le_bytes();
if isa::decode_at_with(&bytes, 0, 0, self.target).is_none() {
self.fail_target("raw16");
}
self.emit16(insn);
self
}
pub fn raw32(&mut self, hw1: u16, hw2: u16) -> &mut Self {
if self.target == isa::Target::Union {
self.emit32(hw1, hw2);
return self;
}
let hw1_le = hw1.to_le_bytes();
let hw2_le = hw2.to_le_bytes();
let bytes = [hw1_le[0], hw1_le[1], hw2_le[0], hw2_le[1]];
match isa::decode_at_with(&bytes, 0, 0, self.target) {
Some(decoded) => {
let form = isa::legality::EncForm::from(decoded.encoding);
let legal = self.target.supports_thumb2()
&& isa::legality::defined_on(
decoded.mnemonic,
form,
self.target,
isa::legality::OpExtra::Plain,
);
if legal {
self.emit32(hw1, hw2);
} else {
self.fail_target(decoded.mnemonic);
self.emit32(hw1, hw2);
}
}
None => {
self.fail_target("raw32");
self.emit32(hw1, hw2);
}
}
self
}
pub fn raw16_unchecked(&mut self, insn: u16) -> &mut Self {
self.emit16(insn);
self
}
pub fn ldr_lit(&mut self, rt: u16, value: u32) -> &mut Self {
self.lo("ldr_lit", "rt", rt);
let pos = self.code.len();
self.emit16(0x4800 | (rt << 8)); self.ldrs.push((pos, value, rt));
self
}
pub fn str_sp(&mut self, rt: u16, offset: u16) -> &mut Self {
self.lo("str_sp", "rt", rt);
self.imm("str_sp", offset, 1020, 4);
self.emit16(0x9000 | (rt << 8) | (offset >> 2));
self
}
pub fn ldrh_reg(&mut self, rt: u16, rn: u16, rm: u16) -> &mut Self {
self.lo("ldrh_reg", "rt", rt);
self.lo("ldrh_reg", "rn", rn);
self.lo("ldrh_reg", "rm", rm);
self.emit16(0x5a00 | (rm << 6) | (rn << 3) | rt);
self
}
pub fn add_sp(&mut self, offset: u16) -> &mut Self {
self.imm("add_sp", offset, 508, 4);
self.emit16(0xb000 | (offset >> 2));
self
}
pub fn ands(&mut self, rd: u16, rm: u16) -> &mut Self {
self.lo("ands", "rd", rd);
self.lo("ands", "rm", rm);
self.emit16(0x4000 | (rm << 3) | rd);
self
}
pub fn replay(&mut self, bytes: &[u8]) -> &mut Self {
let mut offset = 0;
while offset < bytes.len() {
let ins = match isa::decode_at_with(bytes, offset, offset as u32, self.target) {
Some(ins) => ins,
None => {
self.fail("replay: invalid or incomplete instruction".into());
break;
}
};
let dependent = ins.is_branch()
|| ins.writes_pc()
|| ins.cond.is_some()
|| ins.mnemonic == "it"
|| ins.operands.as_slice().any(|operand| match operand {
isa::Operand::Reg(isa::Reg::PC)
| isa::Operand::RegShifted(isa::Reg::PC, _)
| isa::Operand::Target(_) => true,
isa::Operand::Mem(memory) => {
memory.base == isa::Reg::PC
|| memory.index.map_or(false, |(reg, _)| reg == isa::Reg::PC)
}
_ => false,
});
if dependent {
self.fail(
"replay: instruction depends on its original address or control flow".into(),
);
break;
}
match isa::encode(&ins) {
Some((low, high)) => {
if ins.len() == 2 {
self.raw16(low);
} else {
self.raw32(low, high);
}
}
None => {
self.fail("replay: instruction cannot be re-encoded".into());
break;
}
}
offset += ins.len();
}
self
}
pub fn ldrb_imm(&mut self, rt: u16, rn: u16, imm5: u16) -> &mut Self {
self.lo("ldrb_imm", "rt", rt);
self.lo("ldrb_imm", "rn", rn);
self.imm("ldrb_imm", imm5, 31, 1);
self.emit16(0x7800 | (imm5 << 6) | (rn << 3) | rt);
self
}
pub fn ldr_imm(&mut self, rt: u16, rn: u16, imm: u16) -> &mut Self {
self.lo("ldr_imm", "rt", rt);
self.lo("ldr_imm", "rn", rn);
self.imm("ldr_imm", imm, 124, 4);
self.emit16(0x6800 | ((imm >> 2) << 6) | (rn << 3) | rt);
self
}
pub fn strh_imm(&mut self, rt: u16, rn: u16, imm: u16) -> &mut Self {
self.lo("strh_imm", "rt", rt);
self.lo("strh_imm", "rn", rn);
self.imm("strh_imm", imm, 62, 2);
self.emit16(0x8000 | ((imm >> 1) << 6) | (rn << 3) | rt);
self
}
pub fn str_imm(&mut self, rt: u16, rn: u16, imm: u16) -> &mut Self {
self.lo("str_imm", "rt", rt);
self.lo("str_imm", "rn", rn);
self.imm("str_imm", imm, 124, 4);
self.emit16(0x6000 | ((imm >> 2) << 6) | (rn << 3) | rt);
self
}
pub fn bics(&mut self, rd: u16, rm: u16) -> &mut Self {
self.lo("bics", "rd", rd);
self.lo("bics", "rm", rm);
self.emit16(0x4380 | (rm << 3) | rd);
self
}
pub fn orrs(&mut self, rd: u16, rm: u16) -> &mut Self {
self.lo("orrs", "rd", rd);
self.lo("orrs", "rm", rm);
self.emit16(0x4300 | (rm << 3) | rd);
self
}
pub fn strb_imm(&mut self, rt: u16, rn: u16, imm5: u16) -> &mut Self {
self.lo("strb_imm", "rt", rt);
self.lo("strb_imm", "rn", rn);
self.imm("strb_imm", imm5, 31, 1);
self.emit16(0x7000 | (imm5 << 6) | (rn << 3) | rt);
self
}
pub fn cmp_imm(&mut self, rn: u16, imm8: u8) -> &mut Self {
self.lo("cmp_imm", "rn", rn);
self.emit16(0x2800 | (rn << 8) | imm8 as u16);
self
}
pub fn cmp_reg(&mut self, rn: u16, rm: u16) -> &mut Self {
self.lo("cmp_reg", "rn", rn);
self.lo("cmp_reg", "rm", rm);
self.emit16(0x4280 | (rm << 3) | rn);
self
}
pub fn movs_imm(&mut self, rt: u16, imm8: u8) -> &mut Self {
self.lo("movs_imm", "rt", rt);
self.emit16(0x2000 | (rt << 8) | imm8 as u16);
self
}
pub fn push(&mut self, reglist: u16) -> &mut Self {
self.reglist("push", "lr", reglist);
self.emit16(0xB400 | reglist);
self
}
pub fn pop(&mut self, reglist: u16) -> &mut Self {
self.reglist("pop", "pc", reglist);
self.emit16(0xBC00 | reglist);
self
}
pub fn blx(&mut self, rm: u16) -> &mut Self {
self.reg("blx", "rm", rm);
if rm == 15 {
self.fail("blx: rm must not be pc (UNPREDICTABLE, A7.7.20)".to_string());
}
self.emit16(0x4780 | (rm << 3));
self
}
pub fn bx(&mut self, rm: u16) -> &mut Self {
self.reg("bx", "rm", rm);
self.emit16(0x4700 | (rm << 3));
self
}
pub fn b_cond(&mut self, cond: Cond, label: u16) -> &mut Self {
match cond {
Cond::Al => self.b(label),
c => {
let pos = self.code.len();
self.emit16(0xD000 | ((c.bits() as u16) << 8));
self.fixups.push((pos, label, false));
self
}
}
}
pub fn beq(&mut self, label: u16) -> &mut Self {
self.b_cond(Cond::Eq, label)
}
pub fn bne(&mut self, label: u16) -> &mut Self {
self.b_cond(Cond::Ne, label)
}
pub fn bhs(&mut self, label: u16) -> &mut Self {
self.b_cond(Cond::Hs, label)
}
pub fn blo(&mut self, label: u16) -> &mut Self {
self.b_cond(Cond::Lo, label)
}
pub fn bmi(&mut self, label: u16) -> &mut Self {
self.b_cond(Cond::Mi, label)
}
pub fn bpl(&mut self, label: u16) -> &mut Self {
self.b_cond(Cond::Pl, label)
}
pub fn bvs(&mut self, label: u16) -> &mut Self {
self.b_cond(Cond::Vs, label)
}
pub fn bvc(&mut self, label: u16) -> &mut Self {
self.b_cond(Cond::Vc, label)
}
pub fn bhi(&mut self, label: u16) -> &mut Self {
self.b_cond(Cond::Hi, label)
}
pub fn bls(&mut self, label: u16) -> &mut Self {
self.b_cond(Cond::Ls, label)
}
pub fn bge(&mut self, label: u16) -> &mut Self {
self.b_cond(Cond::Ge, label)
}
pub fn blt(&mut self, label: u16) -> &mut Self {
self.b_cond(Cond::Lt, label)
}
pub fn bgt(&mut self, label: u16) -> &mut Self {
self.b_cond(Cond::Gt, label)
}
pub fn ble(&mut self, label: u16) -> &mut Self {
self.b_cond(Cond::Le, label)
}
pub fn b(&mut self, label: u16) -> &mut Self {
let pos = self.code.len();
self.emit16(0xE000);
self.fixups.push((pos, label, true));
self
}
pub fn ldrb_reg(&mut self, rt: u16, rn: u16, rm: u16) -> &mut Self {
self.lo("ldrb_reg", "rt", rt);
self.lo("ldrb_reg", "rn", rn);
self.lo("ldrb_reg", "rm", rm);
self.emit16(0x5C00 | (rm << 6) | (rn << 3) | rt);
self
}
pub fn adds_imm(&mut self, rt: u16, imm8: u8) -> &mut Self {
self.lo("adds_imm", "rt", rt);
self.emit16(0x3000 | (rt << 8) | imm8 as u16);
self
}
pub fn subs_imm(&mut self, rt: u16, imm8: u8) -> &mut Self {
self.lo("subs_imm", "rt", rt);
self.emit16(0x3800 | (rt << 8) | imm8 as u16);
self
}
pub fn lsls_imm(&mut self, rd: u16, rm: u16, imm5: u16) -> &mut Self {
self.lo("lsls_imm", "rd", rd);
self.lo("lsls_imm", "rm", rm);
self.imm("lsls_imm", imm5, 31, 1);
self.emit16((imm5 << 6) | (rm << 3) | rd);
self
}
pub fn lsrs_imm(&mut self, rd: u16, rm: u16, imm5: u16) -> &mut Self {
self.lo("lsrs_imm", "rd", rd);
self.lo("lsrs_imm", "rm", rm);
self.imm("lsrs_imm", imm5, 31, 1);
self.emit16(0x0800 | (imm5 << 6) | (rm << 3) | rd);
self
}
pub fn adds_reg(&mut self, rd: u16, rn: u16, rm: u16) -> &mut Self {
self.lo("adds_reg", "rd", rd);
self.lo("adds_reg", "rn", rn);
self.lo("adds_reg", "rm", rm);
self.emit16(0x1800 | (rm << 6) | (rn << 3) | rd);
self
}
pub fn mov_reg(&mut self, rd: u16, rm: u16) -> &mut Self {
self.reg("mov_reg", "rd", rd);
self.reg("mov_reg", "rm", rm);
self.emit16(0x4600 | ((rd & 8) << 4) | ((rm & 0xF) << 3) | (rd & 7));
self
}
pub fn movs_reg(&mut self, rd: u16, rm: u16) -> &mut Self {
self.lo("movs_reg", "rd", rd);
self.lo("movs_reg", "rm", rm);
self.emit16((rm << 3) | rd);
self
}
pub fn sdiv(&mut self, rd: u16, rn: u16, rm: u16) -> &mut Self {
self.divmod_wide("sdiv", 0xFB90, rd, rn, rm);
self
}
pub fn udiv(&mut self, rd: u16, rn: u16, rm: u16) -> &mut Self {
self.divmod_wide("udiv", 0xFBB0, rd, rn, rm);
self
}
fn divmod_wide(&mut self, mnemonic: &'static str, hw1_base: u16, rd: u16, rn: u16, rm: u16) {
self.reg(mnemonic, "rd", rd);
self.reg(mnemonic, "rn", rn);
self.reg(mnemonic, "rm", rm);
for (field, r) in [("rd", rd), ("rn", rn), ("rm", rm)] {
if r == 13 || r == 15 {
self.fail(format!(
"{mnemonic}: {field} = r{r} is UNPREDICTABLE (SP/PC), refuse rather than emit"
));
}
}
self.check_target(
mnemonic,
isa::legality::EncForm::T1,
isa::legality::OpExtra::Plain,
);
let hw1 = hw1_base | (rn & 0xF);
let hw2 = 0xF0F0 | ((rd & 0xF) << 8) | (rm & 0xF);
self.emit32(hw1, hw2);
}
pub fn adr(&mut self, rd: u16, blob_label: u16) -> &mut Self {
self.lo("adr", "rd", rd);
let pos = self.code.len();
self.emit16(0xA000 | (rd << 8));
self.adrs.push((pos, blob_label));
self
}
pub fn data_blob(&mut self, bytes: Vec<u8>) -> u16 {
let label = self.label();
self.blobs.push((label, bytes));
label
}
pub fn finish(&mut self) -> Result<Vec<u8>, AsmError> {
let target = self.target;
let mut this = core::mem::replace(self, Asm::with_target(target));
if let Some(e) = this.err.take() {
return Err(e);
}
for (pos, label, uncond) in core::mem::take(&mut this.fixups) {
let target = match this.labels.get(label as usize) {
Some(Some(t)) => *t,
Some(None) => {
return Err(AsmError::Layout {
at: pos,
msg: format!("unbound label {label}"),
})
}
None => {
return Err(AsmError::Layout {
at: pos,
msg: format!("label {label} was never reserved by `label()`"),
})
}
};
let off = (target as i32 - (pos as i32 + 4)) / 2;
let enc = if uncond {
if !(-1024..=1023).contains(&off) {
return Err(AsmError::Layout {
at: pos,
msg: format!("branch out of range ({off} halfwords)"),
});
}
0xE000u16 | (off as u16 & 0x07FF)
} else {
if !(-128..=127).contains(&off) {
return Err(AsmError::Layout {
at: pos,
msg: format!("conditional branch out of range ({off} halfwords)"),
});
}
let base = u16::from_le_bytes([this.code[pos], this.code[pos + 1]]) & 0xFF00;
base | (off as i8 as u8 as u16)
};
this.code[pos..pos + 2].copy_from_slice(&enc.to_le_bytes());
}
while this.code.len() % 4 != 0 {
this.code.push(0x00);
}
let mut placed: Vec<(u32, u32)> = Vec::new();
for (pos, value, rt) in core::mem::take(&mut this.ldrs) {
let off = match placed.iter().find(|(v, _)| *v == value) {
Some(&(_, o)) => o,
None => {
let o = this.code.len() as u32;
this.code.extend_from_slice(&value.to_le_bytes());
placed.push((value, o));
o
}
};
let pc = (pos as u32 + 4) & !3;
let imm8 = (off - pc) / 4;
if imm8 > 0xFF {
return Err(AsmError::Layout {
at: pos,
msg: format!("ldr literal out of range (imm8 = {imm8})"),
});
}
let enc = 0x4800u16 | (rt << 8) | imm8 as u16;
this.code[pos..pos + 2].copy_from_slice(&enc.to_le_bytes());
}
for (label, bytes) in core::mem::take(&mut this.blobs) {
while this.code.len() % 4 != 0 {
this.code.push(0x00);
}
this.labels[label as usize] = Some(this.code.len());
this.code.extend_from_slice(&bytes);
}
for (pos, label) in core::mem::take(&mut this.adrs) {
let target = match this.labels.get(label as usize) {
Some(Some(t)) => *t,
Some(None) => {
return Err(AsmError::Layout {
at: pos,
msg: format!("unbound blob label {label}"),
})
}
None => {
return Err(AsmError::Layout {
at: pos,
msg: format!("blob label {label} was never reserved by `label()`"),
})
}
};
let base = (pos as u32 + 4) & !3;
let imm = target as u32;
if imm < base || (imm - base) % 4 != 0 || (imm - base) / 4 > 0xFF {
return Err(AsmError::Layout {
at: pos,
msg: format!("adr target out of range (pos=0x{pos:x} target=0x{target:x})"),
});
}
let enc = 0xA000u16
| ((u16::from_le_bytes([this.code[pos], this.code[pos + 1]]) >> 8 & 7) << 8)
| ((imm - base) / 4) as u16;
this.code[pos..pos + 2].copy_from_slice(&enc.to_le_bytes());
}
Ok(this.code)
}
}
pub fn decode_bl(image: &[u8], off: usize) -> Option<u32> {
let b = image.get(off..off.checked_add(4)?)?;
let hw1 = u16::from_le_bytes([b[0], b[1]]);
let hw2 = u16::from_le_bytes([b[2], b[3]]);
if (hw1 & 0xF800) != 0xF000 || (hw2 & 0xD000) != 0xD000 {
return None;
}
let s = ((hw1 >> 10) & 1) as u32;
let imm10 = (hw1 & 0x3FF) as u32;
let j1 = ((hw2 >> 13) & 1) as u32;
let j2 = ((hw2 >> 11) & 1) as u32;
let imm11 = (hw2 & 0x7FF) as u32;
let i1 = (!(j1 ^ s)) & 1;
let i2 = (!(j2 ^ s)) & 1;
let mut imm = (imm11 | (imm10 << 11) | (i2 << 21) | (i1 << 22) | (s << 23)) << 1;
if imm & (1 << 24) != 0 {
imm |= !0u32 << 25;
}
Some((off as u32).wrapping_add(4).wrapping_add(imm))
}
pub fn encode_bl(site: usize, target: u32) -> Option<[u8; 4]> {
let pc = (site as u32).wrapping_add(4);
let off = (target.wrapping_sub(pc)) as i32;
if !(-(1 << 24)..(1 << 24)).contains(&off) || off & 1 != 0 {
return None;
}
let imm = (off >> 1) as u32 & 0x00ff_ffff;
let s = (imm >> 23) & 1;
let i1 = (imm >> 22) & 1;
let i2 = (imm >> 21) & 1;
let imm10 = (imm >> 11) & 0x3ff;
let imm11 = imm & 0x7ff;
let j1 = (!(i1 ^ s)) & 1;
let j2 = (!(i2 ^ s)) & 1;
let hw1 = 0xF000 | (s << 10) as u16 | imm10 as u16;
let hw2 = 0xD000 | (j1 << 13) as u16 | (j2 << 11) as u16 | imm11 as u16;
let mut out = [0u8; 4];
out[0..2].copy_from_slice(&hw1.to_le_bytes());
out[2..4].copy_from_slice(&hw2.to_le_bytes());
Some(out)
}
pub fn encode_b_wide(site: usize, target: u32) -> Option<[u8; 4]> {
let pc = (site as u32).wrapping_add(4);
let off = (target.wrapping_sub(pc)) as i32;
if !(-(1 << 24)..(1 << 24)).contains(&off) || off & 1 != 0 {
return None;
}
let imm = (off >> 1) as u32 & 0x00ff_ffff;
let s = (imm >> 23) & 1;
let i1 = (imm >> 22) & 1;
let i2 = (imm >> 21) & 1;
let imm10 = (imm >> 11) & 0x3ff;
let imm11 = imm & 0x7ff;
let j1 = (!(i1 ^ s)) & 1;
let j2 = (!(i2 ^ s)) & 1;
let hw1 = 0xF000 | (s << 10) as u16 | imm10 as u16;
let hw2 = 0x9000 | (j1 << 13) as u16 | (j2 << 11) as u16 | imm11 as u16;
let mut out = [0u8; 4];
out[0..2].copy_from_slice(&hw1.to_le_bytes());
out[2..4].copy_from_slice(&hw2.to_le_bytes());
Some(out)
}
pub fn decode_b_wide(image: &[u8], at: usize) -> Option<u32> {
if at.checked_add(4).map_or(true, |end| end > image.len()) {
return None;
}
let hw1 = u16::from_le_bytes([image[at], image[at + 1]]);
let hw2 = u16::from_le_bytes([image[at + 2], image[at + 3]]);
if (hw1 & 0xF800) != 0xF000 || (hw2 & 0xD000) != 0x9000 {
return None;
}
let s = ((hw1 >> 10) & 1) as u32;
let imm10 = (hw1 & 0x3FF) as u32;
let j1 = ((hw2 >> 13) & 1) as u32;
let j2 = ((hw2 >> 11) & 1) as u32;
let imm11 = (hw2 & 0x7FF) as u32;
let i1 = (!(j1 ^ s)) & 1;
let i2 = (!(j2 ^ s)) & 1;
let mut imm = (imm11 | (imm10 << 11) | (i2 << 21) | (i1 << 22) | (s << 23)) << 1;
if imm & (1 << 24) != 0 {
imm |= !0u32 << 25;
}
Some((at as u32).wrapping_add(4).wrapping_add(imm))
}
pub fn find_bl_sites(image: &[u8], target: u32) -> Vec<usize> {
let want = target & !1;
(0..image.len().saturating_sub(3))
.step_by(2)
.filter(|&off| decode_bl(image, off).map(|t| t & !1) == Some(want))
.collect()
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct CondBranch {
pub cond: Cond,
pub target: u32,
pub len: usize,
}
pub fn decode_b_cond(image: &[u8], at: usize) -> Option<CondBranch> {
let hw1 = try_read_u16(image, at)?;
if (hw1 & 0xF000) == 0xD000 {
let cond = match Cond::from_bits(((hw1 >> 8) & 0xF) as u8) {
Some(c) if c != Cond::Al => c,
_ => return None,
};
let imm = ((hw1 & 0xFF) as u8 as i8 as i32) * 2;
return Some(CondBranch {
cond,
target: (at as u32).wrapping_add(4).wrapping_add(imm as u32),
len: 2,
});
}
let hw2 = try_read_u16(image, at + 2)?;
if (hw1 & 0xF800) != 0xF000 || (hw2 & 0xD000) != 0x8000 {
return None;
}
let cond = match Cond::from_bits(((hw1 >> 6) & 0xF) as u8) {
Some(c) if c != Cond::Al => c,
_ => return None,
};
let s = ((hw1 >> 10) & 1) as u32;
let imm6 = (hw1 & 0x3F) as u32;
let j1 = ((hw2 >> 13) & 1) as u32;
let j2 = ((hw2 >> 11) & 1) as u32;
let imm11 = (hw2 & 0x7FF) as u32;
let mut imm = (imm11 | (imm6 << 11) | (j1 << 17) | (j2 << 18) | (s << 19)) << 1;
if imm & (1 << 20) != 0 {
imm |= !0u32 << 21;
}
Some(CondBranch {
cond,
target: (at as u32).wrapping_add(4).wrapping_add(imm),
len: 4,
})
}
pub fn encode_b_cond(site: usize, cond: Cond, target: u32) -> Option<Vec<u8>> {
if cond == Cond::Al {
return None;
}
let bits = cond.bits() as u16;
let pc = (site as u32).wrapping_add(4);
let off = target.wrapping_sub(pc) as i32;
if off & 1 != 0 {
return None;
}
if (-256..=254).contains(&off) {
let hw = 0xD000u16 | (bits << 8) | ((off >> 1) as i8 as u8 as u16);
return Some(hw.to_le_bytes().to_vec());
}
if !(-1_048_576..=1_048_574).contains(&off) {
return None;
}
let imm = (off >> 1) as u32 & 0xF_FFFF;
let s = (imm >> 19) & 1;
let j2 = (imm >> 18) & 1;
let j1 = (imm >> 17) & 1;
let imm6 = (imm >> 11) & 0x3F;
let imm11 = imm & 0x7FF;
let hw1 = 0xF000u16 | (s as u16) << 10 | (bits << 6) | imm6 as u16;
let hw2 = 0x8000u16 | (j1 as u16) << 13 | (j2 as u16) << 11 | imm11 as u16;
let mut out = Vec::with_capacity(4);
out.extend_from_slice(&hw1.to_le_bytes());
out.extend_from_slice(&hw2.to_le_bytes());
Some(out)
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[non_exhaustive]
pub enum BranchKind {
Bl,
BWide,
}
impl BranchKind {
pub fn encode(self, site: usize, target: u32) -> Option<[u8; 4]> {
match self {
BranchKind::Bl => encode_bl(site, target),
BranchKind::BWide => encode_b_wide(site, target),
}
}
pub fn decode(self, image: &[u8], at: usize) -> Option<u32> {
match self {
BranchKind::Bl => decode_bl(image, at),
BranchKind::BWide => decode_b_wide(image, at),
}
}
}
impl core::fmt::Display for BranchKind {
fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
f.write_str(match self {
BranchKind::Bl => "bl",
BranchKind::BWide => "b.w",
})
}
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[non_exhaustive]
pub struct InstallMismatch {
pub site: usize,
pub kind: BranchKind,
pub expected: u32,
pub found: Option<u32>,
}
impl InstallMismatch {
pub fn reason(&self) -> &'static str {
match self.found {
None => "not-a-branch",
Some(_) => "wrong-target",
}
}
}
impl core::fmt::Display for InstallMismatch {
fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
let Self {
site,
kind,
expected,
found,
} = self;
match found {
Some(got) => write!(
f,
"{kind} at 0x{site:x}: expected target 0x{expected:08x}, found 0x{got:08x}"
),
None => write!(
f,
"{kind} at 0x{site:x}: expected target 0x{expected:08x}, \
but no {kind} decodes there"
),
}
}
}
impl std::error::Error for InstallMismatch {}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[non_exhaustive]
pub enum BranchAt {
NotABranch,
Direct {
kind: Option<BranchKind>,
width: u8,
target: u32,
},
Indirect {
width: u8,
},
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[non_exhaustive]
pub enum InstallHazard {
OutOfBounds {
site: usize,
image_len: usize,
},
NotAnInstruction {
site: usize,
},
SplitsInstruction {
at: usize,
displaced: usize,
},
}
impl InstallHazard {
pub fn reason(&self) -> &'static str {
match self {
InstallHazard::OutOfBounds { .. } => "out-of-bounds",
InstallHazard::NotAnInstruction { .. } => "not-an-instruction",
InstallHazard::SplitsInstruction { .. } => "splits-instruction",
}
}
}
impl core::fmt::Display for InstallHazard {
fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
match self {
InstallHazard::OutOfBounds { site, image_len } => write!(
f,
"a 4-byte branch at {site:#x} runs past the end of a {image_len:#x}-byte image"
),
InstallHazard::NotAnInstruction { site } => {
write!(f, "nothing decodes at {site:#x}")
}
InstallHazard::SplitsInstruction { at, displaced } => write!(
f,
"a 4-byte branch at this site cuts the instruction at {at:#x} in half; \
whole instructions occupy {displaced} bytes"
),
}
}
}
impl std::error::Error for InstallHazard {}
pub fn can_install(image: &[u8], site: usize, kind: BranchKind) -> Result<(), InstallHazard> {
can_install_with(isa::Target::Union, image, site, kind)
}
pub fn can_install_with(
target: isa::Target,
image: &[u8],
site: usize,
kind: BranchKind,
) -> Result<(), InstallHazard> {
let _ = kind; if site.checked_add(4).map_or(true, |end| end > image.len()) {
return Err(InstallHazard::OutOfBounds {
site,
image_len: image.len(),
});
}
let mut at = site;
while at < site + 4 {
let insn = match isa::decode_at_with(image, at, at as u32, target) {
Some(i) => i,
None => return Err(InstallHazard::NotAnInstruction { site: at }),
};
let next = at + insn.len();
if next > site + 4 {
return Err(InstallHazard::SplitsInstruction {
at,
displaced: next - site,
});
}
at = next;
}
Ok(())
}
pub fn classify_branch(image: &[u8], at: usize) -> BranchAt {
classify_branch_with(isa::Target::Union, image, at)
}
pub fn classify_branch_with(target: isa::Target, image: &[u8], at: usize) -> BranchAt {
let insn = match isa::decode_at_with(image, at, at as u32, target) {
Some(i) => i,
None => return BranchAt::NotABranch,
};
if !insn.is_branch() {
return BranchAt::NotABranch;
}
let width = insn.len() as u8;
let has_mem = insn
.operands
.as_slice()
.any(|o| matches!(o, isa::Operand::Mem(_)));
match insn.branch_target() {
Some(target) if !has_mem => {
let kind = match (insn.mnemonic, insn.len()) {
("bl", 4) => Some(BranchKind::Bl),
("b", 4) => Some(BranchKind::BWide),
_ => None,
};
BranchAt::Direct {
kind,
width,
target: target & !1,
}
}
_ => BranchAt::Indirect { width },
}
}
pub fn verify_branch(
image: &[u8],
site: usize,
kind: BranchKind,
expected: u32,
) -> Result<(), InstallMismatch> {
let expected = expected & !1;
let found = kind.decode(image, site).map(|t| t & !1);
if found == Some(expected) {
Ok(())
} else {
Err(InstallMismatch {
site,
kind,
expected,
found,
})
}
}
pub fn install_branch(
image: &mut [u8],
site: usize,
kind: BranchKind,
target: u32,
) -> Result<(), InstallMismatch> {
let target = target & !1;
let fail = || InstallMismatch {
site,
kind,
expected: target,
found: None,
};
if site.checked_add(4).map_or(true, |end| end > image.len()) {
return Err(fail());
}
let bytes = kind.encode(site, target).ok_or_else(fail)?;
write(image, site, &bytes);
verify_branch(image, site, kind, target)
}
fn find_bytes(image: &[u8], pat: &[u8], start: usize) -> Option<usize> {
find_bytes_in(image, pat, start, image.len())
}
fn find_bytes_in(image: &[u8], pat: &[u8], start: usize, end: usize) -> Option<usize> {
let end = end.min(image.len());
if pat.is_empty() || start >= end || pat.len() > end - start {
return None;
}
image[start..end]
.windows(pat.len())
.position(|w| w == pat)
.map(|p| p + start)
}
fn find_free_run(image: &[u8], len: usize, align: usize, start: usize) -> Option<usize> {
find_free_run_in(image, len, align, start, image.len())
}
fn find_free_run_in(
image: &[u8],
len: usize,
align: usize,
start: usize,
end: usize,
) -> Option<usize> {
assert!(align != 0, "alignment must be at least 1 byte");
let end = end.min(image.len());
let mut p = round_up(start.min(end), align);
loop {
if p.checked_add(len).map_or(true, |stop| stop > end) {
return None;
}
match image[p..p + len].iter().position(|&b| b != 0xFF) {
None => return Some(p),
Some(k) => p = round_up(p + k + 1, align),
}
}
}
fn find_masked(image: &[u8], pat: &[(u16, u16)], start: usize) -> Option<usize> {
find_masked_in(image, pat, start, image.len())
}
fn find_masked_in(image: &[u8], pat: &[(u16, u16)], start: usize, end: usize) -> Option<usize> {
if pat.is_empty() {
return None;
}
let need = pat.len() * 2;
let end = end.min(image.len());
let mut p = round_up(start.min(end), 2);
while p.checked_add(need).map_or(false, |stop| stop <= end) {
let hit = pat.iter().enumerate().all(|(i, &(value, mask))| {
let at = p + i * 2;
u16::from_le_bytes([image[at], image[at + 1]]) & mask == value & mask
});
if hit {
return Some(p);
}
p += 2;
}
None
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[non_exhaustive]
pub enum Fit {
First,
Largest,
}
pub fn find_free_space_in(
image: &[u8],
len: usize,
align: usize,
within: &[core::ops::Range<usize>],
fit: Fit,
) -> Option<usize> {
assert!(align != 0, "alignment must be at least 1 byte");
let mut best: Option<(usize, usize)> = None; for region in within {
let lo = region.start.min(image.len());
let hi = region.end.min(image.len());
let mut p = lo;
while p < hi {
if image[p] != 0xFF {
p += 1;
continue;
}
let run_start = p;
while p < hi && image[p] == 0xFF {
p += 1;
}
let at = round_up(run_start, align);
if at.checked_add(len).map_or(false, |end| end <= p) {
let usable = p - at;
let better = match (fit, best) {
(_, None) => true,
(Fit::First, Some((_, b_at))) => at < b_at,
(Fit::Largest, Some((b_len, b_at))) => {
usable > b_len || (usable == b_len && at < b_at)
}
};
if better {
best = Some((usable, at));
}
}
}
}
best.map(|(_, at)| at)
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[non_exhaustive]
pub enum Straddle {
Clip,
Reject,
}
#[derive(Debug, Clone)]
pub struct FreeSpace<'a> {
image: &'a [u8],
runs: Vec<core::ops::Range<usize>>,
align: usize,
at: usize,
cursor: usize,
}
impl<'a> FreeSpace<'a> {
pub fn new(
image: &'a [u8],
within: &[core::ops::Range<usize>],
align: usize,
straddle: Straddle,
) -> Self {
assert!(align != 0, "alignment must be at least 1 byte");
let mut regions: Vec<core::ops::Range<usize>> = within
.iter()
.map(|r| r.start.min(image.len())..r.end.min(image.len()))
.filter(|r| r.start < r.end)
.collect();
regions.sort_by_key(|r| r.start);
let mut merged: Vec<core::ops::Range<usize>> = Vec::with_capacity(regions.len());
for r in regions {
match merged.last_mut() {
Some(last) if r.start <= last.end => last.end = last.end.max(r.end),
_ => merged.push(r),
}
}
let mut runs = Vec::new();
for region in &merged {
let mut p = region.start;
while p < region.end {
if image[p] != 0xFF {
p += 1;
continue;
}
let start = p;
while p < region.end && image[p] == 0xFF {
p += 1;
}
let runs_off_the_front =
start > 0 && start == region.start && image[start - 1] == 0xFF;
let runs_off_the_back = p < image.len() && p == region.end && image[p] == 0xFF;
if straddle == Straddle::Reject && (runs_off_the_front || runs_off_the_back) {
continue;
}
runs.push(start..p);
}
}
let cursor = runs.first().map_or(0, |r| r.start);
FreeSpace {
image,
runs,
align,
at: 0,
cursor,
}
}
pub fn alloc(&mut self, len: usize) -> Option<usize> {
let mut at = self.at;
let mut cursor = self.cursor;
while at < self.runs.len() {
let run = &self.runs[at];
let start = round_up(cursor.max(run.start), self.align);
if start.checked_add(len).map_or(false, |end| end <= run.end) {
self.at = at;
self.cursor = start + len;
return Some(start);
}
at += 1;
cursor = self.runs.get(at).map_or(0, |r| r.start);
}
None
}
pub fn remaining(&self) -> usize {
self.runs
.iter()
.enumerate()
.map(|(i, r)| match i.cmp(&self.at) {
core::cmp::Ordering::Less => 0,
core::cmp::Ordering::Equal => r.end.saturating_sub(self.cursor.max(r.start)),
core::cmp::Ordering::Greater => r.end - r.start,
})
.sum()
}
pub fn runs(&self) -> &[core::ops::Range<usize>] {
&self.runs
}
pub fn image(&self) -> &'a [u8] {
self.image
}
}
fn round_up(v: usize, align: usize) -> usize {
match v % align {
0 => v,
r => v.saturating_add(align - r),
}
}
#[cfg(test)]
#[path = "thumb_tests.rs"]
mod tests;
#[cfg(test)]
mod unreserved_label_tests {
use super::*;
#[test]
fn a_label_never_reserved_is_refused_by_every_path_that_takes_one() {
let mut a = Asm::new();
a.b_cond(Cond::Eq, 7);
let err = a.finish().expect_err("an unreserved label must not panic");
let msg = err.to_string();
assert!(msg.contains("never reserved"), "{msg}");
let mut a = Asm::new();
a.b(9);
let err = a.finish().expect_err("an unreserved label must not panic");
assert!(err.to_string().contains("never reserved"));
let mut a = Asm::new();
a.adr(0, 3);
let err = a
.finish()
.expect_err("an unreserved blob label must not panic");
assert!(err.to_string().contains("never reserved"));
}
#[test]
fn a_reserved_but_unbound_label_reports_separately() {
let mut a = Asm::new();
let l = a.label();
a.b_cond(Cond::Eq, l);
let err = a.finish().expect_err("never bound");
let msg = err.to_string();
assert!(msg.contains("unbound label"), "{msg}");
assert!(!msg.contains("never reserved"));
}
}
#[cfg(test)]
mod command_table_overflow_tests {
use super::*;
#[test]
fn a_table_whose_base_plus_stride_overflows_is_refused_not_wrapped() {
let image = vec![0u8; 100];
let table = CommandTable {
base: usize::MAX - 10,
stride: 20,
opcode_off: 0,
flags_off: 1,
handler_off: 4,
term_flag: 0xFF,
max_records: 5,
};
assert_eq!(
table.find(&image, 0x42),
None,
"an overflowing base+stride must be refused, not wrapped into range"
);
assert!(
table.walk(&image, 0x01).is_empty(),
"walk must refuse the same table"
);
}
}
#[cfg(test)]
mod error_reason_tests {
use super::*;
#[test]
fn every_error_type_reports_a_stable_machine_readable_reason() {
assert_eq!(FindError::NotFound.reason(), "not-found");
assert_eq!(
FindError::Ambiguous {
count: 3,
first: 0x10
}
.reason(),
"ambiguous"
);
assert_eq!(
InstallHazard::OutOfBounds {
site: 0,
image_len: 2
}
.reason(),
"out-of-bounds"
);
assert_eq!(
InstallHazard::NotAnInstruction { site: 0 }.reason(),
"not-an-instruction"
);
let nothing = InstallMismatch {
site: 0,
kind: BranchKind::Bl,
expected: 0x1000,
found: None,
};
assert_eq!(nothing.reason(), "not-a-branch");
let wrong = InstallMismatch {
found: Some(0x2000),
..nothing
};
assert_eq!(wrong.reason(), "wrong-target");
}
#[test]
fn the_split_instruction_hazard_reports_its_reason() {
let image = [0x00, 0xBF, 0x00, 0xF0, 0x00, 0xF8, 0x00, 0xBF];
let hazard =
can_install(&image, 0, BranchKind::Bl).expect_err("site splits an instruction");
assert_eq!(hazard.reason(), "splits-instruction");
}
#[test]
fn an_assembler_error_reports_its_reason_and_message() {
let mut asm = Asm::new();
asm.movs_imm(8, 0);
let err = asm.finish().expect_err("a high register must fail");
assert_eq!(err.reason(), "operand");
let msg = err.to_string();
assert!(
msg.contains("movs"),
"the message should name the instruction, got: {msg}"
);
}
}
#[cfg(test)]
mod asm_reuse_tests {
use super::*;
use crate::isa::Target;
#[test]
fn a_second_finish_on_the_same_assembler_produces_the_empty_buffer() {
let mut a = Asm::with_target(Target::Union);
a.push(0x0100); let first = a.finish().expect("push assembles");
assert_eq!(
first.len(),
4,
"one halfword padded to the 4-byte pool align"
);
let second = a.finish().expect("a reset assembler still finishes");
assert!(
second.is_empty(),
"a fresh assembler after finish must produce no bytes, got {second:02x?}"
);
}
#[test]
fn a_label_from_a_previous_finish_is_refused_by_the_next_one() {
let mut a = Asm::new();
let stale = a.label();
a.bind(stale);
let _ = a.finish().expect("empty buffer assembles");
a.b(stale);
let err = a
.finish()
.expect_err("stale label must not silently branch into the previous buffer");
assert!(
err.to_string().contains("was never reserved"),
"expected an unreserved-label diagnostic, got: {err}"
);
}
#[test]
fn a_reset_assembler_keeps_the_original_target() {
let mut a = Asm::with_target(Target::V8M);
let _ = a.finish().expect("empty buffer");
assert_eq!(
a.target(),
Target::V8M,
"target must survive the reset in finish"
);
}
}
#[cfg(test)]
mod asm_target_gate_tests {
use super::*;
use crate::isa::Target;
#[test]
fn sdiv_is_refused_under_v7a() {
let mut a = Asm::with_target(Target::V7A);
a.sdiv(0, 1, 2);
let err = a.finish().expect_err("sdiv is UNDEFINED on Armv7-A");
assert!(matches!(
&err,
AsmError::Unsupported {
mnemonic: "sdiv",
target: Target::V7A,
at: 0
}
));
}
#[test]
fn sdiv_is_accepted_under_v7r_and_encodes_correctly() {
let mut a = Asm::with_target(Target::V7R);
a.sdiv(0, 1, 2);
let bytes = a.finish().expect("sdiv is mandatory on Armv7-R");
assert_eq!(
&bytes[..4],
&[0x91, 0xFB, 0xF2, 0xF0],
"sdiv r0, r1, r2 encoding"
);
}
#[test]
fn v7ar_is_strictly_stricter_than_v7r() {
let mut a = Asm::with_target(Target::V7AR);
a.sdiv(0, 1, 2);
let err = a
.finish()
.expect_err("V7AR must refuse anything V7A refuses");
assert!(matches!(
err,
AsmError::Unsupported {
mnemonic: "sdiv",
target: Target::V7AR,
..
}
));
}
#[test]
fn raw16_refuses_a_wide_prefix_under_non_union() {
let mut a = Asm::with_target(Target::V7A);
a.raw16(0xF400);
let err = a
.finish()
.expect_err("wide prefix via raw16 has no second halfword to decode");
assert!(matches!(
err,
AsmError::Unsupported {
mnemonic: "raw16",
target: Target::V7A,
..
}
));
let mut u = Asm::with_target(Target::Union);
u.raw16(0xF400);
let bytes = u.finish().expect("Union is permissive");
assert_eq!(
&bytes[..2],
&[0x00, 0xF4],
"Union writes 0xF400 little-endian"
);
}
#[test]
fn thumb1_refuses_wide_thumb2_but_accepts_thumb1() {
let mut a = Asm::with_target(Target::Thumb1);
a.raw32(0xF8DF, 0xF000); assert!(
a.finish().is_err(),
"Thumb1 must refuse a wide Thumb-2 encoding"
);
let mut b = Asm::with_target(Target::Thumb1);
b.push(0b1); b.pop(0b1); assert!(
b.finish().is_ok(),
"Thumb1 must accept Thumb-1 base 16-bit ops"
);
}
#[test]
fn raw16_refuses_thumbee_undefined_pattern() {
let mut a = Asm::with_target(Target::ThumbEE);
a.raw16(0xC100);
let err = a
.finish()
.expect_err("0xC1xx is UNDEFINED in ThumbEE (Table A9-2)");
assert_eq!(err.reason(), "unsupported");
}
#[test]
fn raw32_accepts_the_v8m_sg_pattern() {
let mut a = Asm::with_target(Target::V8M);
a.raw32(0xE97F, 0xE97F);
let bytes = a.finish().expect("V8M decoder recovers this as sg");
assert_eq!(
&bytes[..4],
&[0x7F, 0xE9, 0x7F, 0xE9],
"SG bytes emitted in little-endian order"
);
}
#[test]
fn raw32_refuses_sdiv_pattern_under_v7a() {
let mut a = Asm::with_target(Target::V7A);
a.raw32(0xFB91, 0xF2F3);
let err = a.finish().expect_err("sdiv via raw32 is UNDEFINED on V7A");
assert!(matches!(
err,
AsmError::Unsupported {
mnemonic: "sdiv",
target: Target::V7A,
..
}
));
}
#[test]
fn raw16_unchecked_bypasses_the_gate() {
let mut a = Asm::with_target(Target::V7A);
a.raw16_unchecked(0xF400); let bytes = a
.finish()
.expect("raw16_unchecked bypasses every legality check");
assert_eq!(&bytes[..2], &[0x00, 0xF4]);
}
#[test]
fn can_install_with_agrees_with_can_install_on_baseline_bytes() {
let image = [0x00, 0xBF, 0x00, 0xBF];
for t in [
Target::Union,
Target::V7M,
Target::V7A,
Target::V7R,
Target::V7AR,
Target::V7EM,
Target::V8M,
] {
assert!(
can_install_with(t, &image, 0, BranchKind::Bl).is_ok(),
"can_install_with({t:?}) must accept a baseline site"
);
}
}
#[test]
fn udiv_encodes_exactly_with_nonzero_rd() {
let mut a = Asm::new();
a.udiv(3, 4, 5);
let bytes = a.finish().expect("udiv is legal under Union");
assert_eq!(&bytes[..4], &[0xB4, 0xFB, 0xF5, 0xF3], "udiv r3, r4, r5");
}
#[test]
fn udiv_is_accepted_under_v7r() {
let mut a = Asm::with_target(Target::V7R);
a.udiv(0, 1, 2);
let bytes = a.finish().expect("udiv is mandatory on Armv7-R (spec:874)");
assert_eq!(&bytes[..4], &[0xB1, 0xFB, 0xF2, 0xF0]);
}
#[test]
fn divmod_wide_refuses_rn_equal_sp() {
let mut a = Asm::new();
a.sdiv(0, 13, 2);
let err = a.finish().expect_err("Rn=SP is UNPREDICTABLE for sdiv");
assert_eq!(err.reason(), "operand");
}
#[test]
fn divmod_wide_refuses_rm_equal_pc() {
let mut a = Asm::new();
a.udiv(0, 1, 15);
let err = a.finish().expect_err("Rm=PC is UNPREDICTABLE for udiv");
assert_eq!(err.reason(), "operand");
}
#[test]
fn asm_error_reason_and_at_cover_every_variant() {
let mut a = Asm::new();
a.push(0); let err = a.finish().expect_err("empty reglist is refused");
assert_eq!(err.reason(), "operand");
assert_eq!(err.at(), 0);
let mut a = Asm::with_target(Target::V7A);
a.sdiv(0, 1, 2);
let err = a.finish().expect_err("sdiv on V7A is refused");
assert_eq!(err.reason(), "unsupported");
let text = format!("{err}");
assert!(text.contains("sdiv"), "Display must name the mnemonic");
assert!(text.contains("V7A"), "Display must name the target");
let mut a = Asm::new();
a.ldr_lit(0, 0xDEAD_BEEF);
for _ in 0..600 {
a.raw16_unchecked(0xBF00);
}
let err = a.finish().expect_err("literal is out of range");
assert_eq!(err.reason(), "layout");
assert_eq!(err.at(), 0, "the failed ldr_lit sits at offset 0");
}
#[test]
fn raw32_under_union_is_byte_for_byte() {
let mut a = Asm::with_target(Target::Union);
a.raw32(0xE97F, 0xE97F);
let bytes = a.finish().expect("Union permits any halfword pair");
assert_eq!(&bytes[..4], &[0x7F, 0xE9, 0x7F, 0xE9]);
}
#[test]
fn raw32_reports_raw32_when_the_pair_is_undecodable() {
let mut a = Asm::with_target(Target::V7A);
a.raw32(0xF7F0, 0x0000);
let err = a.finish().expect_err("this pair is UNDEFINED");
assert!(matches!(
&err,
AsmError::Unsupported {
mnemonic: "raw32",
..
}
));
}
#[test]
fn detour_options_with_target_records_the_target() {
let opts = crate::detour::DetourOptions::default().with_target(Target::V8M);
assert_eq!(opts.target, Target::V8M);
}
#[test]
fn raw16_accepts_a_narrow_defined_pattern_under_non_union() {
let mut a = Asm::with_target(Target::V7A);
a.raw16(0xBF00);
let bytes = a.finish().expect("nop is baseline everywhere");
assert_eq!(&bytes[..2], &[0x00, 0xBF]);
}
#[test]
fn asm_error_at_returns_the_actual_byte_position() {
let mut a = Asm::with_target(Target::V7A);
a.raw16_unchecked(0xBF00); a.raw16_unchecked(0xBF00); a.sdiv(0, 1, 2); let err = a.finish().expect_err("sdiv is UNDEFINED on V7A");
assert_eq!(
err.at(),
4,
"at() must return the actual position (4), not 0 or 1"
);
}
}