JSON Format

Airhdl uses the JSON file format to import and export register maps to and from the web application. The airhdl command line generator, which can be purchased separately, expects register map descriptions in the same JSON format.

The listing below shows an example JSON description for a register map called map1 with the following registers:

• control, a read-write register with a 1-bit ena field and a 1-bit self-clearing rst field
• status, a read-only register with a 32-bit value field
• interrupt, an interrupt register with a 1-bit timeout field

{
    "jsonVersion": 2,
    "registerMap": {
        "name": "map1",
        "description": "my first register map",
        "width": 32,
        "baseAddress": 0,
        "addrWidthBits": 32,
        "registers": [
            {
                "type": "Register",
                "name": "control",
                "description": "Control register",
                "access": "READ_WRITE",
                "addressOffset": 0,
                "size": 32,
                "fields": [
                    {
                        "name": "ena",
                        "description": "Enable the component",
                        "bitWidth": 1,
                        "bitOffset": 0,
                        "reset": 0,
                        "selfClear": false,
                        "enumValues": [
                            {
                                "name": "on",
                                "value": 1
                            },
                            {
                                "name": "off",
                                "value": 0
                            }
                        ]
                    },
                    {
                        "name": "rst",
                        "description": "Reset the component",
                        "bitWidth": 1,
                        "bitOffset": 31,
                        "reset": 0,
                        "selfClear": true,
                        "enumValues": []
                    }
                ]
            },
            {
                "type": "Register",
                "name": "status",
                "description": "Status register",
                "access": "READ_ONLY",
                "addressOffset": 8,
                "size": 32,
                "fields": [
                    {
                        "name": "value",
                        "description": "",
                        "bitWidth": 32,
                        "bitOffset": 0,
                        "reset": 0,
                        "selfClear": false,
                        "enumValues": []
                    }
                ]
            },
            {
                "type": "Register",
                "name": "interrupt",
                "description": "Event register",
                "access": "INTERRUPT",
                "addressOffset": 12,
                "size": 32,
                "fields": [
                    {
                        "name": "timeout",
                        "description": "",
                        "bitWidth": 1,
                        "bitOffset": 0,
                        "reset": 0,
                        "selfClear": false,
                        "enumValues": []
                    }
                ]
            }
        ],
        "revision": 21,
        "generateRecordPorts": false
    }
}

Root Object Attributes

The root JSON object has the following attributes:

Attribute	Description	Type	Required	Allowed Values
jsonVersion	The version of the JSON schema	integer	yes	2
registerMap	The register map object (see below)	object	yes

Register Map Object Attributes

The Register Map object has the following attributes:

Attribute	Description	Type	Required	Allowed Values
name	The register map's name	string	yes
description	The register map's description	string	yes
width	The register map's data width, in bits	integer	yes	32
baseAddress	The register map's base address	integer	yes
addrWidthBits	The register map's default address with, in bits	integer	no
revision	The register map's revision	integer	yes
generateRecordPorts	Wrap user-logic facing ports into VHDL record and SystemVerilog struct types	boolean	yes	true, false
generatePackedStructs	Generate packed SystemVerilog structs	boolean	yes	true, false
registers	The list of register map elements	array	yes

Register Map Elements

Register map elements can be of three different types: Register, Register Array or Memory.

Register Object Attributes

The Register object has the following attributes:

Attribute	Description	Type	Required	Allowed Values
type	The register map element's type	string	yes	Register
name	The register's name	string	yes
description	The register's description	string	yes
access	The register's access mode	string	yes	READ_WRITE, READ_ONLY, WRITE_ONLY, INTERRUPT
addressOffset	The register's address offset	integer	yes
size	The register's width, in bits	integer	yes	32
fields	The register fields	array	yes

Register Array Object Attributes

The Register Array object has the following attributes:

Attribute	Description	Type	Required	Allowed Values
type	The register map element's type	string	yes	RegisterArray
arrayLength	The array length, in elements	integer	yes
name	The array's name	string	yes
description	The array's description	string	yes
access	The array's access mode	string	yes	READ_WRITE, READ_ONLY, WRITE_ONLY, INTERRUPT
addressOffset	The array's address offset	integer	yes
size	The array's width, in bits	integer	yes	32
fields	The array fields	array	yes

Memory Object Attributes

The Memory object has the following attributes:

Attribute	Description	Type	Required	Allowed Values
type	The register map element's type	string	yes	Memory
depth	The memory depth, in elements	integer	yes	[1 .. 1073741824]
readLatency	The memory read latency, in clock cycles	integer	yes	[1 .. 5]
name	The memory's name	string	yes
description	The memory's description	string	yes
access	The memory's access mode	string	yes	READ_WRITE, READ_ONLY, WRITE_ONLY
addressOffset	The memory's address offset	integer	yes
size	The memory's width, in bits	integer	yes	32
fields	The memory fields	array	yes

caution

Memories do not support the INTERRUPT access mode.

Field Object Attributes

The Field object has the following attributes:

Attribute	Description	Type	Required	Allowed Values
name	The field's name	string	yes
description	The field's description	string	yes
bitWidth	The field's width, in bits	integer	yes	[1 .. 32]
bitOffset	The field's bit offset	integer	yes	[0 .. 31]
reset	The field's reset value	integer	yes
selfClear	Whether the field is a self-clearing one	boolean	yes	true, false
enumValues	The field's enumerated values. Must be an array of objects with name and value properties, e.g.:	array	yes
volatile	Whether the field is a volatile one (only supported in registers or arrays with read-write access).	boolean	no	true, false

caution

Memories do not support self-clearing fields.