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


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



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:


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.


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.


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.


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.

triggerpointsnot supported

This component does not support triggerpoints.

state save/restorenot supported

This component does not support state save/restore.


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

access-portany addressany accessmapping

namecategorylegal valuesdefault valuebehaviors
latencysettingnumber0memory latency
state-snapshot-opaque string-state save/restore

ACCESSOR, any of the specified formsany accessconfiguration, mapping

Variant: hw-mapper-transparent

Same as hw-mapper-basic