rigless 0.0.4

// Copyright (c) 2026 Rigless Labs.
// SPDX-License-Identifier: Apache-2.0
//! The power controller of RM0090 rev 22 chapter 5, written against the `pwr` layout.
//!
//! Sections 5.5.1 and 5.5.2 are the `PWR_CR` and `PWR_CSR` of the STM32F42xxx and STM32F43xxx, which is
//! this SoC. Sections 5.4.1 and 5.4.2 are the same two registers for the STM32F405/407/415/417: they are
//! numbered alike and read almost the same, and they are the wrong part. Only 5.5 carries over-drive at
//! all. Every register citation here is 5.5; the prose of 5.1 and 5.2 covers both parts and is cited as it
//! stands. This is the same trap chapter 6 sets against chapter 7 for the clock controller.
//!
//! | Register or section | Behaviour | Source | Test |
//! |---|---|---|---|
//! | Reset state | Scale 1 selected, nothing ready, the detector off | 5.5.1, 5.5.2 | `reset_selects_scale_one_with_nothing_ready` |
//! | `CR` `VOS` | Three scales, and the regulator reaching the one selected raises `VOSRDY` | 5.5.1, 5.5.2 | `a_new_voltage_scale_becomes_ready_after_the_regulator_settles`, `a_scale_changed_mid_settling_starts_its_own` |
//! | `CR` `VOS` encoding | `00` is reserved and reads as scale 3, `01` scale 3, `10` scale 2, `11` scale 1 | 5.5.1 | `the_reserved_scale_encoding_is_scale_three` |
//! | `CSR` `VOSRDY` | Hardware's; a write cannot set it, which ST's file allows | 5.5.2 | `software_cannot_set_a_flag_hardware_owns`, `a_firmware_that_only_polls_the_status_register_still_sees_the_regulator` |
//! | `CR` `ODEN` | Enabling over-drive arms `ODRDY`; clearing it drops `ODRDY`, `ODSWEN`, and `ODSWRDY` together | 5.1.4, 5.5.1 | `over_drive_comes_up_in_two_steps`, `clearing_the_enable_takes_the_switch_with_it`, `clearing_the_over_drive_alone_takes_the_switch_bit_with_it` |
//! | `CR` `ODSWEN` | Stands as soon as it is written; the switch itself waits for `ODRDY` | 5.1.4, 5.5.1 | `the_switch_waits_for_the_over_drive_to_be_ready`, `over_drive_comes_up_in_two_steps` |
//! | The manual's entry sequence | Steps 3 to 5 of section 5.1.4, run as a firmware runs them | 5.1.4 | `the_manuals_entry_sequence_leaves_both_spin_loops` |
//! | The manual's exit sequences | Both: the two bits cleared together, and the switch cleared before the enable | 5.1.4 | `either_exit_sequence_brings_the_regulator_back` |
//! | `CR` `DBP` | Stored, and inside this peripheral it gates `BRE` | 5.5.1, 5.5.2 | `bre_is_writable_only_once_dbp_is_set` |
//! | `CSR` `BRE`, `BRR` | Enabling the backup regulator raises `BRR`. Clearing it drops the flag, which the page does not say in as many words: bit 3 gives only what sets `BRR`, and bit 9 says that with `BRE` reset "the backup regulator is switched off", from which a regulator that is off is not a regulator that is ready | 5.5.2 | `the_backup_regulator_becomes_ready` |
//! | `CR` `PVDE`, `PLS` | The detector and its eight thresholds | 5.5.1 | `the_detector_reports_the_supply_against_its_threshold` |
//! | `CSR` `PVDO` | Set while the supply is below the threshold, with the datasheet's hysteresis, and zero whenever the detector is off | 5.5.2 | `the_detector_reports_the_supply_against_its_threshold`, `the_detector_crosses_every_rising_threshold_where_the_datasheet_puts_it`, `the_detector_holds_its_output_through_the_hysteresis`, `a_disabled_detector_reports_nothing` |
//! | `CR` `CWUF`, `CSBF` | Write one to clear `WUF` and `SBF`; both read zero | 5.5.1, 5.5.2 | `the_clear_bits_clear_their_flags_and_read_zero` |
//! | `CSR` `UDRDY` | Only a Stop entry sets these, so the model never does, and a write cannot either | 5.5.2 | `software_cannot_set_a_flag_hardware_owns` |
//! | `CSR` `WUF`, `SBF` | Hardware's, and only the `CR` clear bits clear them | 5.5.2 | `software_cannot_set_a_flag_hardware_owns` |
//! | `CSR` `EWUP` | Stored; the pin it enables reaches no wire | 5.5.2 | `the_wake_up_pin_enable_is_stored` |
//! | `CR` `LPDS`, `PDDS`, `FPDS`, `MRUDS`, `LPUDS`, `UDEN`, `ADCDC1` | Stored; what they qualify is a mode the processor enters, not a register behaviour | 5.5.1 | `the_deepsleep_configuration_is_stored` |
//!
//! **What the model leaves out, and why.**
//!
//! | Behaviour | Source | Reason |
//! |---|---|---|
//! | `VOSRDY` is up shortly after reset on the part, because the regulator is always reaching for the scale `VOS` selects | 5.5.2 | A model is first called when the firmware touches the peripheral, so the settling starts at that first access, whether it is a read or a write. A firmware that never touches `PWR` at all cannot tell the difference |
//! | The instance's interrupt line | 5.1.2, RM0090 rev 22 table 63 line 1 | The detector's output is "internally connected to the EXTI line 16 and can generate an interrupt if enabled through the EXTI registers", so what the vector table calls the PWR interrupt is the EXTI raising it. This model drives no line; the EXTI is its own model, as it is for the GPIO port's pins |
//! | Stop, Standby, and under-drive themselves, and everything that only entering one can set: `WUF`, `SBF`, and `UDRDY` rising, and over-drive being disabled on a Stop entry | 5.1.4, 5.2 | The processor enters deepsleep inside the engine, which sends the runtime no event for it. The bits are stored and the clear paths work, so a firmware reading them after a reset sees the truth |
//! | `VOS` is writable only while the PLL is off and the HSI or HSE is the system clock, the new value is active only once the PLL is on, and with the PLL off the regulator is at scale 3 whatever `VOS` says | 5.1.4, 5.5.1 | `PLLON` and `SWS` are the RCC's bits, and no model can read another's register yet, RL-112. [`Pwr::scale`] therefore answers the scale `VOS` selects, which is the scale the part is at once the PLL is running |
//! | The over-drive switch taking `Tod_swdis`, 20 us typical, to go back to normal mode, which is what step 4 of both exit sequences waits for | 5.1.4, DS9405 rev 13 table 23 | The model drops `ODSWRDY` inside the write that asks for it, so that wait ends at once. A simplification, and the model's own; it errs in the direction that cannot hang a firmware, as the same choice does for a ready flag in chapter 6 |
//! | `CWUF` clearing `WUF` "after 2 System clock cycles", where the model clears it inside the write | 5.5.1 | The runtime counts nothing finer than the access, and no firmware can observe the gap without a cycle counter it does not have |
//! | `BRE` and `BRR` surviving a system reset, and being reset only by a backup domain reset | 5.5.2 | The register file has one reset, the one the SoC is built with. Modelling two needs a reset kind the runtime does not carry |
//! | `DBP` also protecting `RCC_BDCR`, the RTC and its backup registers, and the backup SRAM region | 5.5.1 | Only `BRE` is this peripheral's; the rest are registers and a memory region no model can reach from here, RL-112 |
//! | `ODEN` and `ODSWEN` require the HSI or HSE to be the system clock | 5.5.1 | `SWS` is the RCC's, RL-112 |
//! | The system clock stalls during an over-drive switch | 5.1.4, 5.5.1 | Stalling the processor is the engine's to do, and the runtime has no way to ask it to |
//! | Over-drive and under-drive are unavailable when the regulator is bypassed, and over-drive when `VDD` is 1.8 to 2.1 V | 5.1.4 table 23 | The bypass is a pin strap the machine does not describe. The supply is known, so the voltage condition could be checked; it is left out because the part it would refuse is one no board here fits |
//! | ES0206 rev 24 2.2.12: over-drive and under-drive unavailable | ES0206 rev 24 | Not applicable. Table 3 marks it for revisions A and Y, and `memory_map.rs` gives `DBGMCU_IDCODE` a `REV_ID` of revision 1 with its reason |
//! | ES0206 rev 24 2.2.9: the backup domain protection takes effect some cycles after `DBP` is programmed | ES0206 rev 24 | A bus-visible latency on the wiring `DBP` itself waits on, RL-112 |
//! | ES0206 rev 24 2.2.11: a backup domain reset missed after its supply drops into a window a few mV wide | ES0206 rev 24 | The model has no `VBAT` rail and no power cycle |
//!
//! **Where this model departs from the vendor's file.** ST types `VOSRDY`, `UDRDY`, `CWUF`, and `CSBF`
//! more permissively than sections 5.5.1 and 5.5.2 do, so the model puts all four back; the register file
//! enforces the rest from the table, which stays the vendor's. ST also carries the STM32F405's names for
//! `PWR_CR` bits 11 and 10, which section 5.5.1 calls `MRUDS` and `LPUDS`, and the model declares those
//! beside it. Section 5.1.4 calls bit 17 `ODSW` where 5.5.1 calls it `ODSWEN`; they are one bit.

