1+ #![ doc( test( attr( deny( warnings) ) ) ) ]
2+ #![ doc( test( attr( allow( dead_code) ) ) ) ]
3+
14use proc_macro:: TokenStream ;
25use proc_macro2:: TokenStream as TokenStream2 ;
36use quote:: ToTokens ;
@@ -11,6 +14,92 @@ macro_rules! bail {
1114
1215mod volatile;
1316
17+ /// A derive macro for method-based accesses to volatile structures.
18+ ///
19+ /// This macro allows you to access the fields of a volatile structure via methods that enforce access limitations.
20+ /// It is also more easily chainable than `map_field`.
21+ ///
22+ /// <div class="warning">
23+ ///
24+ /// This macro generates and implements a new `{T}VolatileFieldAccess` trait, that you have to import if used from other modules.
25+ /// Currently, the trait is only implemented for `VolatilePtr<'_, _, ReadWrite>`.
26+ ///
27+ /// </div>
28+ ///
29+ /// # Examples
30+ ///
31+ /// ```
32+ /// use volatile::access::ReadOnly;
33+ /// use volatile::{VolatileFieldAccess, VolatileRef};
34+ ///
35+ /// #[repr(C)]
36+ /// #[derive(VolatileFieldAccess, Default)]
37+ /// pub struct DeviceConfig {
38+ /// feature_select: u32,
39+ /// #[access(ReadOnly)]
40+ /// feature: u32,
41+ /// }
42+ ///
43+ /// let mut device_config = DeviceConfig::default();
44+ /// let mut volatile_ref = VolatileRef::from_mut_ref(&mut device_config);
45+ /// let volatile_ptr = volatile_ref.as_mut_ptr();
46+ ///
47+ /// volatile_ptr.feature_select().write(42);
48+ /// assert_eq!(volatile_ptr.feature_select().read(), 42);
49+ ///
50+ /// // This does not compile, because we specified `#[access(ReadOnly)]` for this field.
51+ /// // volatile_ptr.feature().write(42);
52+ ///
53+ /// // A real device might have changed the value, though.
54+ /// assert_eq!(volatile_ptr.feature().read(), 0);
55+ ///
56+ /// // You can also use shared references.
57+ /// let volatile_ptr = volatile_ref.as_ptr();
58+ /// assert_eq!(volatile_ptr.feature_select().read(), 42);
59+ /// // This does not compile, because `volatile_ptr` is `ReadOnly`.
60+ /// // volatile_ptr.feature_select().write(42);
61+ /// ```
62+ ///
63+ /// # Details
64+ ///
65+ /// This macro generates a new trait (`{T}VolatileFieldAccess`) and implements it for `VolatilePtr<'a, T, ReadWrite>`.
66+ /// The example above results in (roughly) the following code:
67+ ///
68+ /// ```
69+ /// # #[repr(C)]
70+ /// # pub struct DeviceConfig {
71+ /// # feature_select: u32,
72+ /// # feature: u32,
73+ /// # }
74+ /// use volatile::access::{ReadOnly, ReadWrite, RestrictAccess};
75+ /// use volatile::{map_field, VolatilePtr};
76+ ///
77+ /// pub trait DeviceConfigVolatileFieldAccess<'a, A> {
78+ /// fn feature_select(self) -> VolatilePtr<'a, u32, A::Restricted>
79+ /// where
80+ /// A: RestrictAccess<ReadWrite>;
81+ ///
82+ /// fn feature(self) -> VolatilePtr<'a, u32, A::Restricted>
83+ /// where
84+ /// A: RestrictAccess<ReadOnly>;
85+ /// }
86+ ///
87+ /// impl<'a, A> DeviceConfigVolatileFieldAccess<'a, A> for VolatilePtr<'a, DeviceConfig, A> {
88+ /// fn feature_select(self) -> VolatilePtr<'a, u32, A::Restricted>
89+ /// where
90+ /// A: RestrictAccess<ReadWrite>
91+ /// {
92+ /// map_field!(self.feature_select).restrict()
93+ /// }
94+ ///
95+ /// fn feature(self) -> VolatilePtr<'a, u32, A::Restricted>
96+ /// where
97+ /// A: RestrictAccess<ReadOnly>
98+ /// {
99+ /// map_field!(self.feature).restrict()
100+ /// }
101+ /// }
102+ /// ```
14103#[ proc_macro_derive( VolatileFieldAccess , attributes( access) ) ]
15104pub fn derive_volatile ( item : TokenStream ) -> TokenStream {
16105 match volatile:: derive_volatile ( parse_macro_input ! ( item) ) {
0 commit comments