// Copyright (c) 2026 Rigless Labs.
// SPDX-License-Identifier: MIT OR Apache-2.0
//! The direct memory access controllers of RM0433 rev 9 chapter 15, written against the `dma1` layout, by
//! the model RM0090 rev 22 gives the STM32F427 too, in [`crate::soc::st::dma`].
//!
//! One layout serves both controllers, `DMA1` and `DMA2`, and they differ only in which of DMAMUX1's
//! sixteen channels their eight streams listen to: section 17.3.2 connects DMAMUX1 channels 0 to 7 to the
//! streams of `DMA1` and channels 8 to 15 to those of `DMA2`. A stream has no channel select of its own on
//! this part, so the `CHSEL` field of the STM32F4 stream control register is gone, and a stream hears one
//! request line and no other. Every citation is RM0433 rev 9 unless it names another document.
//!
//! A stream is a byte pipe with a FIFO in the middle. It loads from the source port and stores to the
//! destination port, one access at a time, as one AHB master is. Everything a transfer does happens at the
//! instant of the access or the request that caused it, because a settle is the part reaching its next
//! steady state rather than time passing.
//!
//! **What reaches what.** Table 3 gives the memory port and the peripheral port of each controller the
//! same slaves, every one of them except ITCM and DTCM. Both ports reach the memories, which is what
//! section 15.3.3 asks for memory-to-memory transfers, so a stream of either controller copies one memory
//! to another, unlike the STM32F4, where the first controller's peripheral port is not on the bus matrix.
//! Section 2.1.6 words it differently: it gives the memory bus the memories alone, where Table 3 also
//! gives it the peripherals. The model follows Table 3. A stream that addresses a tightly coupled memory
//! is refused by the bus matrix, and the manual's only word for a refused access is the bus error that
//! section 15.3.20 gives `TEIF`. The model ends the stream in that flag, and does not make the access
//! that would have landed in memory the controller cannot reach.
//!
//! **What the controller tells the multiplexer.** Section 15.3.4 has the controller send an acknowledge
//! to the peripheral as soon as it accesses it. The multiplexer counts served requests, section 17.4.4, so
//! the stream drives its request output `n` high and low again at the instant it makes the peripheral
//! access that serves a request. Output `n` is the acknowledge of stream `n`.
//!
//! **The counter follows the peripheral port.** Section 15.3.7 gives it the peripheral bus's width.
//! Section 15.3.15 ends a transfer when it "has reached zero in the memory-to-peripheral mode", where the
//! peripheral is the destination, and section 15.3.17's `0xFFFF - DMA_SxNDTR` counts what the peripheral
//! moved. The manual doesn't agree with itself about the instant. Section 15.3.4 makes the decrement the
//! third of three operations, after the store, which for a stream whose two ports are decoupled by the
//! FIFO is a different moment from the peripheral's own access. And section 15.3.14 has the counter after
//! a flush "indicate how many data items are currently available in the destination memory", which only
//! holds if it hadn't already come down for what the FIFO was holding. Both of those read the counter
//! against the memory port. This model takes the peripheral port, which is the reading the other three
//! sections carry, and makes the flush the exception by freezing the counter there.
//!
//! **What the model handles and what falls to the register file.** Every register of the chapter has an
//! arm in [`Device::write`](crate::device::Device::write) and the model overrides no read, so the register file answers every read from
//! the values the model keeps in it. `DMA_LISR` and `DMA_HISR` are read-only and the file drops a write to
//! either. `DMA_LIFCR` and `DMA_HIFCR` take their write in the model, which applies it to the status
//! register and clears itself. The model owns the flags, the `FS` level, the counter, the enable and the
//! forced configuration bits, and it restores the write-protected registers while a stream runs.
//!
//! | Register or section | Behavior | Source | Test |
//! |---|---|---|---|
//! | Request mapping | A stream hears DMAMUX1's output of its own index: `DMA1` streams 0 to 7 channels 0 to 7 and `DMA2` streams 0 to 7 channels 8 to 15. No other instance's request reaches it | 15.1, 15.3.5, 17.3.2 | `a_request_reaches_only_the_stream_of_its_multiplexer_channel` |
//! | Serving a peripheral | A stream takes a word off a peripheral, or gives one to it, while the request stands, and the access it makes is what clears the flag behind the request. The stream acknowledges each served request to the multiplexer | 15.3.4, 15.3.8 | `a_peripheral_to_memory_stream_is_driven_by_a_fake_peripherals_request_through_the_multiplexer`, `a_peripheral_drives_a_stream_each_way_and_the_words_come_back`, `every_served_request_is_acknowledged_to_the_multiplexer` |
//! | Either port on a peripheral | Both ports reach the bus matrix, so a stream moves words between two peripherals with no memory in between | 15.3.3, 15.3.8, Table 3 | `a_stream_carries_words_from_one_peripheral_to_another` |
//! | `DIR` | Peripheral-to-memory, memory-to-peripheral and memory-to-memory, with the source and destination of Table 110 | 15.3.8, 15.5.5 | `each_direction_moves_its_block_between_the_right_two_ports` |
//! | Memory to memory | Runs as soon as the stream is enabled, with no request, on either controller | 15.3.3, 15.3.8, Table 3 | `memory_to_memory_copies_a_block_with_no_request_on_either_controller` |
//! | The boot loader's copy | A byte-wide memory-to-memory copy of 128 bytes from flash to SRAM, `CR` written whole and then `EN` set by a read-modify-write, and a spin on `EN` clearing | 15.3.8, 15.5.5 | `a_stream_copies_flash_to_ram_the_way_the_boot_loader_does` |
//! | Memory the controller cannot reach | A transfer whose access lies in ITCM or DTCM ends in `TEIF` with `EN` cleared, and nothing lands. The same transfer to any other memory runs | 2.1.6, Table 3, 15.3.20 | `a_transfer_into_the_tightly_coupled_memories_ends_in_a_transfer_error`, `a_transfer_from_the_tightly_coupled_memories_ends_in_a_transfer_error`, `every_other_memory_is_reachable` |
//! | Direct mode | There's no FIFO to fill: a memory-to-peripheral stream preloads one item and a peripheral-to-memory one drains each straight through, `MSIZE` follows `PSIZE`, and the burst fields are forced to single | 15.3.14, 15.5.5 | `enabling_a_stream_applies_every_rule_the_configuration_forces`, `the_counter_counts_the_peripheral_ports_items_and_not_the_memory_ports` |
//! | FIFO mode | Bytes gather to the threshold before the destination is written, the tail of a transfer drains whatever is left, and a memory-to-peripheral stream reloads the FIFO whole once its level falls to the threshold | 15.3.8, 15.3.14 | `the_fifo_holds_bytes_until_the_threshold_and_then_drains`, `a_half_threshold_drains_eight_bytes_at_a_time`, `a_memory_to_peripheral_stream_reloads_the_fifo_at_its_threshold` |
//! | Packing | Source and destination widths differ and the bytes repack little-endian, Table 112 | 15.3.12 | `bytes_repack_between_two_widths_in_the_order_the_table_gives` |
//! | `FS` | The FIFO level as the encodings of section 15.5.10 give it | 15.5.10 | `the_fifo_holds_bytes_until_the_threshold_and_then_drains` |
//! | `PINC`, `MINC`, `PINCOS` | Each port's pointer steps by its own width, or by four where `PINCOS` fixes it, or stands still | 15.3.9, 15.5.5 | `a_fixed_pointer_writes_one_address_and_an_incrementing_one_walks`, `the_peripheral_step_is_four_where_pincos_survives_the_enable` |
//! | `NDTR` | Counts peripheral-port items, decrements as they move, is read-only while the stream is enabled, holds what's left after a suspension, is reloaded with what was last programmed at every enable, and serves nothing at zero | 15.3.4, 15.3.16, 15.5.6 | `the_counter_follows_the_peripheral_port_and_survives_a_suspension`, `the_counter_counts_the_peripheral_ports_items_and_not_the_memory_ports`, `a_stream_enabled_again_runs_the_block_it_was_programmed_with`, `a_stream_enabled_with_no_count_serves_nothing_and_stays_enabled` |
//! | Circular | The counter and the pointers start again and the requests go on being served | 15.3.10 | `circular_mode_starts_the_block_again` |
//! | Double buffer | `CT` names the pointer in use and swaps at each end of transaction. The current one is write-protected, and writing it is a transfer error | 15.3.11 | `double_buffer_swaps_its_target_at_each_end`, `writing_the_target_in_use_is_a_transfer_error` |
//! | `HTIF`, `TCIF` | Half and whole of the block as the destination port takes it | 15.3.19 | `the_half_and_complete_flags_stand_at_the_halves_of_the_block` |
//! | `TEIF`, `FEIF` | An access the bus refuses, a write to the target in use, and a FIFO threshold the memory burst doesn't divide, each of which clears `EN` and ends the block where it stands | 15.3.20, Table 114 | `a_stream_pointed_at_an_address_nothing_answers_ends_in_a_transfer_error`, `a_threshold_the_burst_does_not_divide_is_a_fifo_error`, `a_stream_stopped_while_an_access_was_in_flight_does_not_take_the_answer` |
//! | `LIFCR`, `HIFCR` | A written one clears its flag in `LISR` or `HISR` | 15.5.3, 15.5.4 | `a_written_one_clears_its_own_flag_and_no_other` |
//! | Interrupts | Each stream raises its own line while an enabled flag stands: `DMA1` streams 0 to 6 on lines 11 to 17 and stream 7 on line 47, `DMA2` streams 0 to 4 on 56 to 60 and 5 to 7 on 68 to 70 | 15.4, Table 116, Table 147 | `each_enable_raises_the_streams_own_line`, `each_flag_raises_the_line_only_under_its_own_enable` |
//! | Suspension | Clearing `EN` ends the transfer, sets `TCIF`, and drains what the FIFO still holds toward memory | 15.3.14, 15.3.16 | `clearing_the_enable_flushes_what_the_fifo_holds`, `a_flush_writes_a_partial_last_item_at_the_memory_width` |
//! | `PFCTRL`, the peripheral as flow controller | The counter is forced to `0xFFFF` at the enable and circular mode is forced off. The stream ends when the counter reaches zero or `EN` is cleared, and `0xFFFF - NDTR` is what moved. Section 15.3.17 has the peripheral signal its last data and no instance of this part does, so that end is left out below | 15.3.17, 15.5.5 | `the_peripheral_as_flow_controller_forces_the_counter_and_forbids_circular` |
//! | Register protection | The configuration, counter and pointer registers take no write while `EN` stands. Bit 20 is held with them | 15.5.5, 15.5.6 | `the_configuration_registers_take_no_write_while_the_stream_runs` |
//! | Enable procedure | `DBM` forces `CIRC`, memory-to-memory forces `PFCTRL` clear and the FIFO on, and the counter and pointers are taken at the enable | 15.3.19, 15.5.5, 15.5.10 | `enabling_a_stream_applies_every_rule_the_configuration_forces` |
//! | `TRBUFF` | Stored with the rest of `SxCR` and protected while the stream runs. It selects "bufferable transfers", which the model's accesses don't distinguish | 15.5.5 | `the_configuration_registers_take_no_write_while_the_stream_runs` |
//! | Reset | A system reset leaves every stream idle with an empty FIFO | 15.5.5 | `a_reset_leaves_every_stream_idle` |
//! | Determinism and the snapshot | Two runs of one script are one run, and the state serializes mid-transfer | none | `two_runs_of_one_script_are_the_same_run`, `the_model_state_round_trips_through_a_snapshot` |
//! | ES0392 rev 15 2.20.4 | Applicable to revision V, table 3 marking it `A`. A USART request served while a concurrent transfer occurs "may not be served and the DMA stream may stay locked". The workaround is `TRBUFF`. See the table below | ES0392 rev 15 | none |
//! | ES0392 rev 15 2.2.28 | Applicable to revision V, marked `A`. HASH input data may be corrupted when a HASH transfer shares a controller with another stream. The part has no HASH | ES0392 rev 15 | none |
//!
//! **What the model leaves out, and why.**
//!
//! | Behavior | Source | Reason |
//! |---|---|---|
//! | The arbiter, and `PL` as anything but a stored field | 15.3.6 | Priority decides which of two streams reaches the bus matrix first in a cycle neither of them has. Every stream here is served in stream order, which is the arbiter's own tie-break, and nothing a firmware can read distinguishes the two |
//! | `DMEIF`, the direct mode error | 15.3.20 | It's set "because the memory bus was not granted" while a second request arrives. The memory bus here is always granted within the access that asked for it, so the condition can't arise. The bit and its enable are stored and never set |
//! | `FEIF` from an underrun or an overrun | 15.3.20 | The same: both are the FIFO caught out by a bus that didn't grant in time. The threshold error of Table 114, which is a configuration and not a race, is modeled |
//! | A burst as an indivisible run of AHB beats, and `PBURST` as a count of them per request | 15.3.13 | Each beat is its own access, so nothing observes the lock. And a request here is the level section 15.3.4 gives it, so what decides how many beats one request is worth is the peripheral's own flag rather than a count. `MBURST` is read, because the threshold rule of Table 114 is a configuration error and not a race |
//! | The peripheral signaling its last data | 15.3.17 | Table 109 lists no input for it and no instance of this part is named as able to signal it, so there is nothing to wire. A stream under `PFCTRL` runs until its counter reaches zero, or `EN` is cleared |
//! | The AHB error of a burst across a 1 Kbyte boundary | 15.3.13 | The section says the error "is not reported by the DMA registers", and each beat is its own access here |
//! | What the stream does when the bus matrix refuses a peripheral that is not clocked | 15.3.20 | The part gates an instance through the bus and the refusal comes back as the bus error of the same section, which is modeled |
//! | ES0392 rev 15 2.20.4: a stream locked by a USART request served during a concurrent transfer | ES0392 rev 15 | Applicable to revision V. The errata says only that the requested transfer "may not be served", gives no condition for a concurrent transfer and no instant, and the model would have to invent both. The workaround, setting `TRBUFF` on the stream that serves the serial port, is stored and held like the rest of `SxCR`. ArduPilot's driver sets it |
//! | ES0392 rev 15 2.2.28: HASH input data corrupted when DMA is used | ES0392 rev 15 | Applicable to revision V. The part has no HASH, so there is no HASH stream to corrupt. The workaround is also `TRBUFF` on the HASH stream |
//! | Clock gating and the reset registers | 8.7 | The part gates the instance through the bus, which is `memory_map.rs`. Being held at reset is a third behavior and isn't this |
//!
//! **Where this model departs from the vendor's file.** Section 15.5.3 types every bit of `DMA_LIFCR` and
//! `DMA_HIFCR` write-only and ST's file types both registers read-write, so a written one stays in the
//! register where the part would drop it. The model clears them itself. ST also gives `DMA_SxFCR` no write
//! rule for `FS`, which section 15.5.10 types read-only, and the register file enforces that from the
//! table, so the model writes the level through [`RegisterFile::set`](crate::device::RegisterFile::set). The file leaves out bit 20 of
//! `DMA_SxCR`, `TRBUFF`, which section 15.5.5 gives. The register file stores a bit no field covers, so
//! it lands and reads back, and the model protects it with the rest of the register.
//!
//! **Determinism.** The model reads no clock and draws nothing. `two_runs_of_one_script_are_the_same_run`
//! drives two benches through the same script and compares every register, the memory, the interrupts
//! and the whole state of each model.
use crate::soc::st::dma::{Reach, Requests};
use crate::soc::stm32h743::generated::DMAMUX1;
use crate::soc::stm32h743::generated::dma1::Register;
pub use crate::soc::st::dma::{STREAMS, Span};
/// The first of DMAMUX1's channels that `DMA1`'s streams hear, section 17.3.2. Stream `n` hears channel
/// `n`.
pub const DMA1_FIRST_CHANNEL: usize = 0;
/// The first of DMAMUX1's channels that `DMA2`'s streams hear, section 17.3.2. Stream `n` hears channel
/// `8 + n`.
pub const DMA2_FIRST_CHANNEL: usize = 8;
/// ITCM, 64 Kbytes at address zero, section 2.4.
pub(crate) const ITCM: Span = Span {
base: 0x0000_0000,
bytes: 64 << 10,
};
/// DTCM, 128 Kbytes at `0x2000_0000`, section 2.4.
pub(crate) const DTCM: Span = Span {
base: 0x2000_0000,
bytes: 128 << 10,
};
/// The memory neither port of either controller reaches, section 2.1.6: "all internal memories except
/// ITCM and DTCM", and Table 3 gives both masters of both controllers no path to either.
pub(crate) const UNREACHABLE: [Span; 2] = [ITCM, DTCM];
/// One direct memory access controller of an STM32H743, RM0433 rev 9 chapter 15.
pub type Dma = crate::soc::st::dma::Dma<Register>;
impl Dma {
/// A controller whose stream `n` hears DMAMUX1's channel `first_channel + n`: [`DMA1_FIRST_CHANNEL`]
/// for `DMA1` and [`DMA2_FIRST_CHANNEL`] for `DMA2`, section 17.3.2.
///
/// The part names the multiplexer a reader of requests, and the controller as a reader too, so the
/// stream hears the level the channel drives. It names the controller as a reader for the
/// multiplexer as well, which counts the acknowledges the stream drives on its own request outputs,
/// output `n` for stream `n`.
#[must_use]
pub fn new(first_channel: usize) -> Self {
Self::wired(
Requests::Multiplexer {
instance: DMAMUX1.name,
first: first_channel,
},
Reach {
memory_to_memory: true,
unreachable: &UNREACHABLE,
},
)
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn the_wiring_constants_are_the_manuals() {
for (span, name) in [(ITCM, "itcm"), (DTCM, "dtcm")] {
let region = crate::soc::stm32h743::MEMORY
.iter()
.find(|region| region.name == name)
.unwrap_or_else(|| panic!("the map has {name}"));
assert_eq!(
(span.base, span.bytes),
(region.base, region.size),
"{name}"
);
}
assert!(ITCM.overlaps(0xFFFF, 1));
assert!(!ITCM.overlaps(0x1_0000, 4), "the first byte past the end");
assert!(ITCM.overlaps(0xFFFE, 4), "an access that straddles the end");
assert!(
DTCM.overlaps(0x1FFF_FFFE, 4),
"and one that straddles the start"
);
}
}