use crate::device::{Device, DeviceContext, RegisterFile};
use crate::soc::{Access, FieldSpec, ReadAction, WriteModify};
use crate::time::{EventId, VirtualNanos};

use crate::soc::stm32f427::generated::pwr::{Register, cr, csr};

/// What the manual names where ST's file names it after another part.
const fn field(name: &'static str, bit: u8, width: u8) -> FieldSpec {
    FieldSpec {
        name,
        bit,
        width,
        access: Access::ReadWrite,
        read: ReadAction::None,
        write: WriteModify::None,
    }
}

/// `MRUDS`, RM0090 rev 22 section 5.5.1 bit 11; ST's file carries the STM32F405's name, `MRLVDS`.
pub static MRUDS: FieldSpec = field("MRUDS", 11, 1);
/// `LPUDS`, RM0090 rev 22 section 5.5.1 bit 10; ST's file carries the STM32F405's name, `LPLVDS`.
pub static LPUDS: FieldSpec = field("LPUDS", 10, 1);

/// The two bits of `CSR` ST types more permissively than RM0090 rev 22 section 5.5.2 does; the register
/// file enforces the rest. Nothing in this model sets either, so putting them back is the whole rule.
const CSR_HARDWARE: u64 = csr::VOSRDY.mask() | csr::UDRDY.mask();

