           hw-mapper-basic (libmapper.la :: mapper_component_library)

Synopsis:

   This component is a generalized model of the distributed computer
   circuitry that decodes bus addresses.

     ----------------------------------------------------------------------

Functionality:

  Modelling:

   This component distributes bus accesses to one of a number of configured
   bus accessors, depending on the address of the incoming memory access.

   A mapper defines a group of address spaces. Each group is known as a bank.
   Each address space is decomposed into non-overlapping regions by
   configuring a dynamic collection of accessors. Each accessor is connected
   to a single slave bus. To configure the address mapping, you must name
   each accessor according to one of these forms:
     * [<low>-<high>]
     * [<wordsize>*<low>-<high>]
     * [<low>-<high>,<stride>,<width>]
     * [<wordsize>*<low>-<high>,<stride>,<width>]
     * [<mapped_base>=<low>-<high>]
     * [<wordsize>*<mapped_base>=<low>-<high>]
     * [<mapped_base>=<low>-<high>,<stride>,<width>]
     * [<wordsize>*<mapped_base>=<low>-<high>,<stride>,<width>]
   where:
     * <low> is the starting address for the mapped region.
     * <high> is the ending address for the mapped region.
     * <stride> is the step size between addressable units.
     * <width> is the width of addressable units.
     * <wordsize> is the number of bytes in an address unit: a constant
       multiplier you can use to permit specifying <low>, <high>, <stride>
       and <width> in terms of multi-byte words.
     * <mapped_base> is the base address of the mapped bytes on the target
       bus. Addresses in the mapped region will be adjusted to start at
       <mapped_base>. For hw-mapper-transparent, the default <mapped_base> is
       the value of <start>. For hw-mapper-basic, the default <mapped_base>
       is zero.

   To the right of the "]" closing bracket, an optional specification block
   may list the numbers of mapping banks for this record. This block is
   formatted as a comma-separated list of numbers, given between "{" and "}"
   brackets. The default is to reside in bank 0 only.

   In addition, any text may appear to the left of the "[" and "]" brackets,
   as long as that text does not include any of the characters "[" "]".
   Likewise, text may appear to the right, but it must exclude the "[", "]",
   "{", and "}" bracket characters.

   Each number may be specified in decimal, hexadecimal, octal, and binary
   forms, with the appropriate prefix (none, "0x", "0", "0b", respectively).

   The first form is appropriate if the slave device is willing to accept all
   possible sid::bus accesses (subject to the address range limits). The
   second form is appropriate if the slave device is willing to accept only
   accesses to addressable units of fixed width at a fixed stride from one
   another.

   The downstream addresses passed by the hw-mapper-basic variant are
   relative to the matching region, so are zero-based, by default. The
   hw-mapper-transparent does not make downstream addresses relative by
   default, so it may be more suitable for carving up an address space by
   multiple layers of mapping. Use of <mapped_base> for either component
   overrides this default behavior.

   See the "mapping" behavior below for more details.

   +-------------------------------------------------+
   |                    Behaviors                    |
   |-------------------------------------------------|
   |  configuration | When an accessor of the        |
   |                | prescribed format is set, and  |
   |                | the address range is valid,    |
   |                | the supplied bus is registered |
   |                | in the decoding table. Future  |
   |                | accesses on the access-port    |
   |                | bus will consider that address |
   |                | range as a candidate.          |
   |                |                                |
   |                | Reasons for rejecting an       |
   |                | address range include          |
   |                | overlapping with an existing   |
   |                | entry, or inconsistent ranges  |
   |                | or stride/width values.        |
   |----------------+--------------------------------|
   |        banking | When the bank attribute is set |
   |                | with a numeric value, or the   |
   |                | bank pin is driven with a      |
   |                | number, the mapping group or   |
   |                | bank number is instantly       |
   |                | changed. Subsequent mapping    |
   |                | activities will see only those |
   |                | mapping entries that include   |
   |                | the new bank number.           |
   |----------------+--------------------------------|
   |        mapping | When an incoming access on the |
   |                | access-port bus is received,   |
   |                | its base address is compared   |
   |                | to all the registered outgoing |
   |                | accessors in the current bank. |
   |                | If one is found that contains  |
   |                | the address, the current       |
   |                | address is transformed         |
   |                | according to the following     |
   |                | rules:                         |
   |                |   * The accessor's             |
   |                |     <mapped_base> address is   |
   |                |     subtracted from the        |
   |                |     incoming address, so       |
   |                |     outgoing addresses will be |
   |                |     relative.                  |
   |                |   * If the accessor has        |
   |                |     stride/width values,       |
   |                |     divide the relative        |
   |                |     address by the quotient    |
   |                |     (<stride>/<width>). As a   |
   |                |     result, outgoing addresses |
   |                |     will refer to consecutive  |
   |                |     addressable units, and an  |
   |                |     outgoing access of the     |
   |                |     desired width will be      |
   |                |     made.                      |
   |                |   * If the accessor has no     |
   |                |     stride/width values, the   |
   |                |     relative address and the   |
   |                |     incoming access width will |
   |                |     be used to make an         |
   |                |     outgoing access.           |
   |                |                                |
   |                | This component will return an  |
   |                | incoming access prematurely    |
   |                | with sid::bus::unmapped if no  |
   |                | accessor covers the incoming   |
   |                | address. Similarly, it will    |
   |                | signal a sid::bus::misaligned  |
   |                | condition if an incoming       |
   |                | access could be handled by a   |
   |                | stride/width accessor, but the |
   |                | addressed bytes don't cover    |
   |                | exactly one addressable unit.  |
   |                |                                |
   |                | Whenever an incoming access is |
   |                | attempted, the component       |
   |                | increments its access-count    |
   |                | attribute. When a repeated     |
   |                | access hits an internal        |
   |                | mapping cache, the             |
   |                | cache-hit-count is             |
   |                | incremented. Whenever an       |
   |                | incoming address is contained  |
   |                | in a specific accessor's       |
   |                | address interval, the          |
   |                | ACCESSOR-count attribute is    |
   |                | incremented. (The ACCESSOR     |
   |                | string is the name of the      |
   |                | accessor.)                     |
   |----------------+--------------------------------|
   | memory latency | This component models constant |
   |                | latency for accesses which     |
   |                | pass through the mapper. The   |
   |                | value of the latency is added  |
   |                | to the total latency of every  |
   |                | bus transaction. The units of  |
   |                | latency are nominal, but       |
   |                | typically represent a number   |
   |                | of system clock cycles.        |
   +-------------------------------------------------+

   +-------------------------------------------------+
   |                 SID Conventions                 |
   |-------------------------------------------------|
   |    functional | supported  | This is a          |
   |               |            | functional         |
   |               |            | component.         |
   |---------------+------------+--------------------|
   |       latency | supported  | This component     |
   |               |            | models memory      |
   |               |            | latency.           |
   |---------------+------------+--------------------|
   | triggerpoints | not        | This component     |
   |               | supported  | does not support   |
   |               |            | triggerpoints.     |
   |---------------+------------+--------------------|
   |         state | not        | This component     |
   |  save/restore | supported  | does not support   |
   |               |            | state              |
   |               |            | save/restore.      |
   +-------------------------------------------------+

     ----------------------------------------------------------------------

