SED Wrapper
===========

Overview
--------

**sed_wrapper** is a VHDL wrapper around the Lattice ECP5 SED primitive ``SEDGA``.  
It is used to initialize the SED block and periodically trigger Single Event Upset
detection by issuing ``SEDSTART`` pulses.

The wrapper performs the following main functions:

* Generates the required ``SEDENABLE`` initialization sequence.
* Instantiates the Lattice ``SEDGA`` primitive.
* Synchronizes the initialization-complete indication into the ``SEDCLKOUT`` clock domain.
* Periodically generates a one-cycle ``SEDSTART`` pulse.
* Monitors ``SEDINPROG`` to detect completion of a SED run.
* Latches ``SEDERR`` as a sticky error output.
* Optionally stops further SED checks after an error is detected.

This module is intended for use in Lattice FPGA designs where the internal SED
primitive is used for configuration-memory error detection.

.. warning::
   According to Lattice errata PB1384, SED functionalities may be compromised in designs using Distributed RAM.
   In the framework of HotRIO, this includes any firmware that instantiates hotrio_master_rx or hotrio_slave
   with ``ctc_g => true``, hotrio_dual_ring_wrapper, ethernet_ipv4_udp_formatter, octo_spi and fifo_dc_9b.

   It is advised to avoid instantiation of sed_wrapper in designs impacted by the errata.


Detailed portlist
-----------------

.. vhdlentity::
   :file: ../Firmware/Source/ip_cores/sed_wrapper/hdl/sed_wrapper.vhd
   :entity: sed_wrapper



Internal Primitive Instantiation
--------------------------------

The wrapper instantiates the Lattice ``SEDGA`` primitive.
The primitive is configured with:

.. list-table::
   :header-rows: 1
   :widths: 25 20 55

   * - Primitive Generic
     - Value
     - Description
   * - ``SED_CLK_FREQ``
     - ``"2.4"``
     - SED clock frequency setting used by the Lattice primitive.
   * - ``CHECKALWAYS``
     - ``"DISABLED"``
     - Continuous checking is disabled. The wrapper manually starts SED checks using ``SEDSTART``.
   * - ``DEV_DENSITY``
     - ``"85KU"``
     - Device density setting for the target Lattice FPGA.

Functional Description
----------------------

The wrapper contains two main control sections:

* Initialization FSM running in the ``clk_i`` clock domain.
* Periodic SED run-control FSM running in the ``SEDCLKOUT`` clock domain.

The initialization FSM controls ``SEDENABLE``. After initialization is complete,
the run-control FSM periodically asserts ``SEDSTART`` to start SED checks.

The outputs ``seddone_o``, ``sedinprog_o`` and ``sedclkout_o`` are passed directly
from the ``SEDGA`` primitive. The output ``sederr_o`` is generated from an
internally latched version of ``SEDERR``.

Initialization Sequence
-----------------------

The initialization process runs from ``clk_i`` and generates the following
``SEDENABLE`` sequence:

.. code-block:: text

   0 -> 1 -> 0 -> 1

Each step is held for ``init_hold_cycles_g`` clock cycles.

The initialization FSM uses the following states:

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

   * - State
     - Description
   * - ``INIT_0A``
     - Holds ``SEDENABLE`` low for ``init_hold_cycles_g`` cycles.
   * - ``INIT_1A``
     - Holds ``SEDENABLE`` high for ``init_hold_cycles_g`` cycles.
   * - ``INIT_0B``
     - Holds ``SEDENABLE`` low again for ``init_hold_cycles_g`` cycles.
   * - ``INIT_1_FINAL``
     - Drives ``SEDENABLE`` high permanently and asserts ``init_done_s``.

After the final initialization state is reached, ``init_done_s`` is asserted and
remains high until reset.


SED Run-Control FSM
-------------------

The SED run-control FSM operates on the rising edge of ``sedclkout_s``.

It is responsible for generating periodic ``SEDSTART`` pulses after the
initialization sequence has completed.

The FSM uses the following states:

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

   * - State
     - Description
   * - ``RUN_IDLE``
     - Waits for ``init_done_sync_s`` to become high. If an error is already latched and ``stop_on_error_g`` is true, the FSM moves to ``RUN_STOPPED``.
   * - ``RUN_PULSE``
     - Asserts ``sedstart_s`` for one ``SEDCLKOUT`` cycle.
   * - ``RUN_WAIT_BUSY``
     - Waits for ``sedinprog_s`` to become high, indicating that the SED run has started.
   * - ``RUN_WAIT_COMPLETE``
     - Waits for the falling edge of ``sedinprog_s``, indicating that the SED run has completed.
   * - ``RUN_GAP``
     - Waits for ``gap_sedclk_cycles_g`` cycles before starting the next SED run.
   * - ``RUN_STOPPED``
     - Stops issuing further ``SEDSTART`` pulses.




Error Handling
--------------

The primitive output ``sederr_s`` is latched internally.

.. code-block:: vhdl

   if (sederr_s = '1') then
     sederr_latched_s <= '1';
   end if;

The output ``sederr_o`` is driven from this latched error signal:

.. code-block:: vhdl

   sederr_o <= sederr_latched_s;

This makes ``sederr_o`` a sticky error indication. Once an error is detected, the
output remains high until ``rstn_i`` is asserted low.

If ``stop_on_error_g`` is set to ``true``, the wrapper stops issuing new
``SEDSTART`` pulses after an error has been latched.

Reset Behaviour
---------------

The reset input ``rstn_i`` is active low.

When ``rstn_i`` is asserted low:

* The initialization FSM returns to ``INIT_0A``.
* ``SEDENABLE`` is driven low.
* ``init_done_s`` is cleared.
* The CDC synchronizer registers are cleared.
* The SED run-control FSM returns to ``RUN_IDLE``.
* ``sedstart_s`` is cleared.
* The gap counter is cleared.
* The latched SED error is cleared.
* The delayed ``SEDINPROG`` register is cleared.