rigless 0.1.0

// Copyright (c) 2026 Rigless Labs.
// SPDX-License-Identifier: MIT OR Apache-2.0
//! The static description of a system on chip, and the [`Bus`] that gives its addresses meaning.
//!
//! The description is what `rigless svd generate` emits from the vendor's SVD: a [`Cpu`], every
//! [`Peripheral`] instance at its address, and one [`RegisterSpec`] table per layout, with a
//! [`Layout`] enum naming each table's registers. A hand-written memory map of [`Region`]s
//! completes it. [`Bus::builder`] assembles all of that with the SoC's corrections, reset values,
//! write rules and field shapes, and the fields a model declares, checks it once, and produces a
//! [`Bus`].
//!
//! **A bus owns no models.** It decodes an address to a slot, holds each slot's [`RegisterFile`],
//! and carries the event queue and the interrupt changes. The models are fields of the MCU that
//! has them, and [`crate::mcu::Mcu`] is what joins the two: it hands the bus and the model in one
//! slot to the runtime, borrowed apart, so a model is reached by a field and never by a name.
//!
//! Nothing here knows which processor family the SoC belongs to: addresses and values are
//! 64-bit, and a [`Cpu`] is a name, an FPU flag, and an interrupt count.
//!
//! A model raises its interrupt by position in its instance's table, `context.raise(UPDATE)` with
//! `const UPDATE: usize = 0`, because a layout is shared by every instance built on it and only the
//! instance knows its number. The bus resolves the position and reports the change as the
//! instance's name, the number, and the level. A position the table doesn't list is a bug in the
//! model and panics with the instance's name.
//!
//! # Joining one instance to another
//!
//! A model may not reach another model. It would be a second borrow of the bus inside a call, and
//! the order of the effects would stop being the description's. Four mechanisms join them instead,
//! and a part that needs none of them declares none.
//!
//! **A gate** is a bit of one instance that another answers behind. Where the vendor says a
//! peripheral whose clock is off doesn't answer its registers, that's one line of the part's
//! description:
//!
//! ```
//! # use rigless::soc::{Access, Bus, Clock, Cpu, Endian, FieldSpec, Gate, Peripheral, ReadAction, Region, RegisterSpec, Width, WriteModify};
//! # const fn flag(name: &'static str, bit: u8) -> FieldSpec {
//! #     FieldSpec { name, bit, width: 1, access: Access::ReadWrite, read: ReadAction::None, write: WriteModify::None }
//! # }
//! # static ENABLES: [RegisterSpec; 1] = [RegisterSpec { name: "ENR", offset: 0, width: Width::W32,
//! #     reset: 0, access: Access::ReadWrite, read: ReadAction::None, write: WriteModify::None,
//! #     fields: &[flag("SERIALEN", 0)] }];
//! # static DATA: [RegisterSpec; 1] = [RegisterSpec { name: "DR", offset: 0, width: Width::W32, reset: 0,
//! #     access: Access::ReadWrite, read: ReadAction::None, write: WriteModify::None, fields: &[] }];
//! # static DMAEN: FieldSpec = flag("DMAEN", 1);
//! # static CPU: Cpu = Cpu { name: "a-core", fpu: true, interrupt_lines: 8, endian: Endian::Little };
//! # static MEMORY: [Region; 1] = [Region::ram("sram", 0x2000_0000, 1 << 16)];
//! # fn instances() -> [Peripheral; 3] { [
//! #     Peripheral { name: "CLOCKS", base: 0x4000_0000, size: 0x400, interrupts: &[], registers: &ENABLES },
//! #     Peripheral { name: "SERIAL", base: 0x4000_0400, size: 0x400, interrupts: &[1], registers: &DATA },
//! #     Peripheral { name: "DMA", base: 0x4000_0800, size: 0x400, interrupts: &[2], registers: &DATA },
//! # ] }
//! # fn main() -> Result<(), Box<dyn std::error::Error>> {
//! let bus = Bus::builder(CPU, &MEMORY, instances())
//!     // Every access to SERIAL is refused while CLOCKS.ENR.SERIALEN is clear.
//!     .gate("SERIAL", Gate::by("CLOCKS", "ENR", "SERIALEN"))
//!     // The same over named registers and in one direction: reads still answer.
//!     .gate_writes("SERIAL", &["DR"], Gate::by("CLOCKS", "ENR", "SERIALEN"))
//!     // A field the vendor's file omits, which a model declares and a gate may then name.
//!     .declare("CLOCKS", "ENR", &DMAEN)
//!     // DMA reads every request any instance drives.
//!     .reads_requests("DMA")
//!     // SERIAL runs on the first clock output of CLOCKS.
//!     .clocked_by("SERIAL", Clock::output("CLOCKS", 0))
//!     .build()?;
//! # let _ = bus;
//! # Ok(())
//! # }
//! ```
//!
//! The bit is named rather than numbered, so its position comes from the generated table. A gate is
//! read where its bit lies and never through a second gate, so gates can't cycle. An access a gate
//! refuses is [`Fault::Gated`] from [`crate::mcu::Mcu::read`] and [`crate::mcu::Mcu::write`]. A
//! [`crate::session::Session`] turns that into the zero the firmware sees, and lists the address in
//! [`crate::session::Session::refused`].
//!
//! **A request line** is a level one instance drives and another reads, the same shape as an
//! interrupt on another wire. `context.request(n, level)` drives the instance's `n`th output in its
//! own numbering, the way [`crate::device::DeviceContext::interrupt`] takes a position. Every
//! instance `reads_requests` named sees it as a [`crate::device::RequestChange`] carrying the
//! driver's name and that number. **A request no reader was named for is dropped and nothing
//! reports it**, so a part whose controller isn't a reader sees none of them.
//!
//! The runtime carries no wiring table of its own, on purpose: what a driver's number means is the
//! reader's to decide. So wiring one instance to another is three things the models own rather than
//! one the crate provides. The driver publishes a constant per output,
//! `pub const RECEIVE_REQUEST: usize = 0` beside its `const GLOBAL: usize = 0`. The reader declares
//! whatever shape its own wiring wants and is handed one at construction. The part writes the table
//! out and names the reader with `reads_requests`. A DMA controller's table of which request lands
//! on which of its channels is one such shape.
//!
//! **A clock** is a rate one instance drives and another runs on: what a clock tree feeds a
//! peripheral that counts. `context.clock(n, hz)` drives the instance's `n`th clock output in its
//! own numbering. `clocked_by(instance, Clock::output(source, n))` says which one an instance runs
//! on, so that instance alone is told at [`crate::device::Device::on_clock`], and only of that
//! output. A rate isn't a level. The reader keeps time against it, so it re-bases at the instant of
//! the change rather than reinterpreting what it had already counted, and an event it placed at the
//! old rate is placed again. A model built with a rate and never wired to a clock keeps the rate it
//! was built with. That's what a test putting one model on a bus of its own gets.
//!
//! **A requested access** is a model asking the runtime to make a bus or memory access on its
//! behalf. `context.read_from(address, width, token)` and
//! `context.write_to(address, width, value, token)` take effect after the call returns, through the
//! same path a firmware's access takes. The answer comes back to
//! [`crate::device::Device::on_access`] carrying the model's own `token`, or to
//! [`crate::device::Device::on_refused`] where the bus wouldn't make it. An access that lies wholly
//! inside one of the part's [`Region`]s reaches the emulator's memory. One that runs past a region's
//! end goes to the bus.
//!
//! **Call [`crate::mcu::Mcu::settle`] after every access and every event.**
//! [`crate::mcu::Mcu::read`], [`crate::mcu::Mcu::write`] and [`crate::mcu::Mcu::advance_to`] only
//! queue what the models asked for. Settling is what carries it out, and a harness that forgets it
//! drives a controller that never moves a byte and says nothing. [`crate::session::Session`] does
//! it for a run, so only a test driving an [`crate::mcu::Mcu`] itself has to.
//!
//! A settle serves clock changes first, then request changes, then answers, then the accesses
//! themselves, each at the instant of the access or event that set it off. A DMA controller is the
//! worked example of three of the four mechanisms at once: it reads requests, is gated by a clock
//! enable, and asks for every access it makes.

