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
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
pub mod support;

use crate::*;
use support::*;

bitfield! {
    /// A bitfield showcasing how to specify bit ranges.
    #[derive(Clone, Copy, PartialEq, Eq)]
    pub struct BitRanges(pub u16): Debug, FromRaw, IntoRaw, DerefRaw {
        // A single field spanning the entire bitfield, using an unbounded range:
        pub whole_bitfield: u16 @ ..,                 // Bits 0 to 15

        // Multi-bit field, specified using an inclusive range:
        pub inclusive_range: u8 @ 0..=3,              // Bits 0 to 3

        // Multi-bit field, specified using an exclusive range:
        pub exclusive_range: u8 @ 4..7,               // Bits 4 to 6

        // Multi-bit field specified using its start bit and length:
        pub start_and_length: u8 @ 7; 5,              // Bits 7 to 11

        // Single-bit field, specified using an inclusive range:
        pub single_bit_inclusive_range: u8 @ 12..=12, // Bit 12

        // Single-bit field, specified using an exclusive range:
        pub single_bit_exclusive_range: u8 @ 13..14,  // Bit 13

        // Single-bit field, specified using its start bit and a length of 1:
        pub single_bit_start_and_length: u8 @ 14; 1,  // Bit 14

        // Single-bit boolean flag, specified using a single bit position.
        // This is equivalent to the single-bit exclusive range, but uses the `Bit` traits instead
        // of `Bits<T>`, and is specific to `bool` (which is conversely not allowed using bit
        // ranges).
        pub flag: bool @ 15,                          // Bit 15
    }
}

bitfield! {
    /// A bitfield showcasing how to specify access restrictions.
    pub struct AccessRestrictions(pub u8): Debug, FromRaw, IntoRaw, DerefRaw {
        // By specifying `read_only` (or `ro`), only `Example::read_only_flag` will be generated (no
        // setters):
        pub read_only_flag: bool [read_only] @ 0,
        // Equivalent:
        // pub read_only_flag: bool [ro] @ 0,

        // By specifying `write_only` (or `wo`), only `Example::set_write_only_flag` and
        // `Example::with_write_only_flag` will be generated (no getters):
        pub write_only_flag: bool [write_only] @ 1,
        // Equivalent:
        // pub read_only_flag: bool [wo] @ 0,

        // Both getters and setters will be generated without any explicit access restrictions:
        // `Example::read_write_flag`, `Example::set_read_write_flag` and
        // `Example::with_read_write_flag` will all be generated.
        pub read_write_flag: bool @ 2,
    }
}

