Skip to content

Commit 6616c04

Browse files
phil-oppphil-opp
authored
Merge pull request #61 from mkroening/general-derive
feat: implement derive macro for all access types
2 parents 53c30e7 + 904021d commit 6616c04

File tree

4 files changed

+117
-82
lines changed

4 files changed

+117
-82
lines changed

‎src/lib.rs

Lines changed: 0 additions & 70 deletions
Original file line numberDiff line numberDiff line change
@@ -47,76 +47,6 @@
4747
#![doc(test(attr(allow(dead_code))))]
4848
#![doc(test(attr(allow(unused_variables))))]
4949

50-
/// A derive macro for method-based accesses to volatile structures.
51-
///
52-
/// This macro allows you to access the fields of a volatile structure via methods that enforce access limitations.
53-
/// It is also more easily chainable than [`map_field`].
54-
///
55-
/// <div class="warning">
56-
///
57-
/// This macro generates and implements a new `{T}VolatileFieldAccess` trait, that you have to import if used from other modules.
58-
/// Currently, the trait is only implemented for `VolatilePtr<'_, _, ReadWrite>`.
59-
///
60-
/// </div>
61-
///
62-
/// # Examples
63-
///
64-
/// ```
65-
/// use volatile::access::ReadOnly;
66-
/// use volatile::{VolatileFieldAccess, VolatileRef};
67-
///
68-
/// #[repr(C)]
69-
/// #[derive(VolatileFieldAccess, Default)]
70-
/// pub struct DeviceConfig {
71-
/// feature_select: u32,
72-
/// #[access(ReadOnly)]
73-
/// feature: u32,
74-
/// }
75-
///
76-
/// let mut device_config = DeviceConfig::default();
77-
/// let mut volatile_ref = VolatileRef::from_mut_ref(&mut device_config);
78-
/// let volatile_ptr = volatile_ref.as_mut_ptr();
79-
///
80-
/// volatile_ptr.feature_select().write(42);
81-
/// assert_eq!(volatile_ptr.feature_select().read(), 42);
82-
///
83-
/// // This does not compile, because we specified `#[access(ReadOnly)]` for this field.
84-
/// // volatile_ptr.feature().write(42);
85-
///
86-
/// // A real device might have changed the value, though.
87-
/// assert_eq!(volatile_ptr.feature().read(), 0);
88-
/// ```
89-
///
90-
/// # Details
91-
///
92-
/// This macro generates a new trait (`{T}VolatileFieldAccess`) and implements it for `VolatilePtr<'a, T, ReadWrite>`.
93-
/// The example above results in (roughly) the following code:
94-
///
95-
/// ```
96-
/// # #[repr(C)]
97-
/// # pub struct DeviceConfig {
98-
/// # feature_select: u32,
99-
/// # feature: u32,
100-
/// # }
101-
/// use volatile::access::{ReadOnly, ReadWrite};
102-
/// use volatile::{map_field, VolatilePtr};
103-
///
104-
/// pub trait DeviceConfigVolatileFieldAccess<'a> {
105-
/// fn feature_select(self) -> VolatilePtr<'a, u32, ReadWrite>;
106-
///
107-
/// fn feature(self) -> VolatilePtr<'a, u32, ReadOnly>;
108-
/// }
109-
///
110-
/// impl<'a> DeviceConfigVolatileFieldAccess<'a> for VolatilePtr<'a, DeviceConfig, ReadWrite> {
111-
/// fn feature_select(self) -> VolatilePtr<'a, u32, ReadWrite> {
112-
/// map_field!(self.feature_select).restrict()
113-
/// }
114-
///
115-
/// fn feature(self) -> VolatilePtr<'a, u32, ReadOnly> {
116-
/// map_field!(self.feature).restrict()
117-
/// }
118-
/// }
119-
/// ```
12050
#[cfg(feature = "derive")]
12151
pub use volatile_macro::VolatileFieldAccess;
12252

‎volatile-macro/Cargo.toml

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,3 +16,6 @@ proc-macro = true
1616
proc-macro2 = "1"
1717
quote = "1"
1818
syn = { version = "2", features = ["full"] }
19+
20+
[dev-dependencies]
21+
volatile = { version = "=0.5.4", path = "..", features = ["derive"] }

‎volatile-macro/src/lib.rs

