avr_device/
generic.rs

1use core::marker;
2
3/// Raw register type (`u8`, `u16`, `u32`, ...)
4pub trait RawReg:
5    Copy
6    + Default
7    + From<bool>
8    + core::ops::BitOr<Output = Self>
9    + core::ops::BitAnd<Output = Self>
10    + core::ops::BitOrAssign
11    + core::ops::BitAndAssign
12    + core::ops::Not<Output = Self>
13    + core::ops::Shl<u8, Output = Self>
14{
15    /// Mask for bits of width `WI`
16    fn mask<const WI: u8>() -> Self;
17    /// Mask for bits of width 1
18    fn one() -> Self;
19}
20
21macro_rules! raw_reg {
22    ($U:ty, $size:literal, $mask:ident) => {
23        impl RawReg for $U {
24            #[inline(always)]
25            fn mask<const WI: u8>() -> Self {
26                $mask::<WI>()
27            }
28            #[inline(always)]
29            fn one() -> Self {
30                1
31            }
32        }
33        const fn $mask<const WI: u8>() -> $U {
34            <$U>::MAX >> ($size - WI)
35        }
36    };
37}
38
39raw_reg!(u8, 8, mask_u8);
40raw_reg!(u16, 16, mask_u16);
41raw_reg!(u32, 32, mask_u32);
42raw_reg!(u64, 64, mask_u64);
43
44/// Raw register type
45pub trait RegisterSpec {
46    /// Raw register type (`u8`, `u16`, `u32`, ...).
47    type Ux: RawReg;
48}
49
50/// Trait implemented by readable registers to enable the `read` method.
51///
52/// Registers marked with `Writable` can be also be `modify`'ed.
53pub trait Readable: RegisterSpec {
54    /// Result from a call to `read` and argument to `modify`.
55    type Reader: From<R<Self>> + core::ops::Deref<Target = R<Self>>;
56}
57
58/// Trait implemented by writeable registers.
59///
60/// This enables the  `write`, `write_with_zero` and `reset` methods.
61///
62/// Registers marked with `Readable` can be also be `modify`'ed.
63pub trait Writable: RegisterSpec {
64    /// Writer type argument to `write`, et al.
65    type Writer: From<W<Self>> + core::ops::DerefMut<Target = W<Self>>;
66
67    /// Specifies the register bits that are not changed if you pass `1` and are changed if you pass `0`
68    const ZERO_TO_MODIFY_FIELDS_BITMAP: Self::Ux;
69
70    /// Specifies the register bits that are not changed if you pass `0` and are changed if you pass `1`
71    const ONE_TO_MODIFY_FIELDS_BITMAP: Self::Ux;
72}
73
74/// Reset value of the register.
75///
76/// This value is the initial value for the `write` method. It can also be directly written to the
77/// register by using the `reset` method.
78pub trait Resettable: RegisterSpec {
79    /// Reset value of the register.
80    const RESET_VALUE: Self::Ux;
81
82    /// Reset value of the register.
83    #[inline(always)]
84    fn reset_value() -> Self::Ux {
85        Self::RESET_VALUE
86    }
87}
88
89/// This structure provides volatile access to registers.
90#[repr(transparent)]
91pub struct Reg<REG: RegisterSpec> {
92    register: vcell::VolatileCell<REG::Ux>,
93    _marker: marker::PhantomData<REG>,
94}
95
96unsafe impl<REG: RegisterSpec> Send for Reg<REG> where REG::Ux: Send {}
97
98impl<REG: RegisterSpec> Reg<REG> {
99    /// Returns the underlying memory address of register.
100    ///
101    /// ```ignore
102    /// let reg_ptr = periph.reg.as_ptr();
103    /// ```
104    #[inline(always)]
105    pub fn as_ptr(&self) -> *mut REG::Ux {
106        self.register.as_ptr()
107    }
108}
109
110impl<REG: Readable> Reg<REG> {
111    /// Reads the contents of a `Readable` register.
112    ///
113    /// You can read the raw contents of a register by using `bits`:
114    /// ```ignore
115    /// let bits = periph.reg.read().bits();
116    /// ```
117    /// or get the content of a particular field of a register:
118    /// ```ignore
119    /// let reader = periph.reg.read();
120    /// let bits = reader.field1().bits();
121    /// let flag = reader.field2().bit_is_set();
122    /// ```
123    #[inline(always)]
124    pub fn read(&self) -> REG::Reader {
125        REG::Reader::from(R {
126            bits: self.register.get(),
127            _reg: marker::PhantomData,
128        })
129    }
130}
131
132impl<REG: Resettable + Writable> Reg<REG> {
133    /// Writes the reset value to `Writable` register.
134    ///
135    /// Resets the register to its initial state.
136    #[inline(always)]
137    pub fn reset(&self) {
138        self.register.set(REG::RESET_VALUE)
139    }
140
141    /// Writes bits to a `Writable` register.
142    ///
143    /// You can write raw bits into a register:
144    /// ```ignore
145    /// periph.reg.write(|w| unsafe { w.bits(rawbits) });
146    /// ```
147    /// or write only the fields you need:
148    /// ```ignore
149    /// periph.reg.write(|w| w
150    ///     .field1().bits(newfield1bits)
151    ///     .field2().set_bit()
152    ///     .field3().variant(VARIANT)
153    /// );
154    /// ```
155    /// or an alternative way of saying the same:
156    /// ```ignore
157    /// periph.reg.write(|w| {
158    ///     w.field1().bits(newfield1bits);
159    ///     w.field2().set_bit();
160    ///     w.field3().variant(VARIANT)
161    /// });
162    /// ```
163    /// In the latter case, other fields will be set to their reset value.
164    #[inline(always)]
165    pub fn write<F>(&self, f: F)
166    where
167        F: FnOnce(&mut REG::Writer) -> &mut W<REG>,
168    {
169        self.register.set(
170            f(&mut REG::Writer::from(W {
171                bits: REG::RESET_VALUE & !REG::ONE_TO_MODIFY_FIELDS_BITMAP
172                    | REG::ZERO_TO_MODIFY_FIELDS_BITMAP,
173                _reg: marker::PhantomData,
174            }))
175            .bits,
176        );
177    }
178}
179
180impl<REG: Writable> Reg<REG> {
181    /// Writes 0 to a `Writable` register.
182    ///
183    /// Similar to `write`, but unused bits will contain 0.
184    ///
185    /// # Safety
186    ///
187    /// Unsafe to use with registers which don't allow to write 0.
188    #[inline(always)]
189    pub unsafe fn write_with_zero<F>(&self, f: F)
190    where
191        F: FnOnce(&mut REG::Writer) -> &mut W<REG>,
192    {
193        self.register.set(
194            f(&mut REG::Writer::from(W {
195                bits: REG::Ux::default(),
196                _reg: marker::PhantomData,
197            }))
198            .bits,
199        );
200    }
201}
202
203impl<REG: Readable + Writable> Reg<REG> {
204    /// Modifies the contents of the register by reading and then writing it.
205    ///
206    /// E.g. to do a read-modify-write sequence to change parts of a register:
207    /// ```ignore
208    /// periph.reg.modify(|r, w| unsafe { w.bits(
209    ///    r.bits() | 3
210    /// ) });
211    /// ```
212    /// or
213    /// ```ignore
214    /// periph.reg.modify(|_, w| w
215    ///     .field1().bits(newfield1bits)
216    ///     .field2().set_bit()
217    ///     .field3().variant(VARIANT)
218    /// );
219    /// ```
220    /// or an alternative way of saying the same:
221    /// ```ignore
222    /// periph.reg.modify(|_, w| {
223    ///     w.field1().bits(newfield1bits);
224    ///     w.field2().set_bit();
225    ///     w.field3().variant(VARIANT)
226    /// });
227    /// ```
228    /// Other fields will have the value they had before the call to `modify`.
229    #[inline(always)]
230    pub fn modify<F>(&self, f: F)
231    where
232        for<'w> F: FnOnce(&REG::Reader, &'w mut REG::Writer) -> &'w mut W<REG>,
233    {
234        let bits = self.register.get();
235        self.register.set(
236            f(
237                &REG::Reader::from(R {
238                    bits,
239                    _reg: marker::PhantomData,
240                }),
241                &mut REG::Writer::from(W {
242                    bits: bits & !REG::ONE_TO_MODIFY_FIELDS_BITMAP
243                        | REG::ZERO_TO_MODIFY_FIELDS_BITMAP,
244                    _reg: marker::PhantomData,
245                }),
246            )
247            .bits,
248        );
249    }
250}
251
252/// Register reader.
253///
254/// Result of the `read` methods of registers. Also used as a closure argument in the `modify`
255/// method.
256pub struct R<REG: RegisterSpec + ?Sized> {
257    pub(crate) bits: REG::Ux,
258    _reg: marker::PhantomData<REG>,
259}
260
261impl<REG: RegisterSpec> R<REG> {
262    /// Reads raw bits from register.
263    #[inline(always)]
264    pub fn bits(&self) -> REG::Ux {
265        self.bits
266    }
267}
268
269impl<REG: RegisterSpec, FI> PartialEq<FI> for R<REG>
270where
271    REG::Ux: PartialEq,
272    FI: Copy,
273    REG::Ux: From<FI>,
274{
275    #[inline(always)]
276    fn eq(&self, other: &FI) -> bool {
277        self.bits.eq(&REG::Ux::from(*other))
278    }
279}
280
281/// Register writer.
282///
283/// Used as an argument to the closures in the `write` and `modify` methods of the register.
284pub struct W<REG: RegisterSpec + ?Sized> {
285    ///Writable bits
286    pub(crate) bits: REG::Ux,
287    _reg: marker::PhantomData<REG>,
288}
289
290impl<REG: RegisterSpec> W<REG> {
291    /// Writes raw bits to the register.
292    ///
293    /// # Safety
294    ///
295    /// Read datasheet or reference manual to find what values are allowed to pass.
296    #[inline(always)]
297    pub unsafe fn bits(&mut self, bits: REG::Ux) -> &mut Self {
298        self.bits = bits;
299        self
300    }
301}
302
303#[doc(hidden)]
304pub struct FieldReaderRaw<U, T> {
305    pub(crate) bits: U,
306    _reg: marker::PhantomData<T>,
307}
308
309impl<U, FI> FieldReaderRaw<U, FI>
310where
311    U: Copy,
312{
313    /// Creates a new instance of the reader.
314    #[allow(unused)]
315    #[inline(always)]
316    pub(crate) fn new(bits: U) -> Self {
317        Self {
318            bits,
319            _reg: marker::PhantomData,
320        }
321    }
322}
323
324#[doc(hidden)]
325pub struct BitReaderRaw<T> {
326    pub(crate) bits: bool,
327    _reg: marker::PhantomData<T>,
328}
329
330impl<FI> BitReaderRaw<FI> {
331    /// Creates a new instance of the reader.
332    #[allow(unused)]
333    #[inline(always)]
334    pub(crate) fn new(bits: bool) -> Self {
335        Self {
336            bits,
337            _reg: marker::PhantomData,
338        }
339    }
340}
341
342/// Field reader.
343///
344/// Result of the `read` methods of fields.
345pub type FieldReader<U, FI> = FieldReaderRaw<U, FI>;
346
347/// Bit-wise field reader
348pub type BitReader<FI> = BitReaderRaw<FI>;
349
350impl<U, FI> FieldReader<U, FI>
351where
352    U: Copy,
353{
354    /// Reads raw bits from field.
355    #[inline(always)]
356    pub fn bits(&self) -> U {
357        self.bits
358    }
359}
360
361impl<U, FI> PartialEq<FI> for FieldReader<U, FI>
362where
363    U: PartialEq,
364    FI: Copy,
365    U: From<FI>,
366{
367    #[inline(always)]
368    fn eq(&self, other: &FI) -> bool {
369        self.bits.eq(&U::from(*other))
370    }
371}
372
373impl<FI> PartialEq<FI> for BitReader<FI>
374where
375    FI: Copy,
376    bool: From<FI>,
377{
378    #[inline(always)]
379    fn eq(&self, other: &FI) -> bool {
380        self.bits.eq(&bool::from(*other))
381    }
382}
383
384impl<FI> BitReader<FI> {
385    /// Value of the field as raw bits.
386    #[inline(always)]
387    pub fn bit(&self) -> bool {
388        self.bits
389    }
390    /// Returns `true` if the bit is clear (0).
391    #[inline(always)]
392    pub fn bit_is_clear(&self) -> bool {
393        !self.bit()
394    }
395    /// Returns `true` if the bit is set (1).
396    #[inline(always)]
397    pub fn bit_is_set(&self) -> bool {
398        self.bit()
399    }
400}
401
402#[doc(hidden)]
403pub struct Safe;
404#[doc(hidden)]
405pub struct Unsafe;
406
407#[doc(hidden)]
408pub struct FieldWriterRaw<'a, U, REG, N, FI, Safety, const WI: u8, const O: u8>
409where
410    REG: Writable + RegisterSpec<Ux = U>,
411    N: From<FI>,
412{
413    pub(crate) w: &'a mut REG::Writer,
414    _field: marker::PhantomData<(N, FI, Safety)>,
415}
416
417impl<'a, U, REG, N, FI, Safety, const WI: u8, const O: u8>
418    FieldWriterRaw<'a, U, REG, N, FI, Safety, WI, O>
419where
420    REG: Writable + RegisterSpec<Ux = U>,
421    N: From<FI>,
422{
423    /// Creates a new instance of the writer
424    #[allow(unused)]
425    #[inline(always)]
426    pub(crate) fn new(w: &'a mut REG::Writer) -> Self {
427        Self {
428            w,
429            _field: marker::PhantomData,
430        }
431    }
432}
433
434#[doc(hidden)]
435pub struct BitWriterRaw<'a, U, REG, FI, M, const O: u8>
436where
437    REG: Writable + RegisterSpec<Ux = U>,
438    bool: From<FI>,
439{
440    pub(crate) w: &'a mut REG::Writer,
441    _field: marker::PhantomData<(FI, M)>,
442}
443
444impl<'a, U, REG, FI, M, const O: u8> BitWriterRaw<'a, U, REG, FI, M, O>
445where
446    REG: Writable + RegisterSpec<Ux = U>,
447    bool: From<FI>,
448{
449    /// Creates a new instance of the writer
450    #[allow(unused)]
451    #[inline(always)]
452    pub(crate) fn new(w: &'a mut REG::Writer) -> Self {
453        Self {
454            w,
455            _field: marker::PhantomData,
456        }
457    }
458}
459
460/// Write field Proxy with unsafe `bits`
461pub type FieldWriter<'a, U, REG, N, FI, const WI: u8, const O: u8> =
462    FieldWriterRaw<'a, U, REG, N, FI, Unsafe, WI, O>;
463/// Write field Proxy with safe `bits`
464pub type FieldWriterSafe<'a, U, REG, N, FI, const WI: u8, const O: u8> =
465    FieldWriterRaw<'a, U, REG, N, FI, Safe, WI, O>;
466
467impl<'a, U, REG, N, FI, const WI: u8, const OF: u8> FieldWriter<'a, U, REG, N, FI, WI, OF>
468where
469    REG: Writable + RegisterSpec<Ux = U>,
470    N: From<FI>,
471{
472    /// Field width
473    pub const WIDTH: u8 = WI;
474}
475
476impl<'a, U, REG, N, FI, const WI: u8, const OF: u8> FieldWriterSafe<'a, U, REG, N, FI, WI, OF>
477where
478    REG: Writable + RegisterSpec<Ux = U>,
479    N: From<FI>,
480{
481    /// Field width
482    pub const WIDTH: u8 = WI;
483}
484
485macro_rules! bit_proxy {
486    ($writer:ident, $mwv:ident) => {
487        #[doc(hidden)]
488        pub struct $mwv;
489
490        /// Bit-wise write field proxy
491        pub type $writer<'a, U, REG, FI, const O: u8> = BitWriterRaw<'a, U, REG, FI, $mwv, O>;
492
493        impl<'a, U, REG, FI, const OF: u8> $writer<'a, U, REG, FI, OF>
494        where
495            REG: Writable + RegisterSpec<Ux = U>,
496            bool: From<FI>,
497        {
498            /// Field width
499            pub const WIDTH: u8 = 1;
500        }
501    };
502}
503
504macro_rules! impl_bit_proxy {
505    ($writer:ident) => {
506        impl<'a, U, REG, FI, const OF: u8> $writer<'a, U, REG, FI, OF>
507        where
508            REG: Writable + RegisterSpec<Ux = U>,
509            U: RawReg,
510            bool: From<FI>,
511        {
512            /// Writes bit to the field
513            #[inline(always)]
514            pub fn bit(self, value: bool) -> &'a mut REG::Writer {
515                self.w.bits &= !(U::one() << OF);
516                self.w.bits |= (U::from(value) & U::one()) << OF;
517                self.w
518            }
519            /// Writes `variant` to the field
520            #[inline(always)]
521            pub fn variant(self, variant: FI) -> &'a mut REG::Writer {
522                self.bit(bool::from(variant))
523            }
524        }
525    };
526}
527
528bit_proxy!(BitWriter, BitM);
529bit_proxy!(BitWriter1S, Bit1S);
530bit_proxy!(BitWriter0C, Bit0C);
531bit_proxy!(BitWriter1C, Bit1C);
532bit_proxy!(BitWriter0S, Bit0S);
533bit_proxy!(BitWriter1T, Bit1T);
534bit_proxy!(BitWriter0T, Bit0T);
535
536impl<'a, U, REG, N, FI, const WI: u8, const OF: u8> FieldWriter<'a, U, REG, N, FI, WI, OF>
537where
538    REG: Writable + RegisterSpec<Ux = U>,
539    U: RawReg + From<N>,
540    N: From<FI>,
541{
542    /// Writes raw bits to the field
543    ///
544    /// # Safety
545    ///
546    /// Passing incorrect value can cause undefined behaviour. See reference manual
547    #[inline(always)]
548    pub unsafe fn bits(self, value: N) -> &'a mut REG::Writer {
549        self.w.bits &= !(U::mask::<WI>() << OF);
550        self.w.bits |= (U::from(value) & U::mask::<WI>()) << OF;
551        self.w
552    }
553    /// Writes `variant` to the field
554    #[inline(always)]
555    pub fn variant(self, variant: FI) -> &'a mut REG::Writer {
556        unsafe { self.bits(N::from(variant)) }
557    }
558}
559impl<'a, U, REG, N, FI, const WI: u8, const OF: u8> FieldWriterSafe<'a, U, REG, N, FI, WI, OF>
560where
561    REG: Writable + RegisterSpec<Ux = U>,
562    U: RawReg + From<N>,
563    N: From<FI>,
564{
565    /// Writes raw bits to the field
566    #[inline(always)]
567    pub fn bits(self, value: N) -> &'a mut REG::Writer {
568        self.w.bits &= !(U::mask::<WI>() << OF);
569        self.w.bits |= (U::from(value) & U::mask::<WI>()) << OF;
570        self.w
571    }
572    /// Writes `variant` to the field
573    #[inline(always)]
574    pub fn variant(self, variant: FI) -> &'a mut REG::Writer {
575        self.bits(N::from(variant))
576    }
577}
578
579impl_bit_proxy!(BitWriter);
580impl_bit_proxy!(BitWriter1S);
581impl_bit_proxy!(BitWriter0C);
582impl_bit_proxy!(BitWriter1C);
583impl_bit_proxy!(BitWriter0S);
584impl_bit_proxy!(BitWriter1T);
585impl_bit_proxy!(BitWriter0T);
586
587impl<'a, U, REG, FI, const OF: u8> BitWriter<'a, U, REG, FI, OF>
588where
589    REG: Writable + RegisterSpec<Ux = U>,
590    U: RawReg,
591    bool: From<FI>,
592{
593    /// Sets the field bit
594    #[inline(always)]
595    pub fn set_bit(self) -> &'a mut REG::Writer {
596        self.w.bits |= U::one() << OF;
597        self.w
598    }
599    /// Clears the field bit
600    #[inline(always)]
601    pub fn clear_bit(self) -> &'a mut REG::Writer {
602        self.w.bits &= !(U::one() << OF);
603        self.w
604    }
605}
606
607impl<'a, U, REG, FI, const OF: u8> BitWriter1S<'a, U, REG, FI, OF>
608where
609    REG: Writable + RegisterSpec<Ux = U>,
610    U: RawReg,
611    bool: From<FI>,
612{
613    /// Sets the field bit
614    #[inline(always)]
615    pub fn set_bit(self) -> &'a mut REG::Writer {
616        self.w.bits |= U::one() << OF;
617        self.w
618    }
619}
620
621impl<'a, U, REG, FI, const OF: u8> BitWriter0C<'a, U, REG, FI, OF>
622where
623    REG: Writable + RegisterSpec<Ux = U>,
624    U: RawReg,
625    bool: From<FI>,
626{
627    /// Clears the field bit
628    #[inline(always)]
629    pub fn clear_bit(self) -> &'a mut REG::Writer {
630        self.w.bits &= !(U::one() << OF);
631        self.w
632    }
633}
634
635impl<'a, U, REG, FI, const OF: u8> BitWriter1C<'a, U, REG, FI, OF>
636where
637    REG: Writable + RegisterSpec<Ux = U>,
638    U: RawReg,
639    bool: From<FI>,
640{
641    ///Clears the field bit by passing one
642    #[inline(always)]
643    pub fn clear_bit_by_one(self) -> &'a mut REG::Writer {
644        self.w.bits |= U::one() << OF;
645        self.w
646    }
647}
648
649impl<'a, U, REG, FI, const OF: u8> BitWriter0S<'a, U, REG, FI, OF>
650where
651    REG: Writable + RegisterSpec<Ux = U>,
652    U: RawReg,
653    bool: From<FI>,
654{
655    ///Sets the field bit by passing zero
656    #[inline(always)]
657    pub fn set_bit_by_zero(self) -> &'a mut REG::Writer {
658        self.w.bits &= !(U::one() << OF);
659        self.w
660    }
661}
662
663impl<'a, U, REG, FI, const OF: u8> BitWriter1T<'a, U, REG, FI, OF>
664where
665    REG: Writable + RegisterSpec<Ux = U>,
666    U: RawReg,
667    bool: From<FI>,
668{
669    ///Toggle the field bit by passing one
670    #[inline(always)]
671    pub fn toggle_bit(self) -> &'a mut REG::Writer {
672        self.w.bits |= U::one() << OF;
673        self.w
674    }
675}
676
677impl<'a, U, REG, FI, const OF: u8> BitWriter0T<'a, U, REG, FI, OF>
678where
679    REG: Writable + RegisterSpec<Ux = U>,
680    U: RawReg,
681    bool: From<FI>,
682{
683    ///Toggle the field bit by passing zero
684    #[inline(always)]
685    pub fn toggle_bit(self) -> &'a mut REG::Writer {
686        self.w.bits &= !(U::one() << OF);
687        self.w
688    }
689}
690
avr_device/generic.rs

avr_device/
generic.rs
