1 // SPDX-License-Identifier: GPL-2.0 2 3 //! `register!` macro to define register layout and accessors. 4 //! 5 //! A single register typically includes several fields, which are accessed through a combination 6 //! of bit-shift and mask operations that introduce a class of potential mistakes, notably because 7 //! not all possible field values are necessarily valid. 8 //! 9 //! The `register!` macro in this module provides an intuitive and readable syntax for defining a 10 //! dedicated type for each register. Each such type comes with its own field accessors that can 11 //! return an error if a field's value is invalid. 12 13 /// Defines a dedicated type for a register with an absolute offset, including getter and setter 14 /// methods for its fields and methods to read and write it from an `Io` region. 15 /// 16 /// Example: 17 /// 18 /// ```no_run 19 /// register!(BOOT_0 @ 0x00000100, "Basic revision information about the GPU" { 20 /// 3:0 minor_revision as u8, "Minor revision of the chip"; 21 /// 7:4 major_revision as u8, "Major revision of the chip"; 22 /// 28:20 chipset as u32 ?=> Chipset, "Chipset model"; 23 /// }); 24 /// ``` 25 /// 26 /// This defines a `BOOT_0` type which can be read or written from offset `0x100` of an `Io` 27 /// region. It is composed of 3 fields, for instance `minor_revision` is made of the 4 least 28 /// significant bits of the register. Each field can be accessed and modified using accessor 29 /// methods: 30 /// 31 /// ```no_run 32 /// // Read from the register's defined offset (0x100). 33 /// let boot0 = BOOT_0::read(&bar); 34 /// pr_info!("chip revision: {}.{}", boot0.major_revision(), boot0.minor_revision()); 35 /// 36 /// // `Chipset::try_from` is called with the value of the `chipset` field and returns an 37 /// // error if it is invalid. 38 /// let chipset = boot0.chipset()?; 39 /// 40 /// // Update some fields and write the value back. 41 /// boot0.set_major_revision(3).set_minor_revision(10).write(&bar); 42 /// 43 /// // Or, just read and update the register in a single step: 44 /// BOOT_0::alter(&bar, |r| r.set_major_revision(3).set_minor_revision(10)); 45 /// ``` 46 /// 47 /// Fields are defined as follows: 48 /// 49 /// - `as <type>` simply returns the field value casted to <type>, typically `u32`, `u16`, `u8` or 50 /// `bool`. Note that `bool` fields must have a range of 1 bit. 51 /// - `as <type> => <into_type>` calls `<into_type>`'s `From::<<type>>` implementation and returns 52 /// the result. 53 /// - `as <type> ?=> <try_into_type>` calls `<try_into_type>`'s `TryFrom::<<type>>` implementation 54 /// and returns the result. This is useful with fields for which not all values are valid. 55 /// 56 /// The documentation strings are optional. If present, they will be added to the type's 57 /// definition, or the field getter and setter methods they are attached to. 58 /// 59 /// Putting a `+` before the address of the register makes it relative to a base: the `read` and 60 /// `write` methods take a `base` argument that is added to the specified address before access: 61 /// 62 /// ```no_run 63 /// register!(CPU_CTL @ +0x0000010, "CPU core control" { 64 /// 0:0 start as bool, "Start the CPU core"; 65 /// }); 66 /// 67 /// // Flip the `start` switch for the CPU core which base address is at `CPU_BASE`. 68 /// let cpuctl = CPU_CTL::read(&bar, CPU_BASE); 69 /// pr_info!("CPU CTL: {:#x}", cpuctl); 70 /// cpuctl.set_start(true).write(&bar, CPU_BASE); 71 /// ``` 72 /// 73 /// It is also possible to create a alias register by using the `=> ALIAS` syntax. This is useful 74 /// for cases where a register's interpretation depends on the context: 75 /// 76 /// ```no_run 77 /// register!(SCRATCH @ 0x00000200, "Scratch register" { 78 /// 31:0 value as u32, "Raw value"; 79 /// }); 80 /// 81 /// register!(SCRATCH_BOOT_STATUS => SCRATCH, "Boot status of the firmware" { 82 /// 0:0 completed as bool, "Whether the firmware has completed booting"; 83 /// }); 84 /// ``` 85 /// 86 /// In this example, `SCRATCH_0_BOOT_STATUS` uses the same I/O address as `SCRATCH`, while also 87 /// providing its own `completed` field. 88 macro_rules! register { 89 // Creates a register at a fixed offset of the MMIO space. 90 ($name:ident @ $offset:literal $(, $comment:literal)? { $($fields:tt)* } ) => { 91 register!(@core $name $(, $comment)? { $($fields)* } ); 92 register!(@io $name @ $offset); 93 }; 94 95 // Creates an alias register of fixed offset register `alias` with its own fields. 96 ($name:ident => $alias:ident $(, $comment:literal)? { $($fields:tt)* } ) => { 97 register!(@core $name $(, $comment)? { $($fields)* } ); 98 register!(@io $name @ $alias::OFFSET); 99 }; 100 101 // Creates a register at a relative offset from a base address. 102 ($name:ident @ + $offset:literal $(, $comment:literal)? { $($fields:tt)* } ) => { 103 register!(@core $name $(, $comment)? { $($fields)* } ); 104 register!(@io $name @ + $offset); 105 }; 106 107 // Creates an alias register of relative offset register `alias` with its own fields. 108 ($name:ident => + $alias:ident $(, $comment:literal)? { $($fields:tt)* } ) => { 109 register!(@core $name $(, $comment)? { $($fields)* } ); 110 register!(@io $name @ + $alias::OFFSET); 111 }; 112 113 // All rules below are helpers. 114 115 // Defines the wrapper `$name` type, as well as its relevant implementations (`Debug`, `BitOr`, 116 // and conversion to the value type) and field accessor methods. 117 (@core $name:ident $(, $comment:literal)? { $($fields:tt)* }) => { 118 $( 119 #[doc=$comment] 120 )? 121 #[repr(transparent)] 122 #[derive(Clone, Copy, Default)] 123 pub(crate) struct $name(u32); 124 125 impl ::core::ops::BitOr for $name { 126 type Output = Self; 127 128 fn bitor(self, rhs: Self) -> Self::Output { 129 Self(self.0 | rhs.0) 130 } 131 } 132 133 impl ::core::convert::From<$name> for u32 { 134 fn from(reg: $name) -> u32 { 135 reg.0 136 } 137 } 138 139 register!(@fields_dispatcher $name { $($fields)* }); 140 }; 141 142 // Captures the fields and passes them to all the implementers that require field information. 143 // 144 // Used to simplify the matching rules for implementers, so they don't need to match the entire 145 // complex fields rule even though they only make use of part of it. 146 (@fields_dispatcher $name:ident { 147 $($hi:tt:$lo:tt $field:ident as $type:tt 148 $(?=> $try_into_type:ty)? 149 $(=> $into_type:ty)? 150 $(, $comment:literal)? 151 ; 152 )* 153 } 154 ) => { 155 register!(@field_accessors $name { 156 $( 157 $hi:$lo $field as $type 158 $(?=> $try_into_type)? 159 $(=> $into_type)? 160 $(, $comment)? 161 ; 162 )* 163 }); 164 register!(@debug $name { $($field;)* }); 165 }; 166 167 // Defines all the field getter/methods methods for `$name`. 168 ( 169 @field_accessors $name:ident { 170 $($hi:tt:$lo:tt $field:ident as $type:tt 171 $(?=> $try_into_type:ty)? 172 $(=> $into_type:ty)? 173 $(, $comment:literal)? 174 ; 175 )* 176 } 177 ) => { 178 $( 179 register!(@check_field_bounds $hi:$lo $field as $type); 180 )* 181 182 #[allow(dead_code)] 183 impl $name { 184 $( 185 register!(@field_accessor $name $hi:$lo $field as $type 186 $(?=> $try_into_type)? 187 $(=> $into_type)? 188 $(, $comment)? 189 ; 190 ); 191 )* 192 } 193 }; 194 195 // Boolean fields must have `$hi == $lo`. 196 (@check_field_bounds $hi:tt:$lo:tt $field:ident as bool) => { 197 #[allow(clippy::eq_op)] 198 const _: () = { 199 ::kernel::build_assert!( 200 $hi == $lo, 201 concat!("boolean field `", stringify!($field), "` covers more than one bit") 202 ); 203 }; 204 }; 205 206 // Non-boolean fields must have `$hi >= $lo`. 207 (@check_field_bounds $hi:tt:$lo:tt $field:ident as $type:tt) => { 208 #[allow(clippy::eq_op)] 209 const _: () = { 210 ::kernel::build_assert!( 211 $hi >= $lo, 212 concat!("field `", stringify!($field), "`'s MSB is smaller than its LSB") 213 ); 214 }; 215 }; 216 217 // Catches fields defined as `bool` and convert them into a boolean value. 218 ( 219 @field_accessor $name:ident $hi:tt:$lo:tt $field:ident as bool => $into_type:ty 220 $(, $comment:literal)?; 221 ) => { 222 register!( 223 @leaf_accessor $name $hi:$lo $field 224 { |f| <$into_type>::from(if f != 0 { true } else { false }) } 225 $into_type => $into_type $(, $comment)?; 226 ); 227 }; 228 229 // Shortcut for fields defined as `bool` without the `=>` syntax. 230 ( 231 @field_accessor $name:ident $hi:tt:$lo:tt $field:ident as bool $(, $comment:literal)?; 232 ) => { 233 register!(@field_accessor $name $hi:$lo $field as bool => bool $(, $comment)?;); 234 }; 235 236 // Catches the `?=>` syntax for non-boolean fields. 237 ( 238 @field_accessor $name:ident $hi:tt:$lo:tt $field:ident as $type:tt ?=> $try_into_type:ty 239 $(, $comment:literal)?; 240 ) => { 241 register!(@leaf_accessor $name $hi:$lo $field 242 { |f| <$try_into_type>::try_from(f as $type) } $try_into_type => 243 ::core::result::Result< 244 $try_into_type, 245 <$try_into_type as ::core::convert::TryFrom<$type>>::Error 246 > 247 $(, $comment)?;); 248 }; 249 250 // Catches the `=>` syntax for non-boolean fields. 251 ( 252 @field_accessor $name:ident $hi:tt:$lo:tt $field:ident as $type:tt => $into_type:ty 253 $(, $comment:literal)?; 254 ) => { 255 register!(@leaf_accessor $name $hi:$lo $field 256 { |f| <$into_type>::from(f as $type) } $into_type => $into_type $(, $comment)?;); 257 }; 258 259 // Shortcut for non-boolean fields defined without the `=>` or `?=>` syntax. 260 ( 261 @field_accessor $name:ident $hi:tt:$lo:tt $field:ident as $type:tt 262 $(, $comment:literal)?; 263 ) => { 264 register!(@field_accessor $name $hi:$lo $field as $type => $type $(, $comment)?;); 265 }; 266 267 // Generates the accessor methods for a single field. 268 ( 269 @leaf_accessor $name:ident $hi:tt:$lo:tt $field:ident 270 { $process:expr } $to_type:ty => $res_type:ty $(, $comment:literal)?; 271 ) => { 272 ::kernel::macros::paste!( 273 const [<$field:upper _RANGE>]: ::core::ops::RangeInclusive<u8> = $lo..=$hi; 274 const [<$field:upper _MASK>]: u32 = ((((1 << $hi) - 1) << 1) + 1) - ((1 << $lo) - 1); 275 const [<$field:upper _SHIFT>]: u32 = Self::[<$field:upper _MASK>].trailing_zeros(); 276 ); 277 278 $( 279 #[doc="Returns the value of this field:"] 280 #[doc=$comment] 281 )? 282 #[inline] 283 pub(crate) fn $field(self) -> $res_type { 284 ::kernel::macros::paste!( 285 const MASK: u32 = $name::[<$field:upper _MASK>]; 286 const SHIFT: u32 = $name::[<$field:upper _SHIFT>]; 287 ); 288 let field = ((self.0 & MASK) >> SHIFT); 289 290 $process(field) 291 } 292 293 ::kernel::macros::paste!( 294 $( 295 #[doc="Sets the value of this field:"] 296 #[doc=$comment] 297 )? 298 #[inline] 299 pub(crate) fn [<set_ $field>](mut self, value: $to_type) -> Self { 300 const MASK: u32 = $name::[<$field:upper _MASK>]; 301 const SHIFT: u32 = $name::[<$field:upper _SHIFT>]; 302 let value = (u32::from(value) << SHIFT) & MASK; 303 self.0 = (self.0 & !MASK) | value; 304 305 self 306 } 307 ); 308 }; 309 310 // Generates the `Debug` implementation for `$name`. 311 (@debug $name:ident { $($field:ident;)* }) => { 312 impl ::core::fmt::Debug for $name { 313 fn fmt(&self, f: &mut ::core::fmt::Formatter<'_>) -> ::core::fmt::Result { 314 f.debug_struct(stringify!($name)) 315 .field("<raw>", &format_args!("{:#x}", &self.0)) 316 $( 317 .field(stringify!($field), &self.$field()) 318 )* 319 .finish() 320 } 321 } 322 }; 323 324 // Generates the IO accessors for a fixed offset register. 325 (@io $name:ident @ $offset:expr) => { 326 #[allow(dead_code)] 327 impl $name { 328 pub(crate) const OFFSET: usize = $offset; 329 330 /// Read the register from its address in `io`. 331 #[inline] 332 pub(crate) fn read<const SIZE: usize, T>(io: &T) -> Self where 333 T: ::core::ops::Deref<Target = ::kernel::io::Io<SIZE>>, 334 { 335 Self(io.read32($offset)) 336 } 337 338 /// Write the value contained in `self` to the register address in `io`. 339 #[inline] 340 pub(crate) fn write<const SIZE: usize, T>(self, io: &T) where 341 T: ::core::ops::Deref<Target = ::kernel::io::Io<SIZE>>, 342 { 343 io.write32(self.0, $offset) 344 } 345 346 /// Read the register from its address in `io` and run `f` on its value to obtain a new 347 /// value to write back. 348 #[inline] 349 pub(crate) fn alter<const SIZE: usize, T, F>( 350 io: &T, 351 f: F, 352 ) where 353 T: ::core::ops::Deref<Target = ::kernel::io::Io<SIZE>>, 354 F: ::core::ops::FnOnce(Self) -> Self, 355 { 356 let reg = f(Self::read(io)); 357 reg.write(io); 358 } 359 } 360 }; 361 362 // Generates the IO accessors for a relative offset register. 363 (@io $name:ident @ + $offset:literal) => { 364 #[allow(dead_code)] 365 impl $name { 366 pub(crate) const OFFSET: usize = $offset; 367 368 #[inline] 369 pub(crate) fn read<const SIZE: usize, T>( 370 io: &T, 371 base: usize, 372 ) -> Self where 373 T: ::core::ops::Deref<Target = ::kernel::io::Io<SIZE>>, 374 { 375 Self(io.read32(base + $offset)) 376 } 377 378 #[inline] 379 pub(crate) fn write<const SIZE: usize, T>( 380 self, 381 io: &T, 382 base: usize, 383 ) where 384 T: ::core::ops::Deref<Target = ::kernel::io::Io<SIZE>>, 385 { 386 io.write32(self.0, base + $offset) 387 } 388 389 #[inline] 390 pub(crate) fn alter<const SIZE: usize, T, F>( 391 io: &T, 392 base: usize, 393 f: F, 394 ) where 395 T: ::core::ops::Deref<Target = ::kernel::io::Io<SIZE>>, 396 F: ::core::ops::FnOnce(Self) -> Self, 397 { 398 let reg = f(Self::read(io, base)); 399 reg.write(io, base); 400 } 401 } 402 }; 403 } 404