device_driver/
register.rs

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
use core::marker::PhantomData;

use crate::{FieldSet, ReadCapability, WriteCapability};

/// A trait to represent the interface to the device.
///
/// This is called to write to and read from registers.
pub trait RegisterInterface {
    /// The error type
    type Error;
    /// The address type used by this interface. Should likely be an integer.
    type AddressType: Copy;

    /// Write the given data to the register located at the given address
    fn write_register(
        &mut self,
        address: Self::AddressType,
        size_bits: u32,
        data: &[u8],
    ) -> Result<(), Self::Error>;

    /// Read the register located at the given addres to the given data slice
    fn read_register(
        &mut self,
        address: Self::AddressType,
        size_bits: u32,
        data: &mut [u8],
    ) -> Result<(), Self::Error>;
}

/// A trait to represent the interface to the device.
///
/// This is called to asynchronously write to and read from registers.
pub trait AsyncRegisterInterface {
    /// The error type
    type Error;
    /// The address type used by this interface. Should likely be an integer.
    type AddressType: Copy;

    /// Write the given data to the register located at the given address
    async fn write_register(
        &mut self,
        address: Self::AddressType,
        size_bits: u32,
        data: &[u8],
    ) -> Result<(), Self::Error>;

    /// Read the register located at the given addres to the given data slice
    async fn read_register(
        &mut self,
        address: Self::AddressType,
        size_bits: u32,
        data: &mut [u8],
    ) -> Result<(), Self::Error>;
}

/// Object that performs actions on the device in the context of a register
pub struct RegisterOperation<'i, Interface, AddressType: Copy, Register: FieldSet, Access> {
    interface: &'i mut Interface,
    address: AddressType,
    register_new_with_reset: fn() -> Register,
    _phantom: PhantomData<(Register, Access)>,
}

impl<'i, Interface, AddressType: Copy, Register: FieldSet, Access>
    RegisterOperation<'i, Interface, AddressType, Register, Access>
{
    #[doc(hidden)]
    pub fn new(
        interface: &'i mut Interface,
        address: AddressType,
        register_new_with_reset: fn() -> Register,
    ) -> Self {
        Self {
            interface,
            address,
            register_new_with_reset,
            _phantom: PhantomData,
        }
    }
}

impl<Interface, AddressType: Copy, Register: FieldSet, Access>
    RegisterOperation<'_, Interface, AddressType, Register, Access>
where
    Interface: RegisterInterface<AddressType = AddressType>,
    Access: WriteCapability,
{
    /// Write to the register.
    ///
    /// The closure is given the write object initialized to the reset value of the register.
    /// If no reset value is specified for this register, this function is the same as [Self::write_with_zero].
    pub fn write<R>(&mut self, f: impl FnOnce(&mut Register) -> R) -> Result<R, Interface::Error> {
        let mut register = (self.register_new_with_reset)();
        let returned = f(&mut register);

        let buffer = Register::BUFFER::from(register);
        self.interface
            .write_register(self.address, Register::SIZE_BITS, buffer.as_ref())?;
        Ok(returned)
    }

    /// Write to the register.
    ///
    /// The closure is given the write object initialized to all zero.
    pub fn write_with_zero<R>(
        &mut self,
        f: impl FnOnce(&mut Register) -> R,
    ) -> Result<R, Interface::Error> {
        let mut register = Register::new_with_zero();
        let returned = f(&mut register);
        self.interface.write_register(
            self.address,
            Register::SIZE_BITS,
            Register::BUFFER::from(register).as_mut(),
        )?;
        Ok(returned)
    }
}

impl<Interface, AddressType: Copy, Register: FieldSet, Access>
    RegisterOperation<'_, Interface, AddressType, Register, Access>
