.. _module_hard_fifo:

Module hard_fifo
================

This document contains technical documentation for the ``hard_fifo`` module.
To browse the source code, please visit the `repository on GitHub <https://github.com/hdl-modules/hdl-modules/tree/main/modules/hard_fifo>`__.

This module contains wrappers around the hard FIFO primitives in the Xilinx Ultrascale+ series
of devices.
Since the code depends on Xilinx primitives, the ``unisim`` library must be compiled and available
in order to simulate this module.
If this is not possible/desirable in your environment, the module can be excluded with the
``names_avoid`` argument to :py:func:`tsfpga.module.get_modules` if you are using tsfpga.
Using the Vivado simulation libraries can easily be enabled in tsfpga though, by following the
guide at :ref:`tsfpga:vivado_simlib`.





.. _hard_fifo.asynchronous_hard_fifo:

asynchronous_hard_fifo.vhd
--------------------------

`View source code on GitHub <https://github.com/hdl-modules/hdl-modules/tree/main/modules/hard_fifo/src/asynchronous_hard_fifo.vhd>`__.

.. symbolator::

  component asynchronous_hard_fifo is
    generic (
      data_width : positive;
      enable_output_register : boolean;
      primitive_type : fifo_primitive_t
    );
    port (
      clk_read : in std_ulogic;
      read_ready : in std_ulogic;
      read_valid : out std_ulogic;
      read_data : out std_ulogic_vector;
      --# {{}}
      clk_write : in std_ulogic;
      write_ready : out std_ulogic;
      write_valid : in std_ulogic;
      write_data : in std_ulogic_vector
    );
  end component;

Asynchronous (two clocks) First In First Out (FIFO) data buffering stage with AXI-Stream-like
handshaking interface. This is a wrapper around the Xilinx hard FIFO primitive, and can only
be used in certain devices.



.. _hard_fifo.asynchronous_hard_fifo.resource_utilization:

Resource utilization
____________________

This entity has `netlist builds <https://tsfpga.com/netlist_build.html>`__ set up with
`automatic size checkers <https://tsfpga.com/netlist_build.html#build-result-checkers>`__
in `module_hard_fifo.py <https://github.com/hdl-modules/hdl-modules/tree/main/modules/hard_fifo/module_hard_fifo.py>`__.
The following table lists the resource utilization for the entity, depending on
generic configuration.

.. list-table:: Resource utilization for **asynchronous_hard_fifo** netlist builds.
  :header-rows: 1

  * - Generics
    - Total LUTs
    - FFs
    - RAMB36
    - Maximum logic level
  * - data_width = 18

      enable_output_register = False
    - 3
    - 1
    - 1
    - 2
  * - data_width = 32

      enable_output_register = True
    - 3
    - 1
    - 1
    - 2


.. _hard_fifo.fifo36e2_wrapper:

fifo36e2_wrapper.vhd
--------------------

`View source code on GitHub <https://github.com/hdl-modules/hdl-modules/tree/main/modules/hard_fifo/src/fifo36e2_wrapper.vhd>`__.

.. symbolator::

  component fifo36e2_wrapper is
    generic (
      data_width : positive;
      is_asynchronous : boolean;
      enable_output_register : boolean
    );
    port (
      clk_read : in std_ulogic;
      read_ready : in std_ulogic;
      read_valid : out std_ulogic;
      read_data : out std_ulogic_vector;
      --# {{}}
      clk_write : in std_ulogic;
      write_ready : out std_ulogic;
      write_valid : in std_ulogic;
      write_data : in std_ulogic_vector
    );
  end component;

Wrapper around the Xilinx UltraScale+ FIFO36E2 primitive, with convenient AXI-Stream-like
interface.

.. note::
  The ``almost_full`` / ``almost_empty`` signals from the FIFO seem to work well. They are not
  routed out at the moment since they do not have a simulation test case.

.. warning::
  The ``level`` signal from the FIFO is not routed either.
  This is because there appears to be glitches in the read/write count signals:

  .. image:: fifo_glitches.png

  Hopefully this is only an issue with the ``unisim`` simulation model, and works
  correctly in the hardware.




.. _hard_fifo.hard_fifo:

hard_fifo.vhd
-------------

`View source code on GitHub <https://github.com/hdl-modules/hdl-modules/tree/main/modules/hard_fifo/src/hard_fifo.vhd>`__.

.. symbolator::

  component hard_fifo is
    generic (
      data_width : positive;
      enable_output_register : boolean;
      primitive_type : fifo_primitive_t
    );
    port (
      clk : in std_ulogic;
      --# {{}}
      read_ready : in std_ulogic;
      read_valid : out std_ulogic;
      read_data : out std_ulogic_vector;
      --# {{}}
      write_ready : out std_ulogic;
      write_valid : in std_ulogic;
      write_data : in std_ulogic_vector
    );
  end component;

Synchronous (one clock) First In First Out (FIFO) data buffering stage with AXI-Stream-like
handshaking interface. This is a wrapper around the Xilinx hard FIFO primitive, and can only
be used in certain devices.



.. _hard_fifo.hard_fifo.resource_utilization:

Resource utilization
____________________

This entity has `netlist builds <https://tsfpga.com/netlist_build.html>`__ set up with
`automatic size checkers <https://tsfpga.com/netlist_build.html#build-result-checkers>`__
in `module_hard_fifo.py <https://github.com/hdl-modules/hdl-modules/tree/main/modules/hard_fifo/module_hard_fifo.py>`__.
The following table lists the resource utilization for the entity, depending on
generic configuration.

.. list-table:: Resource utilization for **hard_fifo** netlist builds.
  :header-rows: 1

  * - Generics
    - Total LUTs
    - FFs
    - RAMB36
    - Maximum logic level
  * - data_width = 18

      enable_output_register = False
    - 3
    - 1
    - 1
    - 2
  * - data_width = 32

      enable_output_register = True
    - 3
    - 1
    - 1
    - 2


.. _hard_fifo.hard_fifo_pkg:

hard_fifo_pkg.vhd
-----------------

`View source code on GitHub <https://github.com/hdl-modules/hdl-modules/tree/main/modules/hard_fifo/src/hard_fifo_pkg.vhd>`__.



Package with functions for the hard FIFO wrappers.