How To - for "memory" device
=======================================================
	(ident "@(#)README.libmemory 1.2     07/04/13 SMI")

I. What is "memory" device?
-----------------
	This device instantiates either ROM or RAM into the address space of
	a hardware domain of a Legion simulated system.

	It enables content for that ROM/RAM to be loaded from a file
	or specified directly in the legion config file.

	Where contents are provided from another file, this module can allow
	changes made under simulator to be percolated back to the originating
	file, or merely kept as private

II. Where is libmemory?
-------------------
	The source is in <ws>/devices/mem_bus/libmemory/mem.c



III. How do I configure a memory device
---------------------------------------

	The configuration file syntax for memory is as a device in the
	addressmap section:

	device "memory" <baseaddress> <size> {
		<options>
	}



III. What are the config options for libmemory ?
------------------------------------------------

	The options supported by the memory device are:

	rom ;
	shared ;
	load <address> <filename> ;
	virtual_disk ;
	load <slice> [rom | shared] <filename> ;

rom
---
	The contents of this memory device are read only.

shared
------
	For a non-rom device, changes made under simulation are written through
	to any underlying file that the memory contents may have originated
	from.
	In this manner NVRAMs may be simulated, and changes to their contents
	may persist from simulation to simulation.

load
----
	This directive loads the contents of a file into the ROM/RAM device
	specified. If the device is marked "shared" then changes are also
	reflected back to the same file during simulation.

	The address specified may be an absolute address (within the legion
	address range of the device), or with the form +<offset> be an offset
	from the starting address of the device.

virtual_disk
------------
	This directive enables the creation of a virtual disk image, with
	multiple load directives for each partition of that disk. Once the
	device is instantiated a partition table for the disk is automatically
	created, thus avoiding the need for an external manual tool to do this.

	Partitions can be specified for this virtual disk using the:
		load s<n> [rom | shared] <filename>
	directive, where <n> is the partition number (0 thru 7).

content
-------
	The content directive allows memory contents to be specified directly
	in the legion config file, and takes the form:

	content +<offset> <wordsize> {
	    <word0> <word1> <word2> ...
	}

	Where <offset> is the byte offset from the start of the memory
	device (and may have any alignment), <wordsize> merely indicates the
	expected size for each word of the content in bits, 8, 16, 32 or 64.
	The content is stored starting at byte <offset> in big-endian byte
	order.

	The content is applied *after* all data from files are mapped/loaded
	in, thus the directive can be used for, say, inline patching of ROM
	contents.

	There may be any number of content directives per memory device.
	Directives are applied in increasing order of offset.
	Overlapping directives will be detected and produce a fatal error.