where
    Interface: RegisterInterface<AddressType = AddressType>,
    Access: ReadCapability,
{
    /// Read the register from the device
    pub fn read(&mut self) -> Result<Register, Interface::Error> {
        let mut buffer = Register::BUFFER::from(Register::new_with_zero());

        self.interface
            .read_register(self.address, Register::SIZE_BITS, buffer.as_mut())?;
        Ok(buffer.into())
    }
}

impl<Interface, AddressType: Copy, Register: FieldSet, Access>
    RegisterOperation<'_, Interface, AddressType, Register, Access>
where
    Interface: RegisterInterface<AddressType = AddressType>,
    Access: ReadCapability + WriteCapability,
{
    /// Modify the existing register value.
    ///
    /// The register is read, the value is then passed to the closure for making changes.
    /// The result is then written back to the device.
    pub fn modify<R>(&mut self, f: impl FnOnce(&mut Register) -> R) -> Result<R, Interface::Error> {
        let mut register = self.read()?;
        let returned = f(&mut register);
        self.interface.write_register(
            self.address,
            Register::SIZE_BITS,
            Register::BUFFER::from(register).as_mut(),
        )?;
        Ok(returned)
    }
}

impl<'i, Interface, AddressType: Copy, Register: FieldSet, Access>
    RegisterOperation<'i, Interface, AddressType, Register, Access>
where
    Interface: AsyncRegisterInterface<AddressType = AddressType>,
    Access: WriteCapability,
{
    /// Write to the register.
    ///
    /// The closure is given the write object initialized to the reset value of the register.
    /// If no reset value is specified for this register, this function is the same as [Self::write_with_zero].
    pub async fn write_async<R>(
        &mut self,
        f: impl FnOnce(&mut Register) -> R,
    ) -> Result<R, Interface::Error> {
        let mut register = (self.register_new_with_reset)();
        let returned = f(&mut register);

        let buffer = Register::BUFFER::from(register);
        self.interface
            .write_register(self.address, Register::SIZE_BITS, buffer.as_ref())
            .await?;
        Ok(returned)
    }

    /// Write to the register.
    ///
    /// The closure is given the write object initialized to all zero.
    pub async fn write_with_zero_async<R>(
        &mut self,
        f: impl FnOnce(&mut Register) -> R,
    ) -> Result<R, Interface::Error> {
        let mut register = Register::new_with_zero();
        let returned = f(&mut register);
        self.interface
            .write_register(
                self.address,
                Register::SIZE_BITS,
                Register::BUFFER::from(register).as_mut(),
            )
            .await?;
        Ok(returned)
    }
}

impl<'i, Interface, AddressType: Copy, Register: FieldSet, Access>
    RegisterOperation<'i, Interface, AddressType, Register, Access>
where
    Interface: AsyncRegisterInterface<AddressType = AddressType>,
    Access: ReadCapability,
{
    /// Read the register from the device
    pub async fn read_async(&mut self) -> Result<Register, Interface::Error> {
        let mut buffer = Register::BUFFER::from(Register::new_with_zero());

        self.interface
            .read_register(self.address, Register::SIZE_BITS, buffer.as_mut())
            .await?;
        Ok(buffer.into())
    }
}

impl<'i, Interface, AddressType: Copy, Register: FieldSet, Access>
    RegisterOperation<'i, Interface, AddressType, Register, Access>
where
    Interface: AsyncRegisterInterface<AddressType = AddressType>,
    Access: ReadCapability + WriteCapability,
{
    /// Modify the existing register value.
    ///
    /// The register is read, the value is then passed to the closure for making changes.
    /// The result is then written back to the device.
    pub async fn modify_async<R>(
        &mut self,
        f: impl FnOnce(&mut Register) -> R,
    ) -> Result<R, Interface::Error> {
        let mut register = self.read_async().await?;
        let returned = f(&mut register);
        self.interface
            .write_register(
                self.address,
                Register::SIZE_BITS,
                Register::BUFFER::from(register).as_mut(),
            )
            .await?;
        Ok(returned)
    }
}