pulse_stretcher
===============

This module generates an output pulse with the minimum duration configurable whenever an input pulse is detected.

By setting the generic DOMAIN_CROSSING to true, an internal clock domain crossing is enabled for the input signal. This is useful when the input signal comes from a different clock domain. The clock domain crossing is done with the `signal_cdc` module that uses a two-stage synchronizer clocked with this module's clock. This module avoids metastability but it cannot guarantee that input pulse is detected if the pulse frequency is high enough.

If another pulse is detected while the output pulse is active from a previous detection, the internal counter is reset and the output pulse is extended.

Generics
--------
.. list-table::
   :header-rows: 1

   * - Name
     - Description
     - Default value
   * - OUTPUT_PULSE_LENGTH
     - Sets the minimum duration of the output pulse in clock cycles.
     - 10
   * - DOMAIN_CROSSING
     - Enables the clock domain crossing for the pulse signal. 
     - false

Ports
-----
.. list-table::
   :header-rows: 1

   * - Name
     - Mode
     - Description
     - Type
   * - clk_i
     - IN
     - Input clock signal
     - std_logic
   * - rst_i
     - IN
     - Synchronous reset signal
     - std_logic
   * - pulse_i
     - IN
     - Input pulse
     - std_logic
   * - pulse_o
     - OUT
     - Output pulse
     - std_logic

Dependencies
------------

.. list-table::
   :header-rows: 1

   * - Name
     - Motivation
   * - :doc:`signal_cdc </firmware/modules/signal_cdc>`
     - Used for the clock domain crossing of input pulse.

Implementation details
----------------------

This module functionality can be divided in two parts. The first crosses the clock domain (if active) of the input pulse and detects a rising edge. The second part implements a simple counter that keeps the output pulse active for the set amount.

Input conditioning
~~~~~~~~~~~~~~~~~~

Using the DOMAIN_CROSSING generic, a generate statement decides if the clock domain crossing is needed. If the crossing is enabled, the input pulse is synchronized to the internal clock domain using the `signal_cdc` module which provides the rising edge detection. On the other hand, if the crossing is disabled, the rising edge is detected by comparing the signal with its previous value.

Counter
~~~~~~~

This part is implemented in the process called `pulse_stretcher`. The process waits for the input signal to go high. When an input edge is detected, the output is set and the counter is set to the value of OUTPUT_PULSE_LENGTH. At each clock cycle the counter is decremented until it reaches zero, and then the output is reset.