#[cfg(feature = "stm32f427")]
pub mod stm32f427;

use std::fmt;
use std::num::{NonZeroU32, NonZeroU64};

use crate::device::{
    Answer, ClockChange, DeviceContext, Effects, InterruptChange, PendingAccess, RegisterFile,
    RequestChange, ResetCause, Told,
};
use crate::emulator::AccessKind;
use crate::snapshot::store;
use crate::time::{EventId, VirtualNanos};

/// The processor core as the SVD describes it.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct Cpu {
    /// The core name as the vendor spells it.
    pub name: &'static str,
    /// Whether the core has a floating-point unit.
    pub fpu: bool,
    /// Number of external interrupt lines the interrupt controller has.
    pub interrupt_lines: u16,
    /// The order the core keeps a value's bytes in memory.
    pub endian: Endian,
}

/// The order of a value's bytes in memory.
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
pub enum Endian {
    /// The least significant byte at the lowest address.
    #[default]
    Little,
    /// The most significant byte at the lowest address.
    Big,
}

/// One peripheral instance at its address.
///
/// Instances the SVD derives from a sibling share that sibling's table, so every instance of one
/// kind points at one generated `REGISTERS`. An SoC module corrects an instance the vendor's file
/// got wrong with struct update syntax: `Peripheral { interrupts: &[87], ..generated::AN_INSTANCE }`.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct Peripheral {
    /// The instance name as the vendor spells it, such as `SERIAL`.
    pub name: &'static str,
    /// Absolute address of the first register.
    pub base: u64,
    /// Bytes the instance occupies on the bus.
    pub size: u64,
    /// Interrupt lines the instance raises, ascending.
    pub interrupts: &'static [u16],
    /// The register table, ordered by offset.
    pub registers: &'static [RegisterSpec],
}

impl Peripheral {
    /// Whether the address falls inside the instance.
    pub const fn contains(&self, address: u64) -> bool {
        address >= self.base && address < self.base + self.size
    }
}

/// One register of a table: where it is, what it holds after reset, and how the bus may treat it.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct RegisterSpec {
    /// The register name as the vendor spells it.
    pub name: &'static str,
    /// Offset from the instance base.
    pub offset: u32,
    /// Width on the bus.
    pub width: Width,
    /// Value after reset.
    pub reset: u64,
    /// Which directions the bus allows.
    pub access: Access,
    /// What a read does to the register.
    pub read: ReadAction,
    /// What arithmetic a write performs before the value lands.
    pub write: WriteModify,
    /// The bit fields, ordered by position.
    pub fields: &'static [FieldSpec],
}

impl RegisterSpec {
    /// One past the last byte of the register, as an offset from the instance base.
    pub const fn end(&self) -> u32 {
        self.offset + self.width.bytes()
    }
}

/// One bit field of a register.
///
/// The generator emits one constant per field, so a model reads a bit by name:
/// `ctrl::EN.is_set(value)`.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct FieldSpec {
    /// The field name as the vendor spells it.
    pub name: &'static str,
    /// Position of the least significant bit.
    pub bit: u8,
    /// Width in bits.
    pub width: u8,
    /// Which directions the bus allows, taken from the register unless the SVD says otherwise.
    pub access: Access,
    /// What a read does to the field, taken from the register unless the SVD says otherwise.
    pub read: ReadAction,
    /// What arithmetic a write performs, taken from the register unless the SVD says otherwise.
    pub write: WriteModify,
}

impl FieldSpec {
    /// The bits the field occupies within the register.
    pub const fn mask(&self) -> u64 {
        if self.width >= Width::W64.bits() {
            u64::MAX
        } else {
            ((1u64 << self.width) - 1) << self.bit
        }
    }

    /// The field's value within a register value.
    pub const fn get(&self, register_value: u64) -> u64 {
        (register_value & self.mask()) >> self.bit
    }

    /// The register value with this field replaced.
    pub const fn set(&self, register_value: u64, field_value: u64) -> u64 {
        (register_value & !self.mask()) | ((field_value << self.bit) & self.mask())
    }

    /// Whether any bit of the field is set in the register value.
    pub const fn is_set(&self, register_value: u64) -> bool {
        register_value & self.mask() != 0
    }
}

/// Width of a register, or of a bus access, in bits.
#[derive(Debug, Clone, Copy, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
pub enum Width {
    /// Eight bits.
    W8,
    /// Sixteen bits.
    W16,
    /// Thirty-two bits.
    W32,
    /// Sixty-four bits.
    W64,
}

impl Width {
    /// The width in bits.
    pub const fn bits(self) -> u8 {
        match self {
            Self::W8 => 8,
            Self::W16 => 16,
            Self::W32 => 32,
            Self::W64 => 64,
        }
    }

    /// The width in bytes.
    pub const fn bytes(self) -> u32 {
        self.bits() as u32 / 8
    }

    /// A mask of the bits a value of this width holds.
    pub const fn mask(self) -> u64 {
        match self {
            Self::W64 => u64::MAX,
            narrower => (1u64 << narrower.bits()) - 1,
        }
    }
}

/// Which directions the bus allows, as the CMSIS-SVD `access` element names them.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum Access {
    /// Reads return the value and writes are ignored.
    ReadOnly,
    /// Writes land and reads return zero.
    WriteOnly,
    /// Both directions.
    ReadWrite,
    /// Only the first write after reset lands, and reads return zero.
    WriteOnce,
    /// Only the first write after reset lands, and reads return the value.
    ReadWriteOnce,
}

impl Access {
    /// Whether the bus may read the value.
    pub const fn is_readable(self) -> bool {
        !matches!(self, Self::WriteOnly | Self::WriteOnce)
    }

    /// Whether the bus may write the value, at least once.
    pub const fn is_writable(self) -> bool {
        !matches!(self, Self::ReadOnly)
    }

    /// Whether only the first write after reset lands.
    pub const fn is_write_once(self) -> bool {
        matches!(self, Self::WriteOnce | Self::ReadWriteOnce)
    }
}

/// What a read does to a register, as the CMSIS-SVD `readAction` element names it.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum ReadAction {
    /// Nothing.
    None,
    /// The register clears.
    Clear,
    /// The register sets.
    Set,
    /// The register changes in a way only the model knows.
    Modify,
    /// Another register changes.
    ModifyExternal,
}

impl ReadAction {
    /// The value the register holds after a read of `value`, within `mask`.
    pub const fn apply(self, value: u64, mask: u64) -> u64 {
        match self {
            Self::Clear => value & !mask,
            Self::Set => value | mask,
            Self::None | Self::Modify | Self::ModifyExternal => value,
        }
    }
}

/// What arithmetic a write performs before the value lands, as the CMSIS-SVD `modifiedWriteValues` element names it.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum WriteModify {
    /// The written value lands.
    None,
    /// Written ones clear their bits.
    OneToClear,
    /// Written ones set their bits.
    OneToSet,
    /// Written ones toggle their bits.
    OneToToggle,
    /// Written zeros clear their bits.
    ZeroToClear,
    /// Written zeros set their bits.
    ZeroToSet,
    /// Written zeros toggle their bits.
    ZeroToToggle,
    /// Any write clears the register.
    Clear,
    /// Any write sets the register.
    Set,
    /// Any write changes the register in a way only the model knows.
    Modify,
}

