###################
Memories and Arrays
###################

This section uses the :term:`SKAO` `Tile Beamformer` module as an example. This is a part of
the Signal Processing System and is responsible for combining channelised signals
from 8 antennas into a single phased beam. The `Tile Beamformer` utilises memory
to store and reorder the input channelized data frames, providing the spectral
regions into the Beamformer. The `XML2VHDL` :term:`XML` `Register Map` description
is shown below. 

External Memory
###############

.. literalinclude:: /example_code/beamformer_memory_map.xml
   :language: xml
   :emphasize-lines: 22-24

The `Tile Beamformer` requires three `external memories` providing
storage for the following data: ``region_off``, ``beam_index``, *and* ``region_sel``.

It can be seen that each of these nodes has the following attributes set:

* ``size="16"``: By setting this attribute to a value greater than `1` this node
  will be attached to a dual-port :term:`RAM`. By default `XML2VHDL` will generate
  its own instance (see :ref:`internal_memories`). To use `external memory`, instead
  of the default `internal memory`, can be forced by also setting:

* ``hw_dp_ram="no"``. By setting this attribute to ``"no"``, `XML2VHDL` will
  generate an independent :term:`IPbus` interface, which the end-user is expected
  to connect to an `external memory` component (see :ref:`external_memories`).
  This component **MUST BE** supplied and managed outside of `XML2VHDL`.
   
External Memory Wrapper
=======================

.. literalinclude:: /example_code/beamformer_wrapper.vhd
   :language: vhdl
   :start-after: -- docstart1
   :end-before: -- docend1

The code above shows a snippet of the :term:`VHDL` wrapper file for the
`Tile Beamformer` module used to instantiate and link the generated `XML2VHDL`
output with the end-user host design.

* ``axi4lite_beamformer_fd_inst``: The generated :term:`VHDL`. In addition
  to the usual :term:`AXI4-Lite` interface, and the expected ``axi4lite_beamformer_fd_*``
  record structures (see :ref:`rmap_hw_impl`). There are also additional 
  :term:`IPbus` interfaces named ``ipb_beamformer_fd_*``. These result from the
  :term:`XML` node ``size=`` attribute being set to a value greater than 1. One
  :term:`IPbus` interface is created for two of the three `external memories`
  described above. Using these interfaces, this generated :term:`VHDL` component
  is connected to:

* ``ces_beamformer_table_bank_inst``: The :term:`VHDL` wrapper file, containing 
  each of the three `external memories`` and associated logic to write to them. 
  This allows the each `external memory` to be targeted in the address
  region configured in the original :term:`XML` description.


.. literalinclude:: /example_code/beamformer_wrapper.vhd
   :language: vhdl
   :start-after: -- docstart2
   :end-before: -- docend2

The remaining ``"region_sel"`` `external_memory` connects to a ``common_ram_sdp``
component. This is a distributed single-port :term:`RAM`, created using a :term:`Vivado`
instantiation template. The :term:`VHDL` code snippet above shows how the :term:`IPbus`
record interface can be expanded to connect to ports on the ``common_ram_sdp``.

This end-user created `external memory` does not have a read acknowledge, instead
it has a write acknowledge which is implemented through the statement:

.. code-block:: vhdl
   
   ipb_beamformer_fd_region_sel_miso_o.wack <= '1';

The expanded signals are used to write into the ``common_ram_sdp`` memory.
This is a single-port memory, write is connected to the `Bus-side` :term:`AXI4-Lite`
and read is connected to downstream `Logic-side` which are read during normal
operation of the `Tile Beamformer`.

.. caution::
   It is not possible to read from the :term:`AXI4-Lite` interface, due to no 
   read side connectivity on the `Bus-side`. For this reason, if a software
   attempts a read access via the :term:`AXI4-Lite` `Bus-side` interface,
   there **WILL NOT** be a corresponding read acknowledge, causing the read
   transaction to fail, resulting in an error.

   It is the responsibility of the :term:`Software` to prevent reads to avoid
   this error condition.

.. include:: ./arrays.rst
.. include:: ./internal_and_external_memories.rst