[OpenSPARC-T2-SAM] / legion / docs / readmes / README.libmemory

		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.
Commit	Line	Data
920dae64 AT	1	How To - for "memory" device
	2	=======================================================
	3	(ident "@(#)README.libmemory 1.2 07/04/13 SMI")
	4
	5	I. What is "memory" device?
	6	-----------------
	7	This device instantiates either ROM or RAM into the address space of
	8	a hardware domain of a Legion simulated system.
	9
	10	It enables content for that ROM/RAM to be loaded from a file
	11	or specified directly in the legion config file.
	12
	13	Where contents are provided from another file, this module can allow
	14	changes made under simulator to be percolated back to the originating
	15	file, or merely kept as private
	16
	17	II. Where is libmemory?
	18	-------------------
	19	The source is in <ws>/devices/mem_bus/libmemory/mem.c
	20
	21
	22
	23	III. How do I configure a memory device
	24	---------------------------------------
	25
	26	The configuration file syntax for memory is as a device in the
	27	addressmap section:
	28
	29	device "memory" <baseaddress> <size> {
	30	<options>
	31	}
	32
	33
	34
	35	III. What are the config options for libmemory ?
	36	------------------------------------------------
	37
	38	The options supported by the memory device are:
	39
	40	rom ;
	41	shared ;
	42	load <address> <filename> ;
	43	virtual_disk ;
	44	load <slice> [rom \| shared] <filename> ;
	45
	46	rom
	47	---
	48	The contents of this memory device are read only.
	49
	50	shared
	51	------
	52	For a non-rom device, changes made under simulation are written through
	53	to any underlying file that the memory contents may have originated
	54	from.
	55	In this manner NVRAMs may be simulated, and changes to their contents
	56	may persist from simulation to simulation.
	57
	58	load
	59	----
	60	This directive loads the contents of a file into the ROM/RAM device
	61	specified. If the device is marked "shared" then changes are also
	62	reflected back to the same file during simulation.
	63
	64	The address specified may be an absolute address (within the legion
65	address range of the device), or with the form +<offset> be an offset
66	from the starting address of the device.
67
68	virtual_disk
69	------------
70	This directive enables the creation of a virtual disk image, with
71	multiple load directives for each partition of that disk. Once the
72	device is instantiated a partition table for the disk is automatically
73	created, thus avoiding the need for an external manual tool to do this.
74
75	Partitions can be specified for this virtual disk using the:
76	load s<n> [rom \| shared] <filename>
77	directive, where <n> is the partition number (0 thru 7).
78
79	content
80	-------
81	The content directive allows memory contents to be specified directly
82	in the legion config file, and takes the form:
83
84	content +<offset> <wordsize> {
85	<word0> <word1> <word2> ...
86	}
87
88	Where <offset> is the byte offset from the start of the memory
89	device (and may have any alignment), <wordsize> merely indicates the
90	expected size for each word of the content in bits, 8, 16, 32 or 64.
91	The content is stored starting at byte <offset> in big-endian byte
92	order.
93
94	The content is applied after all data from files are mapped/loaded
95	in, thus the directive can be used for, say, inline patching of ROM
96	contents.
97
98	There may be any number of content directives per memory device.
99	Directives are applied in increasing order of offset.
100	Overlapping directives will be detected and produce a fatal error.