impl WriteModify {
    /// The value that lands when `written` arrives over `old`.
    pub const fn apply(self, old: u64, written: u64) -> u64 {
        match self {
            Self::None => written,
            Self::OneToClear => old & !written,
            Self::OneToSet => old | written,
            Self::OneToToggle => old ^ written,
            Self::ZeroToClear => old & written,
            Self::ZeroToSet => old | !written,
            Self::ZeroToToggle => old ^ !written,
            Self::Clear => 0,
            Self::Set => u64::MAX,
            Self::Modify => old,
        }
    }

    /// The written value that leaves `old` unchanged, for the lanes a narrow access doesn't touch.
    pub const fn neutral(self, old: u64) -> u64 {
        match self {
            Self::OneToClear | Self::OneToSet | Self::OneToToggle => 0,
            Self::ZeroToClear | Self::ZeroToSet | Self::ZeroToToggle => u64::MAX,
            Self::None | Self::Clear | Self::Set | Self::Modify => old,
        }
    }
}

/// A register table's names as a type, so a model matches on registers instead of strings.
///
/// The generator emits one enum implementing this per table. A variant's index is its row in
/// [`Layout::REGISTERS`].
pub trait Layout: Copy + fmt::Debug {
    /// The table this layout names.
    const REGISTERS: &'static [RegisterSpec];

    /// The register at this row of the table.
    fn from_index(index: usize) -> Option<Self>;

    /// This register's row in the table.
    fn index(self) -> usize;

    /// This register's row of the table.
    fn spec(self) -> &'static RegisterSpec {
        &Self::REGISTERS[self.index()]
    }
}

/// What a memory region holds.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum RegionKind {
    /// Code and constant data, loaded from the firmware image.
    Flash,
    /// Read-write memory.
    Ram,
    /// Vendor read-only data such as the unique device ID.
    System,
}

impl RegionKind {
    /// Whether the firmware can write the region. The emulator maps every other kind read-only, and
    /// a snapshot saves only these, since what the image put in the rest never changes.
    #[must_use]
    pub const fn is_writable(self) -> bool {
        matches!(self, Self::Ram)
    }
}

/// One memory region of the SoC.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[non_exhaustive]
pub struct Region {
    /// The region name, such as `sram`.
    pub name: &'static str,
    /// Absolute address of the first byte.
    pub base: u64,
    /// Size in bytes.
    pub size: u64,
    /// What the region holds.
    pub kind: RegionKind,
    /// The blocks the region erases in, in the order they sit in it from its base, or none for one
    /// block the size of the region. A debugger loading flash erases whole blocks.
    pub blocks: &'static [EraseBlocks],
}

/// A run of erase blocks of one size, in the order they sit in a flash region.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct EraseBlocks {
    /// The bytes of each block.
    pub size: NonZeroU64,
    /// How many blocks of that size there are in a row.
    pub count: NonZeroU32,
}

impl Region {
    /// A flash region.
    pub const fn flash(name: &'static str, base: u64, size: u64) -> Self {
        Self {
            name,
            base,
            size,
            kind: RegionKind::Flash,
            blocks: &[],
        }
    }

    /// A RAM region.
    pub const fn ram(name: &'static str, base: u64, size: u64) -> Self {
        Self {
            name,
            base,
            size,
            kind: RegionKind::Ram,
            blocks: &[],
        }
    }

    /// This region, erased in `blocks`, which add up to its size.
    #[must_use]
    pub const fn erased_in(self, blocks: &'static [EraseBlocks]) -> Self {
        Self { blocks, ..self }
    }

    /// Whether this region holds `address`.
    #[must_use]
    pub const fn contains(&self, address: u64) -> bool {
        address >= self.base && address - self.base < self.size
    }

    /// A system memory region.
    pub const fn system(name: &'static str, base: u64, size: u64) -> Self {
        Self {
            name,
            base,
            size,
            kind: RegionKind::System,
            blocks: &[],
        }
    }
}

/// Why an SoC description doesn't hold together.
#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)]
#[non_exhaustive]
pub enum Error {
    /// Two memory regions share addresses.
    #[error("memory regions {lower} and {upper} overlap")]
    OverlappingRegions {
        /// The region with the lower base.
        lower: &'static str,
        /// The region that starts inside it.
        upper: &'static str,
    },
    /// A region's erase blocks don't add up to its size.
    #[error("the erase blocks of memory region {region} don't add up to its size")]
    EraseBlocksMismatch {
        /// The region.
        region: &'static str,
    },
    /// Two peripheral instances share addresses.
    #[error("peripheral instances {lower} and {upper} overlap")]
    OverlappingInstances {
        /// The instance with the lower base.
        lower: &'static str,
        /// The instance that starts inside it.
        upper: &'static str,
    },
    /// An instance raises an interrupt line the CPU doesn't have.
    #[error("{instance} raises interrupt {line} but the CPU has {lines} lines")]
    InterruptOutOfRange {
        /// The instance.
        instance: &'static str,
        /// The interrupt line.
        line: u16,
        /// Lines the CPU has.
        lines: u16,
    },
    /// A binding or correction names an instance the SoC doesn't have.
    #[error("{instance} is not an instance of this SoC")]
    UnknownInstance {
        /// The name given.
        instance: &'static str,
    },
    /// The description runs one instance on two clocks, and an instance runs on one.
    #[error("{instance} is clocked twice, and an instance runs on one clock")]
    ClockedTwice {
        /// The instance named twice.
        instance: &'static str,
    },
    /// A correction, a declaration or a gate names a register the instance doesn't have.
    #[error("{instance} has no register {register}")]
    UnknownRegister {
        /// The instance.
        instance: &'static str,
        /// The name given.
        register: &'static str,
    },
    /// A gate names a field the register doesn't declare, in the tables or by a model, or a
    /// correction names one the tables don't carry.
    #[error("{instance}.{register} has no field {field}")]
    UnknownField {
        /// The instance.
        instance: &'static str,
        /// The register.
        register: &'static str,
        /// The name given.
        field: &'static str,
    },
    /// A corrected or declared field runs past its register.
    #[error("{instance}.{register}.{field} does not fit its register")]
    FieldOutOfRange {
        /// The instance.
        instance: &'static str,
        /// The register.
        register: &'static str,
        /// The field corrected.
        field: &'static str,
    },
    /// A corrected reset value has bits beyond the register's width.
    #[error("reset value {value:#x} does not fit {instance}.{register}")]
    ResetTooWide {
        /// The instance.
        instance: &'static str,
        /// The register.
        register: &'static str,
        /// The value given.
        value: u64,
    },
    /// A device written for one register layout was bound to an instance of another.
    #[error("{instance} does not have the register layout the device was written for")]
    LayoutMismatch {
        /// The instance.
        instance: &'static str,
    },
    /// Two devices were bound to one instance.
    #[error("{instance} is bound twice")]
    BoundTwice {
        /// The instance.
        instance: &'static str,
    },
}

