stm32_fmc/
lib.rs

1//! Hardware Abstraction Layer for STM32 Memory Controllers (FMC/FSMC)
2//!
3//!
4//! # Implementation Guide
5//!
6//! You can use the functionality in this crate by implementing the
7//! [`FmcPeripheral`](FmcPeripheral) trait. You should implement this trait for a
8//! structure that:
9//!
10//! * Takes ownership of the `FMC`/`FSMC` peripheral
11//! * Takes ownership of any structures / ZSTs related to the power or clock for the `FMC`/`FSMC` peripheral
12//! * Contains the frequency of the `FMC`/`FSMC` source clock (usually HCLK)
13//!
14//! A basic structure:
15//!
16//! ```
17//! pub struct FMC {
18//!     source_clock: u32,
19//!     // any other fields here...
20//! }
21//! ```
22//!
23//! An implementation of [`FmcPeripheral`](FmcPeripheral):
24//!
25//! ```rust
26//! # mod stm32 { pub struct FMC {} impl FMC { pub const fn ptr() -> *const u32 { &0 } } }
27//! # struct FMC { source_clock: u32 }
28//! use stm32_fmc::FmcPeripheral;
29//!
30//! unsafe impl Sync for FMC {}
31//! unsafe impl FmcPeripheral for FMC {
32//!     const REGISTERS: *const () = stm32::FMC::ptr() as *const ();
33//!
34//!     fn enable(&mut self) {
35//!         // Enable and reset the FMC/FSMC using the RCC registers
36//!         // Typically RCC.AHBxEN and RCC.AHBxRST
37//!     }
38//!
39//!     fn memory_controller_enable(&mut self) {
40//!         // Only required if your part has an `FMCEN` bit
41//!     }
42//!
43//!     fn source_clock_hz(&self) -> u32 {
44//!         self.source_clock
45//!     }
46//! }
47//! ```
48//!
49//! In a HAL, you can allow users to construct your structure by implementing a
50//! `new` method, or by making the fields public.
51//!
52//! ## Wrap constructor methods
53//!
54//! Each memory controller type ([`Sdram`](Sdram), [`Nand`](Nand), ..) provides both
55//! `new` and `new_unchecked` methods.
56//!
57//! For the convenience of users, you may want to wrap these with your `new` method,
58//! so that each memory can be created from the peripheral in one step.
59//!
60//! ```
61//! # mod stm32 { pub struct FMC {} }
62//! # type CoreClocks = u32;
63//! # struct FMC {}
64//! # impl FMC { pub fn new(_: stm32::FMC, _: &CoreClocks) -> Self { Self {} } }
65//! # unsafe impl stm32_fmc::FmcPeripheral for FMC {
66//! #     const REGISTERS: *const () = &0 as *const _ as *const ();
67//! #     fn enable(&mut self) { }
68//! #     fn source_clock_hz(&self) -> u32 { 0 }
69//! # }
70//! use stm32_fmc::{
71//!     AddressPinSet, PinsSdram, Sdram, SdramChip, SdramPinSet, SdramTargetBank,
72//! };
73//!
74//! impl FMC {
75//!     /// A new SDRAM memory via the Flexible Memory Controller
76//!     pub fn sdram<
77//!         BANK: SdramPinSet,
78//!         ADDR: AddressPinSet,
79//!         PINS: PinsSdram<BANK, ADDR>,
80//!         CHIP: SdramChip,
81//!     >(
82//!         fmc: stm32::FMC,
83//!         pins: PINS,
84//!         chip: CHIP,
85//!         clocks: &CoreClocks,
86//!     ) -> Sdram<FMC, CHIP> {
87//!         let fmc = Self::new(fmc, clocks);
88//!         Sdram::new(fmc, pins, chip)
89//!     }
90//!
91//!     /// A new SDRAM memory via the Flexible Memory Controller
92//!     pub fn sdram_unchecked<CHIP: SdramChip, BANK: Into<SdramTargetBank>>(
93//!         fmc: stm32::FMC,
94//!         bank: BANK,
95//!         chip: CHIP,
96//!         clocks: &CoreClocks,
97//!     ) -> Sdram<FMC, CHIP> {
98//!         let fmc = Self::new(fmc, clocks);
99//!         Sdram::new_unchecked(fmc, bank, chip)
100//!     }
101//! }
102//! ```
103//!
104//! # Pin implementations
105//!
106//! In contrast with the `new_unchecked` methods, the `new` methods require the user
107//! pass a tuple as the `pins` argument. In a HAL, you can mark which types are
108//! suitable as follows:
109//!
110//! ```rust
111//! # pub use core::marker::PhantomData;
112//! # struct AF12 {}
113//! # struct Alternate<AF> { _af: PhantomData<AF> }
114//! # mod gpiof { pub use core::marker::PhantomData; pub struct PF0<A> { _a: PhantomData<A> } }
115//! impl stm32_fmc::A0 for gpiof::PF0<Alternate<AF12>> {}
116//! // ...
117//! ```
118//!
119
120#![no_std]
121// rustc lints.
122#![warn(
123    bare_trait_objects,
124    missing_copy_implementations,
125    missing_debug_implementations,
126    missing_docs,
127    trivial_casts,
128    trivial_numeric_casts,
129    unused_extern_crates,
130    unused_qualifications,
131    unused_results
132)]
133
134#[macro_use]
135mod macros;
136
137mod fmc;
138pub use fmc::*;
139
140#[cfg(feature = "sdram")]
141mod sdram;
142#[cfg(feature = "sdram")]
143pub use sdram::{
144    PinsSdram, Sdram, SdramChip, SdramConfiguration, SdramPinSet,
145    SdramTargetBank, SdramTiming,
146};
147
148#[cfg(feature = "nand")]
149mod nand;
150#[cfg(feature = "nand")]
151pub use nand::device as nand_device;
152#[cfg(feature = "nand")]
153pub use nand::{Nand, NandChip, NandConfiguration, NandTiming, PinsNand};
154
155/// Memory device definitions
156pub mod devices;
157
158mod ral;
159
160/// A trait for device-specific FMC peripherals. Implement this to add support
161/// for a new hardware platform. Peripherals that have this trait must have the
162/// same register block as STM32 FMC peripherals.
163pub unsafe trait FmcPeripheral: Send {
164    /// Pointer to the register block
165    const REGISTERS: *const ();
166
167    /// Enables the FMC on its peripheral bus
168    fn enable(&mut self);
169
170    /// Enables the FMC memory controller (not always required)
171    fn memory_controller_enable(&mut self) {}
172
173    /// The frequency of the clock used as a source for the fmc_clk.
174    ///
175    /// F4/F7/G4: hclk
176    /// H7: fmc_ker_ck
177    fn source_clock_hz(&self) -> u32;
178}
stm32_fmc/lib.rs

stm32_fmc/
lib.rs
