Top-Level RTL Entity
====================

This page documents the top-level VHDL entity for Simple-Kria-Kv260-Example.
Source: :repo:`firmware/targets/SimpleKriaKv260Example/hdl/SimpleKriaKv260Example.vhd`.


Entity surface
--------------

The entity ``SimpleKriaKv260Example`` has the following generics and ports:

.. list-table:: Generics
   :header-rows: 1
   :widths: 30 20 50

   * - Generic
     - Type
     - Description
   * - ``TPD_G``
     - ``time``
     - Simulation propagation delay (default: ``1 ns``)
   * - ``BUILD_INFO_G``
     - ``BuildInfoType``
     - Build-time metadata injected by the ruckus build system

.. list-table:: Ports
   :header-rows: 1
   :widths: 30 20 50

   * - Port
     - Direction
     - Description
   * - ``pmod``
     - ``inout slv(7 downto 0)``
     - Kria K26 PMOD I/O pins (bidirectional, driven by HDA I/O block)
   * - ``fanEnableL``
     - ``out sl``
     - Active-low fan enable (driven by PMU interface in ``AxiSocUltraPlusCore``)
   * - ``vPIn``
     - ``in sl``
     - SYSMON positive analog input
   * - ``vNIn``
     - ``in sl``
     - SYSMON negative analog input


Instantiated blocks
-------------------

.. list-table::
   :header-rows: 1
   :widths: 25 75

   * - Instance
     - Description
   * - ``U_XVC_PLL`` (``surf.ClockManagerUltraScale``)
     - Derives ``xvcClk156`` (156.25 MHz) from ``axilClk`` (100 MHz) via an
       MMCM. Used by the XVC debug module.
   * - ``U_Core`` (``axi_soc_ultra_plus_core.AxiSocUltraPlusCore``)
     - Platform core: PS-PL AXI-Lite bridge, DMA engine (``DMA_SIZE_C = 2``
       lanes), SysMon, fan control, and build-info register bank. Produces
       ``axilClk`` (100 MHz), ``axilRst``, ``dmaClk`` (250 MHz), ``dmaRst``.
   * - ``U_App`` (``work.Application``)
     - Application logic: PRBS TX/RX loopback and HDA I/O. Receives AXI-Lite
       at ``AXIL_BASE_ADDR_G = APP_ADDR_OFFSET_C`` and DMA lane 0 streams.
   * - ``U_XVC`` (``surf.DmaXvcWrapper``)
     - Xilinx Virtual Cable debug bridge. Connects DMA lane 1 to the XVC
       protocol handler running at ``xvcClk156`` (156.25 MHz).

No ADC/DAC converter block is instantiated in this design (no DSP path).


Clock domain
------------

This design uses two primary functional clock domains sourced from
``AxiSocUltraPlusCore``:

- ``axilClk`` (100 MHz) — AXI-Lite register access. Drives the ``Application``
  AXI-Lite slave ports and the ``AxiSocCore`` register interface.
- ``dmaClk`` (250 MHz) — DMA engine and application datapath. Drives the
  ``Application`` internal crossbar (after the ``AxiLiteAsync`` bridge) and the
  ``SsiPrbsTx``/``SsiPrbsRx`` cores.

A third derived clock ``xvcClk156`` (156.25 MHz) is generated by ``U_XVC_PLL``
solely for the XVC debug module.

No separate DSP or ADC clock is present in this design — only the AXI-Lite
and DMA clock domains from ``AxiSocUltraPlusCore`` are used.


Async clock groups (XDC)
------------------------

The constraint file
:repo:`firmware/targets/SimpleKriaKv260Example/hdl/SimpleKriaKv260Example.xdc`
declares one asynchronous clock group to prevent false-path timing analysis
between the XVC PLL output and the AxiSocUltraPlusCore PLL output:

.. code-block:: text

   set_clock_groups -asynchronous \
     -group [get_clocks -of_objects [get_pins U_XVC_PLL/MmcmGen.U_Mmcm/CLKOUT0]] \
     -group [get_clocks -of_objects [get_pins U_Core/REAL_CPU.U_CPU/U_Pll/PllGen.U_Pll/CLKOUT0]]

For the platform-level explanation of the AXI-Lite / DMA architecture see
:hub:`explanation/architecture.html`.