/// Why a bus access couldn't complete.
#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error, serde::Serialize, serde::Deserialize)]
#[non_exhaustive]
pub enum Fault {
    /// No register covers the address.
    #[error("no register at {address:#x}")]
    Unmapped {
        /// The address accessed.
        address: u64,
    },
    /// A gate the part declares is shut, so the instance doesn't answer.
    #[error("{instance}.{register} is gated by {}.{}.{}", by.instance, by.register, by.field)]
    Gated {
        /// The instance that didn't answer.
        instance: &'static str,
        /// The register reached.
        register: &'static str,
        /// The bit that would have opened it.
        by: Gate,
    },
    /// The access runs past the end of the register that covers the address.
    #[error("a {}-bit access at {address:#x} runs past its register", width.bits())]
    Misaligned {
        /// The address accessed.
        address: u64,
        /// The width of the access.
        width: Width,
    },
}

impl Fault {
    /// Whether this is the part saying no, a gate it declares being shut, which is the model answering
    /// as the silicon does rather than a gap in the models.
    #[must_use]
    pub fn is_shut_gate(&self) -> bool {
        matches!(self, Self::Gated { .. })
    }
}

/// A field of a register the vendor's file leaves out, which the part declares so the bus can find it.
struct Declaration {
    instance: &'static str,
    register: &'static str,
    field: &'static FieldSpec,
}

/// The row of `table` named `register`, failing on a name the table doesn't carry.
fn row_named(
    table: &'static [RegisterSpec],
    instance: &'static str,
    register: &'static str,
) -> Result<usize, Error> {
    table
        .iter()
        .position(|candidate| candidate.name == register)
        .ok_or(Error::UnknownRegister { instance, register })
}

/// Replaces one field of one register of `instance` with `correction.corrected`, in the [`RegisterFile`]
/// rather than in [`Peripheral::registers`]: that table is what [`crate::device::Device::layout`]
/// compares itself to, so a model's own layout stays the vendor's shape and only what the register file
/// applies, reads and writes through, learns the correction. [`Builder::reset`] and [`Builder::write_modify`]
/// take the same path for the same reason.
fn correct_field(slots: &mut [Slot], correction: &FieldCorrection) -> Result<(), Error> {
    let slot = slot_named_mut(slots, correction.instance)?;
    let row = row_named(
        slot.peripheral.registers,
        correction.instance,
        correction.register,
    )?;
    let register = &slot.peripheral.registers[row];
    let past = u32::from(correction.corrected.bit) + u32::from(correction.corrected.width);
    if past > u32::from(register.width.bits()) {
        return Err(Error::FieldOutOfRange {
            instance: correction.instance,
            register: correction.register,
            field: correction.field,
        });
    }
    if !register
        .fields
        .iter()
        .any(|field| field.name == correction.field)
    {
        return Err(Error::UnknownField {
            instance: correction.instance,
            register: correction.register,
            field: correction.field,
        });
    }
    slot.registers
        .correct_field(row, correction.field, correction.corrected);
    Ok(())
}

/// Where the instance a description names sits, failing on a name nothing carries.
fn slot_named(slots: &[Slot], instance: &'static str) -> Result<usize, Error> {
    slots
        .iter()
        .position(|slot| slot.peripheral.name == instance)
        .ok_or(Error::UnknownInstance { instance })
}

/// Turns a declared gate into the slot it belongs to and the slot, row and mask the bus tests against,
/// failing on a name nothing carries.
fn resolve_gate(
    slots: &[Slot],
    declarations: &[Declaration],
    spec: &GateSpec,
) -> Result<(usize, ResolvedGate), Error> {
    let gate = spec.gate;
    let by_slot = slot_named(slots, gate.instance)?;
    let by_row = row_named(
        slots[by_slot].peripheral.registers,
        gate.instance,
        gate.register,
    )?;
    let mask = slots[by_slot]
        .registers
        .fields(by_row)
        .iter()
        .find(|field| field.name == gate.field)
        .or_else(|| {
            declarations
                .iter()
                .find(|declared| {
                    declared.instance == gate.instance
                        && declared.register == gate.register
                        && declared.field.name == gate.field
                })
                .map(|declared| declared.field)
        })
        .map(FieldSpec::mask)
        .ok_or(Error::UnknownField {
            instance: gate.instance,
            register: gate.register,
            field: gate.field,
        })?;
    let gated = slot_named(slots, spec.instance)?;
    let rows = spec
        .registers
        .iter()
        .map(|name| row_named(slots[gated].peripheral.registers, spec.instance, name))
        .collect::<Result<Vec<usize>, Error>>()?;
    Ok((
        gated,
        ResolvedGate {
            by_slot,
            by_row,
            mask,
            writes_only: spec.writes_only,
            rows: rows.into_boxed_slice(),
            gate,
        },
    ))
}

/// One peripheral instance on the bus: where it answers, and what it holds. The model that gives it
/// behaviour is a field of the MCU, not a box in here.
pub struct Slot {
    peripheral: Peripheral,
    registers: RegisterFile,
    /// What has to be true elsewhere for this instance to answer. Usually none.
    gates: Box<[ResolvedGate]>,
}

/// A gate as the bus checks it: a bit of another slot, resolved once when the part is built.
#[derive(Debug, Clone)]
struct ResolvedGate {
    by_slot: usize,
    by_row: usize,
    mask: u64,
    writes_only: bool,
    /// The rows it covers. Empty covers every row of the instance.
    rows: Box<[usize]>,
    gate: Gate,
}

impl ResolvedGate {
    fn covers(&self, row: usize, writing: bool) -> bool {
        (writing || !self.writes_only) && (self.rows.is_empty() || self.rows.contains(&row))
    }
}

/// The bit that opens a gate: a field of a register of an instance.
///
/// Naming the field rather than a bit means the position comes from the tables, or from a model's
/// own declaration where the vendor's file omits it, and there's no number to mistype.
#[derive(Debug, Clone, Copy, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
pub struct Gate {
    /// The instance holding the bit.
    pub instance: &'static str,
    /// The register holding it.
    pub register: &'static str,
    /// The field, as the manual names it.
    pub field: &'static str,
}

impl Gate {
    /// The bit `field` of `register` of `instance`.
    #[must_use]
    pub const fn by(instance: &'static str, register: &'static str, field: &'static str) -> Self {
        Self {
            instance,
            register,
            field,
        }
    }
}

/// The clock an instance runs on: one clock output of another instance, in that instance's own numbering.
///
/// The output is numbered rather than named because it's the driver's own, the way an interrupt
/// position and a request output are. The driver publishes a constant per output beside them.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct Clock {
    /// The instance driving it.
    pub instance: &'static str,
    /// Which of that instance's clock outputs.
    pub output: usize,
}

impl Clock {
    /// Output `output` of `instance`.
    #[must_use]
    pub const fn output(instance: &'static str, output: usize) -> Self {
        Self { instance, output }
    }
}

/// A clock as the bus delivers it: which slot runs on which output of which slot, resolved once.
#[derive(Debug, Clone, Copy)]
struct ResolvedClock {
    source: usize,
    output: usize,
    sink: usize,
}

store!(Slot {
    values: [],
    parts: [registers],
    built: [peripheral, gates],
});

impl Slot {
    /// The instance this slot answers for.
    #[must_use]
    pub fn peripheral(&self) -> &Peripheral {
        &self.peripheral
    }

    /// What this instance holds.
    #[must_use]
    pub fn registers(&self) -> &RegisterFile {
        &self.registers
    }

    /// What this instance holds, for the model that owns it.
    pub fn registers_mut(&mut self) -> &mut RegisterFile {
        &mut self.registers
    }
}

impl fmt::Debug for Slot {
    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
        formatter
            .debug_struct("Slot")
            .field("peripheral", &self.peripheral.name)
            .field("registers", &self.registers)
            .field("gates", &self.gates)
            .finish()
    }
}

