.. role:: raw-html(raw)
   :format: html

.. _nomenclature:

############
Nomenclature
############

To ensure consistency through-out this documentation, the following naming convention
is used to describe the relationship between the :term:`XML` descriptions and
the generated :term:`XML` and :term:`VHDL` output.

+---------------------+---------------------------------------------------------------------------------------------------------+
| Convention          |                                                                                                         |
+=====================+=========================================================================================================+
| ``attr=``           | Reference to a node attribute, Where ``attr`` is substituted with the actual name of the attribute.     |
+---------------------+---------------------------------------------------------------------------------------------------------+
| ``attr="<value>"``  | Provides an example with node attribute value set. ``<value>`` is substituted with the example's value. |
+---------------------+---------------------------------------------------------------------------------------------------------+
| BUS_LINK_LIB        | This "linked" library is an external library which provides the :term:`VHDL` definitions and resources  |
|                     | required by the chosen `Bus-side` interface. See :ref:`vhdl_libraries`.                                 |
+---------------------+---------------------------------------------------------------------------------------------------------+
| UPPERCASE words     | Indicate user-substitution for:                                                                         |
|                     |                                                                                                         |
|                     |  * :term:`XML` input filenames;                                                                         |
|                     |  * :term:`XML` node names; *and*                                                                        |
|                     |  * :term:`XML` node attribute values.                                                                   |
|                     |                                                                                                         |
|                     | and the relationship to these UPPERCASE word substitutions in the resulting:                            |
|                     |                                                                                                         |
|                     |  * :term:`XML` output filenames;                                                                        |
|                     |  * :term:`VHDL` filenames;                                                                              |
|                     |  * :term:`VHDL` component names;                                                                        |
|                     |  * :term:`VHDL` package files;                                                                          |
|                     |  * ID references for :term:`VHDL` signal array indexes; *and*                                           |
|                     |  * Expandible :term:`VHDL` records to target register and bit-field entries.                            |
+---------------------+---------------------------------------------------------------------------------------------------------+
| XML_LINK_LIB        | This "linked" library is used to reference the generated :term:`VHDL` in the end-user host design.      |
|                     | See :ref:`vhdl_libraries`.                                                                              |
+---------------------+---------------------------------------------------------------------------------------------------------+

Active-low signals
==================

Active-low signals, which may be defined in referenced materials with a line above
the signal name, are suffixed with a lowercase *n* throughout this document.

Concepts
########

Node types
==========

+-------------------------------+--------------------------------------------------------------------------------------------+
| Type                          |                                                                                            |
+-------------------------------+--------------------------------------------------------------------------------------------+
| Register                      | A register description, of up-to 32 bits. See :ref:`rmaps`.                                |
+-------------------------------+--------------------------------------------------------------------------------------------+
| Register with child bit-field | A register description, of up-to 32 bits, which has additional bit-field descriptions.     |
|                               | See :ref:`rmaps`.                                                                          |
+-------------------------------+--------------------------------------------------------------------------------------------+
| Interconnect                  | An `Interconnect (IC)` describes how to join other `registers` and `interconnects`.        |
|                               | See :ref:`ics`.                                                                            |
+-------------------------------+--------------------------------------------------------------------------------------------+
| Internal Memory               | A register description with attributes to describe connections to dual-port :term:`FPGA`   |
|                               | :term:`RAM`\ s. See :ref:`internal_memories`.                                              |
+-------------------------------+--------------------------------------------------------------------------------------------+
| External Memory               | See :ref:`external_memories`.                                                              |
+-------------------------------+--------------------------------------------------------------------------------------------+

Sides
=====

`XML2VHDL` is built around the connectivity from two interfaces. This results in the
concept of sides:

#. `Bus-side`. Operations which happen on the :term:`AXI4-Lite` (or equivalent) interface.
   These are configured using the ``permission=`` node attribute; *and*
#. `Logic-side` or `Hardware-side`. Operations which happen in connected user-logic,
   and are connected to components in the host design. These are configured using 
   the ``hw_permission=`` and/or ``hw_reset=`` node attributes.

Host design
===========

Host design, refers to the end-user design, to which the `XML2VHDL` generated output
is being integrated.

.. _vhdl_libraries:

VHDL libraries
##############

Bus Library
===========

When generating :term:`VHDL` from the :term:`XML` descriptions, `XML2VHDL` expects the output :term:`VHDL`
to be linked to a library. This is done using the ``--bus_library`` argument.

.. important::
   This is an external library and |NOT| currently distributed with `XML2VHDL`.
   For :term:`AXI4-Lite` the following (or equivalent) can be used:

   * |dl_axi4lite_pkg|.
   * |dl_slave_logic|.

XML Linked Library
==================

When generating :term:`VHDL` from the :term:`XML` descriptions, `XML2VHDL` expects the output :term:`VHDL`
to be linked to a library. This is done using the ``--slave_library`` argument.

.. caution::
   As :term:`VHDL` output can be "linked" to libraries at generation time, care should be taken 
   to include the correct generated output files in the end-user host design.
 
Linking
=======

The :term:`VHDL` libraries are required to be linked at `XML2VHDL` generation time by
providing each via arguments to `XML2VHDL`:

.. code-block:: bash

    xml2vhdl --bus_library "BUS_LINKED_LIB" --slave_library "XML_LINKED_LIB"