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.