/// A named span of addresses, for the overlap checks.
struct Extent {
    name: &'static str,
    base: u64,
    size: u64,
}

impl Extent {
    const fn end(&self) -> u64 {
        self.base.saturating_add(self.size)
    }
}

/// Assembles a bus from its description and the SoC's corrections, checking everything once in [`Builder::build`].
#[must_use = "a builder does nothing until built"]
pub struct Builder {
    cpu: Cpu,
    memory: &'static [Region],
    peripherals: Vec<Peripheral>,
    reset_corrections: Vec<ResetCorrection>,
    write_corrections: Vec<WriteCorrection>,
    field_corrections: Vec<FieldCorrection>,
    gates: Vec<GateSpec>,
    sinks: Vec<&'static str>,
    clocks: Vec<(&'static str, Clock)>,
    declarations: Vec<Declaration>,
}

struct GateSpec {
    instance: &'static str,
    registers: &'static [&'static str],
    writes_only: bool,
    gate: Gate,
}

struct ResetCorrection {
    instance: &'static str,
    register: &'static str,
    value: u64,
}

struct WriteCorrection {
    instance: &'static str,
    register: &'static str,
    rule: WriteModify,
}

struct FieldCorrection {
    instance: &'static str,
    register: &'static str,
    field: &'static str,
    corrected: FieldSpec,
}

impl fmt::Debug for Builder {
    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
        formatter
            .debug_struct("Builder")
            .field("cpu", &self.cpu)
            .field("reset_corrections", &self.reset_corrections.len())
            .field("write_corrections", &self.write_corrections.len())
            .finish_non_exhaustive()
    }
}

impl Builder {
    /// Overrides a reset value where the SVD disagrees with the vendor's documentation of the SoC.
    pub fn reset(mut self, instance: &'static str, register: &'static str, value: u64) -> Self {
        self.reset_corrections.push(ResetCorrection {
            instance,
            register,
            value,
        });
        self
    }

    /// Declares a field of a register the vendor's file leaves out. The register file then applies
    /// its access and write rules, [`RegisterFile::fields`] lists it, and a gate can name it.
    ///
    /// A generated table is the vendor's file transcribed and stays that way, so a field the vendor omits
    /// is the model's own.
    pub fn declare(
        mut self,
        instance: &'static str,
        register: &'static str,
        field: &'static FieldSpec,
    ) -> Self {
        self.declarations.push(Declaration {
            instance,
            register,
            field,
        });
        self
    }

    /// Gates every access to `instance` on a bit of another instance.
    ///
    /// A peripheral whose clock is off doesn't answer its registers, and which bit says so is the
    /// part's to know. So the part's binding is where a gate is declared and where the manual is
    /// cited. An access the gate refuses is refused the way the bus refuses any other: it answers
    /// zero, the write is dropped, and it's reported.
    pub fn gate(mut self, instance: &'static str, gate: Gate) -> Self {
        self.gates.push(GateSpec {
            instance,
            registers: &[],
            writes_only: false,
            gate,
        });
        self
    }

    /// Gates writes to named registers of `instance` on a bit of another instance.
    ///
    /// See [`Builder::gate`].
    pub fn gate_writes(
        mut self,
        instance: &'static str,
        registers: &'static [&'static str],
        gate: Gate,
    ) -> Self {
        self.gates.push(GateSpec {
            instance,
            registers,
            writes_only: true,
            gate,
        });
        self
    }

    /// Drops every gate the description declared, for a bus built to hold one model rather than a part.
    ///
    /// A gate is another instance's bit, and a bus with one model on it doesn't carry the instance
    /// holding it in any meaningful state. [`crate::mcu::Single`] and [`crate::mcu::Bare`] build
    /// through this so that a model under the microscope answers. That's what a test asking about
    /// that model alone means by putting it on a bus.
    pub(crate) fn ungated(mut self) -> Self {
        self.gates.clear();
        self
    }

    /// Sends every request any instance drives to `instance` as well.
    ///
    /// A controller knows its own wiring, so it recognises the requests meant for it and ignores the rest.
    /// Sinks see a change in the order they were named here.
    pub fn reads_requests(mut self, instance: &'static str) -> Self {
        self.sinks.push(instance);
        self
    }

    /// Runs `instance` on `clock`, an output of another instance: a change of that output's rate reaches
    /// `instance` at [`crate::device::Device::on_clock`], and no other output does.
    ///
    /// An instance runs on one clock. Naming a second replaces nothing and is refused at build.
    pub fn clocked_by(mut self, instance: &'static str, clock: Clock) -> Self {
        self.clocks.push((instance, clock));
        self
    }

    /// Overrides the write rule of a register and of every field in it where the SVD disagrees with the
    /// vendor's documentation of the SoC, a status register whose flags clear on a written zero for one.
    pub fn write_modify(
        mut self,
        instance: &'static str,
        register: &'static str,
        rule: WriteModify,
    ) -> Self {
        self.write_corrections.push(WriteCorrection {
            instance,
            register,
            rule,
        });
        self
    }

    /// Corrects a field's shape where the SVD disagrees with the vendor's documentation of the SoC, the
    /// way [`Builder::reset`] corrects a register's reset value: `corrected` replaces the named field
    /// whole, so a struct update over the table's own constant keeps what the SVD got right and
    /// restates only what it did not.
    pub fn field(
        mut self,
        instance: &'static str,
        register: &'static str,
        field: &'static str,
        corrected: FieldSpec,
    ) -> Self {
        self.field_corrections.push(FieldCorrection {
            instance,
            register,
            field,
            corrected,
        });
        self
    }

    /// Checks the description and produces the bus, naming what is at fault otherwise.
    ///
    /// A description with no gates declared builds as it is. A gate is something a part declares
    /// between two of its instances, and a bus of your own with none needs nothing more than this.
    pub fn build(self) -> Result<Bus, Error> {
        let regions = self.memory.iter().map(|region| Extent {
            name: region.name,
            base: region.base,
            size: region.size,
        });
        if let Some((lower, upper)) = first_overlap(regions) {
            return Err(Error::OverlappingRegions { lower, upper });
        }
        check_erase_blocks(self.memory)?;
        let spans = self.peripherals.iter().map(|peripheral| Extent {
            name: peripheral.name,
            base: peripheral.base,
            size: peripheral.size,
        });
        if let Some((lower, upper)) = first_overlap(spans) {
            return Err(Error::OverlappingInstances { lower, upper });
        }
        check_interrupts(&self.peripherals, self.cpu.interrupt_lines)?;

        let mut slots: Vec<Slot> = self
            .peripherals
            .into_iter()
            .map(|peripheral| Slot {
                gates: Box::default(),
                peripheral,
                registers: RegisterFile::new(peripheral.registers),
            })
            .collect();
        slots.sort_by_key(|slot| slot.peripheral.base);

        for correction in self.reset_corrections {
            let instance = slot_named_mut(&mut slots, correction.instance)?;
            let row = row_named(
                instance.peripheral.registers,
                correction.instance,
                correction.register,
            )?;
            let register = &instance.peripheral.registers[row];
            if correction.value & !register.width.mask() != 0 {
                return Err(Error::ResetTooWide {
                    instance: correction.instance,
                    register: correction.register,
                    value: correction.value,
                });
            }
            instance.registers.correct_reset(row, correction.value);
        }

        for correction in self.write_corrections {
            let instance = slot_named_mut(&mut slots, correction.instance)?;
            let row = row_named(
                instance.peripheral.registers,
                correction.instance,
                correction.register,
            )?;
            instance.registers.correct_write(row, correction.rule);
        }

        for correction in &self.field_corrections {
            correct_field(&mut slots, correction)?;
        }

        for declaration in &self.declarations {
            let instance = slot_named_mut(&mut slots, declaration.instance)?;
            let row = row_named(
                instance.peripheral.registers,
                declaration.instance,
                declaration.register,
            )?;
            let past = u32::from(declaration.field.bit) + u32::from(declaration.field.width);
            if past > u32::from(instance.peripheral.registers[row].width.bits()) {
                return Err(Error::FieldOutOfRange {
                    instance: declaration.instance,
                    register: declaration.register,
                    field: declaration.field.name,
                });
            }
            instance.registers.declare_field(row, declaration.field);
        }

        let sinks = self
            .sinks
            .iter()
            .map(|name| slot_named(&slots, name))
            .collect::<Result<Vec<usize>, Error>>()?;

        let mut clocks = Vec::with_capacity(self.clocks.len());
        for (instance, clock) in &self.clocks {
            let sink = slot_named(&slots, instance)?;
            if clocks
                .iter()
                .any(|wired: &ResolvedClock| wired.sink == sink)
            {
                return Err(Error::ClockedTwice { instance });
            }
            clocks.push(ResolvedClock {
                source: slot_named(&slots, clock.instance)?,
                output: clock.output,
                sink,
            });
        }

        for spec in self.gates {
            let (gated, resolved) = resolve_gate(&slots, &self.declarations, &spec)?;
            let mut gates = std::mem::take(&mut slots[gated].gates).into_vec();
            gates.push(resolved);
            slots[gated].gates = gates.into_boxed_slice();
        }

        let spans = slots
            .iter()
            .map(|slot| (slot.peripheral.base, slot.peripheral.size))
            .collect();
        Ok(Bus {
            cpu: self.cpu,
            memory: self.memory,
            spans,
            slots,
            effects: Effects::default(),
            sinks,
            clocks,
        })
    }
}

