diff options
Diffstat (limited to 'docs/source/techspecs/memory.rst')
-rw-r--r-- | docs/source/techspecs/memory.rst | 90 |
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 ~~~~~~~~~~~~~~~~~~~~~ |