diff options
Diffstat (limited to 'docs/source/techspecs/device_rom_interface.rst')
-rw-r--r-- | docs/source/techspecs/device_rom_interface.rst | 123 |
1 files changed, 72 insertions, 51 deletions
diff --git a/docs/source/techspecs/device_rom_interface.rst b/docs/source/techspecs/device_rom_interface.rst index 576800e634a..4125bc9536a 100644 --- a/docs/source/techspecs/device_rom_interface.rst +++ b/docs/source/techspecs/device_rom_interface.rst @@ -1,92 +1,113 @@ The device_rom_interface ======================== +.. contents:: :local: + + 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 +This interface is designed for devices that 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. +may make it impractical (graphics decode caching, for instance). The +interface provides the capability to connect a ROM region, connect an +address map, or dynamically set up a block of memory as ROM. In the +region/memory block cases, banking is handled automatically. + 2. Setup -------- -| **device_rom_interface**\ (const machine_config &mconfig, device_t &device, u8 addrwidth, endianness_t endian = ENDIANNESS_LITTLE, u8 datawidth = 8) +.. code-block:: C++ + + device_rom_interface<AddrWidth, DataWidth=0, AddrShift=0, Endian=ENDIANNESS_LITTLE> -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. +The interface is a template that takes the address width of the +dedicated bus as a parameter. In addition the data bus width (if not +byte), address shift (if non-zero) and Endianness (if not little Endian +or byte-sized bus) can be provided. Data bus width is 0 for byte, 1 +for word, etc. -| **MCFG_DEVICE_ADDRESS_MAP**\ (AS_0, map) +.. code-block:: C++ -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 + void set_map(map); + +Use that method at machine configuration time to provide an address map +for the bus to connect to. It has priority over a ROM region if one is also present. -| **MCFG_DEVICE_ROM**\ (tag) +.. code-block:: C++ + + void set_device_rom_tag(tag); + +Used to specify a ROM region to use if a device address map is not +given. Defaults to ``DEVICE_SELF``, i.e. the device’s tag. -Used to select a rom region to use if a device address map is not -given. Defaults to DEVICE_SELF, e.g. the device tag. +.. code-block:: C++ -| **ROM_REGION**\ (length, tag, flags) + ROM_REGION(length, tag, flags) -If a rom region with a tag as given with **MCFG_DEVICE_ROM** if +If a ROM region with the tag specified using ``set_device_rom_tag`` if present, or identical to the device tag otherwise, 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. +ROM definitions 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 configuration. -| void **set_rom_endianness**\ (endianness_t endian) -| void **set_rom_data_width**\ (u8 width) -| void **set_rom_addr_width**\ (u8 width) +.. code-block:: C++ -These methods, intended for generic devices with indefinite hardware -specifications, override the endianness, data bus width and address -bus width assigned through the constructor. They must be called from -within the device before **config_complete** time. + void override_address_width(u8 width); -| void **set_rom**\ (const void \*base, u32 size); +This method allows the address bus width to be overridden. It must be +called from within the device before **config_complete** time. -At any time post- **interface_pre_start**, a memory block can be -setup as the connected rom with that method. It overrides any +.. code-block:: C++ + + void set_rom(const void *base, u32 size); + +At any time post-\ ``interface_pre_start``, a memory block can be +set up 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 + +3. ROM access ------------- -| u8 **read_byte**\ (offs_t byteaddress) -| u16 **read_word**\ (offs_t byteaddress) -| u32 **read_dword**\ (offs_t byteaddress) -| u64 **read_qword**\ (offs_t byteaddress) +.. code-block:: C++ + + u8 read_byte(offs_t addr); + u16 read_word(offs_t addr); + u32 read_dword(offs_t addr); + u64 read_qword(offs_t addr); -These methods provide read access to the connected rom. Out-of-bounds -access results in standard unmapped read logerror messages. +These methods provide read access to the connected ROM. Out-of-bounds +access results in standard unmapped read ``logerror`` messages. -4. Rom banking + +4. ROM banking -------------- -If the rom region or the memory block in set_rom is larger than the -address bus, banking is automatically setup. +If the ROM region or the memory block in ``set_rom`` is larger than the +address bus can access, banking is automatically set up. + +.. code-block:: C++ -| void **set_rom_bank**\ (int bank) + 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**. - -For devices which have outputs that can be used to address ROMs but -only to forward the data to another device for processing, it may be -helpful to disable the interface when it is not required. This can be -done by overriding **memory_space_config** to return an empty vector. +``device_memory_interface``. If the device wants to actually use the +memory interface for itself, remember that space zero (0, or +``AS_PROGRAM``) is used by the ROM interface, and don’t forget to call +the base ``memory_space_config`` method. + +For devices which have outputs that can be used to address ROMs but only +to forward the data to another device for processing, it may be helpful +to disable the interface when it is not required. This can be done by +overriding ``memory_space_config`` to return an empty vector. |