XML Descriptions

Register Maps

Node Attributes

Top-Level

<?xml version="1.0" encoding="ISO-8859-1"?>

<node id="REGISTERMAP_XML_NODENAME">
    <node id="FULL_RW_REGISTER"  address="0x0"  mask="0xFFFFFFFF" permission="rw" description="A 32 bit read/write register."/>
    <node id="MASKED_REGISTER"   address="0x4"  mask="0xFFFFF"    permission="rw" description="A masked, 20 bit, read/write register."/>
    <node id="FULL_RD_REGISTER"  address="0x8"  mask="0xFFFFFFFF" permission="r"  description="A 32 bit read-only register"/>
    <node id="FULL_WR_REGISTER"  address="0xc"  mask="0xFFFFFFFF" permission="w"  description="A 32 bit write-only register"/>
    <node id="BITFIELD_REGISTER" address="0x10" description="A bit-field register." >
        <node id="ONE_RW_BITFIELD"  mask="0x00000001" permission="rw" description="A single read/write bit in a bit-field register."/>
        <node id="ONE_RD_BITFIELD"  mask="0x00000002" permission="r"  description="A single read-only bit in a bit-field register."/>
        <node id="ONE_WR_BITFIELD"  mask="0x00000004" permission="w"  description="A single write-only bit in a bit-field register."/>
        <node id="ONE_RW_BYTEFIELD" mask="0x0000FF00" permission="rw" description="A single read/write byte in a bit-field register."/>
        <node id="ONE_RD_BYTEFIELD" mask="0x00FF0000" permission="r"  description="A single read-only byte in a bit-field register."/>
        <node id="ONE_WR_BYTEFIELD" mask="0xFF000000" permission="w"  description="A single write-only byte in a bit-field register."/>
    </node>
</node>

Attribute

Required

Possible Values

Notes

id

Yes

-

A string, MUST NOT be a VHDL keyword.

Entries

Attribute

Required

Possible Values

Notes

id

Yes

-

A string, MUST NOT be a VHDL keyword.

address

Yes

-

Hexadecimal string prefixed with “0x”. The address offset to apply to the Register Map entry. See Considerations.

mask

Yes

-

Hexadecimal string prefixed with “0x”. The bit mask to apply to the register. See Considerations.

array

No

1-N

(Optional), Integer value. Number of array elements to implement. Requires array_offset= to also be defined. See Considerations.

array_offset

No

-

