mirror of
https://github.com/mamedev/mame.git
synced 2024-11-16 07:48:32 +01:00
dimemory, dirom: Add some documentation [O. Galibert]
This commit is contained in:
Olivier Galibert
parent
e153f45560
commit
a2c306e923
3 changed files with 173 additions and 0 deletions
99
docs/source/techspecs/device_memory_interface.rst
Normal file
99
docs/source/techspecs/device_memory_interface.rst
Normal file
|
|
@ -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.
|
||||
72
docs/source/techspecs/device_rom_interface.rst
Normal file
72
docs/source/techspecs/device_rom_interface.rst
Normal file
|
|
@ -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**.
|
||||
|
|
@ -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
|
||||
|
|
|
|||
Loading…
Reference in a new issue