.. _module_resync: Module resync ============= This document contains technical documentation for the ``resync`` module. .. _resync.resync_counter: resync_counter.vhd ------------------ .. symbolator:: component resync_counter is generic ( width : positive; -- Initial value for the output that will be set for a few cycles before the first input -- value has propagated. default_value : u_unsigned; -- Optional pipeline step on the output after Gray conversion pipeline_output : boolean ); port ( clk_in : in std_ulogic; counter_in : in u_unsigned; --# {{}} clk_out : in std_ulogic; counter_out : out u_unsigned ); end component; Synchronize a counter value between two domains, using Gray coded values. .. note:: This entity has a scoped constraint file that must be used. Note that unlike e.g. :ref:`resync.resync_level`, it is safe to drive the input of this entity with LUTs as well as FFs. .. warning:: This entity assumes that the input counter value only increments and decrements in steps of one. Erroneous values can appear on the output if this is not followed. This entity converts the linear input counter word to Gray code, resynchronizes it to the output clock domain with an ``async_reg`` chain, and converts it back to a linear number. A ``set_bus_skew`` constraint is a applied to the Gray coded bits that are sampled in the output clock domain. That constraint imposes an upper limit for the difference in the inter-word routing delay. This in turn means that the bits are always sampled coherently with regards to changes on the input side. It is possible to sample while one bit is transitioning, but the meta-stability protection of an ``async_reg`` chain will resolve that to a "clean" ``'0'`` or ``'1'``. Since the value is Gray coded, there will never be more than one bit transitioning for each value change, which means that it does not matter if the transitioning value is resolved to ``'0'`` or ``'1'``. Resource utilization ____________________ This entity has :ref:`netlist builds ` set up with :ref:`automatic size checkers ` in ``module_resync.py``. The following table lists the resource utilization for the entity, depending on generic configuration. .. list-table:: Resource utilization for resync_counter.vhd netlist builds. :header-rows: 1 * - Generics - Total LUTs - FFs * - width = 16 - 23 - 48 .. _resync.resync_cycles: resync_cycles.vhd ----------------- .. symbolator:: component resync_cycles is generic ( counter_width : positive; active_level : std_ulogic ); port ( clk_in : in std_ulogic; data_in : in std_ulogic; --# {{}} clk_out : in std_ulogic; data_out : out std_ulogic ); end component; Resynchronizes a bit, so that the output bit is asserted as many clock cycles as the input bit. .. note:: This entity instantiates :ref:`resync.resync_counter` which has a scoped constraint file that must be used. This module counts each ``clk_in`` cycle the input bit is asserted. The counter is resynchronized to ``clk_out``, and used as a reference to know how many ``clk_out`` cycles the output bit should be asserted. The module may fail when ``clk_out`` is slower than ``clk_in`` and the input is asserted many cycles in a row. An assertion is made to check for this case. Note that unlike e.g. :ref:`resync.resync_level`, it is safe to drive the input of this entity with LUTs as well as FFs. .. _resync.resync_level: resync_level.vhd ---------------- .. symbolator:: component resync_level is generic ( -- Enable or disable a register on the input side before the async_reg flip-flip chain. -- Must be used if the input can contain glitches. See header for more details. -- The 'clk_in' port must be assigned if this generic is set to 'true'. enable_input_register : boolean; -- Initial value for the output that will be set for a few cycles before the first input -- value has propagated. default_value : std_ulogic ); port ( clk_in : in std_ulogic; data_in : in std_ulogic; --# {{}} clk_out : in std_ulogic; data_out : out std_ulogic ); end component; Resync a single bit from one clock domain to another, using two ``async_reg`` registers. .. note:: This entity has a scoped constraint file that must be used. The two registers will be placed in the same slice, in order to minimize Mean Time Between Failure (MTBF). This guarantees proper resynchronization of semi static "level" type signals without meta stability on rising/falling edges. It can not handle "pulse" type signals. Pulses can be missed and single-cycle pulse behavior will not work. The ``clk_in`` port does not necessarily have to be set. But if you want to have a deterministic latency through the resync block (via a ``set_max_delay`` constraint) it has to be set. If not, a simple ``set_false_path`` constraint will be used and the latency can be arbitrary, depending on the placer/router. Input register ______________ There is an option to include a register on the input side before the ``async_reg`` flip-flop chain. This option is to prevent sampling of data when the input is in a transient "glitch" state, which can occur if it is driven by a LUT as opposed to a flip-flop. If the input is already driven by a flip-flop, you can safely set the generic to ``false`` in order to save resources. Note that this is a separate issue from meta-stability; they can happen independently of each other. When this option is enabled, the ``clk_in`` port must be driven with the correct clock. Some motivation why the input needs to be driven by a register: While LUTs are designed to be glitch-free in order to save switching power, this can only be achieved as long as only one LUT input value changes state. When more than one input changes state per clock cycle, glitches will almost certainly appear on the LUT output before reaching its steady state. This is partly due to difference in propagation delay between the inputs, and partly due to the electrical structure of a LUT. In a regular synchronous design, the Vivado timing engine guarantees that all these glitches have been resolved and LUT output has reached its steady state before the value is sampled by a FF. When the value is fed to our ``async_reg`` FF chain however there is no control over this, and we may very well sample an erroneous glitch value. So given this knowledge the rule of thumb is to always drive ``resync_level`` input by a FF. However since LUTs are glitch-free in some scenarios, exceptions can be made if we are sure of what we are doing. For example if the value is inverted in a LUT before being fed to ``resync_level``, then that is a scenario where we do not actually need the extra FF. .. _resync.resync_level_on_signal: resync_level_on_signal.vhd -------------------------- .. symbolator:: component resync_level_on_signal is generic ( -- Initial value for the output that will be set until the first input value has propagated -- and been sampled. default_value : std_ulogic ); port ( data_in : in std_ulogic; --# {{}} clk_out : in std_ulogic; sample_value : in std_ulogic; data_out : out std_ulogic ); end component; Sample a bit from one clock domain to another. .. note:: This entity has a scoped constraint file that must be used. This entity does not utilize any meta stability protection. It is up to the user to ensure that ``data_in`` is stable when ``sample_value`` is asserted. Note that unlike e.g. :ref:`resync.resync_level`, it is safe to drive the input of this entity with LUTs as well as FFs. .. _resync.resync_pulse: resync_pulse.vhd ---------------- .. symbolator:: component resync_pulse is generic ( assert_false_on_pulse_overload : boolean ); port ( clk_in : in std_ulogic; pulse_in : in std_ulogic; --# {{}} clk_out : in std_ulogic; pulse_out : out std_ulogic ); end component; A robust way of resyncing a pulse signal from one clock domain to another. .. note:: This entity instantiates :ref:`resync.resync_level` which has a scoped constraint file that must be used. This entity features a feedback input gating which makes it robust in all configurations. Without input gating, if multiple pulses arrive close to each other, pulse overload will occur and some, or even all of them, can be missed and not arrive on the output. With input gating, if multiple pulses arrive one and only one will arrive on the output. Note that unlike e.g. :ref:`resync.resync_level`, it is safe to drive the input of this entity with LUTs as well as FFs. .. _resync.resync_slv_level: resync_slv_level.vhd -------------------- .. symbolator:: component resync_slv_level is generic ( width : positive; -- Enable or disable a register on the input side before the async_reg flip-flip chain. -- Must be used if the input can contain glitches. See resync_slv header for more details. -- The 'clk_in' port must be assigned if this generic is set to 'true'. enable_input_register : boolean; -- Initial value for the output that will be set for a few cycles before the first input -- value has propagated. default_value : std_ulogic_vector ); port ( clk_in : in std_ulogic; data_in : in std_ulogic_vector; --# {{}} clk_out : in std_ulogic; data_out : out std_ulogic_vector ); end component; Resync a vector from one clock domain to another. .. note:: This entity instantiates :ref:`resync.resync_level` which has a scoped constraint file that must be used. This simple vector resync mechanism does not guarantee any coherency between the bits. There might be a large skew between different bits. It does however have meta-stability protection. See :ref:`resync.resync_level` for details about constraining and usage of the ``enable_input_register`` generic. .. _resync.resync_slv_level_coherent: resync_slv_level_coherent.vhd ----------------------------- .. symbolator:: component resync_slv_level_coherent is generic ( width : positive; -- Initial value for the output that will be set for a few cycles before the first input -- value has propagated. default_value : std_ulogic_vector ); port ( clk_in : in std_ulogic; data_in : in std_ulogic_vector; --# {{}} clk_out : in std_ulogic; data_out : out std_ulogic_vector ); end component; Resynchronize a data vector from one clock domain to another. Unlike e.g. :ref:`resync.resync_slv_level`, this entity contains a mechanism that guarantees bit coherency. An :ref:`fifo.asynchronous_fifo` can also be used to achieve this task, but this entity results in a smaller logic footprint. .. note:: This entity has a scoped constraint file that must be used. Note that unlike e.g. :ref:`resync.resync_level`, it is safe to drive the input of this entity with LUTs as well as FFs. A level signal is rotated around between input and output side, with three registers in each direction. The level toggles for each roundtrip, and data is sampled on each side upon a level transition. This ensures that data is sampled on the output side only when we know that the sampled input data is stable. Conversely, input data is only sampled when we know that data has been sampled on the output in a stable fashion. The latency is less than or equal to 3 * period(clk_in) + 3 * period(clk_out) This is also the sampling period of the signal. As such this resync is not suitable for signals that change quickly. It is instead typically used for e.g. monotonic counters, slow moving status words, and other data where the different bits are correlated. The LUT utilization is always 3. The FF utilization increases linearly at a rate of ``2 * width``. Compared to :ref:`resync.resync_counter` this entity has lower LUT and FF usage in all scenarios. It does however have higher latency. Compared to :ref:`fifo.asynchronous_fifo` this entity has lower LUT usage. FF usage is lower up to around width 32 where this entity will consume more FF. Latency is about the same for both. Resource utilization ____________________ This entity has :ref:`netlist builds ` set up with :ref:`automatic size checkers ` in ``module_resync.py``. The following table lists the resource utilization for the entity, depending on generic configuration. .. list-table:: Resource utilization for resync_slv_level_coherent.vhd netlist builds. :header-rows: 1 * - Generics - Total LUTs - FFs * - width = 16 - 3 - 38 .. _resync.resync_slv_level_on_signal: resync_slv_level_on_signal.vhd ------------------------------ .. symbolator:: component resync_slv_level_on_signal is generic ( width : positive; -- Initial value for the output that will be set until the first input -- value has propagated and been sampled. default_value : std_ulogic_vector ); port ( data_in : in std_ulogic_vector; --# {{}} clk_out : in std_ulogic; sample_value : in std_ulogic; data_out : out std_ulogic_vector ); end component; Sample a vector from one clock domain to another. .. note:: This entity instantiates :ref:`resync.resync_level_on_signal` which has a scoped constraint file that must be used. This modules does not utilize any meta stability protection. It is up to the user to ensure that ``data_in`` is stable when ``sample_value`` is asserted. Note that unlike e.g. :ref:`resync.resync_level`, it is safe to drive the input of this entity with LUTs as well as FFs.