################
Development Flow
################

Generally, the end-user will develop and define the host design memory-map using
a bottom-to-top approach. It is expected that larger designs will leverage pre-defined
`XML2VHDL` descriptions for reusable components with the potential to integrate
memory-mapped :term:`FPGA` vendor :term:`IP` into the final design.

#. The end-user defines :term:`XML` `Register Maps` for each element [module] in the 
   host design. If required, these design elements may require the definition
   of `Interconnects` to logically group `Register Maps` by function (i.e. 
   separating status and control registers).

   .. tip::
      The calculated total address-space can be checked using the ``byte_size=``
      node attribute in the generated :term:`XML` output file for each `Register Map`
      description. This can be used to determine address-offset values in `Interconnect`
      descriptions.

#. Process the :term:`XML` input files using `XML2VHDL`, ensuring the output
   :term:`VHDL` is associated with the correct :term:`VHDL` libraries (via
   the ``--bus_library``\|\ ``--slave_library`` arguments).
#. The end-user is required to **manually** integrate the resulting :term:`VHDL`
   into the host design, by making `Bus-side` connections between `Interconnects`
   and other `Interconnects` and/or `Register Maps`. The end-user also needs
   to expand and connect to/from `Register Maps` on the `Logic-side` as required.
#. Repeat steps 1-3 as necessary.
#. Add the selected ``BUS_LINKED_LIB`` :term:`VHDL` support package(s) and components
   to the :term:`FPGA`:term:`Firmware` project.

   For :term:`AXI4-Lite` these will be the equivalent of [``axi4_lib``]
   |dl_axi4lite_pkg| and |dl_slave_logic| 

#. Add the generated :term:`VHDL` components and package files to the :term:`FPGA` 
   :term:`Firmware` project.

   .. attention::
      Ensure these files are assigned to the correct :term:`VHDL` libraries.

#. Once all of the generated :term:`VHDL` components and support packages have 
   been added to the :term:`FPGA` :term:`Firmware` project, it can be compiled
   to generate the :term:`Bitstream` file.
#. *Optional*. Assuming the target :term:`FPGA` :term:`Hardware` and associated
   control-plane :term:`Software` has a mechanism to retrieve and extract the 
   contents. It is possible to embed `XML2VHDL`:term:`HEX` file of the top-level
   description into a :term:`FPGA` :term:`BRAM` (or equivalent). This allows the
   :term:`FPGA` to self-describe its own address-space.

   In this case, it is the responsibility of the software to retrieve, and extract,
   this address-space description. The software can then determine what features
   to support on the target :term:`Hardware`. The physical addresses remain 
   transparent to the software, with registers/register child bit-fields being
   referenced by name instead.
   
   .. note::
      The advantage of having a transparent physical address is that it improves
      development, making it more flexible and less error prone.

Generation Methods
##################

Various methods for managing the generation of `XML2VHDL` memory-maps are possible.

* Directly, via the Command Line Interface.
* `Linux` `BASH` scripts.
* Scripted :term:`FPGA` build - including using pre-synthesis hooks.
* Scripted, called during `Continuous Integration` work-flows.
* Using project specific GUI tools.

.. attention::
   To ensure the most recent versions of address-spaces are generated, it is recommended
   to automate the generation of `XML2VHDL` output prior to compiling the :term:`FPGA`
   :term:`Firmware` project.

Software Support
################

.. tip::
   In parallel to the :term:`FPGA` :term:`Firmware` development, it is recommended
   the end-user, using the `XML2VHDL` generated :term:`XML` output file(s),
   develops the software framework to provide the required interactions with
   the :term:`FPGA` :term:`Firmware`.