xref: /linux/rust/kernel/io/register.rs (revision 486b257357c23743d9729ea715136d105fff461e)
1 // SPDX-License-Identifier: GPL-2.0
2 
3 //! Macro to define register layout and accessors.
4 //!
5 //! The [`register!`](kernel::io::register!) macro provides an intuitive and readable syntax for
6 //! defining a dedicated type for each register and accessing it using [`Io`](super::Io). Each such
7 //! type comes with its own field accessors that can return an error if a field's value is invalid.
8 //!
9 //! Note: most of the items in this module are public so they can be referenced by the macro, but
10 //! most are not to be used directly by users. Outside of the `register!` macro itself, the only
11 //! item you might want to import from this module is [`Array`].
12 //!
13 //! # Simple example
14 //!
15 //! ```no_run
16 //! use kernel::io::{
17 //!     register,
18 //!     Region,
19 //! };
20 //!
21 //! register! {
22 //!     base: Region<0x1000>;
23 //!
24 //!     /// Basic information about the chip.
25 //!     pub BOOT_0(u32) @ 0x00000100 {
26 //!         /// Vendor ID.
27 //!         15:8 vendor_id;
28 //!         /// Major revision of the chip.
29 //!         7:4 major_revision;
30 //!         /// Minor revision of the chip.
31 //!         3:0 minor_revision;
32 //!     }
33 //! }
34 //! ```
35 //!
36 //! This defines a 32-bit `BOOT_0` type which can be read from or written to offset `0x100` of an
37 //! `Io` region, with the described bitfields. For instance, `minor_revision` consists of the 4
38 //! least significant bits of the type.
39 //!
40 //! Fields are instances of [`Bounded`](kernel::num::Bounded) and can be read by calling their
41 //! getter method, which is named after them. They also have setter methods prefixed with `with_`
42 //! for runtime values and `with_const_` for constant values. All setters return the updated
43 //! register value.
44 //!
45 //! Fields can also be transparently converted from/to an arbitrary type by using the `=>` and
46 //! `?=>` syntaxes.
47 //!
48 //! If present, doc comments above register or fields definitions are added to the relevant item
49 //! they document (the register type itself, or the field's setter and getter methods).
50 //!
51 //! Note that multiple registers can be defined in a single `register!` invocation. This can be
52 //! useful to group related registers together.
53 //!
54 //! Here is how the register defined above can be used in code:
55 //!
56 //!
57 //! ```no_run
58 //! use kernel::{
59 //!     io::{
60 //!         register,
61 //!         Io,
62 //!         IoLoc,
63 //!         Region,
64 //!     },
65 //!     num::Bounded,
66 //! };
67 //! # use kernel::io::Mmio;
68 //! # register! {
69 //! #     base: Region<0x1000>;
70 //! #
71 //! #     pub BOOT_0(u32) @ 0x00000100 {
72 //! #         15:8 vendor_id;
73 //! #         7:4 major_revision;
74 //! #         3:0 minor_revision;
75 //! #     }
76 //! # }
77 //! # fn test(io: Mmio<'_, Region<0x1000>>) {
78 //! # fn obtain_vendor_id() -> u8 { 0xff }
79 //!
80 //! // Read from the register's defined offset (0x100).
81 //! let boot0 = io.read(BOOT_0);
82 //! pr_info!("chip revision: {}.{}", boot0.major_revision().get(), boot0.minor_revision().get());
83 //!
84 //! // Update some fields and write the new value back.
85 //! let new_boot0 = boot0
86 //!     // Constant values.
87 //!     .with_const_major_revision::<3>()
88 //!     .with_const_minor_revision::<10>()
89 //!     // Runtime value.
90 //!     .with_vendor_id(obtain_vendor_id());
91 //! io.write_reg(new_boot0);
92 //!
93 //! // Or, build a new value from zero and write it:
94 //! io.write_reg(BOOT_0::zeroed()
95 //!     .with_const_major_revision::<3>()
96 //!     .with_const_minor_revision::<10>()
97 //!     .with_vendor_id(obtain_vendor_id())
98 //! );
99 //!
100 //! // Or, read and update the register in a single step.
101 //! io.update(BOOT_0, |r| r
102 //!     .with_const_major_revision::<3>()
103 //!     .with_const_minor_revision::<10>()
104 //!     .with_vendor_id(obtain_vendor_id())
105 //! );
106 //!
107 //! // Constant values can also be built using the const setters.
108 //! const V: BOOT_0 = pin_init::zeroed::<BOOT_0>()
109 //!     .with_const_major_revision::<3>()
110 //!     .with_const_minor_revision::<10>();
111 //! # }
112 //! ```
113 //!
114 //! For more extensive documentation about how to define registers, see the
115 //! [`register!`](kernel::io::register!) macro.
116 
117 use core::marker::PhantomData;
118 
119 use crate::{
120     build_assert::build_assert,
121     io::IoLoc, //
122 };
123 
124 /// Allows `()` to be used as the `location` parameter of [`Io::write`](super::Io::write) when
125 /// passing a [`FixedIoLoc`] value.
126 impl<Base: ?Sized, T> IoLoc<Base, T> for ()
127 where
128     T: FixedIoLoc<Base>,
129 {
130     #[inline(always)]
131     fn offset(self) -> usize {
132         T::LOCATION.offset()
133     }
134 }
135 
136 // Provides a `IoLoc` impl that for a fixed offset.
137 #[doc(hidden)]
138 pub struct OffsetLoc<Base: ?Sized, T>(usize, PhantomData<(T, Base)>);
139 
140 impl<Base: ?Sized, T> OffsetLoc<Base, T> {
141     #[inline]
142     pub const fn new(offset: usize) -> Self {
143         Self(offset, PhantomData)
144     }
145 
146     #[inline]
147     pub const fn const_offset(self) -> usize {
148         self.0
149     }
150 }
151 
152 impl<Base: ?Sized, T> IoLoc<Base, T> for OffsetLoc<Base, T> {
153     #[inline(always)]
154     fn offset(self) -> usize {
155         self.0
156     }
157 }
158 
159 /// Trait implemented by arrays of registers.
160 pub trait RegisterArray: Sized {
161     /// Base type for this register.
162     type Base: ?Sized;
163 
164     /// Start offset of the register.
165     ///
166     /// The interpretation of this offset depends on the type of the register.
167     const OFFSET: usize;
168     /// Number of elements in the registers array.
169     const SIZE: usize;
170     /// Number of bytes between the start of elements in the registers array.
171     const STRIDE: usize;
172 }
173 
174 /// Location of an array register.
175 pub struct RegisterArrayLoc<T: RegisterArray>(usize, PhantomData<T>);
176 
177 impl<T: RegisterArray> RegisterArrayLoc<T> {
178     /// Returns the location of register `T` at position `idx`, with build-time validation.
179     #[inline(always)]
180     pub fn new(idx: usize) -> Self {
181         build_assert!(idx < T::SIZE);
182 
183         Self(idx, PhantomData)
184     }
185 
186     /// Attempts to return the location of register `T` at position `idx`, with runtime validation.
187     #[inline(always)]
188     pub fn try_new(idx: usize) -> Option<Self> {
189         if idx < T::SIZE {
190             Some(Self(idx, PhantomData))
191         } else {
192             None
193         }
194     }
195 }
196 
197 impl<Base: ?Sized, T> IoLoc<Base, T> for RegisterArrayLoc<T>
198 where
199     T: RegisterArray<Base = Base>,
200 {
201     #[inline(always)]
202     fn offset(self) -> usize {
203         T::OFFSET + self.0 * T::STRIDE
204     }
205 }
206 
207 /// Trait providing location builders for [`RegisterArray`]s.
208 pub trait Array {
209     /// Returns the location of the register at position `idx`, with build-time validation.
210     #[inline(always)]
211     fn at(idx: usize) -> RegisterArrayLoc<Self>
212     where
213         Self: RegisterArray,
214     {
215         RegisterArrayLoc::new(idx)
216     }
217 
218     /// Returns the location of the register at position `idx`, with runtime validation.
219     #[inline(always)]
220     fn try_at(idx: usize) -> Option<RegisterArrayLoc<Self>>
221     where
222         Self: RegisterArray,
223     {
224         RegisterArrayLoc::try_new(idx)
225     }
226 }
227 
228 /// Trait implemented by types that indicate there is a fixed I/O location for this given type.
229 ///
230 /// Implementors can be used with [`Io::write_reg`](super::Io::write_reg).
231 pub trait FixedIoLoc<Base: ?Sized>: Sized {
232     /// Type of [`FixedIoLoc::LOCATION`].
233     type Location: IoLoc<Base, Self>;
234 
235     /// Location of this type within given base.
236     const LOCATION: Self::Location;
237 }
238 
239 /// Trait implemented by items that contain both a register value and the absolute I/O location at
240 /// which to write it.
241 ///
242 /// Implementors can be used with [`Io::write_reg`](super::Io::write_reg).
243 pub trait LocatedRegister<Base: ?Sized> {
244     /// Value to write.
245     type Value;
246     /// Full location information at which to write the value.
247     type Location: IoLoc<Base, Self::Value>;
248 
249     /// Consumes `self` and returns a `(location, value)` tuple describing a valid I/O write
250     /// operation.
251     fn into_io_op(self) -> (Self::Location, Self::Value);
252 }
253 
254 impl<Base: ?Sized, T> LocatedRegister<Base> for T
255 where
256     T: FixedIoLoc<Base>,
257 {
258     type Location = T::Location;
259     type Value = T;
260 
261     #[inline(always)]
262     fn into_io_op(self) -> (T::Location, T) {
263         (T::LOCATION, self)
264     }
265 }
266 
267 /// Helper function for register element alias implementation.
268 ///
269 /// This is used to enforce base matching and provide bounds checking.
270 #[doc(hidden)]
271 #[inline(always)] // for const eval only
272 pub const fn element_alias_offset<Base: ?Sized, Alias: RegisterArray<Base = Base>>(
273     idx: usize,
274 ) -> usize {
275     assert!(idx < Alias::SIZE);
276     Alias::OFFSET + idx * Alias::STRIDE
277 }
278 
279 /// Defines a dedicated type for a register, including getter and setter methods for its fields and
280 /// methods to read and write it from an [`Io`](kernel::io::Io) region.
281 ///
282 /// This documentation focuses on how to declare registers. See the [module-level
283 /// documentation](mod@kernel::io::register) for examples of how to access them.
284 ///
285 /// Registers can either be fixed offset registers or arrays of registers.
286 ///
287 /// ## Fixed offset registers
288 ///
289 /// These are the simplest kind of registers. Their location is simply an offset inside the I/O
290 /// region. For instance:
291 ///
292 /// ```ignore
293 /// register! {
294 ///     pub FIXED_REG(u16) @ 0x80 {
295 ///         ...
296 ///     }
297 /// }
298 /// ```
299 ///
300 /// This creates a 16-bit register named `FIXED_REG` located at offset `0x80` of an I/O region.
301 ///
302 /// These registers' location can be built simply by referencing their name:
303 ///
304 /// ```no_run
305 /// use kernel::{
306 ///     io::{
307 ///         register,
308 ///         Io,
309 ///         Region,
310 ///     },
311 /// };
312 /// # use kernel::io::Mmio;
313 ///
314 /// register! {
315 ///     base: Region<0x1000>;
316 ///
317 ///     FIXED_REG(u32) @ 0x100 {
318 ///         15:8 high_byte;
319 ///         7:0  low_byte;
320 ///     }
321 /// }
322 ///
323 /// # fn test(io: Mmio<'_, Region<0x1000>>) {
324 /// let val = io.read(FIXED_REG);
325 ///
326 /// // Write from an already-existing value.
327 /// io.write(FIXED_REG, val.with_low_byte(0xff));
328 ///
329 /// // Create a register value from scratch.
330 /// let val2 = FIXED_REG::zeroed().with_high_byte(0x80);
331 ///
332 /// // The location of fixed offset registers is already contained in their type. Thus, the
333 /// // `location` argument of `Io::write` is technically redundant and can be replaced by `()`.
334 /// io.write((), val2);
335 ///
336 /// // Or, the single-argument `Io::write_reg` can be used.
337 /// io.write_reg(val2);
338 /// # }
339 ///
340 /// ```
341 ///
342 /// It is possible to create an alias of an existing register with new field definitions by using
343 /// the `=> ALIAS` syntax. This is useful for cases where a register's interpretation depends on
344 /// the context:
345 ///
346 /// ```no_run
347 /// use kernel::io::{
348 ///     register,
349 ///     Region,
350 /// };
351 ///
352 /// register! {
353 ///     base: Region<0x1000>;
354 ///
355 ///     /// Scratch register.
356 ///     pub SCRATCH(u32) @ 0x00000200 {
357 ///         31:0 value;
358 ///     }
359 ///
360 ///     /// Boot status of the firmware.
361 ///     pub SCRATCH_BOOT_STATUS(u32) => SCRATCH {
362 ///         0:0 completed;
363 ///     }
364 /// }
365 /// ```
366 ///
367 /// In this example, `SCRATCH_BOOT_STATUS` uses the same I/O address as `SCRATCH`, while providing
368 /// its own `completed` field.
369 ///
370 /// If you do not wish to have a bitfield defined, you can also create a register using an existing
371 /// type.
372 ///
373 /// ```no_run
374 /// # use kernel::io::*;
375 /// register! {
376 ///     base: Region<0x1000>;
377 ///
378 ///     /// UART RX register.
379 ///     pub UART_RX: u8 @ 0x100;
380 /// }
381 /// ```
382 ///
383 /// In case there is a fixed register associated with a specific type in the base, you can apply
384 /// `#[unique]` attribute which enables `write_reg` shorthand. This is automatically applied to
385 /// bitfields instantiated via the `register!` macro.
386 ///
387 /// This should only be used when types meaningfully represent a register. For example, in the
388 /// previous `UART_RX` example, even if only a single register is defined with `u8` type, it is a
389 /// bad idea to annotate it with `#[unique]`.
390 ///
391 /// ```no_run
392 /// # use kernel::{bitfield, io::*};
393 ///
394 /// bitfield! {
395 ///     pub struct Reset(u32) {
396 ///         0:0 reset;
397 ///     }
398 /// }
399 ///
400 /// register! {
401 ///     base: Region<0x1000>;
402 ///
403 ///     pub RESET: #[unique] Reset @ 0x100;
404 /// }
405 ///
406 /// # fn test(mmio: Mmio<'_, Region<0x1000>>) {
407 /// // let mmio: Mmio<'_, Region<0x1000>>;
408 /// mmio.write_reg(Reset::zeroed().with_const_reset::<1>());
409 /// # }
410 /// ```
411 ///
412 /// ## Arrays of registers
413 ///
414 /// Some I/O areas contain consecutive registers that share the same field layout. These areas can
415 /// be defined as an array of identical registers, allowing them to be accessed by index with
416 /// compile-time or runtime bound checking:
417 ///
418 /// ```ignore
419 /// register! {
420 ///     pub REGISTER_ARRAY(u8)[10, stride = 4] @ 0x100 {
421 ///         ...
422 ///     }
423 /// }
424 /// ```
425 ///
426 /// This defines `REGISTER_ARRAY`, an array of 10 byte registers starting at offset `0x100`. Each
427 /// register is separated from its neighbor by 4 bytes.
428 ///
429 /// The `stride` parameter is optional; if unspecified, the registers are placed consecutively from
430 /// each other.
431 ///
432 /// A location for a register in a register array is built using the [`Array::at`] trait method.
433 /// All arrays of registers implement [`Array`].
434 ///
435 /// ```no_run
436 /// use kernel::{
437 ///     io::{
438 ///         register,
439 ///         register::Array,
440 ///         Io,
441 ///         Region,
442 ///     },
443 /// };
444 /// # use kernel::io::Mmio;
445 /// # fn get_scratch_idx() -> usize {
446 /// #   0x15
447 /// # }
448 ///
449 /// // Array of 64 consecutive registers with the same layout starting at offset `0x80`.
450 /// register! {
451 ///     base: Region<0x1000>;
452 ///
453 ///     /// Scratch registers.
454 ///     pub SCRATCH(u32)[64] @ 0x00000080 {
455 ///         31:0 value;
456 ///     }
457 /// }
458 ///
459 /// # fn test(io: Mmio<'_, Region<0x1000>>)
460 /// #     -> Result<(), Error>{
461 /// // Read scratch register 0, i.e. I/O address `0x80`.
462 /// let scratch_0 = io.read(SCRATCH::at(0)).value();
463 ///
464 /// // Write scratch register 15, i.e. I/O address `0x80 + (15 * 4)`.
465 /// io.write(Array::at(15), SCRATCH::from(0xffeeaabb));
466 ///
467 /// // This is out of bounds and won't build.
468 /// // let scratch_128 = io.read(SCRATCH::at(128)).value();
469 ///
470 /// // Runtime-obtained array index.
471 /// let idx = get_scratch_idx();
472 /// // Access on a runtime index returns an error if it is out-of-bounds.
473 /// let some_scratch = io.read(SCRATCH::try_at(idx).ok_or(EINVAL)?).value();
474 ///
475 /// // Alias to a specific register in an array.
476 /// // Here `SCRATCH[8]` is used to convey the firmware exit code.
477 /// register! {
478 ///     base: Region<0x1000>;
479 ///
480 ///     /// Firmware exit status code.
481 ///     pub FIRMWARE_STATUS(u32) => SCRATCH[8] {
482 ///         7:0 status;
483 ///     }
484 /// }
485 ///
486 /// let status = io.read(FIRMWARE_STATUS).status();
487 ///
488 /// // Non-contiguous register arrays can be defined by adding a stride parameter.
489 /// // Here, each of the 16 registers of the array is separated by 8 bytes, meaning that the
490 /// // registers of the two declarations below are interleaved.
491 /// register! {
492 ///     base: Region<0x1000>;
493 ///
494 ///     /// Scratch registers bank 0.
495 ///     pub SCRATCH_INTERLEAVED_0(u32)[16, stride = 8] @ 0x000000c0 {
496 ///         31:0 value;
497 ///     }
498 ///
499 ///     /// Scratch registers bank 1.
500 ///     pub SCRATCH_INTERLEAVED_1(u32)[16, stride = 8] @ 0x000000c4 {
501 ///         31:0 value;
502 ///     }
503 /// }
504 /// # Ok(())
505 /// # }
506 /// ```
507 ///
508 /// ## Relative registers
509 ///
510 /// There are cases where a register region is subdivided into small subregions, and you may wish to
511 /// have your register definition be relative to these subregions. This may be needed, for example,
512 /// if these subregions are instantiated several times, or you just want it for encapsulation
513 /// purpose.
514 ///
515 /// For instance, imagine the following I/O space:
516 ///
517 /// ```text
518 ///           +-----------------------------+
519 ///           |             ...             |
520 ///           |                             |
521 ///  0x100--->+------------CPU0-------------+
522 ///           |                             |
523 ///  0x110--->+-----------------------------+
524 ///           |           CPU_CTL           |
525 ///           +-----------------------------+
526 ///           |             ...             |
527 ///           |                             |
528 ///           |                             |
529 ///  0x200--->+------------CPU1-------------+
530 ///           |                             |
531 ///  0x210--->+-----------------------------+
532 ///           |           CPU_CTL           |
533 ///           +-----------------------------+
534 ///           |             ...             |
535 ///           +-----------------------------+
536 /// ```
537 ///
538 /// `CPU0` and `CPU1` both have a `CPU_CTL` register that starts at offset `0x10` of their I/O
539 /// space segment. Since both instances of `CPU_CTL` share the same layout, we don't want to define
540 /// them twice and would prefer a way to select which one to use from a single definition.
541 ///
542 /// This can be done by defining a new type for the subregion, and then defining registers that use
543 /// the new type as the base:
544 ///
545 /// ```no_run
546 /// use kernel::{
547 ///     io::{
548 ///         io_project,
549 ///         register,
550 ///         Io,
551 ///         Region,
552 ///     },
553 /// };
554 /// # use kernel::io::Mmio;
555 ///
556 /// // Subregion type. Make sure it has adequate size and alignment.
557 /// #[repr(align(4))]
558 /// #[derive(FromBytes, IntoBytes)]
559 /// pub struct CpuCtl([u8; 0x100]);
560 ///
561 /// register! {
562 ///     base: Region<0x1000>;
563 ///
564 ///     // Subregions can just be defined like normal registers.
565 ///     CPU0: CpuCtl @ 0x100;
566 ///     CPU1: CpuCtl @ 0x200;
567 /// }
568 ///
569 /// // Then you can define new registers on the subregion.
570 /// register! {
571 ///     base: CpuCtl;
572 ///
573 ///     /// CPU core control.
574 ///     pub CPU_CTL(u32) @ 0x10 {
575 ///         0:0 start;
576 ///     }
577 /// }
578 ///
579 /// # fn test(io: Mmio<'_, Region<0x1000>>) {
580 /// // Read the status of `Cpu0`.
581 /// let cpu0_started = io_project!(io, build: CPU0).read(CPU_CTL);
582 ///
583 /// // Stop `Cpu0`.
584 /// io_project!(io, build: CPU0).write_reg(CPU_CTL::zeroed());
585 /// # }
586 /// ```
587 #[macro_export]
588 macro_rules! register {
589     ($($tt:tt)*) => {
590         $crate::macros::register!($($tt)*);
591     };
592 }
593