summaryrefslogtreecommitdiffstatshomepage
path: root/docs/source/techspecs/device_memory_interface.rst
blob: 6056cce81de62678507a0886bdddc9a077a7cfbd (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
The device_memory_interface
===========================

.. contents:: :local:


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 (logical) address/data bus
that other devices can be connected to.  That’s mainly, but not solely,
CPUs.

The interface allows for an unlimited set of address spaces, numbered
with small, non-negative values.  The IDs index vectors, so they should
stay small to keep the lookup fast.  Spaces numbered 0-3 have associated
constant name:

+----+---------------+
| ID | Name          |
+====+===============+
| 0  | AS_PROGRAM    |
+----+---------------+
| 1  | AS_DATA       |
+----+---------------+
| 2  | AS_IO         |
+----+---------------+
| 3  | AS_OPCODES    |
+----+---------------+

Spaces 0 and 3, i.e. ``AS_PROGRAM`` and ``AS_OPCODES``, are special for
the debugger and some CPUs.  ``AS_PROGRAM`` is use by the debugger and
the CPUs as the space from which the CPU reads its instructions for the
disassembler.  When present, ``AS_OPCODES`` is used by the debugger and
some CPUs to read the opcode part of the instruction.  What opcode means
is device-dependant, for instance for the Z80 it's the initial byte(s)
which are read with the M1 signal asserted, while for the 68000 is means
every instruction word plus PC-relative accesses.  The main, but not
only, use of ``AS_OPCODES`` is to implement hardware decryption of
instructions separately from data.


2. Setup
--------

.. code-block:: C++

    std::vector<std::pair<int, const address_space_config *>> memory_space_config() const;

The device must override that method to provide a vector of pairs
comprising of a space number and an associated ``address_space_config``
describing its configuration.  Some examples to look up when needed:

* Standard two-space vector:
  `v60_device <https://git.redump.net/mame/tree/src/devices/cpu/v60/v60.cpp?h=mame0226>`_
* Conditional ``AS_OPCODES``:
  `z80_device <https://git.redump.net/mame/tree/src/devices/cpu/z80/z80.cpp?h=mame0226>`_
* Inherit configuration and add a space:
  `hd647180x_device <https://git.redump.net/mame/tree/src/devices/cpu/z180/hd647180x.cpp?h=mame0226>`_
* Inherit configuration and modify a space:
  `tmpz84c011_device <https://git.redump.net/mame/tree/src/devices/cpu/z80/tmpz84c011.cpp?h=mame0226>`_

.. code-block:: C++

    bool has_configured_map(int index = 0) const;

The ``has_configured_map`` method allows to test whether an
``address_map`` has been associated with a given space in the
``memory_space_config`` method .  That allows optional memory spaces to
be implemented, such as ``AS_OPCODES`` in certain CPU cores.


3. Associating maps to spaces
-----------------------------
Associating maps to spaces is done at the machine configuration level,
after the device is instantiated.

.. code-block:: C++

    void set_addrmap(int spacenum, T &obj, Ret (U::*func)(Params...));
    void set_addrmap(int spacenum, Ret (T::*func)(Params...));
    void set_addrmap(int spacenum, address_map_constructor map);

These function associate a map with a given space.  Address maps
associated with non-existent spaces are ignored (no warning given).  The
first form takes a reference to an object and a method to call on that
object.  The second form takes a method to call on the current device
being configured.  The third form takes an ``address_map_constructor``
to copy.  In each case, the function must be callable with reference to
an ``address_map`` object as an argument.

To remove a previously configured address map, call ``set_addrmap`` with
a default-constructed ``address_map_constructor`` (useful for removing a
map for an optional space in a derived machine configuration).

As an example, here’s the address map configuration for the main CPU in
the Hana Yayoi and Hana Fubuki machines, with all distractions removed:

.. code-block:: C++

    class hnayayoi_state : public driver_device
    {
    public:
        void hnayayoi(machine_config &config);
        void hnfubuki(machine_config &config);

    private:
	required_device<cpu_device> m_maincpu;

	void hnayayoi_map(address_map &map);
	void hnayayoi_io_map(address_map &map);
	void hnfubuki_map(address_map &map);
    };

    void hnayayoi_state::hnayayoi(machine_config &config)
    {
        Z80(config, m_maincpu, 20000000/4);
        m_maincpu->set_addrmap(AS_PROGRAM, &hnayayoi_state::hnayayoi_map);
        m_maincpu->set_addrmap(AS_IO, &hnayayoi_state::hnayayoi_io_map);
    }

    void hnayayoi_state::hnfubuki(machine_config &config)
    {
        hnayayoi(config);

        m_maincpu->set_addrmap(AS_PROGRAM, &hnayayoi_state::hnfubuki_map);
        m_maincpu->set_addrmap(AS_IO, address_map_constructor());
    }


4. Accessing the spaces
-----------------------

.. code-block:: C++

    address_space &space(int index = 0) const;

Returns the specified address space post-initialization.  The specified
address space must exist.

.. code-block:: C++

    bool has_space(int index = 0) const;

Indicates whether a given space actually exists.


5. MMU support for disassembler
-------------------------------

.. code-block:: C++

    bool translate(int spacenum, int intention, offs_t &address, address_space *&target_space);

Does a logical to physical address translation through the device's
MMU.  spacenum gives the space number, intention for the type of the
future access (``TR_(READ\|WRITE\|FETCH)``), address is an in/out
parameter holding the address to translate on entry and the translated
version on return, and finally target_space is the actual space the
access would end up in, which may be in a different device.  Should
return ``true`` if the translation went correctly, or ``false`` if the
address is unmapped.  The call must not change the state of the
device.

Note that for some historical reason, the device itself must override
the virtual method ``memory_translate`` with the same signature.