Struct Word

pub struct Word { /* private fields */ }

A memory location that can be read and written to.

Reading

A word’s value can be read with:

• Word::get to directly access the value, ignoring any initialization state
• Word::get_if_init to directly access the value after verifying initialization state

See the respective functions for more details.

Both functions return the unsigned representation of the word. If needed, this can be converted to a signed integer with typical as casting (data as i16).

Writing

A word can be written into with a value or with another word:

• Word::set to read a value into this word
• Word::set_if_init to read a word into this word

Word::set_if_init may be more useful in situations where initialization state needs to be preserved or when it needs to be verified.

See the respective functions for more details.

Words can also be written to by applying assign operations (e.g., add, sub, and, etc.). All arithmetic operations that can be applied to words are assumed to be wrapping. See those implementations for more details.

Initialization

Internally, each memory location keeps track of two fields:

1. its data (i.e., the value stored at this location)
2. which bits of its data are truly “initialized” (as in the program knows what values are present there)

This second field is not used except for when the simulator is set to strict mode. Then, this second field is leveraged to detect if uninitialized memory is being written to places it shouldn’t be (e.g., PC, addresses, registers and memory).

When a Word is created for memory/register files (i.e., via Word::new_uninit), it is created with the initialization bits set to fully uninitialized. The data associated with this Word is decided by the creation strategy (see super::MachineInitStrategy for details).

Implementations

impl Word

pub fn new_uninit<F: WordFiller + ?Sized>(fill: &mut F) -> Self

Creates a new word that is considered uninitialized.

pub fn new_init(data: u16) -> Self

Creates a new word that is initialized with a given data value.

pub fn get(&self) -> u16

Reads the word, returning its unsigned representation.

The data is returned without checking for initialization state. If the initialization state should be checked before trying to query the data, then Word::get_if_init should be used instead.

pub fn get_if_init<E>(&self, strict: bool, err: E) -> Result<u16, E>

Reads the word if it is properly initialized under strictness requirements, returning its unsigned representation.

This function is more cognizant of word initialization than Word::get.

• In non-strict mode (strict == false), this function unconditionally allows access to the data regardless of initialization state.
• In strict mode (strict == true), this function verifies self is fully initialized, raising the provided error if not.

pub fn set(&mut self, data: u16)

Writes to the word.

This sets the word to the data value assuming it is fully initialized and correspondingly sets the initialization state to be fully initialized.

If the initialization state of the data value should be checked before trying to write to the word, then Word::set_if_init should be used instead.

pub fn set_if_init<E>( &mut self, data: Word, strict: bool, err: E, ) -> Result<(), E>

Writes to the word while verifying the data stored is properly initialized under strictness requirements.

This function is more cognizant of word initialization than Word::set.

• In non-strict mode, this function preserves the initialization data of the data argument.
• In strict mode, this function verifies data is fully initialized, raising the provided error if not.

pub fn is_init(&self) -> bool

Checks that a word is fully initialized

pub fn clear_init(&mut self)

Clears initialization of this word.

Trait Implementations

impl Add for Word

fn add(self, rhs: Self) -> Self::Output

Adds two words together (wrapping if overflow occurs).

If the two words are fully initialized, the resulting word will also be fully initialized. Otherwise, the resulting word is fully uninitialized.

type Output = Word

The resulting type after applying the + operator.

impl AddAssign<i16> for Word

fn add_assign(&mut self, rhs: i16)

Increments the word by the provided value.

If the word was fully initialized, its updated value is also fully initialized. Otherwise, the resulting word is fully uninitialized.

impl AddAssign<u16> for Word

fn add_assign(&mut self, rhs: u16)

Increments the word by the provided value.

If the word was fully initialized, its updated value is also fully initialized. Otherwise, the resulting word is fully uninitialized.

impl AddAssign for Word

fn add_assign(&mut self, rhs: Self)

Performs the += operation.

impl BitAnd for Word

fn bitand(self, rhs: Self) -> Self::Output

Applies a bitwise AND across two words.

This will also compute the correct initialization for the resulting word, taking into account bit clearing.

type Output = Word

The resulting type after applying the & operator.

impl BitAndAssign for Word

fn bitand_assign(&mut self, rhs: Self)

Performs the &= operation.

impl Clone for Word

fn clone(&self) -> Word

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Word

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl From<i16> for Word

fn from(value: i16) -> Self

Creates a fully initialized word.

impl From<u16> for Word

fn from(value: u16) -> Self

Creates a fully initialized word.

impl Not for Word

fn not(self) -> Self::Output

Inverts the data on this word, preserving any initialization state.

type Output = Word

The resulting type after applying the ! operator.

impl PartialEq for Word

fn eq(&self, other: &Word) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Sub for Word

fn sub(self, rhs: Self) -> Self::Output

Subtracts two words together (wrapping if overflow occurs).

If the two words are fully initialized, the resulting word will also be fully initialized. Otherwise, the resulting word is fully uninitialized.

type Output = Word

The resulting type after applying the - operator.

impl SubAssign<i16> for Word

fn sub_assign(&mut self, rhs: i16)

Decrements the word by the provided value.

If the word was fully initialized, its updated value is also fully initialized. Otherwise, the resulting word is fully uninitialized.

impl SubAssign<u16> for Word

fn sub_assign(&mut self, rhs: u16)

Decrements the word by the provided value.

If the word was fully initialized, its updated value is also fully initialized. Otherwise, the resulting word is fully uninitialized.

impl SubAssign for Word

fn sub_assign(&mut self, rhs: Self)

Performs the -= operation.

impl Copy for Word

impl Eq for Word

impl StructuralPartialEq for Word