Required when using array=. Hexadecimal string prefixed with “0x”. The address offset to apply to each array` entry. See Considerations.

hw_permission

No

[default]"no"|"w"|"we"

Controls the access permission from the Logic-side of the node, and child bit-field nodes. See Considerations.

permission

No

[default]"rw"|"r"|"w"

Controls the access permission from the Bus-side side of the node, and child bit-field nodes. See Considerations.

hw_reset

No

[default]"no"|"GENERIC_NAME"

Hexadecimal string representation of the reset value, prefixed with “0x”. When defining a VHDL generic it MUST NOT be a VHDL keyword. See Considerations.

hw_prio

No

[default]"logic"|"bus"

Controls the write priority between Logic-side and Bus-side when simultaneous writes occur in each of the write domains.

hw_ignore

No

[default]"no"|"yes"

When set to hw_ignore="yes", VHDL generation will be disabled for the current node, and child bit-field nodes. See Considerations.

size

No

[default]1, 1-N

Integer value. specifies the node size, in 32 bit words. See Considerations.

description

No

[default]""

A string. An optional description to be linked to the generated entry.
Register Nodes
<?xml version="1.0" encoding="ISO-8859-1"?>

<node id="REGISTERMAP_XML_NODENAME">
    <node id="FULL_RW_REGISTER"  address="0x0"  mask="0xFFFFFFFF" permission="rw" description="A 32 bit read/write register."/>
    <node id="MASKED_REGISTER"   address="0x4"  mask="0xFFFFF"    permission="rw" description="A masked, 20 bit, read/write register."/>
    <node id="FULL_RD_REGISTER"  address="0x8"  mask="0xFFFFFFFF" permission="r"  description="A 32 bit read-only register"/>
    <node id="FULL_WR_REGISTER"  address="0xc"  mask="0xFFFFFFFF" permission="w"  description="A 32 bit write-only register"/>
    <node id="BITFIELD_REGISTER" address="0x10" description="A bit-field register." >
        <node id="ONE_RW_BITFIELD"  mask="0x00000001" permission="rw" description="A single read/write bit in a bit-field register."/>
        <node id="ONE_RD_BITFIELD"  mask="0x00000002" permission="r"  description="A single read-only bit in a bit-field register."/>
        <node id="ONE_WR_BITFIELD"  mask="0x00000004" permission="w"  description="A single write-only bit in a bit-field register."/>
        <node id="ONE_RW_BYTEFIELD" mask="0x0000FF00" permission="rw" description="A single read/write byte in a bit-field register."/>
        <node id="ONE_RD_BYTEFIELD" mask="0x00FF0000" permission="r"  description="A single read-only byte in a bit-field register."/>
        <node id="ONE_WR_BYTEFIELD" mask="0xFF000000" permission="w"  description="A single write-only byte in a bit-field register."/>
    </node>
</node>
Register with child bit-field
<?xml version="1.0" encoding="ISO-8859-1"?>

<node id="REGISTERMAP_XML_NODENAME">
    <node id="FULL_RW_REGISTER"  address="0x0"  mask="0xFFFFFFFF" permission="rw" description="A 32 bit read/write register."/>
    <node id="MASKED_REGISTER"   address="0x4"  mask="0xFFFFF"    permission="rw" description="A masked, 20 bit, read/write register."/>
    <node id="FULL_RD_REGISTER"  address="0x8"  mask="0xFFFFFFFF" permission="r"  description="A 32 bit read-only register"/>
    <node id="FULL_WR_REGISTER"  address="0xc"  mask="0xFFFFFFFF" permission="w"  description="A 32 bit write-only register"/>
    <node id="BITFIELD_REGISTER" address="0x10" description="A bit-field register." >
        <node id="ONE_RW_BITFIELD"  mask="0x00000001" permission="rw" description="A single read/write bit in a bit-field register."/>
        <node id="ONE_RD_BITFIELD"  mask="0x00000002" permission="r"  description="A single read-only bit in a bit-field register."/>
        <node id="ONE_WR_BITFIELD"  mask="0x00000004" permission="w"  description="A single write-only bit in a bit-field register."/>
        <node id="ONE_RW_BYTEFIELD" mask="0x0000FF00" permission="rw" description="A single read/write byte in a bit-field register."/>
        <node id="ONE_RD_BYTEFIELD" mask="0x00FF0000" permission="r"  description="A single read-only byte in a bit-field register."/>
        <node id="ONE_WR_BYTEFIELD" mask="0xFF000000" permission="w"  description="A single write-only byte in a bit-field register."/>
    </node>
</node>

Considerations

  • hw_reset= values ARE NOT applied to register values as pre-initialised values. In order for these values to be applied to registers, the AXI4-Lite (or equivalent) interface needs to go through a reset assertion/de-assertion sequence. This MUST be managed separately in the end-user host design.

  • When describing child bit-field nodes, the hw_reset= hexadecimal string (or VHDL generic) can be defined using either the mask= or unmasked values.

  • In addition to hw_reset="no" or a hexadecimal string prefixed with “0x” being defined, it is possible to assign a string. In this case, XML2VHDL will create a corresponding VHDL generic, allowing the value to defined via a generic in the end-user host design.

  • Bit mask positions, defined using the mask= node attribute, MUST NOT overlap positions in any of its child bit-field nodes.

  • Setting the attribute hw_permission="w" will result in the user-side "logic" to continuously write into the register.

    Caution

    NEVER use hw_permission="w" with permission="w" or permission="rw" as this will prevent writes from AXI4-Lite (or equivalent), interface Bus-side, regardless of the hw_prio= attribute.

  • Setting the attribute hw_permission="we" will result in the Logic-side to only write into the register when the corresponding write enable signal is asserted.

  • Logic-side will always be able to read from registers, regardless of the hw_permission= attribute.

  • Setting the size= to a value greater than 1 implies the instantiation of an independent IPbus which can be connected to end-user managed components in the host design. This is an alternative to generating a dual-port RAM using the hw_dp_ram=”yes” and associated attributes. See Internal Memory.

    Caution

    Care should be taken to ensure the defined address offsets are calculated to taken into account the extra locations required when setting size= to a value greater than 1.

  • array= allows the node to be replicated N number of times. The underlying node structure will be duplicated, with each element having its address incremented by the value configured using the array_offset= attribute. Both attributes are required when using this feature.

    Caution

    Care should be taken to ensure the defined address offsets are calculated to taken into account the extra locations required when setting array= to a value greater than 1.

  • Nodes will always be included in the generated XML output files, regardless to the value of the hw_ignore= attribute.

Interconnects

Interconnect XML descriptions provide XML2VHDL a method to join other XML types together in order to describe the complete end-user system. It is this type which enables a hierarchical tree structure and promotes XML file reuse and interoperability between VHDL libraries.

Node Attributes

Top-Level

<?xml version="1.0" encoding="ISO-8859-1"?>

<node id="IC_XML_NODENAME"  address="0x0"  hw_type="ic">
    <node id="EXAMPLE_IC_0"   address="0x0000"  link="XML_FILENAME_memory_map_output.xml"/>
    <node id="EXAMPLE_IC_1"   address="0x8000"  link="XML_FILENAME_memory_map_output.xml"/>
    <node id="EXAMPLE_IC_2"   address="0xC000"  link="XML_FILENAME_memory_map_output.xml"/>
</node>

Attribute

Required

Possible Values

Notes

id

Yes

-

A string, MUST NOT be a VHDL keyword.

address

Yes

-

Hexadecimal string prefixed with “0x”. Additional address offset to apply to Interconnect. Usually: “0x0”.

hw_type

Yes

"ic"|“transparent_ic”

Attention

The top-level hw_type="transparent_ic” attribute creates a special type of Interconnect, which will be processed differently by XML2VHDL. This type of Interconnect will be ignored when XML2VHDL is generating the absolute_id= reference. This is useful when creating components and it it makes more sense to the resulting downstream address-space to be presented in a more monolithic fashion. See Generated Output.

Entries

<?xml version="1.0" encoding="ISO-8859-1"?>

<node id="IC_XML_NODENAME"  address="0x0"  hw_type="ic">
    <node id="EXAMPLE_IC_0"   address="0x0000"  link="XML_FILENAME_memory_map_output.xml"/>
    <node id="EXAMPLE_IC_1"   address="0x8000"  link="XML_FILENAME_memory_map_output.xml"/>
    <node id="EXAMPLE_IC_2"   address="0xC000"  link="XML_FILENAME_memory_map_output.xml"/>
</node>

Attribute

Required

Possible Values

Notes

id

Yes

-

A string, MUST NOT be a VHDL keyword. See Considerations.

address

Yes

-

Hexadecimal string prefixed with “0x”. Additional address offset to apply to the Interconnect top-level node address attribute. See Considerations.

link

Yes

-

A string, XML2VHDL XML output filename. See Considerations.

Considerations

The following points should be considered when implementing a Interconnect:

  • The Interconnect node entry id=IC_INDEX_NAME will result in a reference named id_IC_INDEX_NAME, which can be used in the resulting VHDL to index the AXI4-Lite (or equivalent) VHDL array, via the XML_LINKED_LIB.axi4lite_IC_XML_NODENAME_mmap_pkg file:

    axi4lite_mmap_get_id(XML_LINKED_LIB.axi4lite_IC_XML_NODENAME_mmap_pkg.id_IC_INDEX_NAME)

  • Interconnect node descriptions are defined an address-space offset using the address= node attribute.

    Attention

    It is the responsibility of the end-user to ensure the offsets within a Interconnect XML description are able to contain the address-space of all of linked descriptions downstream of the node.

  • Interconnect node descriptions are required to the linked to the downstream connections using the link= node attribute. This attribute needs to reference the corresponding XML output file generated by XML2VHDL.

    The referenced link= file needs to be in the location provided by the --relative_output_path argument. XML2VHDL generates resulting output files using a bottom to top approach. Therefore, this file does not to exist before XML2VHDL is executed, However, it is expected that:

    • XML2VHDL will generate the referenced XML output file; or

    • A previous XML2VHDL generated XML output file already exists in the --relative_output_path location.

      Caution

      If relying on this option, care should be taken that:

      • any pre-generated files are added to source-code version management; and

      • these files are not inadvertently overwritten when re-generating XML2VHDL output.

  • Interconnect node descriptions can link to any XML2VHDL description type, but NEVER itself.

  • Interconnect node descriptions are assigned a zero-indexed numerical ID reference in the order which they are assigned in the XML description.

    The preferred method to access the resulting VHDL record array is to use the provided VHDL function from the corresponding XML_LINKED_LIB.axi4lite_IC_XML_NODENAME_mmap_pkg file:

    axi4lite_mmap_get_id(XML_LINKED_LIB.axi4lite_IC_XML_NODENAME_mmap_pkg.id_EXAMPLE_IC_0)

    Tip

    Sometimes the end-user may want to determine Interconnect node ID values within a VHDL generate statement. Leveraging the behaviour of ID reference assignment it is possible to bypass the axi4lite_mmap_get_id method and use VHDL generate indexes directly.

    Caution

    Care should be taken when referencing array ID assignments directly, as modifying the Interconnect node assignments by adding or removing entries or changing the existing order, MAY have a knock-on effect to current VHDL assignments in the end-user host design.

Internal Memory

Attention

In XML2VHDL terms, internal memory refers to FPGA dual-port RAM which is generated by XML2VHDL with one side connected to the Bus-side interface. It is required for the end-user to connect the Logic-side manually to the host design.

Internal FPGA dual-port RAM can be implemented. This is useful when creating contiguous addressable locations like Look-Up Tables.

Node Attributes

Attribute

Required

Possible Values

Notes

id

Yes

-

A string, MUST NOT be a VHDL keyword.

address

Yes

-

Hexadecimal string prefixed with “0x”. The address offset to apply to the internal memory entry.

mask

Yes

-

Hexadecimal string prefixed with “0x”. The bit mask to apply to the register. See Considerations.

hw_dp_ram

Yes

"yes"

See Considerations.

hw_dp_ram_bus_lat

No

[default]"1"|"2"

Bus-side read latency of instantiated dual-port RAM.

hw_dp_ram_init_file

No

[default]""

A string. Memory initialisation file, to be applied to the dual-port RAM.

hw_dp_ram_init_file_check

No

[default]"yes"|"no"

Check if the referenced hw_dp_ram_init_file= file exists.

hw_dp_ram_init_file_format

No

[default]"hex"|"bin"

File format of te referenced hw_dp_ram_init_file= file. Supported binary (“bin”`) or hexadecimal ("hex").