fn slot_named_mut<'a>(slots: &'a mut [Slot], name: &'static str) -> Result<&'a mut Slot, Error> {
    let index = slot_named(slots, name)?;
    Ok(&mut slots[index])
}

/// The first two spans that share an address, by ascending base.
fn first_overlap(spans: impl Iterator<Item = Extent>) -> Option<(&'static str, &'static str)> {
    let mut sorted: Vec<Extent> = spans.collect();
    sorted.sort_by_key(|span| span.base);
    sorted
        .windows(2)
        .find(|pair| pair[1].base < pair[0].end())
        .map(|pair| (pair[0].name, pair[1].name))
}

/// Refuses a region whose erase blocks don't add up to its size.
fn check_erase_blocks(memory: &[Region]) -> Result<(), Error> {
    let covered = |region: &Region| {
        region.blocks.iter().try_fold(0_u64, |covered, blocks| {
            blocks
                .size
                .get()
                .checked_mul(u64::from(blocks.count.get()))
                .and_then(|bytes| covered.checked_add(bytes))
        })
    };
    match memory
        .iter()
        .find(|region| !region.blocks.is_empty() && covered(region) != Some(region.size))
    {
        Some(region) => Err(Error::EraseBlocksMismatch {
            region: region.name,
        }),
        None => Ok(()),
    }
}

fn check_interrupts(peripherals: &[Peripheral], lines: u16) -> Result<(), Error> {
    for peripheral in peripherals {
        if let Some(&line) = peripheral.interrupts.iter().find(|&&line| line >= lines) {
            return Err(Error::InterruptOutOfRange {
                instance: peripheral.name,
                line,
                lines,
            });
        }
    }
    Ok(())
}

/// A checked bus: the CPU, the memory map, and every peripheral instance with its register file.
///
/// It answers where an address lands and what that register holds. It doesn't answer what the
/// peripheral *does*. That's the model, which is a field of the MCU built on this bus.
#[derive(Debug)]
pub struct Bus {
    cpu: Cpu,
    memory: &'static [Region],
    slots: Vec<Slot>,
    /// Each slot's first address and its size, in the slots' order, where finding the slot an
    /// address lands in reads only these.
    spans: Box<[(u64, u64)]>,
    effects: Effects,
    /// The slots that read every request, in the order the description named them.
    sinks: Vec<usize>,
    /// Which slot runs on which clock output of which slot, in the order the description named them.
    clocks: Vec<ResolvedClock>,
}

/// How many events one instant may carry before the runtime calls it a model that can't move time
/// on. Several models legitimately schedule at one instant, but none of them needs a thousand.
pub(crate) const SAME_INSTANT_LIMIT: u32 = 1_000;

/// How many steps one settle may take before the runtime calls it a model that never finishes.
///
/// A settle carries out what the models asked for, and each answer may produce another ask. The
/// largest legitimate run of them is one block move: the 65535 items a sixteen-bit counter holds,
/// four bytes each at the widest, moved a byte at a time at the narrowest on the other side.
/// That's 65535 accesses on one port and four times as many on the other, and each access is two
/// steps here, itself and its answer. Twice that leaves room for the other models the same settle
/// reaches and still catches one answering its own answer.
// ceiling: one sixteen-bit block move per settle; upgrade when a wider counter moves more
pub(crate) const SETTLE_LIMIT: u32 = 2 * 2 * (65_535 + 4 * 65_535);

store!(Bus {
    values: [effects],
    parts: [slots],
    built: [cpu, memory, spans, sinks, clocks],
});

impl Bus {
    /// Starts assembling a bus from its CPU, memory map, and peripheral instances.
    pub fn builder(
        cpu: Cpu,
        memory: &'static [Region],
        peripherals: impl IntoIterator<Item = Peripheral>,
    ) -> Builder {
        Builder {
            cpu,
            memory,
            peripherals: peripherals.into_iter().collect(),
            reset_corrections: Vec::new(),
            write_corrections: Vec::new(),
            field_corrections: Vec::new(),
            gates: Vec::new(),
            sinks: Vec::new(),
            clocks: Vec::new(),
            declarations: Vec::new(),
        }
    }

    /// Every slot, in address order. The index is what [`crate::mcu::Mcu::split`] dispatches on.
    #[must_use]
    pub fn slots(&self) -> &[Slot] {
        &self.slots
    }

    /// The part as a system reset leaves it: every register at its reset value and nothing scheduled,
    /// driven, or waiting for an answer.
    pub fn reset(&mut self) {
        for slot in &mut self.slots {
            slot.registers.reset();
        }
        let mut events = std::mem::take(&mut self.effects.events);
        events.clear();
        self.effects = Effects {
            events,
            ..Effects::default()
        };
    }

    /// The slot index of the instance called `name`, which an MCU resolves once at construction so
    /// that nothing after it looks a peripheral up by string.
    #[must_use]
    pub fn slot_of(&self, name: &str) -> Option<usize> {
        self.slots
            .iter()
            .position(|slot| slot.peripheral.name == name)
    }

    /// The slot an address falls in, or `None` where no instance covers it.
    ///
    /// The same search an access decodes with, for a caller that wants to know which instance an address
    /// belongs to without making the access.
    #[must_use]
    pub fn slot_at(&self, address: u64) -> Option<usize> {
        let candidates = self.spans.partition_point(|&(base, _)| base <= address);
        let index = candidates.checked_sub(1)?;
        let (base, size) = self.spans[index];
        (address - base < size).then_some(index)
    }

    /// The CPU.
    pub fn cpu(&self) -> Cpu {
        self.cpu
    }

