feat(dmac): Updates the dmac::DmacController to use the clock::v2 API for thumbv7 targets.

* Renames the `dmac::DmacController::init` to `dmac::DmacController::new` for all targets for consistency with other peripherals
* `dmac::DmacController::new` now requires the `AhbClk<Dmac>` for `thumbv7` targets instead of `&mut Pm`.
* `dmac::DmacController::free` also now returns the `AhbClk<Dmac>` for `thumbv7` targets.
* Addresses some other `cargo doc` warnings in the `dmac` module.

Author: kyp44

hal/src/dmac/dma_controller.rs

@@ -3,7 +3,7 @@
 //! # Initializing
 //!
 //! The DMAC should be initialized using the
-//! [`DmaController::init`] method. It will consume the
+//! [`DmaController::new`] method. It will consume the
 //! DMAC object generated by the PAC. By default, all four priority levels
 //! will be enabled, but can be selectively enabled/disabled through the
 //! [`DmaController::enable_levels`] ansd [`DmaController::disable_levels`]
@@ -44,10 +44,12 @@ use super::{
     channel::{Channel, Uninitialized},
     sram,
 };
-use crate::{
-    pac::{Dmac, Pm},
-    typelevel::NoneT,
-};
+#[hal_cfg(any("dmac-d11", "dmac-d21"))]
+use crate::pac::Pm;
+use crate::{pac::Dmac, typelevel::NoneT};
+
+#[hal_cfg("dmac-d5x")]
+type DmacAhbClk = crate::clock::v2::ahb::AhbClk<crate::clock::v2::types::Dmac>;
 
 /// Trait representing a DMA channel ID
 pub trait ChId {
@@ -150,28 +152,18 @@ macro_rules! define_channels_struct_future {
 with_num_channels!(define_channels_struct_future);
 
 /// Initialized DMA Controller
+#[hal_macro_helper]
 pub struct DmaController<I = NoneT> {
     dmac: Dmac,
+    #[hal_cfg("dmac-d5x")]
+    ahb_clk: DmacAhbClk,
     _irqs: PhantomData<I>,
 }
 
 impl DmaController {
-    /// Initialize the DMAC and return a DmaController object useable by
-    /// [`Transfer`](super::transfer::Transfer)'s. By default, all
-    /// priority levels are enabled unless subsequently disabled using the
-    /// `level_x_enabled` methods.
-    #[inline]
-    #[hal_macro_helper]
-    pub fn init(mut dmac: Dmac, _pm: &mut Pm) -> Self {
-        // ----- Initialize clocking ----- //
-        #[hal_cfg(any("dmac-d11", "dmac-d21"))]
-        {
-            // Enable clocking
-            _pm.ahbmask().modify(|_, w| w.dmac_().set_bit());
-            _pm.apbbmask().modify(|_, w| w.dmac_().set_bit());
-        }
-
-        Self::swreset(&mut dmac);
+    /// Reset and enable the DMA controller.
+    fn init(dmac: &mut Dmac) {
+        Self::swreset(dmac);
 
         // SAFETY:
         //
@@ -196,36 +188,77 @@ impl DmaController {
 
         // Enable DMA controller
         dmac.ctrl().modify(|_, w| w.dmaenable().set_bit());
+    }
+
+    #[hal_cfg(any("dmac-d11", "dmac-d21"))]
+    /// Initialize the DMAC and return a DmaController object useable by
+    /// [`Transfer`](super::transfer::Transfer)'s. By default, all
+    /// priority levels are enabled unless subsequently disabled using the
+    /// `level_x_enabled` methods.
+    #[inline]
+    pub fn new(mut dmac: Dmac, pm: &mut Pm) -> Self {
+        // ----- Initialize clocking ----- //
+        // Enable clocking
+        pm.ahbmask().modify(|_, w| w.dmac_().set_bit());
+        pm.apbbmask().modify(|_, w| w.dmac_().set_bit());
+
+        Self::init(&mut dmac);
 
         Self {
             dmac,
             _irqs: PhantomData,
         }
     }
 
+    #[hal_cfg("dmac-d5x")]
+    /// Initialize the DMAC and return a DmaController object useable by
+    /// [`Transfer`](super::transfer::Transfer)'s. By default, all
+    /// priority levels are enabled unless subsequently disabled using the
+    /// `level_x_enabled` methods.
+    #[inline]
+    pub fn new(mut dmac: Dmac, ahb_clk: DmacAhbClk) -> Self {
+        Self::init(&mut dmac);
+
+        Self {
+            dmac,
+            ahb_clk,
+            _irqs: PhantomData,
+        }
+    }
+
+    #[hal_cfg(any("dmac-d11", "dmac-d21"))]
     /// Release the DMAC and return the register block.
     ///
     /// **Note**: The [`Channels`] struct is consumed by this method. This means
     /// that any [`Channel`] obtained by [`split`](DmaController::split) must be
     /// moved back into the [`Channels`] struct before being able to pass it
     /// into [`free`](DmaController::free).
     #[inline]
-    #[hal_macro_helper]
-    pub fn free(mut self, _channels: Channels, _pm: &mut Pm) -> Dmac {
-        self.dmac.ctrl().modify(|_, w| w.dmaenable().clear_bit());
+    pub fn free(mut self, _channels: Channels, pm: &mut Pm) -> Dmac {
+        Self::disable_and_reset(&mut self.dmac);
 
-        Self::swreset(&mut self.dmac);
-
-        #[hal_cfg(any("dmac-d11", "dmac-d21"))]
-        {
-            // Disable the DMAC clocking
-            _pm.apbbmask().modify(|_, w| w.dmac_().clear_bit());
-            _pm.ahbmask().modify(|_, w| w.dmac_().clear_bit());
-        }
+        // Disable the DMAC clocking
+        pm.apbbmask().modify(|_, w| w.dmac_().clear_bit());
+        pm.ahbmask().modify(|_, w| w.dmac_().clear_bit());
 
         // Release the DMAC
         self.dmac
     }
+
+    #[hal_cfg("dmac-d5x")]
+    /// Release the DMAC and return the register block.
+    ///
+    /// **Note**: The [`Channels`] struct is consumed by this method. This means
+    /// that any [`Channel`] obtained by [`split`](DmaController::split) must be
+    /// moved back into the [`Channels`] struct before being able to pass it
+    /// into [`free`](DmaController::free).
+    #[inline]
+    pub fn free(mut self, _channels: Channels) -> (Dmac, DmacAhbClk) {
+        Self::disable_and_reset(&mut self.dmac);
+
+        // Release the DMAC and bus clock
+        (self.dmac, self.ahb_clk)
+    }
 }
 
 impl<T> DmaController<T> {
@@ -290,6 +323,7 @@ impl<T> DmaController<T> {
     /// [`bind_interrupts`](crate::bind_interrupts).
     #[cfg(feature = "async")]
     #[inline]
+    #[hal_macro_helper]
     pub fn into_future<I>(self, _interrupts: I) -> DmaController<I>
     where
         I: crate::async_hal::interrupts::Binding<
@@ -304,10 +338,20 @@ impl<T> DmaController<T> {
 
         DmaController {
             dmac: self.dmac,
+            #[hal_cfg("dmac-d5x")]
+            ahb_clk: self.ahb_clk,
             _irqs: PhantomData,
         }
     }
 
+    /// Disable and reset the DMAC
+    #[inline]
+    fn disable_and_reset(dmac: &mut Dmac) {
+        dmac.ctrl().modify(|_, w| w.dmaenable().clear_bit());
+
+        Self::swreset(dmac);
+    }
+
     /// Issue a software reset to the DMAC and wait for reset to complete
     #[inline]
     fn swreset(dmac: &mut Dmac) {
@@ -324,29 +368,39 @@ where
             super::async_api::InterruptHandler,
         >,
 {
+    #[hal_cfg(any("dmac-d11", "dmac-d21"))]
     /// Release the DMAC and return the register block.
     ///
     /// **Note**: The [`Channels`] struct is consumed by this method. This means
     /// that any [`Channel`] obtained by [`split`](DmaController::split) must be
     /// moved back into the [`Channels`] struct before being able to pass it
     /// into [`free`](DmaController::free).
     #[inline]
-    #[hal_macro_helper]
-    pub fn free(mut self, _channels: FutureChannels, _pm: &mut Pm) -> Dmac {
-        self.dmac.ctrl().modify(|_, w| w.dmaenable().clear_bit());
+    pub fn free(mut self, _channels: FutureChannels, pm: &mut Pm) -> Dmac {
+        Self::disable_and_reset(&mut self.dmac);
 
-        Self::swreset(&mut self.dmac);
-
-        #[hal_cfg(any("dmac-d11", "dmac-d21"))]
-        {
-            // Disable the DMAC clocking
-            _pm.apbbmask().modify(|_, w| w.dmac_().clear_bit());
-            _pm.ahbmask().modify(|_, w| w.dmac_().clear_bit());
-        }
+        // Disable the DMAC clocking
+        pm.apbbmask().modify(|_, w| w.dmac_().clear_bit());
+        pm.ahbmask().modify(|_, w| w.dmac_().clear_bit());
 
         // Release the DMAC
         self.dmac
     }
+
+    #[hal_cfg("dmac-d5x")]
+    /// Release the DMAC and return the register block.
+    ///
+    /// **Note**: The [`Channels`] struct is consumed by this method. This means
+    /// that any [`Channel`] obtained by [`split`](DmaController::split) must be
+    /// moved back into the [`Channels`] struct before being able to pass it
+    /// into [`free`](DmaController::free).
+    #[inline]
+    pub fn free(mut self, _channels: FutureChannels) -> (Dmac, DmacAhbClk) {
+        Self::disable_and_reset(&mut self.dmac);
+
+        // Release the DMAC and bus clock
+        (self.dmac, self.ahb_clk)
+    }
 }
 
 macro_rules! define_split {

hal/src/dmac/mod.rs

@@ -64,7 +64,7 @@
 //! priority (in the default, ie static, arbitration scheme).
 //!
 //! By default, all priority levels are enabled when initializing the DMAC
-//! (see [`DmaController::init`]). Levels
+//! (see [`DmaController::new`]). Levels
 //! can be enabled or disabled through the
 //! [`DmaController::enable_levels`] and
 //! [`DmaController::disable_levels`] methods. These methods must be supplied a
@@ -119,7 +119,7 @@
 //!
 //! # Example
 //! ```
-//! let mut peripherals = Peripherals::take().unwrap();
+//! let mut peripherals = Periphserals::take().unwrap();
 //! let mut dmac = DmaController::init(peripherals.DMAC, &mut peripherals.PM);
 //! // Get individual handles to DMA channels
 //! let channels = dmac.split();