#################################
External Memory-Mapped Components
#################################

An important feature of `XML2VHDL` is the ability to link external memory-mapped
components into the shared generated memory-mapped architecture as a device
using the :term:`XML` register descriptions.

An example use-case is integrating the :term:`Xilinx` System Management Wizard
:term:`IP` (refer to :ref:`links`). This is a useful component, as it provides
temperature and voltage monitoring of the :term:`FPGA`.

.. literalinclude:: /example_code/pg185_xml_snippet.xml
   :language: xml

The :term:`XML` `Register Map` description in the code above describes registers
within the :term:`Xilinx` System Management Wizard :term:`IP`.
This file needs to be manually created, with the names and descriptions obtained from
the :term:`Xilinx` :term:`IP` Product Guide (PG185). Mapping all the registers of
this :term:`IP` into a `XML2VHDL` description allows any associated monitoring and
control software to reference these locations and child bit-fields in a
consistent manner. This ensures their underlying meaning can be derived by name, instead
of the end-suer having to cross-reference address locations and decode bit-field values
from registers manually.

.. attention::
   It should be noted that this :term:`XML` `Register Map` top-level node uses the
   attribute ``hw_ignore="yes"``. This this will disable the generation of
   :term:`VHDL` output files for the current description. These are **NOT**
   required as the :term:`Xilinx` :term:`IP` already provides an :term:`AXI4-Lite`
   interface to connect to the `Logic-side` of the generated `XML2VHDL` output.


Linking to an Interconnect
==========================

The next step is to link the generated :term:`XML` output to a parent `Interconnect`
(in the example, the ``id="sys_mon"`` of the ``IC_XML_NODENAME`` `Interconnect`),
as shown below. ``IC_XML_NODENAME`` can also be used to link any other external
memory-mapped components.

.. tip::
   It is recommended to connect external memory-mapped components via an `Interconnect`
   positioned at the end-user host design top-level in order to simplify 
   connectivity throughout the design.

.. literalinclude:: /example_code/pg185_ic_xml_snippet.xml
   :language: xml

Connecting to Logic-side
========================

The final step is to instantiate and connect the System Management :term:`IP`
to the end-user host design. This needs to be done using a custom :term:`VHDL`
wrapper file, used to expand the :term:`AXI4-Lite` interface :term:`VHDL` Recordings
types and to connect them to the corresponding signals presented by the
:term:`AXI4-Lite` interface on the :term:`Xilinx` :term:`IP`. A non-functional
example :term:`VHDL` wrapper template is shown below.

.. literalinclude:: /example_code/external_mmap_expansion.vhd
   :language: vhdl

The example :term:`VHDL` below demonstrates the final instantiation of the
external memory-mapped component with the `XML2VHDL` generated :term:`VHDL`
`Interconnect` which is used to decode the absolute addresses of the target
address-space.

.. literalinclude:: /example_code/pg185_inst_snippet.vhd
   :language: vhdl