/// The regulator's settling and the over-drive's two steps.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
enum Ready {
    /// The backup regulator, which `BRE` starts.
    BackupRegulator = 0,
    /// The main regulator reaching the scale `VOS` selects.
    Scale = 1,
    /// The over-drive regulator coming up, which `ODEN` starts.
    OverDrive = 2,
    /// The switch to the over-drive rail, which `ODSWEN` starts.
    OverDriveSwitch = 3,
}

impl Ready {
    /// Every one, each at the index its own discriminant gives.
    const ALL: [Self; 4] = [
        Self::BackupRegulator,
        Self::Scale,
        Self::OverDrive,
        Self::OverDriveSwitch,
    ];

    /// The flag in `CSR` this one raises.
    fn flag(self) -> &'static FieldSpec {
        match self {
            Self::Scale => csr::VOSRDY,
            Self::OverDrive => csr::ODRDY,
            Self::OverDriveSwitch => csr::ODSWRDY,
            Self::BackupRegulator => csr::BRR,
        }
    }

    /// The bit that asks for this one, and the register it lives in. `VOS` is a selection rather than an
    /// enable, so the regulator is always reaching for some scale and the scale has none.
    fn enable(self) -> Option<(Register, &'static FieldSpec)> {
        match self {
            Self::Scale => None,
            Self::OverDrive => Some((Register::Cr, cr::ODEN)),
            Self::OverDriveSwitch => Some((Register::Cr, cr::ODSWEN)),
            Self::BackupRegulator => Some((Register::Csr, csr::BRE)),
        }
    }

    /// How long this one takes. DS9405 rev 13 table 23 gives the over-drive switch 45 us typical; nothing
    /// fixes the other three, so they are the model's own, large enough for a poll loop to turn.
    fn settling(self) -> VirtualNanos {
        VirtualNanos(match self {
            Self::OverDriveSwitch => 45_000,
            Self::Scale | Self::OverDrive | Self::BackupRegulator => 10_000,
        })
    }
}