bitfield! {
    /// A bitfield showcasing various kinds of field type conversions.
    pub struct FieldTypeConversions(pub u16): Debug, FromRaw, IntoRaw, DerefRaw {
        // Infallible conversions

        // Will:
        // - Return a `U8WithParity` on reads, calling `<U8WithParity as From<u8>>::from`
        // - Take a `u8` for writes
        pub read_as_u8_with_parity: u8 [get U8WithParity] @ 0..=3,

        // Will:
        // - Return a `u8` on reads
        // - Take a `U8WithParity` for writes, calling `<U8WithParity as Into<u8>>::into`
        pub write_as_u8_with_parity: u8 [set U8WithParity] @ 4..=7,

        // Will:
        // - Return a `U8WithParity` on reads, calling `<U8WithParity as From<u8>>::from`
        // - Take a `U8WithParity` for writes, calling `<U8WithParity as Into<u8>>::into`
        pub as_u8_with_parity: u8 [U8WithParity] @ 8..=11,
        // Equivalent to:
        // pub u8_with_parity: u8 [get U8WithParity, set U8WithParity] @ 8..=11,


        // Infallible conversion functions

        // Will:
        // - Return a `U8WithParity` on reads, calling `<U8WithParity as From<u8>>::from`
        // - Take a `u8` for writes
        pub read_as_u8_with_parity_fn: u8 [get_fn U8WithParity::from -> U8WithParity] @ 0..=3,

        // Will:
        // - Return a `u8` on reads
        // - Take a `U8WithParity` for writes, calling `<U8WithParity as Into<u8>>::into`
        pub write_as_u8_with_parity_fn: u8 [set_fn U8WithParity::into(U8WithParity)] @ 4..=7,


        // Unsafe/unchecked conversions

        // Will:
        // - Return a `NonZeroU8` on reads, marking them as `unsafe` and calling
        //   `<NonZeroU8 as UnsafeFrom<u8>>::unsafe_from`
        // - Take a `u8` for writes
        pub unsafe_read_as_non_zero_u8: u8 [unsafe_get NonZeroU8] @ 0..=3,

        // Will:
        // - Return a `u8` on reads
        // - Take a `U16` for writes, marking them as `unsafe` and calling
        //   `<U16 as UnsafeInto<u8>>::unsafe_into`
        pub unsafe_write_as_u16: u8 [unsafe_set U16] @ 4..=7,

        // Will:
        // - Return a `SpuriouslyFailingU8` on reads, marking them as `unsafe` and calling
        //   `<SpuriouslyFailingU8 as UnsafeFrom<u8>>::unsafe_from`
        // - Take a `SpuriouslyFailingU8` for writes, marking them as `unsafe` and calling
        //   `<SpuriouslyFailingU8 as UnsafeInto<u8>>::unsafe_into`
        pub unsafe_as_spuriously_failing: u8 [unsafe_both SpuriouslyFailingU8] @ 8..=11,
        // Equivalent to:
        // pub unsafe_as_spuriously_failing: u8
        //  [unsafe_get SpuriouslyFailingU8, unsafe_set SpuriouslyFailingU8] @ 8..=11,

        // Will:
        // - Return a `NonZeroU8` on reads, marking them as `unsafe` and calling
        //   `<NonZeroU8 as UnsafeFrom<u8>>::unsafe_from`
        // - Take a `NonZeroU8` for writes, calling `<NonZeroU8 as Into<u8>>::into`
        pub unsafe_as_non_zero_u8: u8 [unsafe NonZeroU8] @ 12..=15,
        // Equivalent to:
        // pub unsafe_as_non_zero_u8: u8 [unsafe_get NonZeroU8, set NonZeroU8] @ 12..=15,


        // Unsafe/unchecked conversion functions

        // Will:
        // - Return a `NonZeroU8` on reads, marking them as `unsafe` and calling
        //   `<NonZeroU8 as UnsafeFrom<u8>>::unsafe_from`
        // - Take a `u8` for writes
        pub unsafe_read_as_non_zero_u8_fn: u8 [
            unsafe_get_fn NonZeroU8::unsafe_from -> NonZeroU8
        ] @ 0..=3,

        // Will:
        // - Return a `u8` on reads
        // - Take a `U16` for writes, marking them as `unsafe` and calling
        //   `<U16 as UnsafeInto<u8>>::unsafe_into`
        pub unsafe_write_as_u16_fn: u8 [unsafe_set_fn U16::unsafe_into(U16)] @ 4..=7,


        // Unsafe/unchecked conversions with safe accessors

        // Will:
        // - Return a `NonZeroU8` on reads, unsafely calling
        //   `<NonZeroU8 as UnsafeFrom<u8>>::unsafe_from`
        // - Take a `u8` for writes
        pub unsafe_read_as_non_zero_u8_safe_acc: u8 [unsafe_get! NonZeroU8] @ 0..=3,

        // Will:
        // - Return a `u8` on reads
        // - Take a `U16` for writes, unsafely calling
        //   `<U16 as UnsafeInto<u8>>::unsafe_into`
        pub unsafe_write_as_u16_safe_acc: u8 [unsafe_set! U16] @ 4..=7,

        // Will:
        // - Return a `SpuriouslyFailingU8` on reads, unsafely calling
        //   `<SpuriouslyFailingU8 as UnsafeFrom<u8>>::unsafe_from`
        // - Take a `SpuriouslyFailingU8` for writes, unsafely calling
        //   `<SpuriouslyFailingU8 as UnsafeInto<u8>>::unsafe_into`
        pub unsafe_as_spuriously_failing_safe_acc: u8 [unsafe_both! SpuriouslyFailingU8] @ 8..=11,
        // Equivalent to:
        // pub unsafe_as_spuriously_failing_safe_acc: u8
        //  [unsafe_get! SpuriouslyFailingU8, unsafe_set! SpuriouslyFailingU8] @ 8..=11,

        // Will:
        // - Return a `NonZeroU8` on reads, unsafely calling
        //   `<NonZeroU8 as UnsafeFrom<u8>>::unsafe_from`
        // - Take a `NonZeroU8` for writes, calling `<NonZeroU8 as Into<u8>>::into`
        pub unsafe_as_non_zero_u8_safe_acc: u8 [unsafe! NonZeroU8] @ 12..=15,
        // Equivalent to:
        // pub unsafe_as_non_zero_u8_safe_acc: u8 [unsafe_get! NonZeroU8, set NonZeroU8] @ 12..=15,


        // Unsafe/unchecked conversion functions with safe accessors

        // Will:
        // - Return a `NonZeroU8` on reads, unsafely calling
        //   `<NonZeroU8 as UnsafeFrom<u8>>::unsafe_from`
        // - Take a `u8` for writes
        pub unsafe_read_as_non_zero_u8_fn_safe_acc: u8 [
            unsafe_get_fn! NonZeroU8::unsafe_from -> NonZeroU8
        ] @ 0..=3,

        // Will:
        // - Return a `u8` on reads
        // - Take a `U16` for writes, unsafely calling `<U16 as UnsafeInto<u8>>::unsafe_into`
        pub unsafe_write_as_u16_fn_safe_acc: u8 [unsafe_set_fn! U16::unsafe_into(U16)] @ 4..=7,


        // Fallible conversions

        // Will:
        // - Return a `Result<NonZeroU8, TryFromIntError>` on reads, calling
        //   `<NonZeroU8 as TryFrom<u8>>::try_from`
        // - Take a `u8` for writes
        pub try_read_as_non_zero_u8: u8 [try_get NonZeroU8] @ 0..=3,

        // Will:
        // - Return a `u8` on reads
        // - Take a `U16` for writes, returning `Result<(), TryFromIntError>` and calling
        //   `<U16 as TryInto<u8>>::try_into`
        pub try_write_as_u16: u8 [try_set U16] @ 4..=7,

        // Will:
        // - Return a `Result<SpuriouslyFailingU8, ()>` on reads, calling
        //   `<SpuriouslyFailingU8 as TryFrom<u8>>::try_from`
        // - Take a `SpuriouslyFailingU8` for writes, returning `Result<(), ()>` and calling
        //   `<SpuriouslyFailingU8 as TryInto<u8>>::try_into`
        pub try_both_as_spuriously_failing: u8 [try_both SpuriouslyFailingU8] @ 8..=11,
        // Equivalent to:
        // pub try_both_as_spuriously_failing: u8
        //  [try_get SpuriouslyFailingU8, try_set SpuriouslyFailingU8] @ 8..=11,

        // Will:
        // - Return a `Result<NonZeroU8, TryFromIntError>` on reads, calling
        //   `<NonZeroU8 as TryFrom<u8>>::try_from`
        // - Take a `NonZeroU8` for writes, calling `<NonZeroU8 as Into<u8>>::into`
        pub try_as_non_zero_u8: u8 [try NonZeroU8] @ 12..=15,
        // Equivalent to:
        // pub try_as_non_zero_u8: u8 [try_get NonZeroU8, set NonZeroU8] @ 12..=15,


        // Fallible conversion functions

        // Will:
        // - Return a `Result<NonZeroU8, TryFromIntError>` on reads, calling
        //   `<NonZeroU8 as TryFrom<u8>>::try_from`
        // - Take a `u8` for writes
        pub try_read_as_non_zero_u8_fn: u8 [
            try_get_fn NonZeroU8::try_from -> Result<NonZeroU8, TryFromIntError>
        ] @ 0..=3,

        // Will:
        // - Return a `u8` on reads
        // - Take a `U16` for writes, returning `Result<(), TryFromIntError>` and calling
        //   `<U16 as TryInto<u8>>::try_into`
        pub try_write_as_u16_fn: u8 [
            try_set_fn U16::try_into(U16) -> Result<u8, TryFromIntError>
        ] @ 4..=7,


        // Unwrapping conversions

        // Will:
        // - Return a `NonZeroU8` on reads, calling `<NonZeroU8 as TryFrom<u8>>::try_from` and
        //   unwrapping the result
        // - Take a `u8` for writes
        pub unwrap_read_as_non_zero_u8: u8 [unwrap_get NonZeroU8] @ 0..=3,

        // Will:
        // - Return a `u8` on reads
        // - Take a `U16` for writes, returning `()`, calling `<U16 as TryInto<u8>>::try_into` and
        //   unwrapping the result
        pub unwrap_write_as_u16: u8 [unwrap_set U16] @ 4..=7,

        // Will:
        // - Return a `SpuriouslyFailingU8` on reads, calling
        //   `<SpuriouslyFailingU8 as TryFrom<u8>>::try_from` and unwrapping the result
        // - Take a `SpuriouslyFailingU8` for writes, returning `()`, calling
        //   `<SpuriouslyFailingU8 as TryInto<u8>>::try_into` and unwrapping the result
        pub unwrap_both_as_spuriously_failing: u8 [unwrap_both SpuriouslyFailingU8] @ 8..=11,
        // Equivalent to:
        // pub try_both_as_spuriously_failing: u8
        //  [try_get SpuriouslyFailingU8, try_set SpuriouslyFailingU8] @ 8..=11,

        // Will:
        // - Return a `NonZeroU8` on reads, calling `<NonZeroU8 as TryFrom<u8>>::try_from` and
        //   unwrapping the result
        // - Take a `NonZeroU8` for writes, calling `<NonZeroU8 as Into<u8>>::into`
        pub unwrap_as_non_zero_u8: u8 [unwrap NonZeroU8] @ 12..=15,
        // Equivalent to:
        // pub unwrap_as_non_zero_u8: u8 [unwrap_get NonZeroU8, set NonZeroU8] @ 12..=15,


        // Unwrapping conversion functions

        // Will:
        // - Return a `NonZeroU8` on reads, calling `<NonZeroU8 as TryFrom<u8>>::try_from` and
        //   unwrapping the result
        // - Take a `u8` for writes
        pub unwrap_read_as_non_zero_u8_fn: u8 [unwrap_get_fn NonZeroU8::try_from -> NonZeroU8] @ 0..=3,

        // Will:
        // - Return a `u8` on reads
        // - Take a `U16` for writes, returning `()`, calling `<U16 as TryInto<u8>>::try_into` and
        //   unwrapping the result
        pub unwrap_write_as_u16_fn: u8 [unwrap_set_fn U16::try_into(U16)] @ 4..=7,
    }
}

/// An enum showcasing the `ConvRaw` derive for converting from/into integers.
#[derive(ConvRaw)]
pub enum ConvRawIntExample {
    A,
    B = 2,
    C,
    D = -1,
    E = 1,
    F = -128,
    G = 128,
}

/// An enum showcasing the `ConvRaw` derive for converting from/into booleans.
#[derive(ConvRaw)]
pub enum ConvRawBoolExample {
    False, // Implicitly, this value is treated as 0 (false).
    True,
}

#[cfg(feature = "nightly")]
#[cfg_attr(all(doc, feature = "nightly"), doc(cfg(feature = "nightly")))]
/// A type showcasing the `UnwrapBits` derive.
#[derive(UnwrapBits)]
pub struct UnwrapBitsExample(NonZeroU8);