rigless 0.2.0

// Copyright (c) 2026 Rigless Labs.
// SPDX-License-Identifier: MIT OR Apache-2.0
//! The runner: a target's core on a thread of its own, and the calls between it and the models.
//!
//! The core is the processor family's, a [`Processor`] the target's spec makes, whether the
//! family is this crate's or another's. [`run`] makes the target's processor and moves it to a
//! thread of its own, maps the target's memory, places the images and boots, then runs the core in
//! stretches to the next instant the models asked for. An access the core doesn't answer from its
//! own space or from plain memory goes to [`Session::access`], between two instructions' worth of
//! the core's state, and the core returns to the runner after that instruction. A core is a value,
//! so a process runs as many as it likes, one after another or at once.
//!
//! Time keeps the rules the runtime has always had. The core retires
//! `CoreSpec::instructions_per_second`, and virtual time is the instructions retired at that rate,
//! in whole nanoseconds rounded down, plus every warp. A run
//! stops at the first instruction boundary at or past the deadline. An access ends its stretch, so
//! an interrupt it raises is taken, and a deadline it moved is met, before the next instruction,
//! and it's reported with the accessing instruction counted. A core waiting for an interrupt warps
//! the clock to the next deadline, and a stop that finds it waiting is [`StopReason::Idle`].
//!
//! A watched instruction is a breakpoint the core stops before. Its arrival is reported once, known
//! by its address and the instructions retired before it, and the core then runs the instruction
//! with the breakpoint lifted. A watched range has its pages routed to the runner, which answers
//! them from [`Memory`] and notes the first store an instruction makes into the range. That store
//! is reported once its instruction is done.
//!
//! [`Session::access`]: crate::session::Session::access

mod gdb;
mod run;
mod stream;

use std::any::Any;
use std::collections::{BTreeMap, BTreeSet};
use std::net::TcpListener;
use std::num::NonZeroU64;
use std::sync::atomic::{AtomicBool, Ordering};

use super::memory::{Mapped, Memory, PAGE_ALIGNMENT, to_target};
use super::{
    Access, AccessKind, CoreBus, Driver, Error, Exit, Finished, Hit, HitKind, Host, HostCall,
    InterruptLine, Interrupted, Memory as GuestMemory, NO_DEADLINE, OpenMode, Processor, Queued,
    Resume, Start, Stop, StopReason, Watch,
};
use crate::device::Level;
use crate::image::{self, Segment};
use crate::machine::Board;
use crate::mcu::Operate;
use crate::rtt::{self, Rtt};
use crate::session::Session;
use crate::snapshot;
use crate::soc::{Endian, Width};
use crate::soc::{Region, RegionKind};
use crate::symbols::Symbols;
use crate::time::VirtualNanos;
#[cfg(fuzzing)]
pub(crate) use gdb::Fuzzed;
use gdb::{Debugger, Fresult, Map, Watchpoint};
use run::{Driven, Kept, Run};
use stream::Stream;

/// The most instructions one stretch runs, so a far deadline is still reached in stretches the
/// core's 32-bit budget holds.
const LONGEST_STRETCH: u64 = 1 << 30;

/// The stack a core's thread gets: the models it calls into, and a debugger stopping inside them.
const CORE_STACK: usize = 64 << 20;

/// The most bytes of pages the run's own watches route to the runner at once, so a watch can't make
/// every access slow, whatever size the processor's pages are. It's what they've always had, so a
/// fault trigger's watch that fit still fits, and it doesn't depend on a debugger.
const RUN_ROUTED_BYTES: u64 = (1 << 20) - (64 << 10);

/// The most bytes of pages a debugger's watchpoints route to the runner at once, more memory than
/// any part here has. A watch on a lot of it slows the run, and that's yours to weigh, as `monitor
/// help` says.
const DEBUGGER_ROUTED_BYTES: u64 = 1 << 26;

/// The most watchpoints a debugger may set at once, since every access to a page one watches looks
/// at each of them.
const DEBUGGER_WATCHPOINTS: usize = 1 << 12;

/// One core and the run it serves.
struct Core {
    driven: Box<dyn Driven>,
    machine: Machine,
    /// Whether the run serves host calls.
    semihosting: bool,
    /// Where the processor's own trace goes.
    trace: Option<Stream>,
    /// Where the firmware's RTT terminal goes.
    terminal: Option<Stream>,
}

/// What a host call that isn't a read or a write answers when it fails, -1.
const HOST_CALL_FAILED: u64 = u64::MAX;

/// How many of [`HostCall::Elapsed`]'s ticks, virtual nanoseconds, make a second.
const TICKS_PER_SECOND: u64 = 1_000_000_000;

/// Virtual nanoseconds in a hundredth of a second, [`HostCall::Clock`]'s unit.
const CLOCK_TICK: u64 = 10_000_000;

/// The permissions a file the firmware makes on the debugger's host gets: read and write for its
/// owner, and read for everyone else, "Debugging with GDB" for GDB 18.1, section E.14's `mode_t`
/// values.
const FILE_MODE: u64 = 0o644;

/// `lseek`'s whence, "Debugging with GDB" for GDB 18.1, section E.14's "Lseek Flags".
const SEEK_SET: u64 = 0;
const SEEK_CUR: u64 = 1;
const SEEK_END: u64 = 2;

/// `open`'s flags for `mode`, as "Debugging with GDB" for GDB 18.1, section E.14's "Open Flags"
/// give them, and as C's `fopen` opens a file in that mode.
fn open_flags(mode: OpenMode) -> u64 {
    const RDONLY: u64 = 0x0;
    const WRONLY: u64 = 0x1;
    const RDWR: u64 = 0x2;
    const APPEND: u64 = 0x8;
    const CREAT: u64 = 0x200;
    const TRUNC: u64 = 0x400;
    match mode {
        OpenMode::Read => RDONLY,
        OpenMode::ReadWrite => RDWR,
        OpenMode::Write => WRONLY | CREAT | TRUNC,
        OpenMode::WriteRead => RDWR | CREAT | TRUNC,
        OpenMode::Append => WRONLY | CREAT | APPEND,
        OpenMode::AppendRead => RDWR | CREAT | APPEND,
    }
}

/// What became of a host call.
enum Answered {
    /// The run answered it, and the core goes on past it.
    Served,
    /// Nothing serves host calls, so the core did what the instruction does without one.
    Unserved,
    /// The firmware ended the run with this status.
    Exited(u32),
}

/// The core's side of a run: what [`Host`] lends the models.
#[derive(Debug)]
struct Machine {
    /// The processor, except while it runs a stretch, when the runner reaches it only through
    /// `queued`. It's declared before `memory` so it's dropped first, while what it maps is still
    /// there, as [`Processor::map`] promises.
    cpu: Option<Box<dyn Processor>>,
    memory: Mapped,
    /// What the run asked of the processor while it ran.
    queued: Vec<Queued>,
    /// How many instructions the core retires in a second of virtual time.
    rate: NonZeroU64,
    /// The bytes in one of the processor's pages, which it maps and routes.
    page: u64,
    /// Each instruction whose watch the run started or stopped while the processor ran a stretch,
    /// with whether the processor had a breakpoint there before. The processor hears the
    /// difference once the stretch ends.
    breakpoints: BTreeMap<u64, bool>,
    /// Virtual time the clock warped while the core waited, on top of its instructions.
    warped: u64,
    /// The next instant the models need control at.
    deadline: VirtualNanos,
    /// An instant a debugger has the core stop at, which a stretch or a waiting core's warp goes no
    /// further than, as it goes no further than the deadline.
    horizon: Option<VirtualNanos>,
    /// The next instant the run drains the firmware's RTT terminal, which a stretch or a warp goes
    /// no further than either.
    drain: Option<VirtualNanos>,
    /// What the run placed, put back in RAM at every reset as a loader would.
    segments: Vec<Segment>,
    /// Where the core boots from.
    boot: u64,
    /// A model asked for a reset from inside a call, and has done its own half.
    restart: bool,
    /// A debugger wrote memory the guest can't, which a snapshot doesn't keep.
    read_only_written: bool,
    watching: Watching,
    /// The processor asked for a reset in the stretch that just ran, taken from it at once so a
    /// checkpoint can see it's pending.
    requested: bool,
    /// The error number of the last host call that failed with one.
    errno: u64,
    /// The firmware's RTT block, when the run drains its terminal.
    rtt: Option<Rtt>,
}