Lines changed: 89 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,6 @@
1+
#![doc(test(attr(deny(warnings))))]
2+
#![doc(test(attr(allow(dead_code))))]
3+
14
use proc_macro::TokenStream;
25
use proc_macro2::TokenStream as TokenStream2;
36
use quote::ToTokens;
@@ -11,6 +14,92 @@ macro_rules! bail {
1114

1215
mod 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))]
15104
pub fn derive_volatile(item: TokenStream) -> TokenStream {
16105
match volatile::derive_volatile(parse_macro_input!(item)) {

‎volatile-macro/src/volatile.rs

Lines changed: 25 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -84,7 +84,9 @@ fn parse_input(input: &ItemStruct) -> Result<ParsedInput> {
8484
}
8585

8686
let sig = parse_quote! {
87-
fn #ident(self) -> ::volatile::VolatilePtr<'a, #ty, #access>
87+
fn #ident(self) -> ::volatile::VolatilePtr<'a, #ty, A::Restricted>
88+
where
89+
A: ::volatile::access::RestrictAccess<#access>
8890
};
8991
sigs.push(sig);
9092
}
@@ -112,7 +114,7 @@ fn emit_trait(
112114
parse_quote! {
113115
#(#attrs)*
114116
#[allow(non_camel_case_types)]
115-
#vis trait #trait_ident <'a> {
117+
#vis trait #trait_ident <'a, A> {
116118
#(
117119
#(#method_attrs)*
118120
#sigs;
@@ -133,9 +135,10 @@ fn emit_impl(
133135

134136
parse_quote! {
135137
#[automatically_derived]
136-
impl<'a> #trait_ident<'a> for ::volatile::VolatilePtr<'a, #struct_ident, ::volatile::access::ReadWrite> {
138+
impl<'a, A> #trait_ident<'a, A> for ::volatile::VolatilePtr<'a, #struct_ident, A> {
137139
#(
138-
#sigs {
140+
#sigs,
141+
{
139142
::volatile::map_field!(self.#fields).restrict()
140143
}
141144
)*
@@ -183,24 +186,34 @@ mod tests {
183186
///
184187
/// This is a wonderful struct.
185188
#[allow(non_camel_case_types)]
186-
pub trait DeviceConfigVolatileFieldAccess<'a> {
187-
fn feature_select(self) -> ::volatile::VolatilePtr<'a, u32, ::volatile::access::ReadWrite>;
189+
pub trait DeviceConfigVolatileFieldAccess<'a, A> {
190+
fn feature_select(self) -> ::volatile::VolatilePtr<'a, u32, A::Restricted>
191+
where
192+
A: ::volatile::access::RestrictAccess<::volatile::access::ReadWrite>;
188193

189194
/// Feature.
190195
///
191196
/// This is a good field.
192-
fn feature(self) -> ::volatile::VolatilePtr<'a, u32, ReadOnly>;
197+
fn feature(self) -> ::volatile::VolatilePtr<'a, u32, A::Restricted>
198+
where
199+
A: ::volatile::access::RestrictAccess<ReadOnly>;
193200
}
194201
};
195202

196203
let expected_impl = quote! {
197204
#[automatically_derived]
198-
impl<'a> DeviceConfigVolatileFieldAccess<'a> for ::volatile::VolatilePtr<'a, DeviceConfig, ::volatile::access::ReadWrite> {
199-
fn feature_select(self) -> ::volatile::VolatilePtr<'a, u32, ::volatile::access::ReadWrite> {
205+
impl<'a, A> DeviceConfigVolatileFieldAccess<'a, A> for ::volatile::VolatilePtr<'a, DeviceConfig, A> {
206+
fn feature_select(self) -> ::volatile::VolatilePtr<'a, u32, A::Restricted>
207+
where
208+
A: ::volatile::access::RestrictAccess<::volatile::access::ReadWrite>,
209+
{
200210
::volatile::map_field!(self.feature_select).restrict()
201211
}
202212

203-
fn feature(self) -> ::volatile::VolatilePtr<'a, u32, ReadOnly> {
213+
fn feature(self) -> ::volatile::VolatilePtr<'a, u32, A::Restricted>
214+
where
215+
A: ::volatile::access::RestrictAccess<ReadOnly>,
216+
{
204217
::volatile::map_field!(self.feature).restrict()
205218
}
206219
}
@@ -230,12 +243,12 @@ mod tests {
230243

231244
let expected_trait = quote! {
232245
#[allow(non_camel_case_types)]
233-
pub trait DeviceConfigVolatileFieldAccess<'a> {}
246+
pub trait DeviceConfigVolatileFieldAccess<'a, A> {}
234247
};
235248

236249
let expected_impl = quote! {
237250
#[automatically_derived]
238-
impl<'a> DeviceConfigVolatileFieldAccess<'a> for ::volatile::VolatilePtr<'a, DeviceConfig, ::volatile::access::ReadWrite> {}
251+
impl<'a, A> DeviceConfigVolatileFieldAccess<'a, A> for ::volatile::VolatilePtr<'a, DeviceConfig, A> {}
239252
};
240253

241254
assert_eq!(

0 commit comments

Comments
 (0)