/// The regulator's output scale, RM0090 rev 22 section 5.5.1 bits 15:14.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum Scale {
    /// The highest, which over-drive extends; the reset value.
    One,
    /// The middle scale.
    Two,
    /// The lowest, and what `00` selects as well as `01`.
    Three,
}

/// The detector's thresholds in millivolts, one pair per `PLS` level, named as DS9405 rev 13 table 22
/// names them: the supply's rising edge then its falling one. `PVDO` follows the supply the other way
/// round, so the rising figure is where it clears.
const PVD_THRESHOLDS_MV: [(u32, u32); 8] = [
    (2140, 2040),
    (2300, 2190),
    (2450, 2350),
    (2600, 2510),
    (2760, 2660),
    (2930, 2840),
    (3030, 2930),
    (3140, 3030),
];

/// The power controller of one STM32F42xxx, RM0090 rev 22 chapter 5.
#[derive(Debug)]
pub struct Pwr {
    supply_mv: u32,
    pending: [Option<EventId>; Ready::ALL.len()],
    shadow: Shadow,
}

impl Default for Pwr {
    fn default() -> Self {
        Self::new()
    }
}

impl Pwr {
    /// The power controller of a bare part, with no rail on it until a board regulates one through
    /// [`Pwr::set_supply`]. A rail is a point a board picks inside the range DS9405 rev 13 table 17 allows
    /// the part, so the part does not pick one for it.
    #[must_use]
    pub fn new() -> Self {
        Self {
            supply_mv: 0,
            pending: [None; Ready::ALL.len()],
            shadow: Shadow::default(),
        }
    }

    /// The board's supply rail has moved: the one analogue input of chapter 5, and the only thing outside
    /// the register file that can change `PVDO`, RM0090 rev 22 section 5.5.2 bit 2.
    pub fn set_supply(&mut self, millivolts: u32, registers: &mut RegisterFile) {
        self.supply_mv = millivolts;
        self.refresh_detector(registers);
        self.store_shadow(registers);
    }

    /// The scale `VOS` selects, RM0090 rev 22 section 5.5.1, where `00` is reserved and selects scale 3.
    /// Section 5.1.4's rule that the PLL off means scale 3 whatever is selected needs the RCC, RL-112.
    #[must_use]
    pub fn scale(registers: &RegisterFile) -> Scale {
        match cr::VOS.get(registers.get(Register::Cr)) {
            0b10 => Scale::Two,
            0b11 => Scale::One,
            _ => Scale::Three,
        }
    }
}

/// What a write must not change, kept because a model sees the value written and not the one before it.
/// `the_shadow_starts_at_the_reset_values` holds its starting point against the register file.
#[derive(Debug)]
struct Shadow {
    cr: u64,
    csr: u64,
}

