diff options
author | 2016-09-06 12:46:40 +0200 | |
---|---|---|
committer | 2016-09-06 12:47:20 +0200 | |
commit | a2c306e92343e6487a485bd0e96fac44b2d87105 (patch) | |
tree | 75775a0ec6d1690429c6881d0bcce0a7df601225 /docs | |
parent | e153f4556044e190729fbed5bf2687259c319eed (diff) |
dimemory, dirom: Add some documentation [O. Galibert]
Diffstat (limited to 'docs')
-rw-r--r-- | docs/source/techspecs/device_memory_interface.rst | 99 | ||||
-rw-r--r-- | docs/source/techspecs/device_rom_interface.rst | 72 | ||||
-rw-r--r-- | docs/source/techspecs/index.rst | 2 |
3 files changed, 173 insertions, 0 deletions
diff --git a/docs/source/techspecs/device_memory_interface.rst b/docs/source/techspecs/device_memory_interface.rst new file mode 100644 index 00000000000..9a7ce333514 --- /dev/null +++ b/docs/source/techspecs/device_memory_interface.rst @@ -0,0 +1,99 @@ +The device_memory_interface +=========================== + +1. Capabilities +--------------- + +The device memory interface provides devices with the capability of +creating address spaces, to which address maps can be associated. +It's used for any device that provides a (logically) address/data bus +other devices can be connected to. It's mainly, but not only, cpus. + +The interface allows for up to four address spaces, numbered 0-3, with +symbolic names associated to them in emumem.h for historical reasons. + ++------------+-------------+----------------------+ +| Numeric ID | Symbolic ID | Symbolic name | ++============+=============+======================+ +| 0 | AS_0 | AS_PROGRAM | ++------------+-------------+----------------------+ +| 1 | AS_1 | AS_DATA | ++------------+-------------+----------------------+ +| 2 | AS_2 | AS_IO | ++------------+-------------+----------------------+ +| 3 | AS_3 | AS_DECRYPTED_OPCODES | ++------------+-------------+----------------------+ + +2. Setup +-------- + +| const address_space_config *\ **memory_space_config**\ (address_spacenum spacenum) const + +The device must override that method to provide, for each of the four +address spaces, either an **address_space_config** describing the +space's configucation or **nullptr** if the space is not to be +created. + +| bool **has_configured_map**\ () const +| bool **has_configured_map**\ (int index) const +| bool **has_configured_map**\ (address_spacenum index) const + +The **has_configured_map** method allows to test in the +**memory_space_config** method whether an **address_map** has been +associated with a given space. That allows to implement optional +memory spaces, such as AS_DECRYPTED_OPCODES in certain cpu cores. The +parameterless version tests for AS_PROGRAM/AS_0. + +3. Associating maps to spaces +----------------------------- +Associating maps to spaces is done at the machine config level, after the device declaration. + +| **MCFG_DEVICE_ADDRESS_MAP**\ (_space, _map) +| **MCFG_DEVICE_PROGRAM_MAP**\ (_map) +| **MCFG_DEVICE_DATA_MAP**\ (_map) +| **MCFG_DEVICE_IO_MAP**\ (_map) +| **MCFG_DEVICE_DECRYPTED_OPCODES_MAP**\ (_map) + +The generic macro and the four specific ones associate a map to a +given space. Address maps associated to non-existing spaces are +ignored (no warning given). devcpu.h defines MCFG_CPU_*_MAP aliases +to the specific macros. + +| **MCFG_DEVICE_REMOVE_ADDRESS_MAP**\ (_space) + +That macro removes a memory map associated to a given space. Useful +when removing a map for an optional space in a machine config +derivative. + + +4. Accessing the spaces +----------------------- + +| address_space &\ **space**\ () const +| address_space &\ **space**\ (int index) const +| address_space &\ **space**\ (address_spacenum index) const + +Returns a given address space post-initialization. The parameterless +version tests for AS_PROGRAM/AS_0. Aborts if the space doesn't exist. + +| bool **has_space**\ () const +| bool **has_space**\ (int index) const +| bool **has_space**\ (address_spacenum index) const + +Indicates whether a given space actually exists. The parameterless +version tests for AS_PROGRAM/AS_0. + + +5. Weird/to deprecate stuff +--------------------------- + +| bool **translate**\ (address_spacenum spacenum, int intention, offs_t &address) +| bool **read**\ (address_spacenum spacenum, offs_t offset, int size, UINT64 &value) +| bool **write**\ (address_spacenum spacenum, offs_t offset, int size, UINT64 value) +| bool **readop**\ (offs_t offset, int size, UINT64 &value) + +These methods override how the debugger accesses memory for a cpu. +Avoid them if you can. Otherwise, prepare for heavy-duty spelunking in +complicated code. + +If really required, should probably be part of cpu_device directly. diff --git a/docs/source/techspecs/device_rom_interface.rst b/docs/source/techspecs/device_rom_interface.rst new file mode 100644 index 00000000000..5d5dbc26192 --- /dev/null +++ b/docs/source/techspecs/device_rom_interface.rst @@ -0,0 +1,72 @@ +The device_rom_interface +======================== + +1. Capabilities +--------------- + +This interface is designed for devices which expect to have a rom +connected to them on a dedicated bus. It's mostly designed for sound +chips. Other devices types may be interested but other considerations +may make it impratical (graphics decode caching for instance). The +interface provides the capability of either connecting a ROM_REGION, +connecting an ADDRESS_MAP or dynamically setting up a block of memory +as rom. In the region/block cases, banking is automatically handled. + +2. Setup +-------- + +| **device_rom_interface**\ (const machine_config &mconfig, device_t &device, UINT8 addrwidth, endianness_t endian = ENDIANNESS_LITTLE, UINT8 datawidth = 8) + +The constructor of the interface wants, in addition to the standard +parameters, the address bus width of the dedicated bus. In addition +the endianness (if not little endian or byte-sized bus) and data bus +width (if not byte) can be provided. + +| **MCFG_DEVICE_ADDRESS_MAP**\ (AS_0, map) + +Use that method at machine config time to provide an address map for +the bus to connect to. It has priority over a rom region if one is +also present. + +| **ROM_REGION**\ (length, tag, flags) + +If a rom region with a tag identical to the device tag is provided in +the rom description for the system, it will be automatically picked up +as the connected rom. An address map has priority over the region if +present in the machine config. + +| void **set_rom**\ (const void \*base, UINT32 size); + +At any time post- **interface_pre_start**, a memory block can be +setup as the connected rom with that method. It overrides any +previous setup that may have been provided. It can be done multiple +times. + +3. Rom access +------------- + +| UINT8 **read_byte**\ (offs_t byteaddress) +| UINT16 **read_word**\ (offs_t byteaddress) +| UINT32 **read_dword**\ (offs_t byteaddress) +| UINT64 **read_qword**\ (offs_t byteaddress) + +These methods provide read access to the connected rom. Out-of-bounds +access results in standard unmapped read logerror messages. + +4. Rom banking +-------------- + +If the rom region or the memory block in set_rom is larger than the +address bus, banking is automatically setup. + +| void **set_rom_bank**\ (int bank) + +That method selects the current bank number. + +5. Caveats +---------- + +Using that interface makes the device derive from +**device_memory_interface**. If the device wants to actually use the +memory interface for itself, remember that AS_0/AS_PROGRAM is used by +the rom interface, and don't forget to upcall **memory_space_config**. diff --git a/docs/source/techspecs/index.rst b/docs/source/techspecs/index.rst index ed836ace341..20b17b2378e 100644 --- a/docs/source/techspecs/index.rst +++ b/docs/source/techspecs/index.rst @@ -6,6 +6,8 @@ This section covers technical specifications useful to programmers working on MA .. toctree:: :titlesonly: + device_memory_interface + device_rom_interface floppy nscsi luaengine |