/// Where a run stands: how many instructions the core has retired, and the instant it's at. Along
/// a run both only ever grow, so positions order as the run reached them.
#[derive(Clone, Copy, Debug, PartialEq, Eq, PartialOrd, Ord)]
pub(super) struct Position {
    pub(super) count: u64,
    pub(super) at: VirtualNanos,
}

/// The run as it stood at a position, which it can be put back to: the core and its memory, the
/// models and what the driver had been told, what the firmware's host calls and ports had done.
#[derive(Debug)]
pub(super) struct Checkpoint {
    pub(super) position: Position,
    machine: Vec<u8>,
    drain: Option<VirtualNanos>,
    /// Every region the guest writes, and the ones it can't too once a debugger has written them.
    memory: Vec<(u64, Vec<u8>)>,
    run: Kept,
    /// What the trace and RTT ports had sent.
    sent: (u64, u64),
}

/// What the run watches, and where the last hit on it was.
#[derive(Debug, Default)]
struct Watching {
    /// Each a breakpoint the core stops before.
    instructions: BTreeSet<u64>,
    /// Each range as its first and last byte, in the order they were started, with every page they
    /// touch routed to the runner.
    writes: Vec<(u64, u64)>,
    /// Where and after how many instructions the core last arrived at a watched instruction, so
    /// it runs the instruction the next time it looks rather than arriving again.
    arrived: Option<(u64, u64)>,
    /// Where the running instruction first stored into a watched range.
    written: Option<u64>,
    /// The debugger's watchpoints, each as its first and last byte and what it watches for.
    debugged: Vec<((u64, u64), Watchpoint)>,
    /// Where the running instruction hit a debugger's watchpoint, and which kind it was, which
    /// stops the core before that access or right after the instruction.
    debugger_hit: Option<(u64, Watchpoint)>,
    /// The instruction a debugger lets run on from a watch stop, by its address and the count it
    /// retires at, whose accesses no watchpoint stops, so it gets past the one it stopped before.
    passing: Option<(u64, u64)>,
}

/// Whether an access of `width` at `address` touches the range from `first` to `last`.
fn touches((first, last): (u64, u64), address: u64, width: Width) -> bool {
    address <= last && first <= address.saturating_add(u64::from(width.bytes()) - 1)
}

/// Every page of `size` bytes `ranges` touch.
fn pages_of<'a>(ranges: impl IntoIterator<Item = &'a (u64, u64)>, size: u64) -> BTreeSet<u64> {
    ranges
        .into_iter()
        .flat_map(|&(first, last)| (first / size..=last / size).map(move |page| page * size))
        .collect()
}

/// Whether `ranges` and `range` touch pages of `size` bytes that come to no more than `limit` bytes
/// between them.
fn fit(ranges: &[(u64, u64)], range: (u64, u64), limit: u64, size: u64) -> bool {
    let pages = limit / size;
    range.1 / size - range.0 / size < pages
        && pages_of(ranges.iter().chain([&range]), size).len() as u64 <= pages
}

/// The virtual nanoseconds `instructions` take at `rate` instructions a second, rounded down.
fn nanos(rate: NonZeroU64, instructions: u64) -> u64 {
    let nanos = u128::from(instructions) * NANOS_PER_SECOND / u128::from(rate.get());
    u64::try_from(nanos).unwrap_or(u64::MAX)
}

/// How many instructions past `retired` take the clock, warped by `warped`, to `target` or past
/// it at `rate`, at least one and at most a stretch.
fn instructions_until(rate: NonZeroU64, warped: u64, retired: u64, target: VirtualNanos) -> u32 {
    let since = u128::from(target.0.saturating_sub(warped));
    let needed = (since * u128::from(rate.get())).div_ceil(NANOS_PER_SECOND);
    let more = needed
        .saturating_sub(u128::from(retired))
        .clamp(1, u128::from(LONGEST_STRETCH));
    u32::try_from(more).expect("clamped to a stretch")
}

/// The nanoseconds in a second.
const NANOS_PER_SECOND: u128 = 1_000_000_000;

impl Watching {
    /// Every page of `size` bytes a watched range or a debugger's watchpoint touches.
    fn pages(&self, size: u64) -> BTreeSet<u64> {
        pages_of(
            self.writes
                .iter()
                .chain(self.debugged.iter().map(|(range, _)| range)),
            size,
        )
    }

    /// Notes an access of `width` at `address` by the running instruction, if it's the
    /// instruction's first store into a watched range. The address noted is the first byte of the
    /// access inside the first range it touches.
    fn accessed(&mut self, kind: AccessKind, address: u64, width: Width) {
        if kind == AccessKind::Write && self.written.is_none() {
            self.written = self
                .writes
                .iter()
                .find(|&&range| touches(range, address, width))
                .map(|&(first, _)| address.max(first));
        }
    }

    /// The first of a debugger's watchpoints an instruction's `access` hits for its kind, as the
    /// first byte of the access inside it and what it watches for. The instruction a debugger lets
    /// run on from a watch stop gets past every watchpoint.
    fn hit(&self, access: &Access) -> Option<(u64, Watchpoint)> {
        let at = access
            .program_counter
            .map(|pc| (pc, access.instruction_count));
        if self.debugged.is_empty() || at.is_some_and(|at| self.passing == Some(at)) {
            return None;
        }
        let Access {
            kind,
            address,
            width,
            ..
        } = *access;
        self.debugged
            .iter()
            .find(|&&(range, watchpoint)| {
                watchpoint.watches(kind) && touches(range, address, width)
            })
            .map(|&((first, _), watchpoint)| (address.max(first), watchpoint))
    }
}

impl Machine {
    /// `cpu` with `memory`, neither mapped into the other yet, retiring `rate` instructions a
    /// second, `segments` put back in RAM at every reset, and booting from `boot`.
    fn new(
        memory: Memory,
        cpu: Box<dyn Processor>,
        rate: NonZeroU64,
        segments: Vec<Segment>,
        boot: u64,
    ) -> Self {
        Self {
            memory: Mapped::new(memory),
            page: cpu.page_size(),
            breakpoints: BTreeMap::new(),
            cpu: Some(cpu),
            queued: Vec::new(),
            rate,
            warped: 0,
            deadline: NO_DEADLINE,
            horizon: None,
            drain: None,
            segments,
            boot,
            restart: false,
            read_only_written: false,
            watching: Watching::default(),
            requested: false,
            errno: 0,
            rtt: None,
        }
    }

    /// The instruction the core is at.
    fn pc(&self) -> u64 {
        self.cpu.as_deref().expect("between stretches").pc()
    }

    /// Where the run stands.
    fn position(&self) -> Position {
        Position {
            count: self.retired(),
            at: self.now(),
        }
    }

