Merge #581

581: First part of advanced timer dead time feature documentation r=burrbull a=janschiefer



Co-authored-by: Jan Schiefer <janschiefer@users.noreply.github.com>
Co-authored-by: Andrey Zgarbul <zgarbul.andrey@gmail.com>

CHANGELOG.md

@@ -13,7 +13,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
  - Bump `synopsys-usb-otg` to 0.3.2 (bug fix)
  - Update readme, clippy fixes
  - Added possibility to pass complementary pins to `Pwm` and change pwm channel polarity [#571],
-   set dead time and idle state for advanced timers [#578]
+   set dead time and idle state for advanced timers [#578] [#581]
 
 ### Added
 
@@ -30,6 +30,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 [#572]: https://github.com/stm32-rs/stm32f4xx-hal/pull/572
 [#577]: https://github.com/stm32-rs/stm32f4xx-hal/pull/577
 [#578]: https://github.com/stm32-rs/stm32f4xx-hal/pull/578
+[#581]: https://github.com/stm32-rs/stm32f4xx-hal/pull/581
 
 
 ## [v0.14.0] - 2022-12-12

src/timer/pwm.rs

@@ -370,36 +370,44 @@ where
     TIM: Instance + WithPwm,
     PINS: Pins<TIM, P>,
 {
+    /// Enable PWM output of the timer on channel `channel`
     #[inline]
     pub fn enable(&mut self, channel: Channel) {
         TIM::enable_channel(PINS::check_used(channel) as u8, true)
     }
 
+    /// Disable PWM output of the timer on channel `channel`
     #[inline]
     pub fn disable(&mut self, channel: Channel) {
         TIM::enable_channel(PINS::check_used(channel) as u8, false)
     }
 
+    /// Set the polarity of the active state for the primary PWM output of the timer on channel `channel`
     #[inline]
     pub fn set_polarity(&mut self, channel: Channel, p: Polarity) {
         TIM::set_channel_polarity(PINS::check_used(channel) as u8, p);
     }
 
+    /// Get the current duty cycle of the timer on channel `channel`
     #[inline]
     pub fn get_duty(&self, channel: Channel) -> u16 {
         TIM::read_cc_value(PINS::check_used(channel) as u8) as u16
     }
 
+    /// Set the duty cycle of the timer on channel `channel`
     #[inline]
     pub fn set_duty(&mut self, channel: Channel, duty: u16) {
         TIM::set_cc_value(PINS::check_used(channel) as u8, duty as u32)
     }
 
+    /// Get the maximum duty cycle value of the timer
+    ///
     /// If `0` returned means max_duty is 2^16
     pub fn get_max_duty(&self) -> u16 {
         (TIM::read_auto_reload() as u16).wrapping_add(1)
     }
 
+    /// Get the PWM frequency of the timer in Hertz
     pub fn get_period(&self) -> Hertz {
         let clk = self.clk;
         let psc = self.tim.read_prescaler() as u32;
@@ -409,6 +417,7 @@ where
         clk / ((psc + 1) * (arr + 1))
     }
 
+    /// Set the PWM frequency for the timer in Hertz
     pub fn set_period(&mut self, period: Hertz) {
         let clk = self.clk;
 
@@ -418,6 +427,7 @@ where
         self.tim.cnt_reset();
     }
 
+    /// Set the polarity of the active state for the complementary PWM output of the advanced timer on channel `channel`
     #[inline]
     pub fn set_complementary_polarity(&mut self, channel: Channel, p: Polarity) {
         TIM::set_channel_polarity(PINS::check_complementary_used(channel) as u8, p);
@@ -429,30 +439,39 @@ where
     TIM: Instance + WithPwm + Advanced,
     PINS: Pins<TIM, P>,
 {
+    /// Enable complementary PWM output of the timer on channel `channel`
     #[inline]
     pub fn enable_complementary(&mut self, channel: Channel) {
         TIM::enable_nchannel(PINS::check_complementary_used(channel) as u8, true)
     }
 
+    /// Disable complementary PWM output of the timer on channel `channel`
     #[inline]
     pub fn disable_complementary(&mut self, channel: Channel) {
         TIM::enable_nchannel(PINS::check_complementary_used(channel) as u8, false)
     }
 
-    /// Set number DTS ticks during that complementary pin is `dead`
+    /// Set number DTS ticks during that the primary and complementary PWM pins are simultaneously forced to their inactive states
+    /// ( see [`Polarity`] setting ) when changing PWM state. This duration when both channels are in an 'off' state  is called 'dead time'.
+    ///
+    /// This is necessary in applications like motor control or power converters to prevent the destruction of the switching elements by
+    /// short circuit in the moment of switching.
     #[inline]
     pub fn set_dead_time(&mut self, dts_ticks: u16) {
         let bits = pack_ceil_dead_time(dts_ticks);
         TIM::set_dtg_value(bits);
     }
 
     /// Set raw dead time (DTG) bits
+    ///
+    /// The dead time generation is nonlinear and constrained by the DTS tick duration. DTG register configuration and calculation of
+    /// the actual resulting dead time is described in the application note RM0368 from ST Microelectronics
     #[inline]
     pub fn set_dead_time_bits(&mut self, bits: u8) {
         TIM::set_dtg_value(bits);
     }
 
-    /// Return dead time for complementary pins in DTS ticks
+    /// Return dead time for complementary pins in the unit of DTS ticks
     #[inline]
     pub fn get_dead_time(&self) -> u16 {
         unpack_dead_time(TIM::read_dtg_value())
@@ -464,11 +483,13 @@ where
         TIM::read_dtg_value()
     }
 
+    /// Set the pin idle state
     #[inline]
     pub fn set_idle_state(&mut self, channel: Channel, s: IdleState) {
         TIM::idle_state(PINS::check_used(channel) as u8, false, s);
     }
 
+    /// Set the complementary pin idle state
     #[inline]
     pub fn set_complementary_idle_state(&mut self, channel: Channel, s: IdleState) {
         TIM::idle_state(PINS::check_complementary_used(channel) as u8, true, s);