summaryrefslogtreecommitdiffstatshomepage
path: root/docs/source/techspecs/memory.rst
diff options
context:
space:
mode:
author Olivier Galibert <galibert@pobox.com>2020-11-12 15:52:20 +0100
committer Olivier Galibert <galibert@pobox.com>2020-11-22 19:43:52 +0100
commit574daf4e49e7e9ef4641f363bd2b007c5a414d47 (patch)
treeb43ca91fa36fbc26e54316de5a33069c85e1df9d /docs/source/techspecs/memory.rst
parent8d4559070f10367dac4fb7f7721b1f3e91098c75 (diff)
Implement views, which are essentially bankdevs integrated into the
memory map system. [O. Galibert]
Diffstat (limited to 'docs/source/techspecs/memory.rst')
-rw-r--r--docs/source/techspecs/memory.rst97
1 files changed, 97 insertions, 0 deletions
diff --git a/docs/source/techspecs/memory.rst b/docs/source/techspecs/memory.rst
index 0b9b24dc7f4..87fd4afd640 100644
--- a/docs/source/techspecs/memory.rst
+++ b/docs/source/techspecs/memory.rst
@@ -64,6 +64,20 @@ Memory regions are read-only memory zones in which ROMs are loaded.
All of these have names allowing to access them.
+2.4 Views
+~~~~~~~~~
+
+Views are a way to multiplex different submaps over a memory range
+with fast switching. It is to be used when multiple devices map at
+the same addresses and are switched in externally. They must be
+created as an object of the device and then setup either statically in
+a memory map or dynamically through install_* calls.
+
+Switchable submaps, aka variants, are named through an integer. An
+internal indirection through a map ensures that any integer value can
+be used.
+
+
3. Memory objects
-----------------
@@ -225,6 +239,37 @@ The ``memregion`` device method retrieves a memory region by name.
Beware that the lookup can be expensive, prefer finders instead.
+3.4 Views - memory_view
+~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: C++
+
+ class memory_view {
+ memory_view(device_t &device, std::string name);
+ memory_view_entry &operator[](int slot);
+
+ void select(int entry);
+ void disable();
+
+ const std::string &name() const;
+ }
+
+A view allows to switch part of a memory map between multiple
+possibilities, or even disable it entirely to see what was there
+before. It is created as an object of the device.
+
+.. code-block:: C++
+
+ memory_view m_view;
+
+ [device constructor] m_view(*this, "name"),
+
+It is then setup through the address map API or dynamically. The, at
+runtime, a variant, which is numbered, can be selected through the
+``select`` method or the view can be disabled through the ``disabled``
+method. A disabled view can be reenabled at any time.
+
+
4. Address maps API
-------------------
@@ -543,6 +588,40 @@ trigger the handler if a wider part of the bus is accessed. The
parameter is that trigger width (would be 16 in the 68000 case).
+4.5 View setup
+~~~~~~~~~~~~~~
+
+.. code-block:: C++
+
+ map(start, end).view(m_view);
+ m_view[0](start1, end1).[...];
+
+A view is setup in a address map with the view method. The only
+qualifier accepted is mirror. The "disabled" version of the view will
+include what was in the range prior to the view setup.
+
+The different variants are setup by indexing the view with the variant
+number and setting up an entry in the usual way. The entries within a
+variant must of course stay within the range. There are no other
+additional constraints. The contents of a variant, by default, are
+what was there before, e.g. the contents of the disabled view, and
+then setting it up allows to override part or all of it.
+
+Variants can only be setup once the view itself has been setup with
+the ``view`` method.
+
+A view can only be put in one address map and in only one position.
+If multiple views have identical or similar contents remember that
+setting up a map is nothing more than a method call, and creating a
+second method to setup a view is perfectly reasonable. A view is of
+type **memory_view** and an indexed entry (e.g. a variant to setup) is
+of type **memory_view::memory_view_entry &**.
+
+A view can be installed in another view, but don't forget that a view
+can be installed only once. A view can also being part of "what was
+there before".
+
+
5. Address space dynamic mapping API
------------------------------------
@@ -695,3 +774,21 @@ with an optional mirror.
Install a device address with an address map in a space. The
``unitmask`` and ``cswidth`` arguments are optional.
+
+5.9 View installation
+~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: C++
+
+ space.install_view(addrstart, addrend, view)
+ space.install_view(addrstart, addrend, addrmirror, view)
+
+ view[0].install...
+
+Installs a view in a space. This can be only done once and in only
+one space, and the view must not have been setup through the address
+map API before. Once the view is installed variants can be selected
+through indexation to call a dynamic mapping method on it.
+
+A view can be installed into a variant of another view without issues
+with the only usual constraint of single installation.