hw-memory-ram/rom-basic (libmemory.la :: mem_component_library)

Synopsis:

This is a general-purpose byte-addressable RAM or ROM. Its contents may be primed with existing data from a file. The size of the memory may be altered at any time.


Functionality:

Modelling:

This component does not model any particular hardware component. It models a generic memory without any access delays.

Behaviors
configuration

When the size attribute is written-to with a legal value, a new cleared byte array is allocated with the new size. The old byte array is thrown away. The size-max read-only attribute supplies to the user the maximum size that this component will attempt to allocate. (Larger memory banks may be modelled by using multiple instances of this component.)

image save/load

When the image-load pin is driven, this component will open and attempt to load the contents of the file given by the image-file attribute into the memory image. The file is copied byte-for-byte. If the file is too short, zeroes are used to fill out the rest of the memory.

Similarly, when the image-store pin is driven, the component will write to the image-file file a byte-for-byte dump of the entire memory image.

image mmap

As an alternative to the batch image load/store function, when the image-mmap pin is driven, the component will map into memory the first size bytes of image-file. It is mapped in MAP_SHARED, PROT_READ|PROT_WRITE mode. Additionally, when the image-msync pin is driven, the msync system call is invoked to force a synchronization between the physical file and the memory image.

The file will be unmapped when the component is deleted, or when the size attribute is written to. State save/restore stores the content of the mapped memory buffer, not the mapped-ness.

error indication

When operating system errors prevent some configuration-related action from succeeding, the error output pin is driven. Reasons may include attempting to access nonexistent files, out-of-memory conditions, permission problems, and so on. It is advantageous to configure the connection from this pin to some system-wide recepient before failure-prone component configuration occurs.

memory latency

The component models the effects of memory latency. The read-latency and write-latency values specify the latencies for memory reads and writes, respectively.

reading/writing

When an access is received on either the read-only-port or read-write-port bus, the component checks the incoming address. If it is an in-range read access, it will be carried out. If it is a write access, it will be prevented through the read-only-port.

There are no restrictions on access alignment or size imposed by this model.

SID Conventions
functional supported -
latency supported -
save/restore supported -
triggerpointsnot supported -


Environment:

Related components

It is most likely that this component will be used as the main memory for a CPU and connected through a mapper component such as hw-mapper-basic.

A configuration file fragment appears below:

	new hw-mapper-basic bus
	new hw-cpu-arm7t cpu
	new hw-memory-ram/rom-basic mem
	# error indication
	connect-pin mem error -> main stop!
	set mem size 65536
	connect-bus cpu insn-memory bus access-port
	connect-bus cpu data-memory bus access-port
	connect bus [0-65535] mem read-write-port
	# a read-only shadow in high memory
	connect-bus [400000,465535] mem read-only-port
    
Host system

The memory is modelled as a contiguous array of bytes in host memory. As such, a component configured for 8MB of memory requires 8MB of host memory. This is an important consideration for simulations running on machines with low memory or on busy multiuser systems. Similarly, when a memory image is written to disk, the same amount of space may be used there.

When using memory mapped files, the host's virtual memory system may reduce physical RAM requirements considerably.


Component Reference:

Component: hw-memory-ram/rom-basic

pins
namedirectionlegalvaluesbehaviors
image-loadinanyimage save/load
image-storeinanyimage save/load
image-mmapinanyimage mmap
image-msyncinanyimage mmap
erroroutanyerror indication

buses
nameaddressesaccessesbehaviors
read-only-port0..size-1any accessreading/writing
read-write-port0..size-1any accessreading/writing

attributes
namecategorylegal valuesdefault valuebehaviors
sizesettingnumeric0configuration
size-maxsettingnumericfixed at 32MBconfiguration
image-filesettingfilename-image save/load
image-loadpinany-image save/load
image-storepinany-image save/load
read-latencysettingnumeric0memory latency
write-latencysettingnumeric0memory latency
state-snapshotstateopaque string-state save/restore