registermap 0.1.0

Main Features

• define a register map by the relationships and order of registers and bit fields

• generate address of registers and modules automatically from relationships

• constrain registers and modules by size or address

• automatically manage registers that span multiple memory units

• automatically generate a series of modules from a template/reference module

• arbitrary number of memory unit bits (but constant across the register map)

• arbitrary number of address bits (but constant across the register map)

• automatically avoid allocating register/module addresses to page registers

Installation

The simplest way to acquire registerMap is using pip.

pip install registerMap

Getting Started

In this framework a register map is an ordered list of modules. A module is an ordered list of registers and a register is made up of bit fields.

A memory space defines the fundamental properties of the register map such as the number of bits in addresses, the base address of the register map and the number of bits in memory units.

The order of the modules defines how module addresses are generated. So the first module in the list would probably get assigned the base address of the register map memory space and the next module might get the next available address. The words ‘probably’ and ‘might’ are used here because there are other factors such as the total span of the module, page registers and constraints applied to modules and registers that can change what addresses are available for assignment. More on that later.

A module is a way of grouping registers together. When there is more than one module, the groups will probably have some functional association of the registers, for example, a set of registers associated with a particular output, or a set of read only registers for reporting status.

A register is made up of bit fields. The order of bit fields is not defined because the bits to which each bit field is assigned must be explicitly defined. A register, or perhaps more accurately, the total span of its bit fields may also span multiple memory units. This enables support for data that is larger than the bit size of a single memory unit; eg. If the memory unit size is 8 bits, then it may still be desirable to store a 16, 32 or 64 bit number for the function of the integrated circuit.

The primary source format of the register map is YAML, so one way to get started is by defining your register map directly in a YAML text file. The other way is to import the Python library and start working on the register map dataset directly in a Python terminal or script.

registerMap: {
  # A memorySpace is not optional
  memorySpace: {
    # but all the parameters are optional.
    # Default: 0x0
    baseAddress: 0x1000
    # Default: None
    pageSize: None
    # Default: 32
    addressBits: 48
    # Default: 8
    memoryUnitBits: 16
  }
  summary: 'A short summary of the register map'
  description: 'A longer description of the register map'
  modules: [
  ]
}

import registerMap
myMap = registerMap.load( 'registermap.yml' )

assert myMap.memory.addressBits == 48
assert myMap.memory.memoryUnitBits == 16
assert myMap.memory.baseAddress == 0x1000

import registerMap
myMap = registerMap.RegisterMap()

assert myMap.memory.addressBits == 32
assert myMap.memory.memoryUnitBits == 8
assert myMap.memory.baseAddress == 0x0
assert len( myMap[ 'modules' ] ) == 0

registerMap.save( myMap, 'registermap.yml' )