    /// Maps the memory into the processor, which keeps pointers into it from then on.
    fn map_memory(&mut self) {
        let cpu = self
            .cpu
            .as_deref_mut()
            .expect("the processor between stretches");
        #[expect(
            unsafe_code,
            reason = "the processor keeps pointers into the machine's memory"
        )]
        // SAFETY: `Machine` declares its processor before its memory, so it drops it first.
        unsafe {
            self.memory.map_into(cpu);
        }
    }

    /// The processor, which is here whenever the runner, the models at a stop, or a debugger asks.
    fn cpu(&mut self) -> &mut dyn Processor {
        self.cpu
            .as_deref_mut()
            .expect("the processor between stretches")
    }

    /// Asks the processor for `queued`: now when it's between stretches, and before its next
    /// instruction when it's running one.
    fn ask(&mut self, queued: Queued) {
        match self.cpu.as_mut() {
            Some(cpu) => cpu.ask(queued),
            None => self.queued.push(queued),
        }
    }

    /// Asks the processor for a breakpoint at `address`, or takes one back, and answers whether it
    /// can stop there. One asked while it runs ends the stretch, so the processor gets it before
    /// its next instruction, and a refusal fails the run then.
    fn breakpoint(&mut self, address: u64, set: bool) -> bool {
        match self.cpu.as_mut() {
            Some(cpu) if set => cpu.add_breakpoint(address),
            Some(cpu) => {
                cpu.remove_breakpoint(address);
                true
            }
            None => {
                self.breakpoints.entry(address).or_insert(!set);
                self.ask(Queued::Return);
                true
            }
        }
    }

    /// Makes `change` to what's watched, then routes the pages it adds and unroutes the ones it
    /// leaves.
    fn rerouted(&mut self, change: impl FnOnce(&mut Watching)) {
        let routed = self.watching.pages(self.page);
        change(&mut self.watching);
        let still = self.watching.pages(self.page);
        for &page in still.difference(&routed) {
            self.ask(Queued::Route(page));
        }
        for &page in routed.difference(&still) {
            self.ask(Queued::Unroute(page));
        }
    }

    /// The virtual clock with `retired` instructions retired.
    fn time(&self, retired: u64) -> VirtualNanos {
        VirtualNanos(self.warped.saturating_add(nanos(self.rate, retired)))
    }

    /// Every instruction retired in the run, across resets.
    fn retired(&self) -> u64 {
        self.cpu.as_ref().expect("between stretches").retired()
    }

    fn now(&self) -> VirtualNanos {
        self.time(self.retired())
    }

    /// Starts the core where the run boots it.
    fn boot(&mut self) {
        let Self {
            memory, cpu, boot, ..
        } = self;
        cpu.as_mut()
            .expect("between stretches")
            .boot(*boot, &|address, width| memory.read(address, width));
    }

    /// The core's half of a reset: the processor and its space as a reset leaves them, RAM's
    /// images placed again, and the core back where it boots, with no instruction between.
    fn reset(&mut self) {
        self.cpu().reset();
        for segment in &self.segments {
            if self.memory.writable(segment.address) {
                self.memory.place(segment.address, &segment.bytes);
            }
        }
        self.boot();
        self.watching.arrived = None;
    }

    /// Drops whatever the core translated from the `length` bytes at `address`, which the core
    /// does at every address those bytes answer at.
    fn invalidate(&mut self, address: u64, length: u64) {
        self.ask(Queued::Invalidate(address, address + length));
    }

    /// Answers an access to memory the core maps, which reaches the runner when its page is
    /// routed, or when it's a store to memory the guest can't write, which is dropped as the bus
    /// drops it.
    fn mapped(&mut self, kind: AccessKind, address: u64, width: Width, value: u64) -> Option<u64> {
        match kind {
            AccessKind::Read => self.memory.read(address, width),
            AccessKind::Write if self.memory.read_only(address) => Some(value),
            AccessKind::Write => self.memory.write(address, width, value).then(|| {
                self.invalidate(address, u64::from(width.bytes()));
                value
            }),
        }
    }

    /// Whether the byte at `address` is memory the core maps.
    fn mapped_byte(&self, address: u64) -> bool {
        self.memory.read(address, Width::W8).is_some()
    }

    /// Sets or clears a debugger's `watchpoint` on `range`, and answers whether the core can
    /// watch it. One set again is the one already there, and past [`DEBUGGER_WATCHPOINTS`] there's
    /// no more.
    fn debugger_watch(&mut self, range: (u64, u64), watchpoint: Watchpoint, set: bool) -> bool {
        let each = (range, watchpoint);
        if !set {
            self.rerouted(|watching| watching.debugged.retain(|&other| other != each));
            return true;
        }
        if self.watching.debugged.contains(&each) {
            return true;
        }
        if self.watching.debugged.len() >= DEBUGGER_WATCHPOINTS {
            return false;
        }
        let ranges: Vec<(u64, u64)> = self
            .watching
            .debugged
            .iter()
            .map(|&(range, _)| range)
            .collect();
        if !fit(&ranges, range, DEBUGGER_ROUTED_BYTES, self.page) {
            return false;
        }
        self.rerouted(|watching| watching.debugged.push(each));
        true
    }

    /// Clears every watchpoint a debugger set.
    fn debugger_unwatch_all(&mut self) {
        self.rerouted(|watching| watching.debugged.clear());
        self.watching.debugger_hit = None;
    }

    /// The state a snapshot keeps of the core: the processor, the clock's warps, a reset a model
    /// asked for and the core hasn't made yet, the last arrival at a watched instruction, the
    /// error number host calls left, and where an ID search found the RTT block with how many bytes
    /// its terminal holds, which a drain at the end of the run takes.
    fn save(&mut self) -> Vec<u8> {
        let rtt = self.rtt.take();
        let terminal = rtt.as_ref().map(|rtt| (rtt.found(), rtt.waiting(self)));
        self.rtt = rtt;
        let saved = Saved {
            core: self.cpu().save(),
            warped: self.warped,
            restart: self.restart,
            arrived: self.watching.arrived,
            errno: self.errno,
            terminal,
        };
        postcard::to_allocvec(&saved).expect("the core's state serializes")
    }

    /// What `Core::next` would answer after an access, with `instructions` retired counting its own
    /// and the processor's own next event at `event`, when it would answer a stretch and do nothing
    /// else first: no reset, no watch hit to report, no event or deadline reached. It never runs
    /// past `until`, and it's `None` there, or with no `until` at all.
    fn carried(
        &self,
        instructions: u64,
        event: Option<VirtualNanos>,
        until: Option<u64>,
    ) -> Option<u32> {
        let left = until?.checked_sub(instructions).filter(|&left| left > 0)?;
        if self.restart || self.watching.written.is_some() || self.watching.debugger_hit.is_some() {
            return None;
        }
        let now = self.time(instructions);
        let target = self.earliest(event);
        if target <= now {
            return None;
        }
        let stretch = instructions_until(self.rate, self.warped, instructions, target);
        Some(stretch.min(u32::try_from(left).unwrap_or(u32::MAX)))
    }

    /// The next instant the core has to stop at, with the processor's own next event at `event`:
    /// the models' deadline, that event, the debugger's horizon, or the next drain of the RTT
    /// terminal, whichever comes first.
    fn earliest(&self, event: Option<VirtualNanos>) -> VirtualNanos {
        [event, self.horizon, self.drain]
            .into_iter()
            .flatten()
            .fold(self.deadline, VirtualNanos::min)
    }

    /// Puts back the core as [`Machine::save`] wrote it and then each of `memory`'s ranges,
    /// in order, dropping whatever the core translated from those bytes, since a core put back
    /// may have run and translated code from what was there. A range that fits no region is
    /// [`Error::State`].
    fn put_back(&mut self, state: &[u8], memory: &[(u64, &[u8])]) -> Result<(), Error> {
        self.load(state)?;
        for &(base, bytes) in memory {
            if !self.memory.place(base, bytes) {
                return Err(Error::State);
            }
            self.invalidate(base, bytes.len() as u64);
        }
        Ok(())
    }

    /// Puts back what [`Machine::save`] wrote. [`Machine::put_back`] is how a run does, with
    /// memory.
    fn load(&mut self, bytes: &[u8]) -> Result<(), Error> {
        let saved: Saved = match postcard::take_from_bytes(bytes) {
            Ok((saved, [])) => saved,
            Ok(_) | Err(_) => return Err(Error::State),
        };
        self.cpu().load(&saved.core)?;
        self.warped = saved.warped;
        self.restart = saved.restart;
        self.watching.arrived = saved.arrived;
        self.errno = saved.errno;
        if let (Some(rtt), Some((found, waiting))) = (self.rtt.as_mut(), saved.terminal) {
            rtt.put_back(found, waiting);
        }
        for page in self.watching.pages(self.page) {
            self.ask(Queued::Route(page));
        }
        Ok(())
    }
}

/// What [`Machine::save`] writes.
#[derive(serde::Serialize, serde::Deserialize)]
struct Saved {
    core: Vec<u8>,
    warped: u64,
    restart: bool,
    arrived: Option<(u64, u64)>,
    errno: u64,
    terminal: Option<(Option<u64>, u64)>,
}

impl GuestMemory for Machine {
    fn read(&mut self, address: u64, width: Width) -> Result<u64, Error> {
        self.memory
            .read(address, width)
            .ok_or(Error::Memory { address, width })
    }