hw_dp_ram_logic_lat

No

[default]"1"|"2"

Logic-side read latency of instantiated dual-port RAM.

hw_dp_ram_width

No

[default]1, 1-32

Data width of the dual-port RAM.

description

No

[default]""

A string. An optional description to be linked to the generated entry.

Considerations

  • When setting the node attribute hw_dp_ram="yes", XML2VHDL will instantiate a dual-port RAM using the related IPbus interface to connect to end-user logic in the host design.

External Memory

Attention

In XML2VHDL terms, external memory refers to memory which is addressable within the generated by XML2VHDL address-map. However, it is expected for the end-user to provide the logic to connect the memory to the Bus-side interface in addition to connecting the Logic-side manually to the host design.

Node Attributes

Attribute

Required

Possible Values

Notes

id

Yes

-

A string, MUST NOT be a VHDL keyword.

address

Yes

-

Hexadecimal string prefixed with “0x”. The address offset to apply to the external memory entry.

mask

Yes

-

Hexadecimal string prefixed with “0x”. The bit mask to apply to the register. See Considerations.

hw_dp_ram

Yes

"no"

See Considerations.

hw_dp_ram_width

No

[default]1, 1-32

Data width of the dual-port RAM.

description

No

[default]""

A string. An optional description to be linked to the generated entry.

