Struct lc3_ensemble::sim::mem::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 return its representation as an unsigned integer.

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::copy_word to read a word into this word

Word::copy_word may be more useful in situations where initialization state may want to be preserved. 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 WordCreateStrategy for details).

Implementations

impl Word

pub fn new_uninit(strat: &mut WordCreateStrategy) -> 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.

pub fn is_init(&self) -> bool

Checks that a word is fully initialized

pub fn clear_init(&mut self)

Clears initialization of this word.

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

Writes to the word.

The data provided is assumed to be FULLY initialized, and will set the initialization state of this word to be fully initialized.

If the data is not fully initialized (e.g., if it is a partially initialized word), Word::copy_word can be used instead.

pub fn copy_word( &mut self, word: Word, strict: bool, err: SimErr ) -> Result<(), SimErr>

Copies the data from one word into another.

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

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

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 copy 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 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