    /// A model's write, which lands where the guest's would: memory the guest can't write refuses
    /// it, as it would a bus master's.
    fn write(&mut self, address: u64, width: Width, value: u64) -> Result<(), Error> {
        if self.memory.read_only(address) || !self.memory.write(address, width, value) {
            return Err(Error::Memory { address, width });
        }
        self.invalidate(address, u64::from(width.bytes()));
        Ok(())
    }

    fn endian(&self) -> Endian {
        self.memory.endian()
    }
}

impl Host for Machine {
    fn set_interrupt(&mut self, line: InterruptLine, level: Level) {
        self.ask(Queued::Line(line, level));
    }

    fn request_reset(&mut self) {
        self.restart = true;
        self.ask(Queued::Return);
    }

    /// The core's state, unless a debugger wrote memory the guest can't, which a snapshot keeps
    /// only as the images placed it.
    fn save_state(&mut self) -> Result<Vec<u8>, Error> {
        if self.read_only_written {
            return Err(Error::WroteReadOnly);
        }
        if self.cpu.is_none() {
            return Err(Error::State);
        }
        Ok(self.save())
    }

    fn watch(&mut self, watch: Watch) -> bool {
        match watch {
            Watch::Instruction(address) => {
                if self.watching.instructions.insert(address) && !self.breakpoint(address, true) {
                    self.watching.instructions.remove(&address);
                    return false;
                }
                true
            }
            Watch::Writes { address, length } => {
                let Some(range) = length
                    .checked_sub(1)
                    .and_then(|extent| address.checked_add(extent))
                    .map(|last| (address, last))
                    .filter(|&range| {
                        fit(&self.watching.writes, range, RUN_ROUTED_BYTES, self.page)
                    })
                else {
                    return false;
                };
                self.rerouted(|watching| watching.writes.push(range));
                true
            }
        }
    }

    fn unwatch(&mut self, watch: Watch) {
        match watch {
            Watch::Instruction(address) => {
                if self.watching.instructions.remove(&address) {
                    self.breakpoint(address, false);
                }
            }
            Watch::Writes { address, length } => {
                let range = (address, address.wrapping_add(length.wrapping_sub(1)));
                self.rerouted(|watching| {
                    if let Some(index) = watching.writes.iter().position(|&each| each == range) {
                        watching.writes.remove(index);
                    }
                });
            }
        }
    }
}

/// What a running processor's bus reaches: the run's memory and its models.
struct Served<'a> {
    machine: &'a mut Machine,
    driven: &'a mut dyn Driven,
    /// The instruction count the core may run on to after an access without the runner, or `None`
    /// when it comes back after every one: a step, or a watched instruction run on its own.
    carry_until: Option<u64>,
    /// The access the processor last asked [`CoreBus::stops_before`] about, which needs no look for
    /// a debugger's watchpoint once it's made.
    asked: Option<Access>,
    /// The instruction, by its address and count, whose access last reached a model rather than
    /// plain memory. No watchpoint stops it before a later access, since the instruction would run
    /// again from its start and the model would see that access twice.
    modeled: Option<(u64, u64)>,
    /// Where the processor's own trace goes.
    trace: Option<&'a mut Stream>,
}

impl CoreBus for Served<'_> {
    fn access(&mut self, access: Access, from_code: bool) -> Option<u64> {
        let asked = self.asked.take() == Some(access);
        let machine = &mut *self.machine;
        let mapped = machine.mapped(access.kind, access.address, access.width, access.value);
        let answer = if let Some(answer) = mapped {
            answer
        } else {
            if from_code {
                self.modeled = access
                    .program_counter
                    .map(|pc| (pc, access.instruction_count));
            }
            let (answer, next, failed) = self.driven.access(access, machine);
            machine.deadline = next;
            if failed {
                return None;
            }
            answer
        };
        if from_code {
            // An access the processor makes on its own, entering an exception say, is no
            // instruction's.
            let watching = &mut machine.watching;
            watching.accessed(access.kind, access.address, access.width);
            // A processor that never asks before an access still stops right after the
            // instruction that made it.
            if !asked && let Some(hit) = watching.hit(&access) {
                watching.debugger_hit.get_or_insert(hit);
            }
        }
        Some(answer)
    }

    fn time(&self, instructions: u64) -> VirtualNanos {
        self.machine.time(instructions)
    }

    fn queued(&mut self) -> Vec<Queued> {
        std::mem::take(&mut self.machine.queued)
    }

    fn carry_on(&mut self, instructions: u64, event: Option<VirtualNanos>) -> Option<u32> {
        self.machine.carried(instructions, event, self.carry_until)
    }

    fn stops_before(&mut self, access: &Access) -> bool {
        self.asked = Some(*access);
        let watching = &mut self.machine.watching;
        let Some(hit) = watching.hit(access) else {
            return false;
        };
        let at = access
            .program_counter
            .map(|pc| (pc, access.instruction_count));
        if at.is_some() && self.modeled == at {
            // The instruction finishes and the core stops right after it.
            watching.debugger_hit.get_or_insert(hit);
            return false;
        }
        // The instruction runs again from its start and notes its own store again then.
        watching.written = None;
        watching.debugger_hit = Some(hit);
        true
    }

    fn send_trace(&mut self, bytes: &[u8]) {
        if let Some(stream) = self.trace.as_deref_mut() {
            stream.send(bytes);
        }
    }
}

/// What the core runs next.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
enum Stretch {
    /// At most this many instructions.
    Run(u32),
    /// The watched instruction at this address, which the core has arrived at and reported, with
    /// its breakpoint lifted.
    Over(u64),
}

impl Core {
    /// The models' stop at the instant the run reached. Answers whether the run goes on.
    fn stop(&mut self, reason: StopReason) -> bool {
        let stop = Stop {
            at: self.machine.now(),
            instruction_count: self.machine.retired(),
            reason,
        };
        match self.driven.stop(stop, &mut self.machine) {
            Some(next) => {
                self.machine.deadline = next;
                true
            }
            None => false,
        }
    }

    /// A debugger's reset: the models hear it as they hear the firmware's own request, then the
    /// core restarts where it boots. A reset is never where a run was asked to reach, so the
    /// run goes on.
    fn debugger_reset(&mut self) {
        let goes_on = self.stop(StopReason::Reset);
        debug_assert!(goes_on, "a run ended at a reset");
        self.machine.reset();
    }

    /// Hands the models a hit on something the run watches, at the instant the run reached.
    fn hit(&mut self, kind: HitKind, address: u64) {
        let count = self.machine.retired();
        let hit = Hit {
            kind,
            address,
            at: self.machine.time(count),
            instruction_count: count,
        };
        self.machine.deadline = self.driven.hit(hit, &mut self.machine);
    }

    /// What the core does next: a stop, the processor's own event, a warp, or a stretch of
    /// instructions. Answers the stretch to run, or `None` once the run is over.
    fn next(&mut self) -> Option<Stretch> {
        loop {
            if std::mem::take(&mut self.machine.restart) {
                self.machine.reset();
            }
            if std::mem::take(&mut self.machine.requested)
                || self.machine.cpu().take_reset_request()
            {
                // The firmware's own request: the models hear it as a stop, then the core restarts.
                if !self.stop(StopReason::Reset) {
                    return None;
                }
                self.machine.reset();
                continue;
            }
            let now = self.machine.now();
            if let Some(event) = self.machine.cpu().next_event()
                && event <= now
            {
                self.machine.cpu().on_event(now);
                continue;
            }
            if now >= self.machine.deadline {
                let reason = if self.machine.cpu().waiting() {
                    StopReason::Idle
                } else {
                    StopReason::Deadline
                };
                if !self.stop(reason) {
                    return None;
                }
                continue;
            }
            if !self.machine.watching.instructions.is_empty() {
                let pc = self.machine.cpu().pc();
                let watching = &self.machine.watching;
                if watching.arrived == Some((pc, self.machine.retired()))
                    && watching.instructions.contains(&pc)
                {
                    return Some(Stretch::Over(pc));
                }
            }
            let target = self.target();
            let machine = &self.machine;
            return Some(Stretch::Run(instructions_until(
                machine.rate,
                machine.warped,
                machine.retired(),
                target,
            )));
        }
    }

    /// The next instant anything happens: the models' deadline, the processor's own event, or
    /// where a debugger has the core stop.
    fn target(&mut self) -> VirtualNanos {
        let event = self.machine.cpu().next_event();
        self.machine.earliest(event)
    }

