diff --git a/kernel/src/utilities/machine_register.rs b/kernel/src/utilities/machine_register.rs new file mode 100644 index 0000000000..6e8c50c2c2 --- /dev/null +++ b/kernel/src/utilities/machine_register.rs @@ -0,0 +1,34 @@ +// Licensed under the Apache License, Version 2.0 or the MIT License. +// SPDX-License-Identifier: Apache-2.0 OR MIT +// Copyright Tock Contributors 2024. + +//! Machine-specific register-sized type. +//! +//! This type holds exactly one machine register of data. This type should be +//! used when storing a value that is exactly the contents of a register with no +//! additional type information. +//! +//! Tock defines this as a custom type as there is currently (Nov 2024) no +//! suitable standard type for this purpose that is correct across all hardware +//! architectures Tock supports. The closest suitable type is `usize`. However, +//! `usize` only captures the size of data, not necessarily the full size of a +//! register. On many platforms these are the same, but on platforms with +//! ISA-level memory protection (e.g., CHERI), a register is larger than +//! `usize`. + +use crate::utilities::capability_ptr::CapabilityPtr; + +/// [`MachineRegister`] is a datatype that can hold exactly the contents of a +/// register with no additional semantic information. +/// +/// We can define this as a [`CapabilityPtr`] as [`CapabilityPtr`] has the same +/// size. +/// +/// [`MachineRegister`] is useful for identifying when data within the Tock +/// kernel has no semantic meaning other than being the size of a register. In +/// the future it may be possible, useful, or necessary to change the +/// implementation of [`MachineRegister`], however, the semantics will remain. +/// To reduce implementation complexity we simply use a type alias, but this +/// should not be construed as to suggest that [`MachineRegister`] will always +/// be implemented as a [`CapabilityPtr`]. +pub type MachineRegister = CapabilityPtr; diff --git a/kernel/src/utilities/mod.rs b/kernel/src/utilities/mod.rs index 8e146ac544..1986ed4ce3 100644 --- a/kernel/src/utilities/mod.rs +++ b/kernel/src/utilities/mod.rs @@ -10,6 +10,7 @@ pub mod capability_ptr; pub mod copy_slice; pub mod helpers; pub mod leasable_buffer; +pub mod machine_register; pub mod math; pub mod mut_imut_buffer; pub mod peripheral_management;