1//! Pulse Width Modulation (PWM) traits.
2
3#[cfg(feature = "defmt-03")]
4use crate::defmt;
5
6/// Error
7pub trait Error: core::fmt::Debug {
8 /// Convert error to a generic error kind.
9 ///
10 /// By using this method, errors freely defined by HAL implementations
11 /// can be converted to a set of generic errors upon which generic
12 /// code can act.
13 fn kind(&self) -> ErrorKind;
14}
15
16impl Error for core::convert::Infallible {
17 #[inline]
18 fn kind(&self) -> ErrorKind {
19 match *self {}
20 }
21}
22
23/// Error kind.
24///
25/// This represents a common set of operation errors. HAL implementations are
26/// free to define more specific or additional error types. However, by providing
27/// a mapping to these common errors, generic code can still react to them.
28#[derive(Debug, Copy, Clone, Eq, PartialEq, Ord, PartialOrd, Hash)]
29#[cfg_attr(feature = "defmt-03", derive(defmt::Format))]
30#[non_exhaustive]
31pub enum ErrorKind {
32 /// A different error occurred. The original error may contain more information.
33 Other,
34}
35
36impl Error for ErrorKind {
37 #[inline]
38 fn kind(&self) -> ErrorKind {
39 *self
40 }
41}
42
43impl core::fmt::Display for ErrorKind {
44 #[inline]
45 fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
46 match self {
47 Self::Other => write!(
48 f,
49 "A different error occurred. The original error may contain more information"
50 ),
51 }
52 }
53}
54
55/// Error type trait.
56///
57/// This just defines the error type, to be used by the other traits.
58pub trait ErrorType {
59 /// Error type
60 type Error: Error;
61}
62
63impl<T: ErrorType + ?Sized> ErrorType for &mut T {
64 type Error = T::Error;
65}
66
67/// Single PWM channel / pin.
68pub trait SetDutyCycle: ErrorType {
69 /// Get the maximum duty cycle value.
70 ///
71 /// This value corresponds to a 100% duty cycle.
72 fn max_duty_cycle(&self) -> u16;
73
74 /// Set the duty cycle to `duty / max_duty`.
75 ///
76 /// The caller is responsible for ensuring that the duty cycle value is less than or equal to the maximum duty cycle value,
77 /// as reported by [`max_duty_cycle`].
78 ///
79 /// [`max_duty_cycle`]: SetDutyCycle::max_duty_cycle
80 fn set_duty_cycle(&mut self, duty: u16) -> Result<(), Self::Error>;
81
82 /// Set the duty cycle to 0%, or always inactive.
83 #[inline]
84 fn set_duty_cycle_fully_off(&mut self) -> Result<(), Self::Error> {
85 self.set_duty_cycle(0)
86 }
87
88 /// Set the duty cycle to 100%, or always active.
89 #[inline]
90 fn set_duty_cycle_fully_on(&mut self) -> Result<(), Self::Error> {
91 self.set_duty_cycle(self.max_duty_cycle())
92 }
93
94 /// Set the duty cycle to `num / denom`.
95 ///
96 /// The caller is responsible for ensuring that `num` is less than or equal to `denom`,
97 /// and that `denom` is not zero.
98 #[inline]
99 fn set_duty_cycle_fraction(&mut self, num: u16, denom: u16) -> Result<(), Self::Error> {
100 debug_assert!(denom != 0);
101 debug_assert!(num <= denom);
102 let duty = u32::from(num) * u32::from(self.max_duty_cycle()) / u32::from(denom);
103
104 // This is safe because we know that `num <= denom`, so `duty <= self.max_duty_cycle()` (u16)
105 #[allow(clippy::cast_possible_truncation)]
106 {
107 self.set_duty_cycle(duty as u16)
108 }
109 }
110
111 /// Set the duty cycle to `percent / 100`
112 ///
113 /// The caller is responsible for ensuring that `percent` is less than or equal to 100.
114 #[inline]
115 fn set_duty_cycle_percent(&mut self, percent: u8) -> Result<(), Self::Error> {
116 self.set_duty_cycle_fraction(u16::from(percent), 100)
117 }
118}
119
120impl<T: SetDutyCycle + ?Sized> SetDutyCycle for &mut T {
121 #[inline]
122 fn max_duty_cycle(&self) -> u16 {
123 T::max_duty_cycle(self)
124 }
125
126 #[inline]
127 fn set_duty_cycle(&mut self, duty: u16) -> Result<(), Self::Error> {
128 T::set_duty_cycle(self, duty)
129 }
130
131 #[inline]
132 fn set_duty_cycle_fully_off(&mut self) -> Result<(), Self::Error> {
133 T::set_duty_cycle_fully_off(self)
134 }
135
136 #[inline]
137 fn set_duty_cycle_fully_on(&mut self) -> Result<(), Self::Error> {
138 T::set_duty_cycle_fully_on(self)
139 }
140
141 #[inline]
142 fn set_duty_cycle_fraction(&mut self, num: u16, denom: u16) -> Result<(), Self::Error> {
143 T::set_duty_cycle_fraction(self, num, denom)
144 }
145
146 #[inline]
147 fn set_duty_cycle_percent(&mut self, percent: u8) -> Result<(), Self::Error> {
148 T::set_duty_cycle_percent(self, percent)
149 }
150}
151