    /// Runs the processor for at most `instructions`, with the run's memory and models as its bus.
    fn execute(&mut self, instructions: u32, carry_until: Option<u64>) -> (Exit, u64) {
        let mut cpu = self.machine.cpu.take().expect("between stretches");
        let ran = cpu.run(
            instructions,
            &mut Served {
                machine: &mut self.machine,
                driven: &mut *self.driven,
                carry_until,
                asked: None,
                modeled: None,
                trace: self.trace.as_mut(),
            },
        );
        self.machine.cpu = Some(cpu);
        let queued = std::mem::take(&mut self.machine.queued);
        for queued in queued {
            self.machine.ask(queued);
        }
        for (address, had) in std::mem::take(&mut self.machine.breakpoints) {
            let wanted = self.machine.watching.instructions.contains(&address);
            if wanted != had && !self.machine.breakpoint(address, wanted) {
                self.machine.watching.instructions.remove(&address);
                self.driven.unwatched(Watch::Instruction(address));
            }
        }
        ran
    }

    /// Runs `stretch`, and answers why it ended and how many instructions it ran.
    /// The core carries on after an access by itself up to `carry_until`.
    fn run_stretch(&mut self, stretch: Stretch, carry_until: Option<u64>) -> (Exit, u64) {
        let ran = match stretch {
            Stretch::Run(instructions) => self.execute(instructions, carry_until),
            Stretch::Over(address) => {
                self.machine.cpu().pass_breakpoint(address);
                self.execute(1, None)
            }
        };
        self.machine.requested |= self.machine.cpu().take_reset_request();
        ran
    }

    /// The run where it stands, or why it can't be kept: a reset pending at this instant, or a
    /// model or a chip that can't be kept.
    fn checkpoint(&mut self) -> Result<Checkpoint, snapshot::Error> {
        // A debugger's write between stretches asks for one too.
        self.machine.requested |= self.machine.cpu().take_reset_request();
        if self.machine.restart || self.machine.requested {
            return Err(snapshot::Error::Resetting);
        }
        let run = self.driven.keep()?;
        let sent = |stream: Option<&Stream>| stream.map_or(0, Stream::sent);
        Ok(Checkpoint {
            position: self.machine.position(),
            machine: self.machine.save(),
            drain: self.machine.drain,
            memory: self.machine.memory.contents(self.machine.read_only_written),
            run,
            sent: (sent(self.trace.as_ref()), sent(self.terminal.as_ref())),
        })
    }

    /// Puts the run back to `checkpoint`, in place. The run's own watches come out first, and go
    /// back in as the session had them. Memory the guest can't write that the checkpoint didn't
    /// keep is as the images placed it, since only a debugger writes it. A debugger's halt point
    /// goes, and the deadline is asked for again. A reset asked for and not yet carried out goes,
    /// since a checkpoint is never taken with one.
    fn restore(&mut self, checkpoint: &Checkpoint) -> Result<(), String> {
        let machine = &mut self.machine;
        machine.cpu().take_reset_request();
        for address in std::mem::take(&mut machine.watching.instructions) {
            machine.breakpoint(address, false);
        }
        machine.rerouted(|watching| watching.writes.clear());
        // Memory the guest can't write and the checkpoint didn't keep is as the images placed it.
        let kept_read_only = checkpoint
            .memory
            .iter()
            .any(|&(base, _)| machine.memory.read_only(base));
        let mut memory: Vec<(u64, Vec<u8>)> = Vec::new();
        if machine.read_only_written && !kept_read_only {
            memory = machine.memory.erased_read_only();
            for segment in &machine.segments {
                if machine.memory.read_only(segment.address) {
                    memory.push((segment.address, segment.bytes.clone()));
                }
            }
        }
        let ranges: Vec<(u64, &[u8])> = memory
            .iter()
            .chain(&checkpoint.memory)
            .map(|(base, bytes)| (*base, bytes.as_slice()))
            .collect();
        machine
            .put_back(&checkpoint.machine, &ranges)
            .map_err(|error| error.to_string())?;
        machine.drain = checkpoint.drain;
        machine.horizon = None;
        machine.requested = false;
        machine.restart = false;
        let watching = &mut machine.watching;
        watching.passing = None;
        watching.debugger_hit = None;
        watching.written = None;
        // A checkpoint is this run's own, whose terminal knows what it sent, so nothing's left out.
        if let Some(rtt) = self.machine.rtt.as_mut() {
            rtt.put_back(rtt.found(), 0);
        }
        if let Some(trace) = self.trace.as_mut() {
            trace.went_back(checkpoint.sent.0);
        }
        if let Some(terminal) = self.terminal.as_mut() {
            terminal.went_back(checkpoint.sent.1);
        }
        self.driven
            .put_back(&checkpoint.run, &mut self.machine)
            .map_err(|error| error.to_string())?;
        self.machine.deadline = self.driven.first_deadline();
        Ok(())
    }

    /// The run goes a new way from where it stands, so the driver and the ports hear everything
    /// from here on.
    fn new_way(&mut self) {
        self.driven.new_way(self.machine.now());
        if let Some(trace) = self.trace.as_mut() {
            trace.new_way();
        }
        if let Some(terminal) = self.terminal.as_mut() {
            terminal.new_way();
        }
    }

    /// Answers the host call the core stopped at, when the run serves them, through `debugger` when
    /// one waits on the core and the call is the debugger's host's.
    fn host_call(&mut self, mut debugger: Option<&mut Debugger<'_>>) -> Answered {
        let machine = &self.machine;
        let call = self.semihosting.then(|| {
            let cpu = machine.cpu.as_deref().expect("between stretches");
            cpu.host_call(&mut |address, width| machine.memory.read(address, width))
        });
        let answer = match call {
            None => {
                self.machine.cpu().answer_host_call(None);
                return Answered::Unserved;
            }
            Some(Some(HostCall::Exit { code })) => return Answered::Exited(code),
            Some(Some(call)) => self.serve(call, debugger.as_deref_mut()),
            Some(None) => HOST_CALL_FAILED,
        };
        self.machine.cpu().answer_host_call(Some(answer));
        if let Some(debugger) = debugger {
            debugger.after_file_call(self);
        }
        Answered::Served
    }

    /// The answer to `call`: the console's to the driver and to GDB, the clock's from virtual time,
    /// and a file's from the debugger's host, or [`failed`]'s with no debugger, since a firmware
    /// never reaches the emulator's own files.
    fn serve(&mut self, call: HostCall, debugger: Option<&mut Debugger<'_>>) -> u64 {
        let now = self.machine.now();
        match call {
            HostCall::Write {
                handle: 1 | 2,
                address,
                length,
            } => {
                let memory = &self.machine.memory;
                let bytes: Vec<u8> = (address..address.saturating_add(length))
                    .map_while(|at| memory.read(at, Width::W8))
                    .map(|byte| u8::try_from(byte).expect("a byte"))
                    .collect();
                let news = self.driven.console(now, self.machine.retired(), &bytes);
                if news && let Some(debugger) = debugger {
                    debugger.console(self, &bytes);
                }
                length - bytes.len() as u64
            }
            HostCall::OpenConsole { handle } => handle,
            HostCall::IsTty { handle: 0..=2 } => 1,
            HostCall::Clock => now.0 / CLOCK_TICK,
            HostCall::Time => now.0 / TICKS_PER_SECOND,
            HostCall::Elapsed { block } => self.elapsed(block, now.0),
            HostCall::TickFrequency => TICKS_PER_SECOND,
            HostCall::Errno => self.machine.errno,
            call => {
                debugger.map_or_else(|| failed(call), |debugger| self.file_call(debugger, call))
            }
        }
    }

    /// Writes `ticks` into the firmware's block at `block`, as a debugger's write to memory lands,
    /// so the core's translated code sees it, and answers 0, or -1 when the block isn't memory the
    /// firmware can write. The block is two words with the low one first where the family's
    /// pointers are 32 bits, and one word of 64 where they're wider.
    fn elapsed(&mut self, block: u64, ticks: u64) -> u64 {
        let cpu = self.machine.cpu();
        let order = cpu.byte_order(block);
        let bytes = if cpu.data_model().pointer() == Width::W32 {
            let mut words = to_target(ticks & u64::from(u32::MAX), 4, order)[..4].to_vec();
            words.extend_from_slice(&to_target(ticks >> 32, 4, order)[..4]);
            words
        } else {
            to_target(ticks, 8, order).to_vec()
        };
        if self.machine.memory.read_only(block) || !self.machine.memory.place(block, &bytes) {
            return HOST_CALL_FAILED;
        }
        self.machine.invalidate(block, 8);
        0
    }

