rigless 0.0.5

// 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
//! and write rules both, 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 does not 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. Three mechanisms join them instead, and a
//! part that needs none of them declares none; ADR-0023.
//!
//! **A gate** is a bit of one instance that another answers behind. Where the vendor says a peripheral
//! whose clock is off does not answer its registers, that is one line of the part's description:
//!
//! ```
//! # use rigless::soc::{Access, Bus, Clock, Cpu, 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: "AHB1ENR", offset: 0, width: Width::W32,
//! #     reset: 0, access: Access::ReadWrite, read: ReadAction::None, write: WriteModify::None,
//! #     fields: &[flag("SPIEN", 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: "CM4", fpu: true, interrupt_lines: 8 };
//! # static MEMORY: [Region; 1] = [Region::ram("sram", 0x2000_0000, 1 << 16)];
//! # fn instances() -> [Peripheral; 3] { [
//! #     Peripheral { name: "RCC", base: 0x4000_0000, size: 0x400, interrupts: &[], registers: &ENABLES },
//! #     Peripheral { name: "SPI", 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 SPI is refused while RCC.AHB1ENR.SPIEN is clear.
//!     .gate("SPI", Gate::by("RCC", "AHB1ENR", "SPIEN"))
//!     // The same over named registers and in one direction: reads still answer.
//!     .gate_writes("SPI", &["DR"], Gate::by("RCC", "AHB1ENR", "SPIEN"))
//!     // A field the vendor's file omits, which a model declares and a gate may then name.
//!     .declare("RCC", "AHB1ENR", &DMAEN)
//!     // DMA reads every request any instance drives.
//!     .reads_requests("DMA")
//!     // SPI runs on RCC's first clock output.
//!     .clocked_by("SPI", Clock::output("RCC", 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 cannot cycle. An access a gate refuses is
//! [`Fault::Gated`] from [`crate::mcu::Mcu::read`] and [`crate::mcu::Mcu::write`]; a
//! [`crate::session::Session`] is what turns that into the zero the firmware sees, and it lists the
//! address in [`crate::session::Session::refused`].
//!
//! **A request line** is a level one instance drives and another reads, which is an interrupt's shape 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, and 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 is not
//! a reader sees none of them.
//!
//! The runtime carries no wiring table of its own, deliberately: what a driver's number means is the
//! reader's to decide. Wiring one instance to another is therefore three things the models own, not 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; and the part writes the table out and names the reader with
//! `reads_requests`. A DMA controller's table of which request lands on which stream 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, and
//! `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 is not 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, which is 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, and 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 would not make it. An address inside one of the
//! part's [`Region`]s reaches the engine's memory rather than 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 request changes first, 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 all three 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 crate::device::{
    Answer, ClockChange, DeviceContext, Effects, InterruptChange, PendingAccess, RegisterFile,
    RequestChange,
};
use crate::emulator::AccessKind;
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,
}

/// 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 `SPI1`.
    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:
/// `cr1::SPE.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; the register's unless the SVD says otherwise.
    pub access: Access,
    /// What a read does to the field; the register's unless the SVD says otherwise.
    pub read: ReadAction,
    /// What arithmetic a write performs; the register's 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)]
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; writes are ignored.
    ReadOnly,
    /// Writes land; reads return zero.
    WriteOnly,
    /// Both directions.
    ReadWrite,
    /// Only the first write after reset lands; reads return zero.
    WriteOnce,
    /// Only the first write after reset lands; 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 does not 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,
}

/// One memory region of the SoC.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
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,
}

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

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

    /// 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,
        }
    }
}

/// Why an SoC description does not 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,
    },
    /// 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 does not 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 does not 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; an instance runs on one clock")]
    ClockedTwice {
        /// The instance named twice.
        instance: &'static str,
    },
    /// A correction names a register the instance does not 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 does not declare, in the tables or by a model.
    #[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 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 could not complete.
#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)]
#[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 does not answer.
    #[error("{instance}.{register} is gated by {}.{}.{}", by.instance, by.register, by.field)]
    Gated {
        /// The instance that did not 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,
    },
}

/// 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,
}

/// 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 = slots[by_slot]
        .peripheral
        .registers
        .iter()
        .position(|register| register.name == gate.register)
        .ok_or(Error::UnknownRegister {
            instance: gate.instance,
            register: gate.register,
        })?;
    let mask = slots[by_slot].peripheral.registers[by_row]
        .fields
        .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| {
            slots[gated]
                .peripheral
                .registers
                .iter()
                .position(|register| register.name == *name)
                .ok_or(Error::UnknownRegister {
                    instance: spec.instance,
                    register: 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 is no number to mistype.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
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 is 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,
}

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>,
    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,
}

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, so the bus can find it by name.
    ///
    /// A generated table is the vendor's file transcribed and stays that way, so a field the vendor omits
    /// is the model's own (ADR-0022). A gate names a field, and a gate on one of those fields has nothing
    /// to resolve against unless the part says here what the model declares.
    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 does not 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 is 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 does not 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, which is 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
    }

    /// Checks the description and produces the bus, naming what is at fault otherwise.
    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 });
        }
        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, register) = instance
                .peripheral
                .registers
                .iter()
                .enumerate()
                .find(|(_, register)| register.name == correction.register)
                .ok_or(Error::UnknownRegister {
                    instance: correction.instance,
                    register: correction.register,
                })?;
            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 = instance
                .peripheral
                .registers
                .iter()
                .position(|register| register.name == correction.register)
                .ok_or(Error::UnknownRegister {
                    instance: correction.instance,
                    register: correction.register,
                })?;
            instance.registers.correct_write(row, correction.rule);
        }

        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();
        }

        Ok(Bus {
            cpu: self.cpu,
            memory: self.memory,
            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))
}

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 does not answer what the
/// peripheral *does*. That is 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>,
    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 cannot move time on.
/// Several models legitimately schedule at one instant; 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 is 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.
pub(crate) const SETTLE_LIMIT: u32 = 2 * 2 * (65_535 + 4 * 65_535);

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(),
            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();
        }
        self.effects = 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
            .slots
            .partition_point(|slot| slot.peripheral.base <= address);
        let index = candidates.checked_sub(1)?;
        self.slots[index]
            .peripheral
            .contains(address)
            .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)
    }

    /// One slot, for the MCU calling the model that owns it.
    pub(crate) 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> {
        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, so
        // that an address the instance does not carry is still reported as the gap in the map it is
        // rather than as the instance declining to answer.
        if 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,
            });
        }
        Ok(Located {
            slot: index,
            row,
            lane: Lane {
                shift: byte_in_register * 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 is not evaluated
    /// through another, which both avoids a cycle, since the regulator is clock-gated and holds the bit
    /// that opens the backup domain, and is 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 engine 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(..)
    }

    /// 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)
    }

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

    /// The oldest answer the runtime has not 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 `address`, if any; an address in none of them is the peripheral bus's.
    pub(crate) fn region_holding(&self, address: u64) -> Option<&'static Region> {
        self.memory.iter().find(|region| region.contains(address))
    }
}

/// 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,
}