| 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. |