rcc: Add some additional documentation and a usage example.

Author: Mathias Gottschlag

src/rcc/mod.rs

@@ -1,3 +1,44 @@
+//! Clock configuration.
+//!
+//! This module provides functionality to configure the RCC to generate the requested clocks.
+//!
+//! # Example
+//!
+//! ```
+//! let dp = stm32::Peripherals::take().unwrap();
+//! let clocks = rcc
+//!     .cfgr
+//!     .use_hse(8.mhz())
+//!     .sysclk(168.mhz())
+//!     .pclk1(24.mhz())
+//!     .i2s_clk(86.mhz())
+//!     .require_pll48clk()
+//!     .freeze();
+//!     // Test that the I2S clock is suitable for 48000KHz audio.
+//!     assert!(clocks.i2s_clk().unwrap() == 48.mhz().into());
+//! ```
+//!
+//! # Limitations
+//!
+//! Unlike the clock configuration tool provided by ST, the code does not extensively search all
+//! possible configurations. Instead, it often relies on an iterative approach to reduce
+//! compitational complexity. On most MCUs the code will first generate a configuration for the 48
+//! MHz clock and the system clock without taking other requested clocks into account, even if the
+//! accuracy of these clocks is affected. **If you specific accuracy requirements, you should
+//! always check the resulting frequencies!**
+//!
+//! Whereas the hardware often supports flexible clock source selection and many clocks can be
+//! sourced from multiple PLLs, the code implements a fixed mapping between PLLs and clocks. The 48
+//! MHz clock is always generated by the main PLL, the I2S clocks are always generated by the I2S
+//! PLL (unless a matching external clock input is provided), and similarly the SAI clocks are
+//! always generated by the SAI PLL. It is therefore not possible to, for example, specify two
+//! different I2S frequencies unless you also provide a matching I2S_CKIN signal for one of them.
+//!
+//! Some MCUs have limited clock generation hardware and do not provide either I2S or SAI PLLs even
+//! though I2S or SAI are available. On the STM32F410, the I2S clock is generated by the main PLL,
+//! and on the STM32F413/423 SAI clocks are generated by the I2S PLL. On these MCUs, the actual
+//! frequencies may substantially deviate from the requested frequencies.
+
 use crate::stm32::rcc::cfgr::{HPRE_A, SW_A};
 use crate::stm32::RCC;