Considerations

  • External memory usage is implied by setting the hw_dp_ram="no". XML2VHDL will generate IPbus based ports to allow the external memory to be interfaced to the Bus-side in the end-user host design.

  • External memory CAN NOT be read from the Bus-side of XML2VHDL, even if this implied by the permission= attribute for the node. They can ONLY be written to from the Bus-side.

Caution

Extra care should be taken to ensure the assigned address-space allow for the external memory to be fully addressable in the resulting XML2VHDL generated output.

Generated Output

The XML output file(s) have the following node attributes.

Attribute

Notes

id

A string, the original id= node attribute value of the XML input file description.

address

Hexadecimal string prefixed with “0x”. The original address= node attribute value of the XML input file description.

mask

Hexadecimal string prefixed with “0x”. The original mask= node attribute value of the XML input file description.

hw_type

Only included if the input node was an Interconnect.

byte_size

The total size, in Bytes, of child-nodes below.

size

The size= node attribute value of the XML input file description, even if it was not defined in the source file (default: size="1")

link_done

Only included if the input node was an Interconnect. The name of the XML output file used as the “linked” downstream reference.

absolute_id

See Considerations.

absolute_offset

The absolute address offset for each memory-mapped location generated by XML2VHDL. See Considerations.

Considerations

  • The absolute_id= attribute value, is generated using three-levels of hierarchy, with the id= attribute value from each level being separated using . notation.

    Note

    In order to consistently maintain three-levels, if the number of levels increases beyond three, id= attribute values of the previously processed first-level and second-level are merged replacing . with _ to create a new first-level absolute_id= attribute value.

  • The calculated absolute_offset= value is a hexadecimal value, but DOES NOT include the “0x” string prefix.