summaryrefslogtreecommitdiffstatshomepage
path: root/docs/source/techspecs/memory.rst
diff options
context:
space:
mode:
Diffstat (limited to 'docs/source/techspecs/memory.rst')
-rw-r--r--docs/source/techspecs/memory.rst90
1 files changed, 59 insertions, 31 deletions
diff --git a/docs/source/techspecs/memory.rst b/docs/source/techspecs/memory.rst
index 76a79ef6d76..ebdca9646d1 100644
--- a/docs/source/techspecs/memory.rst
+++ b/docs/source/techspecs/memory.rst
@@ -126,7 +126,8 @@ A memory share can be created if it doesn’t exist in a memory map
through that creator class. If it already exists it is just
retrieved. That class behaves like a pointer but also has the
``target()``, ``length()``, ``bytes()``, ``endianness()``,
-``bitwidth()`` and ``bytewidth()`` methods for share information.
+``bitwidth()`` and ``bytewidth()`` methods for share information. The
+desired size is specified in bytes.
.. code-block:: C++
@@ -154,12 +155,17 @@ A memory bank is a named memory zone indirection that can be mapped in
address spaces. It points to ``nullptr`` when created.
``configure_entry`` associates an entry number and a base pointer.
``configure_entries`` does the same for multiple consecutive entries
-spanning a memory zone. Alternatively ``set_base`` sets the base for
-entry 0 and selects it.
+spanning a memory zone.
-``set_entry`` allows to dynamically and efficiently select the current
-active entry, ``entry()`` gets that selection back, and ``base()`` gets
-the associated base pointer.
+``set_base`` sets the base address for the active entry. If there are
+no entries, entry 0 (zero) is automatically created and selected. Use
+of ``set_base`` should be avoided in favour of pre-configured entries
+unless there are an impractically large number of possible base
+addresses.
+
+``set_entry`` dynamically and efficiently selects the active entry,
+``entry()`` returns the active entry number, and ``base()`` gets the
+associated base pointer.
.. code-block:: C++
@@ -180,7 +186,7 @@ retrieved by building one of these four finders.
[device constructor] m_bank(*this, "name"),
-A memory share can be created if it doesn’t exist in a memory map
+A memory bank can be created if it doesn’t exist in a memory map
through that creator class. If it already exists it is just
retrieved.
@@ -197,7 +203,7 @@ that the lookup can be expensive, prefer finders instead.
.. code-block:: C++
- class memory_bank {
+ class memory_region {
u8 *base();
u8 *end();
u32 bytes() const;
@@ -355,7 +361,7 @@ Sets a method of the current device or driver to read, write or both
for the current entry. The prototype of the method can take multiple
forms making some elements optional. ``uNN`` represents ``u8``,
``u16``, ``u32`` or ``u64`` depending on the data width of the handler.
-The handler can be narrower than the bus itself (for instance a 8-bit
+The handler can be narrower than the bus itself (for instance an 8-bit
device on a 32-bit bus).
The offset passed in is built from the access address. It starts at
@@ -588,6 +594,19 @@ 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.4.6 User flags
+''''''''''''''''
+
+.. code-block:: C++
+
+ (...).flags(16-bits mask)
+
+This parameter allows to set user-defined flags on the handler which
+can then be retrieved by an accessing device to change their
+behaviour. An example of use the i960 which marks burstable zones
+that way (they have a specific hardware-level support).
+
+
4.5 View setup
~~~~~~~~~~~~~~
@@ -634,7 +653,7 @@ changed on-the-fly. They’re powerful but have some issues:
* changing the mappings repeatedly can be slow
* the address space state is not saved in the saved states, so it has to
be rebuilt after state load
-* they can be hidden anywhere rather that be grouped in an address map,
+* they can be hidden anywhere rather than be grouped in an address map,
which can be less readable
The methods, rather than decomposing the information in handler, handler
@@ -683,18 +702,18 @@ Note that as all delegates, they can also wrap lambdas.
.. code-block:: C++
- space.install_read_handler(addrstart, addrend, read_delegate, unitmask, cswidth)
- space.install_read_handler(addrstart, addrend, addrmask, addrmirror, addrselect, read_delegate, unitmask, cswidth)
- space.install_write_handler(addrstart, addrend, write_delegate, unitmask, cswidth)
- space.install_write_handler(addrstart, addrend, addrmask, addrmirror, addrselect, write_delegate, unitmask, cswidth)
- space.install_readwrite_handler(addrstart, addrend, read_delegate, write_delegate, unitmask, cswidth)
- space.install_readwrite_handler(addrstart, addrend, addrmask, addrmirror, addrselect, read_delegate, write_delegate, unitmask, cswidth)
+ space.install_read_handler(addrstart, addrend, read_delegate, unitmask, cswidth, flags)
+ space.install_read_handler(addrstart, addrend, addrmask, addrmirror, addrselect, read_delegate, unitmask, cswidth, flags)
+ space.install_write_handler(addrstart, addrend, write_delegate, unitmask, cswidth, flags)
+ space.install_write_handler(addrstart, addrend, addrmask, addrmirror, addrselect, write_delegate, unitmask, cswidth, flags)
+ space.install_readwrite_handler(addrstart, addrend, read_delegate, write_delegate, unitmask, cswidth, flags)
+ space.install_readwrite_handler(addrstart, addrend, addrmask, addrmirror, addrselect, read_delegate, write_delegate, unitmask, cswidth, flags)
These six methods allow to install delegate-wrapped handlers in a live
address space. Either plain or with mask, mirror and select. In the
read/write case both delegates must be of the same flavor (``smo``
stuff) to avoid a combinatorial explosion of method types. The
-``unitmask`` and ``cswidth`` arguments are optional.
+``unitmask``, ``cswidth`` and ``flags`` arguments are optional.
5.3 Direct memory range mapping
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -703,15 +722,18 @@ stuff) to avoid a combinatorial explosion of method types. The
space.install_rom(addrstart, addrend, void *pointer)
space.install_rom(addrstart, addrend, addrmirror, void *pointer)
+ space.install_rom(addrstart, addrend, addrmirror, flags, void *pointer)
space.install_writeonly(addrstart, addrend, void *pointer)
space.install_writeonly(addrstart, addrend, addrmirror, void *pointer)
+ space.install_writeonly(addrstart, addrend, addrmirror, flags, void *pointer)
space.install_ram(addrstart, addrend, void *pointer)
space.install_ram(addrstart, addrend, addrmirror, void *pointer)
+ space.install_ram(addrstart, addrend, addrmirror, flags, void *pointer)
-Installs a memory block in an address space, with or without mirror.
-``_rom`` is read-only, ``_ram`` is read/write, ``_writeonly`` is
-write-only. The pointer must be non-null, this method will not allocate
-the memory.
+Installs a memory block in an address space, with or without mirror
+and flags. ``_rom`` is read-only, ``_ram`` is read/write,
+``_writeonly`` is write-only. The pointer must be non-null, this
+method will not allocate the memory.
5.4 Bank mapping
~~~~~~~~~~~~~~~~
@@ -720,10 +742,13 @@ the memory.
space.install_read_bank(addrstart, addrend, memory_bank *bank)
space.install_read_bank(addrstart, addrend, addrmirror, memory_bank *bank)
+ space.install_read_bank(addrstart, addrend, addrmirror, flags, memory_bank *bank)
space.install_write_bank(addrstart, addrend, memory_bank *bank)
space.install_write_bank(addrstart, addrend, addrmirror, memory_bank *bank)
+ space.install_write_bank(addrstart, addrend, addrmirror, flags, memory_bank *bank)
space.install_readwrite_bank(addrstart, addrend, memory_bank *bank)
space.install_readwrite_bank(addrstart, addrend, addrmirror, memory_bank *bank)
+ space.install_readwrite_bank(addrstart, addrend, addrmirror, flags, memory_bank *bank)
Install an existing memory bank for reading, writing or both in an
address space.
@@ -735,10 +760,13 @@ address space.
space.install_read_port(addrstart, addrend, const char *rtag)
space.install_read_port(addrstart, addrend, addrmirror, const char *rtag)
+ space.install_read_port(addrstart, addrend, addrmirror, flags, const char *rtag)
space.install_write_port(addrstart, addrend, const char *wtag)
space.install_write_port(addrstart, addrend, addrmirror, const char *wtag)
+ space.install_write_port(addrstart, addrend, addrmirror, flags, const char *wtag)
space.install_readwrite_port(addrstart, addrend, const char *rtag, const char *wtag)
space.install_readwrite_port(addrstart, addrend, addrmirror, const char *rtag, const char *wtag)
+ space.install_readwrite_port(addrstart, addrend, addrmirror, flags, const char *rtag, const char *wtag)
Install ports by name for reading, writing or both.
@@ -747,33 +775,33 @@ Install ports by name for reading, writing or both.
.. code-block:: C++
- space.nop_read(addrstart, addrend, addrmirror)
- space.nop_write(addrstart, addrend, addrmirror)
- space.nop_readwrite(addrstart, addrend, addrmirror)
+ space.nop_read(addrstart, addrend, addrmirror, flags)
+ space.nop_write(addrstart, addrend, addrmirror, flags)
+ space.nop_readwrite(addrstart, addrend, addrmirror, flags)
-Drops the accesses for a given range with an optional mirror.
+Drops the accesses for a given range with an optional mirror and flags;
5.7 Unmapped accesses
~~~~~~~~~~~~~~~~~~~~~
.. code-block:: C++
- space.unmap_read(addrstart, addrend, addrmirror)
- space.unmap_write(addrstart, addrend, addrmirror)
- space.unmap_readwrite(addrstart, addrend, addrmirror)
+ space.unmap_read(addrstart, addrend, addrmirror, flags)
+ space.unmap_write(addrstart, addrend, addrmirror, flags)
+ space.unmap_readwrite(addrstart, addrend, addrmirror, flags)
Unmaps the accesses (e.g. logs the access as unmapped) for a given range
-with an optional mirror.
+with an optional mirror and flags.
5.8 Device map installation
~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. code-block:: C++
- space.install_device(addrstart, addrend, device, map, unitmask, cswidth)
+ space.install_device(addrstart, addrend, device, map, unitmask, cswidth, flags)
Install a device address with an address map in a space. The
-``unitmask`` and ``cswidth`` arguments are optional.
+``unitmask``, ``cswidth`` and ``flags`` arguments are optional.
5.9 View installation
~~~~~~~~~~~~~~~~~~~~~