    /// A file call made on the debugger's host, "Debugging with GDB" for GDB 18.1, section E.14,
    /// answered as the firmware's call answers: bytes not read or written for a read or a write, 0
    /// for a seek that went, and the debugger's answer otherwise, or [`failed`]'s when the call
    /// failed.
    fn file_call(&mut self, debugger: &mut Debugger<'_>, call: HostCall) -> u64 {
        let mut ask = |core: &mut Self, request: String| {
            let Fresult { result, errno } = debugger.file_call(core, &request)?;
            if result < 0
                && let Some(errno) = errno
            {
                core.machine.errno = errno;
            }
            u64::try_from(result).ok()
        };
        let answered = match call {
            HostCall::Open { path, length, mode } => ask(
                self,
                format!(
                    "Fopen,{path:x}/{:x},{:x},{FILE_MODE:x}",
                    length + 1,
                    open_flags(mode)
                ),
            ),
            HostCall::Close { handle } => ask(self, format!("Fclose,{handle:x}")),
            HostCall::Read {
                handle,
                address,
                length,
            } => ask(self, format!("Fread,{handle:x},{address:x},{length:x}"))
                .map(|read| length.saturating_sub(read)),
            HostCall::Write {
                handle,
                address,
                length,
            } => ask(self, format!("Fwrite,{handle:x},{address:x},{length:x}"))
                .map(|written| length.saturating_sub(written)),
            HostCall::Seek { handle, position } => {
                ask(self, format!("Flseek,{handle:x},{position:x},{SEEK_SET:x}")).map(|_| 0)
            }
            // A length is where the end is, which the file is moved to and moved back from.
            HostCall::Length { handle } => ask(self, format!("Flseek,{handle:x},0,{SEEK_CUR:x}"))
                .and_then(|position| {
                    let end = ask(self, format!("Flseek,{handle:x},0,{SEEK_END:x}"))?;
                    ask(self, format!("Flseek,{handle:x},{position:x},{SEEK_SET:x}"))?;
                    Some(end)
                }),
            HostCall::IsTty { handle } => ask(self, format!("Fisatty,{handle:x}")),
            _ => None,
        };
        answered.unwrap_or_else(|| failed(call))
    }

    /// The run is over: each output port's client gets what's left for it, the RTT terminal
    /// drained once more.
    fn finish_ports(&mut self) {
        if let Some(trace) = self.trace.take() {
            trace.finish();
        }
        self.drain_rtt(true);
        if let Some(terminal) = self.terminal.take() {
            terminal.finish();
        }
    }

    /// Drains the firmware's RTT terminal to its port once the run reaches the drain's instant,
    /// or `now`, and has the next drain at the next whole period.
    fn drain_rtt(&mut self, now: bool) {
        let Some(terminal) = self.terminal.as_mut() else {
            return;
        };
        let machine = &mut self.machine;
        let at = machine.now();
        if now || machine.drain.is_some_and(|drain| at >= drain) {
            if let Some(mut rtt) = machine.rtt.take() {
                terminal.send(&rtt.drain(machine));
                machine.rtt = Some(rtt);
            }
            machine.drain = Some(rtt::next_drain(at));
        }
        terminal.flush();
    }

    /// The core returned from a stretch with `exit`, having run `ran` instructions.
    fn after(&mut self, exit: Exit, ran: u64) {
        if let Some(address) = self.machine.watching.written.take() {
            self.hit(HitKind::Write, address);
        }
        if exit == Exit::Breakpoint {
            let arrival = (self.machine.cpu().pc(), self.machine.retired());
            let watching = &mut self.machine.watching;
            if watching.instructions.contains(&arrival.0) && watching.arrived != Some(arrival) {
                watching.arrived = Some(arrival);
                self.hit(HitKind::Instruction, arrival.0);
            }
            return;
        }
        let halted = matches!(exit, Exit::Waiting | Exit::Lockup) && ran == 0;
        if halted || (self.machine.cpu().waiting() && ran == 0) {
            // Waiting with nothing to wake it before the next instant anything happens: the clock
            // goes straight there.
            let now = self.machine.now();
            let target = self.target();
            if target > now && target != NO_DEADLINE {
                self.machine.warped += target.0 - now.0;
            }
        }
    }
}