impl Default for Shadow {
    fn default() -> Self {
        Self {
            cr: 0x0000_C000,
            csr: 0,
        }
    }
}

impl Device for Pwr {
    type Register = Register;

    /// The model answers no read; it is here because the regulator is always reaching for the scale `VOS`
    /// selects, so a firmware that only polls `PWR_CSR` must still see `VOSRDY` rise.
    fn read(
        &mut self,
        _register: Register,
        registers: &mut RegisterFile,
        context: &mut DeviceContext<'_>,
    ) -> Option<u64> {
        self.follow_settling(registers, context);
        self.store_shadow(registers);
        None
    }

    fn write(
        &mut self,
        register: Register,
        written: u64,
        registers: &mut RegisterFile,
        context: &mut DeviceContext<'_>,
    ) {
        match register {
            Register::Cr => self.write_cr(written, registers, context),
            Register::Csr => self.write_csr(registers, context),
        }
        self.store_shadow(registers);
    }

    fn on_event(
        &mut self,
        event: EventId,
        registers: &mut RegisterFile,
        _context: &mut DeviceContext<'_>,
    ) {
        let Some(index) = self
            .pending
            .iter()
            .position(|pending| *pending == Some(event))
        else {
            // A model keeps the id it last scheduled and ignores any other; there is no cancel.
            return;
        };
        // A settling that has landed owns its slot no longer. [`Pwr::follow_settling`] clears it too, on
        // the path where a flag is dropped rather than raised, which is the one this does not reach.
        self.pending[index] = None;
        let which = Ready::ALL[index];
        let csr_value = registers.get(Register::Csr);
        registers.set(Register::Csr, which.flag().set(csr_value, 1));
        self.store_shadow(registers);
    }
}

impl Pwr {
    fn store_shadow(&mut self, registers: &RegisterFile) {
        self.shadow = Shadow {
            cr: registers.get(Register::Cr),
            csr: registers.get(Register::Csr),
        };
    }

    /// Whether the thing a settling belongs to is asked for and able to start: the switch needs `ODRDY` as
    /// well as its own bit, RM0090 rev 22 section 5.5.1 bit 17, and the other two need only their bit.
    fn is_started(registers: &RegisterFile, which: Ready) -> bool {
        let asked = which
            .enable()
            .is_none_or(|(register, enable)| enable.is_set(registers.get(register)));
        asked
            && (which != Ready::OverDriveSwitch || csr::ODRDY.is_set(registers.get(Register::Csr)))
    }

    /// `CR`: the scale, the over-drive pair, the detector, and the two clear bits.
    fn write_cr(
        &mut self,
        written: u64,
        registers: &mut RegisterFile,
        context: &mut DeviceContext<'_>,
    ) {
        // RM0090 rev 22 section 5.5.1 bits 3 and 2: CSBF and CWUF clear their flags and are always read
        // as zero. ST's file types them plain read-write and gives them no rule, so the model applies it.
        let mut csr_value = registers.get(Register::Csr);
        if cr::CSBF.is_set(written) {
            csr_value = csr::SBF.set(csr_value, 0);
        }
        if cr::CWUF.is_set(written) {
            csr_value = csr::WUF.set(csr_value, 0);
        }
        registers.set(Register::Csr, csr_value);
        let cr_value = registers.get(Register::Cr);
        let cleared = cr::CWUF.set(cr::CSBF.set(cr_value, 0), 0);
        registers.set(Register::Cr, cleared);

        // RM0090 rev 22 section 5.5.1 bit 17 names two things that clear ODSWEN, and "must only be set
        // when ODRDY is set" is a rule on software rather than an interlock. Refusing the write instead
        // would hang a firmware that sets both bits in one word and then polls both flags.
        let cr_value = registers.get(Register::Cr);
        if !cr::ODEN.is_set(cr_value) {
            registers.set(Register::Cr, cr::ODSWEN.set(cr_value, 0));
        }

        if cr::VOS.get(self.shadow.cr) != cr::VOS.get(registers.get(Register::Cr)) {
            // A new scale is not reached yet, section 5.1.4, so the flag drops and the regulator settles.
            let csr_value = registers.get(Register::Csr);
            registers.set(Register::Csr, csr::VOSRDY.set(csr_value, 0));
            self.pending[Ready::Scale as usize] = None;
        }
        self.follow_settling(registers, context);
        self.refresh_detector(registers);
    }

