Struct lc3_ensemble::sim::mem::Mem

pub struct Mem { /* private fields */ }

Memory.

This can be addressed with any u16 (16-bit address).

Note that this struct provides two methods of accessing memory:

• Mem::get_raw and Mem::get_raw_mut: direct access to memory values
• Mem::read and Mem::write: memory access with privilege checks, strictness checks, and IO updating

get_raw and get_raw_mut

Mem::get_raw and Mem::get_raw_mut’s API is simple, it simply accesses the memory value at the address. Note that this means:

• These functions do not trigger IO effects (and as a result, IO values will not be updated).
• These functions do not perform access violation checks.

use lc3_ensemble::sim::mem::Mem;
 
let mut mem = Mem::new(&mut ()); // never should have to initialize mem
mem.get_raw_mut(0x3000).set(11);
assert_eq!(mem.get_raw(0x3000).get(), 11);

read and write

In contrast, Mem::read and Mem::write have to account for all of the possible conditions behind a memory access. This means:

• These functions do trigger IO effects.
• These functions do perform access violation and strictness checks.

Additionally, these functions require a MemAccessCtx, defining the configuration of the access, which consists of:

• privileged: if false, this access errors if the address is a memory location outside of the user range.
• strict: If true, all accesses that would cause a memory location to be set with uninitialized data causes an error (writes only).

The Simulator defines Simulator::default_mem_ctx to produce this value automatically based on the simulator’s state.

use lc3_ensemble::sim::Simulator;
use lc3_ensemble::sim::mem::Word;
 
let mut sim = Simulator::new(Default::default());
 
assert!(sim.mem.write(0x0000, Word::new_init(0x9ABC), sim.default_mem_ctx()).is_err());
assert!(sim.mem.write(0x3000, Word::new_init(0x9ABC), sim.default_mem_ctx()).is_ok());
assert!(sim.mem.read(0x0000, sim.default_mem_ctx()).is_err());
assert!(sim.mem.read(0x3000, sim.default_mem_ctx()).is_ok());

Implementations

impl Mem

pub fn new(filler: &mut impl WordFiller) -> Self

Creates a new memory with a provided word creation strategy.

pub fn get_raw(&self, addr: u16) -> &Word

Gets a reference to a word from the memory’s current state.

This is only meant to be used to query the state of the memory, not to simulate a read from memory.

Note the differences from Mem::read:

• This function does not trigger IO effects (and as a result, IO values will not be updated).
• This function does not require MemAccessCtx.
• This function does not perform access violation checks.

If any of these effects are necessary (e.g., when trying to execute instructions from the simulator), Mem::read should be used instead.

pub fn get_raw_mut(&mut self, addr: u16) -> &mut Word

Gets a mutable reference to a word from the memory’s current state.

This is only meant to be used to query/edit the state of the memory, not to simulate a write from memory.

Note the differences from Mem::write:

• This function does not trigger IO effects (and as a result, IO values will not be updated).
• This function does not require MemAccessCtx.
• This function does not perform access violation checks or strict uninitialized memory checking.

If any of these effects are necessary (e.g., when trying to execute instructions from the simulator), Mem::write should be used instead.

pub fn read(&mut self, addr: u16, ctx: MemAccessCtx) -> Result<Word, SimErr>

Fallibly reads the word at the provided index, erroring if not possible.

This accepts a MemAccessCtx, that describes the parameters of the memory access. The simulator provides a default MemAccessCtx under Simulator::default_mem_ctx.

The flags are used as follows:

• privileged: if false, this access errors if the address is a memory location outside of the user range.
• strict: not used for read

Note that this method is used for simulating a read. If you would like to query the memory’s state, consider Mem::get_raw.

pub fn write( &mut self, addr: u16, data: Word, ctx: MemAccessCtx, ) -> Result<(), SimErr>

Fallibly writes the word at the provided index, erroring if not possible.

This accepts a MemAccessCtx, that describes the parameters of the memory access. The simulator provides a default MemAccessCtx under Simulator::default_mem_ctx.

The flags are used as follows:

• privileged: if false, this access errors if the address is a memory location outside of the user range.
• strict: If true, all accesses that would cause a memory location to be set with uninitialized data causes an error.

Note that this method is used for simulating a write. If you would like to edit the memory’s state, consider Mem::get_raw_mut.

Trait Implementations

impl Debug for Mem

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

Formats the value using the given formatter.