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
//! A [`Bitfield`] is an integer value treated as a sequence of bits, which can //! be toggled individually. //! //! A type with named bit-fields can be defined with the attribute macro: //! //! ``` //! use drone_core::bitfield::Bitfield; //! //! #[derive(Clone, Copy, Bitfield)] //! #[bitfield( //! // The syntax of the field definitions is the following: //! // field_name(mode, offset[, width[, doc_string]]) //! // `width` is default to 1 when omitted. //! // `mode` is one of `r` (for read-only), `rw` (for read-write), //! // `w` (for write-only). //! foo(rw, 1, 4, "4-bits field"), //! bar(rw, 5, 1, "1-bit field"), //! )] //! // The choice of the underlying integer determines the total number of bits. //! // Available sizes: `u8`, `u16`, `u32`, `u64`, `u128`. //! struct MyValue(u8); //! //! // * foo bit //! let mut value = MyValue(0b0011_1010); //! // * *** bar bits //! //! // The size of the value is exactly the size of the underlying integer. //! assert_eq!(core::mem::size_of_val(&value), 1); //! //! // For one-bit fields, the macro defines the following methods: //! // value.bar() for reading the bit (except `w` mode) //! // value.set_bar() for setting the bit (except `r` mode) //! // value.clear_bar() for clearing the bit (except `r` mode) //! // value.toggle_bar() for toggling the bit (except `r` mode) //! assert!(value.bar()); //! value.clear_bar(); //! assert!(!value.bar()); //! value.set_bar(); //! assert!(value.bar()); //! value.toggle_bar(); //! assert!(!value.bar()); //! //! // For multiple-bit fields, the macro defines the following methods: //! // value.foo() for reading the bits (except `w` mode) //! // value.write_foo(bits) for writing the bits (except `r` mode) //! assert_eq!(value.foo(), 0b1101); //! value.write_foo(0b1010); //! assert_eq!(value.foo(), 0b1010); //! //! assert_eq!(value.0, 0b0001_0100); //! ``` mod bits; /// Defines a new [`Bitfield`]. /// /// See [the module level documentation](self) for details. #[doc(inline)] pub use drone_core_macros::Bitfield; pub use self::bits::Bits; /// An integer value treated as a sequence of bits, which can be toggled /// individually. /// /// See [the module level documentation](self) for more. pub trait Bitfield: Sized + Send + Sync + Clone + Copy + 'static { /// The type of the integer. Determines the total number of bits. type Bits: Bits; /// Returns a copy of the underlying integer. fn bits(&self) -> Self::Bits; /// Returns a mutable reference to the underlying integer. fn bits_mut(&mut self) -> &mut Self::Bits; /// Returns `true` if the bit at `offset` is set. /// /// # Safety /// /// `offset` must not exceed the integer size. #[inline] unsafe fn read_bit(&self, offset: Self::Bits) -> bool { !(self.bits() & bit_at(offset)).is_zero() } /// Sets the bit at `offset`. /// /// # Safety /// /// `offset` must not exceed the integer size. #[inline] unsafe fn set_bit(&mut self, offset: Self::Bits) { *self.bits_mut() = self.bits() | bit_at(offset); } /// Clears the bit at `offset`. /// /// # Safety /// /// `offset` must not exceed the integer size. #[inline] unsafe fn clear_bit(&mut self, offset: Self::Bits) { *self.bits_mut() = self.bits() & !bit_at(offset); } /// Toggles the bit at `offset`. /// /// # Safety /// /// `offset` must not exceed the integer size. #[inline] unsafe fn toggle_bit(&mut self, offset: Self::Bits) { *self.bits_mut() = self.bits() ^ bit_at(offset); } /// Returns `width` number of bits at `offset` position. /// /// # Safety /// /// `offset + width` must not exceed the integer size. #[inline] unsafe fn read_bits(&self, offset: Self::Bits, width: Self::Bits) -> Self::Bits { if width == Self::Bits::width() { self.bits() } else { self.bits() >> offset & bit_mask(width) } } /// Writes `width` number of bits at `offset` position from `bits`. /// /// # Safety /// /// `offset + width` must not exceed the integer size. #[inline] unsafe fn write_bits(&mut self, offset: Self::Bits, width: Self::Bits, bits: Self::Bits) { *self.bits_mut() = if width == Self::Bits::width() { bits } else { self.bits() & !(bit_mask(width) << offset) | (bits & bit_mask(width)) << offset }; } } fn bit_at<T: Bits>(offset: T) -> T { T::from_usize(1) << offset } fn bit_mask<T: Bits>(width: T) -> T { bit_at(width) - T::from_usize(1) }