summaryrefslogtreecommitdiffstatshomepage
path: root/docs
diff options
context:
space:
mode:
author Olivier Galibert <galibert@pobox.com>2016-09-06 12:46:40 +0200
committer Olivier Galibert <galibert@pobox.com>2016-09-06 12:47:20 +0200
commita2c306e92343e6487a485bd0e96fac44b2d87105 (patch)
tree75775a0ec6d1690429c6881d0bcce0a7df601225 /docs
parente153f4556044e190729fbed5bf2687259c319eed (diff)
dimemory, dirom: Add some documentation [O. Galibert]
Diffstat (limited to 'docs')
-rw-r--r--docs/source/techspecs/device_memory_interface.rst99
-rw-r--r--docs/source/techspecs/device_rom_interface.rst72
-rw-r--r--docs/source/techspecs/index.rst2
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