Environment:

   Related components

   Commonly, this component will be placed between a CPU and an array of bus
   peripherals. The hw-glue-probe-bus component may be used in conjunction
   with this component to analyze and troubleshoot bus configuration
   problems, being chained to either the CPU side of the mapper or the
   peripherals side.

   An illustration of a simple configuration for an ARM7T system with a main
   memory and a memory mapped UART follows:

         new hw-cpu-arm7t cpu
         new hw-mapper-basic bus
         new hw-uart-ns16550
         new hw-memory-ram/rom-basic mem
         set mem size 4194304
         connect-bus cpu insn-memory bus access-port
         connect-bus cpu data-memory bus access-port
         connect-bus bus [0xD800000,0xD80001F,4,1] uart Bus
         connect-bus bus [0x0,0x400000] mem read-write-port

   Here, the CPU's accessors are connected directly to the mapper. All
   peripherals are connected downstream from the mapper. They will have their
   bus transactions routed to them by the mapper, by virtue of configuration.

     ----------------------------------------------------------------------

Component Reference:

  Component: hw-mapper-basic

   +-------------------------------------------------+
   |                      buses                      |
   |-------------------------------------------------|
   |    name     | addresses  | accesses | behaviors |
   |-------------+------------+----------+-----------|
   | access-port | any        | any      | mapping   |
   |             | address    | access   |           |
   +-------------------------------------------------+

   +-----------------------------------------------------+
   |                     attributes                      |
   |-----------------------------------------------------|
   |     name      |category|legal |default| behaviors  ||
   |               |        |values| value |            ||
   |---------------+--------+------+-------+------------||
   |access-count   |register|number|0      |mapping     ||
   |---------------+--------+------+-------+------------||
   |cache-hit-count|register|number|0      |mapping     ||
   |---------------+--------+------+-------+------------||
   |ACCESSOR-count |register|number|0      |mapping     ||
   |---------------+--------+------+-------+------------||
   |latency        |setting |number|0      |memory      ||
   |               |        |      |       |latency     ||
   |---------------+--------+------+-------+------------||
   |state-snapshot |-       |opaque|-      |state       ||
   |               |        |string|       |save/restore||
   +-----------------------------------------------------+

   +-------------------------------------------------+
   |                    accessors                    |
   |-------------------------------------------------|
   |       name        |  accesses  |   behaviors    |
   |-------------------+------------+----------------|
   | ACCESSOR, any of  |            | configuration, |
   | the specified     | any access | mapping        |
   | forms             |            |                |
   +-------------------------------------------------+

  Variant: hw-mapper-transparent

   Same as hw-mapper-basic