/// Runs `session`'s target on the core its [`CoreSpec`](super::CoreSpec) makes,
/// driven by `driver`, and hands back what the run left.
///
/// The core runs on a thread of its own, which ends with the run, so a process runs as many as it
/// likes. A run that resumes from a snapshot puts the core's state and memory back before its first
/// instruction.
///
/// # Panics
///
/// Panics when the system has no thread to give the core, or when a run resumed from a snapshot
/// reaches its first stop anywhere but where the snapshot was taken, which is the core not running
/// the run it was given.
#[expect(
    clippy::disallowed_methods,
    reason = "the core's own thread, the only one a run has, joined before this returns"
)]
pub fn run<D, R>(session: Session<D>, start: &Start<'_>, driver: R) -> Result<Finished<D, R>, Error>
where
    D: Board + ?Sized + 'static,
    R: Driver<D> + 'static,
{
    let mut session = session;
    let (spec, map, peripherals, segments, endian) = {
        let target = session.target();
        let mut targets = session.board_mut().targets();
        let chosen = targets.swap_remove(target);
        let map = chosen.mcu.bus().memory().to_vec();
        // The part's byte order, which the core, its memory, its debugger and its snapshots keep.
        let endian = chosen.mcu.cpu().endian;
        let segments = image::place(start.images, &map, &chosen.core, endian, start.boot)?;
        let peripherals: Vec<_> = chosen
            .mcu
            .bus()
            .peripherals()
            .map(|peripheral| peripheral.base..peripheral.base + peripheral.size)
            .collect();
        (chosen.core, map, peripherals, segments, endian)
    };
    let cpu = (spec.processor)(endian)?;
    let model = cpu.data_model();
    // What a debugger is told of the memory, which only the processor and the part know together.
    let memory_map = start
        .debugger
        .map(|_| Map::new(&map, &spec.aliases, &peripherals, &cpu.own_ranges()));
    let page = cpu.page_size();
    if !page.is_power_of_two() || page > PAGE_ALIGNMENT as u64 {
        return Err(Error::Machine(format!(
            "the core asks for pages of {page:#x} bytes, and a page has to be a power of two no larger than {PAGE_ALIGNMENT:#x}"
        )));
    }
    let memory = Memory::new(&map, &spec.aliases, endian);
    if let Some(mapping) = memory.partial_page(page) {
        return Err(Error::Machine(format!(
            "the core maps memory in pages of {page:#x} bytes, and the {:#x} bytes at {:#x} aren't whole pages",
            mapping.length, mapping.start
        )));
    }
    if let Some(mapping) = memory
        .mappings()
        .into_iter()
        .find(|mapping| !cpu.maps(mapping.start, mapping.length))
    {
        return Err(Error::Machine(format!(
            "the core can't hold the {:#x} bytes of memory at {:#x}, outside its addresses or over ones it answers itself",
            mapping.length, mapping.start
        )));
    }
    let resume = start.resume;
    let driven: Box<dyn Driven> =
        Box::new(Run::new(session, driver, resume.map(|resume| resume.stop)));
    let mut machine = Machine::new(
        memory,
        cpu,
        spec.instructions_per_second,
        segments,
        start.boot.unwrap_or(spec.boot.reset),
    );
    let debugger = start
        .debugger
        .zip(memory_map)
        .map(|(listener, map)| {
            Debugger::listen(
                listener,
                start.wait_for_debugger,
                map,
                start.kernels,
                start.interrupt,
            )
        })
        .transpose()?;
    let trace = start.trace.map(Stream::listen).transpose()?;
    let (rtt, terminal) = start
        .rtt
        .map(|listener| terminal(start, &map, (model.pointer(), spec.code_address), listener))
        .transpose()?
        .unzip();
    // A firmware whose symbols say it has no block has nothing to drain, so its stretches aren't
    // cut for it.
    machine.drain = rtt
        .as_ref()
        .filter(|rtt| !rtt.has_none())
        .map(|_| VirtualNanos(rtt::PERIOD));
    machine.rtt = rtt;
    let (left, exit_status, interrupted) = std::thread::scope(|scope| {
        std::thread::Builder::new()
            .name("core".into())
            .stack_size(CORE_STACK)
            .spawn_scoped(scope, move || {
                run_core(
                    Core {
                        driven,
                        machine,
                        semihosting: start.semihosting,
                        trace,
                        terminal,
                    },
                    resume,
                    debugger,
                    start.interrupt,
                )
            })
            .expect("a thread for the core")
            .join()
            .unwrap_or_else(|panic| std::panic::resume_unwind(panic))
    })?;
    let run = left
        .downcast::<Run<D, R>>()
        .unwrap_or_else(|_| unreachable!("the run that was prepared"));
    let Run {
        session,
        driver,
        last,
        ..
    } = *run;
    Ok(Finished {
        session,
        driver,
        stop: last,
        exit_status,
        interrupted,
    })
}

/// What `call` answers when it fails: a read or a write that fails answers its length, every byte
/// not read or not written, and anything else -1.
fn failed(call: HostCall) -> u64 {
    match call {
        HostCall::Read { length, .. } | HostCall::Write { length, .. } => length,
        _ => HOST_CALL_FAILED,
    }
}

/// What drains the firmware's RTT terminal to `listener`: the block where the firmware's symbols
/// say, or nowhere when they don't, or looked for in the RAM `map` gives when it has none, laid out
/// with pointers `pointer` wide, the symbols read with the family's `code_address`.
fn terminal(
    start: &Start<'_>,
    map: &[Region],
    (pointer, code_address): (Width, fn(u64) -> u64),
    listener: &TcpListener,
) -> Result<(Rtt, Stream), Error> {
    let ram = map
        .iter()
        .filter(|region| region.kind == RegionKind::Ram)
        .map(|region| region.base..region.base + region.size)
        .collect();
    let symbols = start
        .images
        .first()
        .and_then(|image| Symbols::read(image.bytes(), code_address).ok());
    let symbol = symbols
        .as_ref()
        .and_then(|symbols| symbols.get(rtt::SYMBOL).ok());
    let has_symbols = symbols.as_ref().is_some_and(Symbols::any);
    Ok((
        Rtt::new(symbol, has_symbols, ram, pointer),
        Stream::listen(listener)?,
    ))
}

/// What a run on the core's thread leaves: the run, the status the firmware ended it with, and where
/// it stood when its interrupt ended it.
type Left = (Box<dyn Any + Send>, Option<u32>, Option<Interrupted>);

/// The whole of a run on the core's thread: map and place, boot or resume, and run until the
/// driver, the firmware or `interrupt` ends it, serving the debugger, host calls and output ports
/// between stretches.
fn run_core(
    mut core: Core,
    resume: Option<&Resume<'_>>,
    mut debugger: Option<Debugger<'_>>,
    interrupt: Option<&AtomicBool>,
) -> Result<Left, Error> {
    let machine = &mut core.machine;
    machine.map_memory();
    for segment in &machine.segments {
        let placed = machine.memory.place(segment.address, &segment.bytes);
        assert!(placed, "image::place keeps every segment inside memory");
    }
    machine.boot();
    if let Some(resume) = resume {
        // A snapshot's memory that fits no region isn't the run it was saved from.
        machine.put_back(resume.state, &resume.memory)?;
        // A state saved at another stop than the snapshot's is another run's.
        if machine.now() != resume.stop.at || machine.retired() != resume.stop.instruction_count {
            return Err(Error::State);
        }
        // The run that never stopped drained last on the period at or before the stop, before
        // the stop was taken.
        if machine.drain.is_some() {
            machine.drain = Some(rtt::next_drain(machine.now()));
        }
    }
    core.machine.deadline = core.driven.first_deadline();
    let mut interrupted = None;
    loop {
        if let Some(debugger) = debugger.as_mut() {
            debugger.serve(&mut core);
        }
        let Some(stretch) = core.next() else {
            break;
        };
        // Every stop due where the core stands is taken, and the next instruction hasn't run.
        if interrupt.is_some_and(|flag| flag.load(Ordering::Relaxed)) {
            interrupted = Some(Interrupted {
                at: core.machine.now(),
                instruction_count: core.machine.retired(),
            });
            break;
        }
        let (stretch, carry_until) = match debugger.as_mut() {
            Some(debugger) => {
                debugger.hold_interrupts(&mut core);
                (debugger.limit(&core, stretch), debugger.carry_until(&core))
            }
            None => (stretch, Some(u64::MAX)),
        };
        let (exit, ran) = core.run_stretch(stretch, carry_until);
        let (exit, ran) = if exit == Exit::HostCall {
            match core.host_call(debugger.as_mut()) {
                Answered::Served => (exit, ran),
                // What the instruction does without a host to serve it, with nothing else run,
                // so the stretch ends as it would have.
                Answered::Unserved => {
                    let (exit, more) = core.run_stretch(Stretch::Run(0), carry_until);
                    (exit, ran + more)
                }
                Answered::Exited(code) => {
                    core.after(exit, ran);
                    if let Some(debugger) = debugger {
                        debugger.ended(code);
                    }
                    core.finish_ports();
                    return Ok((core.driven.into_any(), Some(code), None));
                }
            }
        } else {
            (exit, ran)
        };
        core.after(exit, ran);
        if let Some(trace) = core.trace.as_mut() {
            trace.flush();
        }
        core.drain_rtt(false);
        if let Some(debugger) = debugger.as_mut() {
            // The stops due where the core stands, which `Core::next` takes before the next
            // instruction anyway, come before the debugger hears it stopped and peeks, so it sees
            // every model settled at that instant. One that ends the run, it hears as the end.
            if core.next().is_none() {
                break;
            }
            debugger.after(&mut core, exit, ran);
        }
    }
    if let Some(debugger) = debugger {
        debugger.exited();
    }
    core.finish_ports();
    Ok((core.driven.into_any(), None, interrupted))
}

#[cfg(test)]
mod tests {
    use super::*;

    /// At 250 million instructions a second the clock is the four nanoseconds an instruction every
    /// target has always run at, so no instant moves.
    #[test]
    fn a_rate_of_four_nanoseconds_is_the_clock_targets_always_ran_on() {
        let rate = NonZeroU64::new(250_000_000).unwrap();
        for retired in [0, 1, 7, 1_000_003, u64::from(u32::MAX) * 3] {
            assert_eq!(nanos(rate, retired), retired * 4);
            for (warped, ahead) in [(0, 1), (0, 4), (6, 5), (1_000, 4_000_001)] {
                let now = warped + retired * 4;
                let target = VirtualNanos(now + ahead);
                let old = ahead.div_ceil(4).clamp(1, LONGEST_STRETCH);
                assert_eq!(
                    u64::from(instructions_until(rate, warped, retired, target)),
                    old,
                    "{retired} retired, {warped} warped, {ahead} ahead"
                );
            }
        }
    }

    /// At a rate that isn't a whole number of nanoseconds an instruction the clock rounds each
    /// instant down, and a stretch ends at the first instruction at or past its target.
    #[test]
    fn a_stretch_ends_at_the_first_instruction_at_or_past_its_target() {
        let rate = NonZeroU64::new(168_000_000).unwrap();
        assert_eq!(nanos(rate, 1), 5);
        assert_eq!(nanos(rate, 168), 1_000);
        assert_eq!(instructions_until(rate, 0, 0, VirtualNanos(1_000)), 168);
        assert_eq!(instructions_until(rate, 0, 0, VirtualNanos(1_001)), 169);
        for target in 1..3_000 {
            let n = u64::from(instructions_until(rate, 0, 0, VirtualNanos(target)));
            assert!(nanos(rate, n) >= target, "{n} reaches {target}");
            assert!(nanos(rate, n - 1) < target, "{} doesn't", n - 1);
        }
        assert_eq!(
            instructions_until(rate, 0, 500, VirtualNanos(10)),
            1,
            "past it already"
        );
    }

    /// A range fits while its pages and those already routed are within the limit, and one that
    /// spans more pages than the limit is refused before they're counted.
    #[test]
    fn a_range_fits_while_its_pages_and_those_already_routed_are_within_the_limit() {
        let page = 0x400;
        let four = 4 * page;
        assert!(fit(&[], (0, page * 4 - 1), four, page));
        assert!(!fit(&[], (0, page * 4), four, page), "a fifth page");
        assert!(
            fit(&[(0, page - 1)], (0, page * 3), four, page),
            "a page both touch counts once"
        );
        assert!(
            !fit(&[(0, page - 1)], (page * 10, page * 13), four, page),
            "four more on top of one"
        );
        assert!(
            !fit(&[], (0, u64::MAX), four, page),
            "the whole address space"
        );
        assert!(
            fit(&[], (0, 0x3FF), four, 1),
            "a kibibyte of byte-sized pages fits the same bytes"
        );
    }

    /// The run's own watches keep the budget they've always had, so a fault trigger's watch fits as
    /// it did, while a debugger's take a quarter mebibyte at once and far more.
    #[test]
    fn the_runs_own_watches_keep_their_budget() {
        let page = 0x400;
        assert_eq!(RUN_ROUTED_BYTES, 960 << 10);
        assert!(fit(&[], (0, RUN_ROUTED_BYTES - 1), RUN_ROUTED_BYTES, page));
        assert!(
            !fit(&[], (0, RUN_ROUTED_BYTES), RUN_ROUTED_BYTES, page),
            "a page more"
        );
        let quarter = (0x2000_0000, 0x2003_FFFF);
        assert!(!fit(&[], quarter, 64 << 10, page), "the old budget");
        assert!(fit(&[], quarter, DEBUGGER_ROUTED_BYTES, page));
    }

    /// A part's memory of any whole number of kibibytes is whole pages the core maps, so a run
    /// accepts SRAM of 2, 6 or 10 KiB.
    #[test]
    fn memory_of_whole_kibibytes_is_whole_pages() {
        const KIB: u64 = 1024;
        for size in [2 * KIB, 6 * KIB, 10 * KIB] {
            let memory = Memory::new(
                &[Region::ram("sram", 0x2000_0000, size)],
                &[],
                Endian::Little,
            );
            assert_eq!(
                memory.partial_page(crate::emulator::core::PAGE_SIZE),
                None,
                "{size:#x}"
            );
        }
    }

    /// A machine at 250 million instructions a second, with nothing mapped, no processor, and the
    /// models' next deadline at `deadline`.
    fn machine(deadline: VirtualNanos) -> Machine {
        Machine {
            cpu: None,
            memory: Mapped::new(Memory::new(&[], &[], Endian::Little)),
            queued: Vec::new(),
            rate: NonZeroU64::new(250_000_000).unwrap(),
            page: 1,
            breakpoints: BTreeMap::new(),
            warped: 0,
            deadline,
            horizon: None,
            drain: None,
            segments: Vec::new(),
            boot: 0,
            restart: false,
            read_only_written: false,
            watching: Watching::default(),
            requested: false,
            errno: 0,
            rtt: None,
        }
    }

    /// After an access the core carries on toward the next deadline or event, as `Core::next` would
    /// send it, but never past the count the debugger needs it back at or the instant it halts it
    /// at, and not at all for a step. With no debugger it's the deadline alone.
    #[test]
    fn carry_never_runs_past_where_the_debugger_needs_the_core() {
        let mut machine = machine(VirtualNanos(4_000));
        assert_eq!(machine.carried(100, None, Some(u64::MAX)), Some(900));
        assert_eq!(
            machine.carried(100, Some(VirtualNanos(800)), Some(u64::MAX)),
            Some(100),
            "the processor's own event first"
        );
        assert_eq!(machine.carried(100, None, Some(150)), Some(50));
        assert_eq!(machine.carried(150, None, Some(150)), None, "there");
        assert_eq!(machine.carried(151, None, Some(150)), None, "past it");
        assert_eq!(machine.carried(100, None, None), None, "a step");
        assert_eq!(
            machine.carried(1_000, None, Some(u64::MAX)),
            None,
            "at the deadline"
        );
        machine.horizon = Some(VirtualNanos(2_000));
        assert_eq!(machine.carried(100, None, Some(u64::MAX)), Some(400));
    }

    /// An instruction's access of a word at `address`, at `pc` with `count` instructions retired
    /// counting its own.
    fn access(kind: AccessKind, address: u64, pc: u64, count: u64) -> Access {
        Access {
            kind,
            address,
            width: Width::W32,
            value: 0,
            instruction_count: count,
            virtual_time: VirtualNanos(count * 4),
            program_counter: Some(pc),
        }
    }

    /// A debugger's watchpoint is hit by what it watches for: a write one by a store, a read one by
    /// a load, and an access one by either, at the first byte of the access inside it. The
    /// instruction the debugger lets run on from a watch stop gets past it, and the same
    /// instruction the next time round doesn't.
    #[test]
    fn a_debugger_watchpoint_is_hit_by_what_it_watches_for() {
        let hit = |watchpoint, kind, address| {
            let watching = Watching {
                debugged: vec![((0x2000_0010, 0x2000_0013), watchpoint)],
                ..Watching::default()
            };
            watching.hit(&access(kind, address, 0x100, 7))
        };
        let (read, write) = (AccessKind::Read, AccessKind::Write);
        assert_eq!(
            hit(Watchpoint::Write, write, 0x2000_0010),
            Some((0x2000_0010, Watchpoint::Write))
        );
        assert_eq!(hit(Watchpoint::Write, read, 0x2000_0010), None);
        assert_eq!(
            hit(Watchpoint::Read, read, 0x2000_000E),
            Some((0x2000_0010, Watchpoint::Read))
        );
        assert_eq!(hit(Watchpoint::Read, write, 0x2000_0010), None);
        for kind in [read, write] {
            assert_eq!(
                hit(Watchpoint::Access, kind, 0x2000_0012),
                Some((0x2000_0012, Watchpoint::Access))
            );
        }
        assert_eq!(hit(Watchpoint::Access, read, 0x2000_0014), None, "past it");
        let watching = Watching {
            debugged: vec![((0x2000_0010, 0x2000_0013), Watchpoint::Access)],
            passing: Some((0x100, 7)),
            ..Watching::default()
        };
        assert_eq!(watching.hit(&access(read, 0x2000_0010, 0x100, 7)), None);
        assert!(watching.hit(&access(read, 0x2000_0010, 0x100, 9)).is_some());
    }

    /// A watchpoint set again is the one already there, so it takes no more room and one clear
    /// takes it out.
    #[test]
    fn a_debuggers_watchpoint_set_again_is_the_one_there() {
        let mut machine = machine(VirtualNanos(4_000));
        let word = (0x2000_0000, 0x2000_0003);
        for _ in 0..3 {
            assert!(machine.debugger_watch(word, Watchpoint::Write, true));
        }
        assert_eq!(machine.watching.debugged.len(), 1);
        assert!(machine.debugger_watch(word, Watchpoint::Write, false));
        assert!(machine.watching.debugged.is_empty());
    }

    /// An instruction's first store into a watched range is the one noted, at the first byte of it
    /// inside the range, and a store that misses every range notes nothing.
    #[test]
    fn the_first_store_into_a_watched_range_is_noted_at_its_first_byte_inside() {
        let mut watching = Watching {
            writes: vec![(0x2000_0010, 0x2000_001F)],
            ..Watching::default()
        };
        watching.accessed(AccessKind::Write, 0x2000_0000, Width::W32);
        assert_eq!(watching.written, None);
        watching.accessed(AccessKind::Read, 0x2000_0010, Width::W32);
        assert_eq!(watching.written, None, "a load is no store");
        watching.accessed(AccessKind::Write, 0x2000_000E, Width::W32);
        assert_eq!(watching.written, Some(0x2000_0010));
        watching.accessed(AccessKind::Write, 0x2000_0018, Width::W8);
        assert_eq!(
            watching.written,
            Some(0x2000_0010),
            "the instruction's first store"
        );
    }
}