    /// The memory regions.
    pub fn memory(&self) -> &'static [Region] {
        self.memory
    }

    /// Every peripheral instance, by ascending base address.
    pub fn peripherals(&self) -> impl Iterator<Item = &Peripheral> {
        self.slots.iter().map(|slot| &slot.peripheral)
    }

    /// The instance with this name.
    #[must_use]
    pub fn peripheral(&self, name: &str) -> Option<&Peripheral> {
        self.slot_of(name).map(|slot| &self.slots[slot].peripheral)
    }

    /// The register file of the instance with this name.
    #[must_use]
    pub fn registers(&self, name: &str) -> Option<&RegisterFile> {
        self.slot_of(name).map(|slot| &self.slots[slot].registers)
    }

    /// The registers of the instance at `slot` and a context for its model at `at`, as an access hands
    /// them over, for an input the bus doesn't carry: a level on a pin, a sample, a word from a chip.
    /// A part's `drive_` method is this with its model's field named beside it. What the model does
    /// with the context, an event, an interrupt or a request, settles when the run resumes from the
    /// stop the input was handed over at, so the firmware sees it at that same stop.
    ///
    /// # Panics
    ///
    /// If `slot` is past the end of [`Bus::slots`].
    pub fn drive(
        &mut self,
        at: VirtualNanos,
        slot: usize,
    ) -> (&mut RegisterFile, DeviceContext<'_>) {
        let (slot, context) = self.call(at, slot);
        (slot.registers_mut(), context)
    }

    /// The slot at `index`, for the MCU that owns its model. A part's setter that changes what its
    /// registers hold with no instant to schedule from, like a supply that sets a status bit, writes
    /// through it. One that schedules or raises goes through [`Bus::drive`].
    ///
    /// # Panics
    ///
    /// If `index` is past the end of [`Bus::slots`].
    pub fn slot_mut(&mut self, index: usize) -> &mut Slot {
        &mut self.slots[index]
    }

    /// Where an access lands, or the fault it takes.
    pub(crate) fn locate(
        &self,
        address: u64,
        width: Width,
        kind: AccessKind,
    ) -> Result<Located, Fault> {
        self.land::<true>(address, width, kind)
    }

    /// Where an access lands whatever its gate says, or the fault it takes: what a debugger's peek
    /// reaches, since a register file holds its values with its gate shut.
    pub(crate) fn locate_ungated(
        &self,
        address: u64,
        width: Width,
        kind: AccessKind,
    ) -> Result<Located, Fault> {
        self.land::<false>(address, width, kind)
    }

    // Both of the above as one body, so the firmware's path compiles to the instructions it did
    // before a debugger's peek needed the other, `row_covering` inlined in it. Had `locate` called
    // `locate_ungated` and then tested the gate, every access the firmware made gained a call.
    fn land<const GATED: bool>(
        &self,
        address: u64,
        width: Width,
        kind: AccessKind,
    ) -> Result<Located, Fault> {
        let allows: fn(Access) -> bool = match kind {
            AccessKind::Read => Access::is_readable,
            AccessKind::Write => Access::is_writable,
        };
        let index = self.slot_at(address).ok_or(Fault::Unmapped { address })?;
        let slot = &self.slots[index];
        let offset = u32::try_from(address - slot.peripheral.base)
            .map_err(|_too_far| Fault::Unmapped { address })?;
        let row = slot
            .registers
            .row_covering(offset, allows)
            .ok_or(Fault::Unmapped { address })?;
        let register = &slot.peripheral.registers[row];
        let byte_in_register = offset - register.offset;
        if byte_in_register + width.bytes() > register.width.bytes() {
            return Err(Fault::Misaligned { address, width });
        }
        // The gate is tested last, after the address has been resolved to a register of this
        // instance. That way an address the instance doesn't carry is still reported as the gap in
        // the map it is, rather than as the instance declining to answer.
        if GATED
            && let Some(shut) = slot.gates.iter().find(|gate| {
                gate.covers(row, kind == AccessKind::Write) && !self.gate_is_open(gate)
            })
        {
            return Err(Fault::Gated {
                instance: slot.peripheral.name,
                register: register.name,
                by: shut.gate,
            });
        }
        // A narrow access takes the bytes it names of the register, whose significance the core's
        // byte order decides.
        // ceiling: a range the architecture keeps little-endian whatever the part's order takes the
        // part's lane here; upgrade when a big-endian part models a register there that takes
        // narrow accesses.
        let lane = match self.cpu.endian {
            Endian::Little => byte_in_register,
            Endian::Big => register.width.bytes() - byte_in_register - width.bytes(),
        };
        Ok(Located {
            slot: index,
            row,
            lane: Lane {
                shift: lane * u32::from(Width::W8.bits()),
            },
        })
    }

    /// Whether the bit a gate names stands.
    ///
    /// The bit is read where it lies, whatever gates the instance holding it. A gate isn't
    /// evaluated through another. That avoids a cycle, since two instances can each hold the bit
    /// that opens the other. It's also the truer reading, since an enable keeps its value when the
    /// thing it enables is off.
    fn gate_is_open(&self, gate: &ResolvedGate) -> bool {
        self.slots[gate.by_slot].registers.get_row(gate.by_row) & gate.mask != 0
    }

    /// The slot at `index` with a context for the model that owns it, borrowed apart.
    pub(crate) fn call(
        &mut self,
        at: VirtualNanos,
        index: usize,
    ) -> (&mut Slot, DeviceContext<'_>) {
        let Self { slots, effects, .. } = self;
        let slot = &mut slots[index];
        let context = DeviceContext::new(at, index, slot.peripheral, effects);
        (slot, context)
    }

    /// The next event due by `now`, as its id, the slot that scheduled it, and its instant.
    pub(crate) fn pop_due(&mut self, now: VirtualNanos) -> Option<(EventId, usize, VirtualNanos)> {
        self.effects.events.pop_due(now)
    }

    /// The instant of the earliest pending event, which is when the emulator next needs to stop.
    #[must_use]
    pub fn next_event(&self) -> Option<VirtualNanos> {
        self.effects.events.next_at()
    }

    /// Takes the interrupt levels the models set since the last drain, in the order they set them.
    pub fn drain_interrupts(&mut self) -> impl Iterator<Item = InterruptChange> + '_ {
        self.effects.interrupts.drain(..)
    }

    /// Takes what the models told since the last drain, in the order they told it.
    pub fn drain_told(&mut self) -> impl Iterator<Item = Told> + '_ {
        self.effects.told.drain(..)
    }

    /// The slots that read every request, in the order the description named them.
    pub(crate) fn sinks(&self) -> &[usize] {
        &self.sinks
    }

    /// The oldest request change no sink has seen yet, with the instant it was driven at.
    pub(crate) fn next_request_change(&mut self) -> Option<(VirtualNanos, RequestChange)> {
        self.effects.requests.pop_front()
    }

    /// Takes the request levels the models set since the last drain, in the order they set them.
    pub fn drain_requests(&mut self) -> impl Iterator<Item = RequestChange> + '_ {
        self.effects.requests.drain(..).map(|(_at, change)| change)
    }

    /// The oldest clock change no reader has seen yet, with the instant it was driven at.
    pub(crate) fn next_clock_change(&mut self) -> Option<(VirtualNanos, ClockChange)> {
        self.effects.clocks.pop_front()
    }

    /// The slots that run on `change`'s output, in the order the description named them.
    pub(crate) fn readers_of(&self, change: ClockChange) -> impl Iterator<Item = usize> + '_ {
        let source = self.slot_of(change.instance);
        self.clocks
            .iter()
            .filter(move |wired| Some(wired.source) == source && wired.output == change.output)
            .map(|wired| wired.sink)
    }

    /// The clock each instance runs on, by name, for a check that every instance keeping time has one.
    pub fn clock_of(&self, instance: &str) -> Option<Clock> {
        let sink = self.slot_of(instance)?;
        self.clocks
            .iter()
            .find(|wired| wired.sink == sink)
            .map(|wired| Clock {
                instance: self.slots[wired.source].peripheral.name,
                output: wired.output,
            })
    }

    /// Takes the clock rates the models drove since the last drain, in the order they drove them.
    pub fn drain_clocks(&mut self) -> impl Iterator<Item = ClockChange> + '_ {
        self.effects.clocks.drain(..).map(|(_at, change)| change)
    }

    /// Whether a model has asked for a system reset during the settle now running, without taking it:
    /// the settle loop stops here rather than carrying out effects a reset is about to discard.
    pub(crate) fn reset_requested(&self) -> bool {
        self.effects.reset.is_some()
    }

    /// Takes the reset a model asked for, if one did.
    pub fn take_reset_request(&mut self) -> Option<ResetCause> {
        self.effects.reset.take()
    }

    /// The oldest access a model asked for and the runtime hasn't made.
    pub(crate) fn next_pending(&mut self) -> Option<PendingAccess> {
        self.effects.accesses.pop_front()
    }

    /// The oldest answer the runtime hasn't handed back to the model that asked.
    pub(crate) fn next_answer(&mut self) -> Option<Answer> {
        self.effects.answers.pop_front()
    }

    /// Puts an answer in the queue for the model that asked, at the instant it asked. `found` is
    /// nothing where the bus refused the access.
    pub(crate) fn answer(&mut self, access: &PendingAccess, found: Option<u64>) {
        self.effects.answers.push_back(Answer {
            at: access.at,
            owner: access.owner,
            token: access.token,
            found,
        });
    }

    /// Which region of memory holds the whole of an access of `width` at `address`, if one does. Any
    /// other access is the peripheral bus's, one that starts in a region and runs past its end among
    /// them: the emulator is only ever handed an access that lies inside memory it lends, never one
    /// crossing into whatever follows a region.
    pub(crate) fn region_holding(&self, address: u64, width: Width) -> Option<&'static Region> {
        let last = address.checked_add(u64::from(width.bytes()) - 1)?;
        self.memory
            .iter()
            .find(|region| region.contains(address) && region.contains(last))
    }
}