    /// `CSR`: the backup regulator behind `DBP`, the under-drive flags, and the flags hardware owns.
    fn write_csr(&mut self, registers: &mut RegisterFile, context: &mut DeviceContext<'_>) {
        registers.restore(Register::Csr, CSR_HARDWARE, self.shadow.csr);
        // RM0090 rev 22 section 5.5.2 bit 9: "The DBP bit of the PWR_CR register must be set before BRE
        // can be written." Both bits are this peripheral's, so this is the one half of the backup domain's
        // write protection the model can enforce without reading another instance.
        if !cr::DBP.is_set(registers.get(Register::Cr)) {
            registers.restore(Register::Csr, csr::BRE.mask(), self.shadow.csr);
        }
        self.follow_settling(registers, context);
    }

    /// Arms or drops each settling: one that is asked for and not yet ready gets its instant scheduled,
    /// and one that is no longer asked for loses its flag.
    fn follow_settling(&mut self, registers: &mut RegisterFile, context: &mut DeviceContext<'_>) {
        for (index, which) in Ready::ALL.iter().enumerate() {
            let flag = which.flag();
            let csr_value = registers.get(Register::Csr);
            if !Self::is_started(registers, *which) {
                registers.set(Register::Csr, flag.set(csr_value, 0));
                self.pending[index] = None;
                continue;
            }
            if !flag.is_set(csr_value) && self.pending[index].is_none() {
                self.pending[index] =
                    Some(context.schedule(VirtualNanos(context.now().0 + which.settling().0)));
            }
        }
    }

    /// `PVDO`: set while the supply sits below the threshold `PLS` selects, and cleared once it climbs back
    /// over the rising figure. RM0090 rev 22 section 5.5.2 bit 2, DS9405 rev 13 table 22.
    fn refresh_detector(&self, registers: &mut RegisterFile) {
        let cr_value = registers.get(Register::Cr);
        let csr_value = registers.get(Register::Csr);
        if !cr::PVDE.is_set(cr_value) {
            // Section 5.5.2: the output "is valid only if PVD is enabled by the PVDE bit", and is zero
            // after a reset until it is.
            registers.set(Register::Csr, csr::PVDO.set(csr_value, 0));
            return;
        }
        // PLS is three bits wide, so the table has a row for every value it can take.
        let level = usize::try_from(cr::PLS.get(cr_value)).expect("three bits fit a usize");
        let (rising_mv, falling_mv) = PVD_THRESHOLDS_MV[level];
        let below = if csr::PVDO.is_set(csr_value) {
            self.supply_mv < rising_mv
        } else {
            self.supply_mv < falling_mv
        };
        registers.set(Register::Csr, csr::PVDO.set(csr_value, u64::from(below)));
    }
}

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

    /// The shadow's starting point is the manual's reset values, written out so that the first write of a
    /// run has something true to compare against. If the table or a correction ever moves, this fails
    /// rather than silently letting that first write through.
    #[test]
    fn the_shadow_starts_at_the_reset_values() {
        let mut soc = crate::mcu::Single::new(stm32f427::builder(), "PWR", Pwr::new()).unwrap();
        let registers = soc.registers();
        let shadow = Shadow::default();
        assert_eq!(shadow.cr, registers.get(Register::Cr));
        assert_eq!(shadow.csr, registers.get(Register::Csr));
    }
}