#################
File Descriptions
#################

.. _relationships:

Relationships
#############

This section describes the relationship between :term:`XML` input file descriptions
and the resulting `XML2VHDL` output.

+---------------------------+------------------------------+-------------------------------+--------------------------------+------------------------------------------------------+---------------------------------------------------------------------------------+
| Type                      | :term:`XML` Input File Name  | Node Name                     | Generated :term:`XML` Filename | Generated :term:`VHDL` Filenames                     | Example                                                                         |
+===========================+==============================+===============================+================================+======================================================+=================================================================================+
| Register Map Description  | * ``XML_FILENAME.xml``       | ``REGISTERMAP_XML_NODENAME``  | ``XML_FILENAME_output.xml``    | * ``axi4lite_REGISTERMAP_XML_NODENAME.vhd``          | .. code-block:: xml                                                             |
|                           |                              |                               |                                | * ``axi4lite_REGISTERMAP_XML_NODENAME_muxdemux.vhd`` |                                                                                 |
|                           |                              |                               |                                | * ``axi4lite_REGISTERMAP_XML_NODENAME_pkg.vhd``      |    <node id="REGISTERMAP_XML_NODENAME"    address="0x0">                        |
|                           |                              |                               |                                |                                                      |    </node>                                                                      |
+---------------------------+------------------------------+-------------------------------+--------------------------------+------------------------------------------------------+---------------------------------------------------------------------------------+
| Interconnect Description  | * ``XML_FILENAME.xml``       | ``IC_XML_NODENAME``           | ``XML_FILENAME_output.xml``    | * ``axi4lite_IC_XML_NODENAME.vhd``                   | .. code-block:: xml                                                             |
|                           | * ``IC_INDEX_NAME``          |                               |                                | * ``axi4lite_IC_XML_NODENAME_pkg.vhd``               |                                                                                 |
|                           |                              |                               |                                | * ``axi4lite_IC_XML_NODENAME_mmap_pkg.vhd``          |    <node id="IC_XML_NODENAME"    address="0x0"    hw_type="ic">                 |
|                           |                              |                               |                                |                                                      |      node id="IC_INDEX_NAME" address="0x0000" link="XML_FILENAME_output.xml"/>  |
|                           |                              |                               |                                |                                                      |    </node>                                                                      |
|                           |                              |                               |                                |                                                      |                                                                                 |
+---------------------------+------------------------------+-------------------------------+--------------------------------+------------------------------------------------------+---------------------------------------------------------------------------------+

.. tip::
   It is recommended to include the description type in the :term:`XML` filename.
   for example by adding the following suffixes to the :term:`XML` input
   filename:
   
   * ``XML_FILENAME_memory_map.xml``
   * ``XML_FILENAME_ic_memory_map.xml``

Input
#####

`XML2VHDL` depends on the following input files. 

See :ref:`xml_descriptions` for a details of the term:`XML` input file structure.

============================= ============================================================== 
 **Input file(s) location:**   Referenced using the `XML2VHDL` ``--input_folder`` argument.
============================= ==============================================================

Output
######

============================== ====================================================================== 
 **Output file(s) location:**   Referenced using the `XML2VHDL` ``--relative_output_path`` argument.
============================== ======================================================================

In addition to the generated :term:`XML` and :term:`VHDL` output files (see :ref:`relationships`).
The following files are also generated:

+--------------------------+-------------------------------------------------------------------------+
| File Type                |                                                                         |
+==========================+=========================================================================+
| :term:`XML` files        | See :ref:`relationships`.                                               |
+--------------------------+-------------------------------------------------------------------------+
| :term:`VHDL` files       | See :ref:`relationships` and :ref:`library_components`.                 |
+--------------------------+-------------------------------------------------------------------------+
| :term:`Test-Bench` files | :term:`Simulation` :term:`Test-Bench` files. Used to aid in interacting |
|                          | with the memory-map registers in hardware simulations by providing      |
|                          | common functions, procedures and address constants of the generated     |
|                          | registers using their :term:`XML` node ``id=`` attribute. The files     |
|                          | have the naming convention: ``REGISTERMAP_XML_NODENAME_tb_pkg.vhd`` or  |
|                          | ``IC_XML_NODENAME_tb_pkg.vhd``.                                         |
+--------------------------+-------------------------------------------------------------------------+
| :term:`HTML` and         | These files are used together to automatically generate the             |
| :term:`CSS` files        | register tables of the memory-maps showing their address locations and  |
|                          | their specifications. The tables are used for legacy documentation      |
|                          | providing the end-user a more visual and readable description of the    |
|                          | generated output.                                                       |
+--------------------------+-------------------------------------------------------------------------+
| Other files              | * ``.hex``. A compressed :term:`XML` output file of the top-level, in   |
|                          |   hexadecimal form. This can used used to initialise a :term:`BRAM`.    |
|                          | * ``.vho``. A :term:`VHDL` template file.                               |
+--------------------------+-------------------------------------------------------------------------+