/// Where one bus access lands: the slot, the register row, and the lane inside the register.
pub(crate) struct Located {
    pub(crate) slot: usize,
    pub(crate) row: usize,
    pub(crate) lane: Lane,
}

pub(crate) struct Lane {
    pub(crate) shift: u32,
}

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

    const ENABLE: FieldSpec = FieldSpec {
        name: "EN",
        bit: 0,
        width: 1,
        access: Access::ReadWrite,
        read: ReadAction::None,
        write: WriteModify::None,
    };

    const fn register(
        name: &'static str,
        offset: u32,
        fields: &'static [FieldSpec],
    ) -> RegisterSpec {
        RegisterSpec {
            name,
            offset,
            width: Width::W32,
            reset: 0,
            access: Access::ReadWrite,
            read: ReadAction::None,
            write: WriteModify::None,
            fields,
        }
    }

    static CLOCKS: [RegisterSpec; 1] = [register("ENR", 0x0, &[ENABLE])];
    static PORT: [RegisterSpec; 2] = [register("DR", 0x0, &[]), register("SR", 0x4, &[])];
    static MEMORY: [Region; 1] = [Region::ram("sram", 0x2000_0000, 4 << 10)];

    const fn blocks(size: u64, count: u32) -> EraseBlocks {
        match (NonZeroU64::new(size), NonZeroU32::new(count)) {
            (Some(size), Some(count)) => EraseBlocks { size, count },
            _ => panic!("a block has bytes"),
        }
    }

    static WHOLE: [Region; 2] = [
        Region::flash("flash", 0x0800_0000, 0x1_8000)
            .erased_in(&[blocks(0x4000, 2), blocks(0x1_0000, 1)]),
        Region::flash("plain", 0x0900_0000, 0x1000),
    ];
    static SHORT: [Region; 1] =
        [Region::flash("short", 0x0800_0000, 0x1_8000).erased_in(&[blocks(0x4000, 2)])];
    static OVER: [Region; 1] = [Region::flash("over", 0x0800_0000, 0x1_8000)
        .erased_in(&[blocks(0x4000, 2), blocks(0x1_0000, 2)])];
    static WRAPS: [Region; 1] = [Region::flash("wraps", 0x0800_0000, 0x1_8000)
        .erased_in(&[blocks(u64::MAX, u32::MAX), blocks(0x1_8001, 1)])];

    /// A region's erase blocks add up to its size, or `Bus::build` names the region whose don't,
    /// however far past its size, or round the address space, they reach. A region with none is one
    /// block.
    #[test]
    fn erase_blocks_that_dont_cover_their_region_are_refused() {
        let cpu = Cpu {
            name: "core",
            fpu: false,
            interrupt_lines: 16,
            endian: Endian::Little,
        };
        let build = |memory: &'static [Region]| Bus::builder(cpu, memory, []).build().map(drop);
        assert_eq!(build(&WHOLE), Ok(()));
        for (memory, region) in [(&SHORT, "short"), (&OVER, "over"), (&WRAPS, "wraps")] {
            assert_eq!(build(memory), Err(Error::EraseBlocksMismatch { region }));
        }
    }

    /// One instance whose every access is gated on another's enable.
    fn gated() -> Bus {
        let cpu = Cpu {
            name: "core",
            fpu: false,
            interrupt_lines: 16,
            endian: Endian::Little,
        };
        let instance = |name, base, registers: &'static [RegisterSpec]| Peripheral {
            name,
            base,
            size: 0x100,
            interrupts: &[],
            registers,
        };
        Bus::builder(
            cpu,
            &MEMORY,
            [
                instance("CLOCKS", 0x4000_0000, &CLOCKS),
                instance("PORT", 0x4000_1000, &PORT),
            ],
        )
        .gate("PORT", Gate::by("CLOCKS", "ENR", "EN"))
        .build()
        .unwrap()
    }

    #[test]
    fn locate_ungated_finds_what_locate_finds_and_skips_the_gate() {
        let mut bus = gated();
        let landing = |located: Result<Located, Fault>| {
            located.map(|located| (located.slot, located.row, located.lane.shift))
        };
        let status_high_half = (0x4000_1006, Width::W16);
        for kind in [AccessKind::Read, AccessKind::Write] {
            let (address, width) = status_high_half;
            assert!(
                matches!(bus.locate(address, width, kind), Err(Fault::Gated { .. })),
                "{kind:?}"
            );
            assert_eq!(
                landing(bus.locate_ungated(address, width, kind)),
                Ok((1, 1, 16))
            );
        }
        assert_eq!(
            landing(bus.locate_ungated(0x4000_1006, Width::W32, AccessKind::Read)),
            Err(Fault::Misaligned {
                address: 0x4000_1006,
                width: Width::W32
            })
        );
        assert_eq!(
            landing(bus.locate_ungated(0x4000_1008, Width::W32, AccessKind::Read)),
            Err(Fault::Unmapped {
                address: 0x4000_1008
            })
        );
        bus.slot_mut(0).registers_mut().bus_write(0, ENABLE.mask());
        let (address, width) = status_high_half;
        assert_eq!(
            landing(bus.locate(address, width, AccessKind::Read)),
            landing(bus.locate_ungated(address, width, AccessKind::Read)),
            "the gate open"
        );
    }
}