<commit_before>
=====================================
**tdc** - time to digital converter
=====================================

Simple time to digital converter. This module digitizes (12 bit resolution) input pulse (TDC_IN) and calculates distance (8 bit resolution) between TDC_IN and TRIG_IN (e.g. trigger signal and hit).
Calculated values (see data format, always 32-bit) are propagated to FIFO data interface.

Data format (Standard)
    +-------------------------+--------------------------------------------------------+--------------------+
    | DATA IDENTIFIER (4 bit) |                 EVENT_COUNTER (16 bit)                 | TDC value (12 bit) |
    +-------------------------+--------------------------------------------------------+--------------------+
Data format (in case of EN_WRITE_TIMESTAMP)
    +-------------------------+--------------------------------------------------------+--------------------+
    | DATA IDENTIFIER (4 bit) |                   TIMESTAMP (16 bit)                   | TDC value (12 bit) |
    +-------------------------+--------------------------------------------------------+--------------------+
Data format (in case of EN_TRIGGER_DIST)
    +-------------------------+----------------------+---------------------------------+--------------------+
    | DATA IDENTIFIER (4 bit) | TRIGGER DIST (8 bit) | TIMESTAMP/EVENT COUNTER (8 bit) | TDC value (12 bit) |
    +-------------------------+----------------------+---------------------------------+--------------------+

NOTE:
 1. Use BROADCAST parameter in order to share fast (640 MHz sampled) trigger signal with other tdc modules.
 2. TDC_IN needs to be longer than one cycle of CLK320, distance of TDC_IN and TRIG_IN needs to be longer than one clock cycle of DV_CLK.
 3. TRIG_IN needs to come before (at least one clock cycle of DV_CLK) TDC_IN.
 4. ARM_TDC and EXT_EN are assumed to be slower than DV_CLK.
 

**Unit test/Example:**
`test_SimTlu.v <https://github.com/SiLab-Bonn/basil/blob/master/tests/test_SimTdc.v>`_
`test_SimTlu.py <https://github.com/SiLab-Bonn/basil/blob/master/tests/test_SimTdc.py>`_

Parameters
    +------------------------------+---------------------+---------------------------------------------------------------------------------------------------------------------+
    | Name                         | Default             | Description                                                                                                         |
    +==============================+=====================+=====================================================================================================================+
    | CLKDV                        | 4 (min. 2)          | Factor of CLK160 to DV_CLK, minimal divider of 2.                                                                   |
    +------------------------------+---------------------+---------------------------------------------------------------------------------------------------------------------+
    | DATA_IDENTIFIER              | 4'b0100             | 4-bit data identifier for TDC words.                                                                                |
    +------------------------------+---------------------+---------------------------------------------------------------------------------------------------------------------+
    | FAST_TDC                     | 1                   | If FAST_TDC is 1, 640 MHz sampling of input TDC_IN is done, else 320 MHz sampling is done.                          |
    +------------------------------+---------------------+---------------------------------------------------------------------------------------------------------------------+
    | FAST_TRIGGER                 | 1                   | If FAST_TRIGGER is 1, 640 MHz sampling of input TRIG_IN is done, else 320 MHz sampling is done.                     |
    +------------------------------+---------------------+---------------------------------------------------------------------------------------------------------------------+
    | BROADCAST                    | 0                   | If BROADCAST is 1, 640 MHz sampled trigger signal can be shared with other TDC modules.                             |
    +------------------------------+---------------------+---------------------------------------------------------------------------------------------------------------------+

Pins
    +--------------------------+---------------------+-----------------------+-------------------------------------------------------------------------------------------------+
    | Name                     | Size                | Direction             | Description                                                                                     |
    +==========================+=====================+=======================+=================================================================================================+
    | CLK320                   | 1                   |  input                | 320 MHz clock                                                                                   |
    +--------------------------+---------------------+-----------------------+-------------------------------------------------------------------------------------------------+
    | CLK160                   | 1                   |  input                | 160 MHz clock                                                                                   |
    +--------------------------+---------------------+-----------------------+-------------------------------------------------------------------------------------------------+
    | DV_CLK                   | 1                   |  input                | clock for ?                                                                                     |
    +--------------------------+---------------------+-----------------------+-------------------------------------------------------------------------------------------------+
    | TDC_IN                   | 1                   |  input                | input pulse which is digitized                                                                  |
    +--------------------------+---------------------+-----------------------+-------------------------------------------------------------------------------------------------+
    | TDC_OUT                  | 1                   |  ouput                | output TDC pulse                                                                                |
    +--------------------------+---------------------+-----------------------+-------------------------------------------------------------------------------------------------+
    | TRIG_IN                  | 1                   |  input                | input trigger signal (distance between TRIG_IN and TDC_IN is calculated)                        |
    +--------------------------+---------------------+-----------------------+-------------------------------------------------------------------------------------------------+
    | TRIG_OUT                 | 1                   |  output               | output TRIG pulse                                                                               |
    +--------------------------+---------------------+-----------------------+-------------------------------------------------------------------------------------------------+
    | FAST_TRIGGER_IN          | CLKDV x 4           |  input                | input of fast trigger signal (in BROADCAST mode use FAST_TRIGGER_OUT as input)                  |
    +--------------------------+---------------------+-----------------------+-------------------------------------------------------------------------------------------------+
    | FAST_TRIGGER_OUT         | CLKDV x 4           |  output               | outgoing fast sampled trigger signal                                                            |
    +--------------------------+---------------------+-----------------------+-------------------------------------------------------------------------------------------------+
    | ARM_TDC                  | 1                   |  input                | enable TDC for single measurement                                                               |
    +--------------------------+---------------------+-----------------------+-------------------------------------------------------------------------------------------------+
    | EXT_EN                   | 1                   |  input                | enable TDC for a fixed time period                                                              |
    +--------------------------+---------------------+-----------------------+-------------------------------------------------------------------------------------------------+
    | TIMESTAMP                | 16                  |  input                | timestamp counter from other modules (e.g. tlu module)                                          |
    +--------------------------+---------------------+-----------------------+-------------------------------------------------------------------------------------------------+

Registers
    +----------------------------------------+----------------------------------+--------+-------+-------------+---------------------------------------------------------------+
    | Name                                   | Address                          | Bits   | r/w   | Default     | Description                                                   |
    +========================================+==================================+========+=======+=============+===============================================================+
    | RESET                                  | 0                                |        | wo    |             | reset                                                         |
    +----------------------------------------+----------------------------------+--------+-------+-------------+---------------------------------------------------------------+
    | VERSION                                | 0                                | [7:0]  | ro    | 0           | version                                                       |
    +----------------------------------------+----------------------------------+--------+-------+-------------+---------------------------------------------------------------+
    | ENABLE                                 | 1                                | [0]    | r/w   | 0           | enable TDC module                                             |
    +----------------------------------------+----------------------------------+--------+-------+-------------+---------------------------------------------------------------+
    | ENABLE_EXTERN                          | 1                                | [1]    | r/w   | 0           | external enable                                               |
    +----------------------------------------+----------------------------------+--------+-------+-------------+---------------------------------------------------------------+
    | EN_ARMING                              | 1                                | [2]    | r/w   | 0           | enable arming                                                 |
    +----------------------------------------+----------------------------------+--------+-------+-------------+---------------------------------------------------------------+
    | EN_WRITE_TIMESTAMP                     | 1                                | [3]    | r/w   | 0           | write timestamp to output data (see data format description ) |
    +----------------------------------------+----------------------------------+--------+-------+-------------+---------------------------------------------------------------+
    | EN_TRIGGER_DIST                        | 1                                | [4]    | r/w   | 0           | write trigger distance to output data                         |
    +----------------------------------------+----------------------------------+--------+-------+-------------+---------------------------------------------------------------+
    | EN_NO_WRITE_TRIG_ERR                   | 1                                | [5]    | r/w   | 0           |                                                               |
    +----------------------------------------+----------------------------------+--------+-------+-------------+---------------------------------------------------------------+
    | EN_INVERT_TDC                          | 1                                | [6]    | r/w   | 0           | invert TDC input                                              |
    +----------------------------------------+----------------------------------+--------+-------+-------------+---------------------------------------------------------------+
    | EN_INVERT_TRIGGER                      | 1                                | [7]    | r/w   | 0           | invert trigger input                                          |
    +----------------------------------------+----------------------------------+--------+-------+-------------+---------------------------------------------------------------+
    | EVENT_COUNTER                          | 2                                | [31:0] | ro    |             | event counter value                                           |
    +----------------------------------------+----------------------------------+--------+-------+-------------+---------------------------------------------------------------+
    | LOST_DATA_COUNTER                      | 6                                | [7:0]  | ro    |             | lost data counter                                             |
    +----------------------------------------+----------------------------------+--------+-------+-------------+---------------------------------------------------------------+
<commit_msg>MAINT: README<commit_after>
=====================================
**tdc** - time to digital converter
=====================================

Simple time to digital converter. This module digitizes (12 bit resolution) input pulse (TDC_IN) and calculates distance (8 bit resolution) between TDC_IN and TRIG_IN (e.g. trigger signal and hit).
Calculated values (see data format, always 32-bit) are propagated to FIFO data interface.

NOTE:
 1. Use BROADCAST parameter in order to share fast (640 MHz sampled) trigger signal with other tdc modules.
 2. TDC_IN needs to be longer than one cycle of CLK320, distance of TDC_IN and TRIG_IN needs to be longer than one clock cycle of DV_CLK.
 3. TRIG_IN needs to come before (at least one clock cycle of DV_CLK) TDC_IN.
 4. ARM_TDC and EXT_EN are assumed to be slower than DV_CLK.

**Unit test/Example:**
`test_SimTlu.v <https://github.com/SiLab-Bonn/basil/blob/master/tests/test_SimTdc.v>`_
`test_SimTlu.py <https://github.com/SiLab-Bonn/basil/blob/master/tests/test_SimTdc.py>`_

Data format (Standard)
    +-------------------------+--------------------------------------------------------+--------------------+
    | DATA IDENTIFIER (4 bit) |                 EVENT_COUNTER (16 bit)                 | TDC value (12 bit) |
    +-------------------------+--------------------------------------------------------+--------------------+
Data format (in case of EN_WRITE_TIMESTAMP)
    +-------------------------+--------------------------------------------------------+--------------------+
    | DATA IDENTIFIER (4 bit) |                   TIMESTAMP (16 bit)                   | TDC value (12 bit) |
    +-------------------------+--------------------------------------------------------+--------------------+
Data format (in case of EN_TRIGGER_DIST)
    +-------------------------+----------------------+---------------------------------+--------------------+
    | DATA IDENTIFIER (4 bit) | TRIGGER DIST (8 bit) | TIMESTAMP/EVENT COUNTER (8 bit) | TDC value (12 bit) |
    +-------------------------+----------------------+---------------------------------+--------------------+

Parameters
    +------------------------------+---------------------+---------------------------------------------------------------------------------------------------------------------+
    | Name                         | Default             | Description                                                                                                         |
    +==============================+=====================+=====================================================================================================================+
    | CLKDV                        | 4 (min. 2)          | Factor of CLK160 to DV_CLK, minimal divider of 2.                                                                   |
    +------------------------------+---------------------+---------------------------------------------------------------------------------------------------------------------+
    | DATA_IDENTIFIER              | 4'b0100             | 4-bit data identifier for TDC words.                                                                                |
    +------------------------------+---------------------+---------------------------------------------------------------------------------------------------------------------+
    | FAST_TDC                     | 1                   | If FAST_TDC is 1, 640 MHz sampling of input TDC_IN is done, else 320 MHz sampling is done.                          |
    +------------------------------+---------------------+---------------------------------------------------------------------------------------------------------------------+
    | FAST_TRIGGER                 | 1                   | If FAST_TRIGGER is 1, 640 MHz sampling of input TRIG_IN is done, else 320 MHz sampling is done.                     |
    +------------------------------+---------------------+---------------------------------------------------------------------------------------------------------------------+
    | BROADCAST                    | 0                   | If BROADCAST is 1, 640 MHz sampled trigger signal can be shared with other TDC modules.                             |
    +------------------------------+---------------------+---------------------------------------------------------------------------------------------------------------------+

Pins
    +--------------------------+---------------------+-----------------------+-------------------------------------------------------------------------------------------------+
    | Name                     | Size                | Direction             | Description                                                                                     |
    +==========================+=====================+=======================+=================================================================================================+
    | CLK320                   | 1                   |  input                | 320 MHz clock                                                                                   |
    +--------------------------+---------------------+-----------------------+-------------------------------------------------------------------------------------------------+
    | CLK160                   | 1                   |  input                | 160 MHz clock                                                                                   |
    +--------------------------+---------------------+-----------------------+-------------------------------------------------------------------------------------------------+
    | DV_CLK                   | 1                   |  input                | clock for ?                                                                                     |
    +--------------------------+---------------------+-----------------------+-------------------------------------------------------------------------------------------------+
    | TDC_IN                   | 1                   |  input                | input pulse which is digitized                                                                  |
    +--------------------------+---------------------+-----------------------+-------------------------------------------------------------------------------------------------+
    | TDC_OUT                  | 1                   |  ouput                | output TDC pulse                                                                                |
    +--------------------------+---------------------+-----------------------+-------------------------------------------------------------------------------------------------+
    | TRIG_IN                  | 1                   |  input                | input trigger signal (distance between TRIG_IN and TDC_IN is calculated)                        |
    +--------------------------+---------------------+-----------------------+-------------------------------------------------------------------------------------------------+
    | TRIG_OUT                 | 1                   |  output               | output TRIG pulse                                                                               |
    +--------------------------+---------------------+-----------------------+-------------------------------------------------------------------------------------------------+
    | FAST_TRIGGER_IN          | CLKDV x 4           |  input                | input of fast trigger signal (in BROADCAST mode use FAST_TRIGGER_OUT as input)                  |
    +--------------------------+---------------------+-----------------------+-------------------------------------------------------------------------------------------------+
    | FAST_TRIGGER_OUT         | CLKDV x 4           |  output               | outgoing fast sampled trigger signal                                                            |
    +--------------------------+---------------------+-----------------------+-------------------------------------------------------------------------------------------------+
    | ARM_TDC                  | 1                   |  input                | enable TDC for single measurement                                                               |
    +--------------------------+---------------------+-----------------------+-------------------------------------------------------------------------------------------------+
    | EXT_EN                   | 1                   |  input                | enable TDC for a fixed time period                                                              |
    +--------------------------+---------------------+-----------------------+-------------------------------------------------------------------------------------------------+
    | TIMESTAMP                | 16                  |  input                | timestamp counter from other modules (e.g. tlu module)                                          |
    +--------------------------+---------------------+-----------------------+-------------------------------------------------------------------------------------------------+

Registers
    +----------------------------------------+----------------------------------+--------+-------+-------------+---------------------------------------------------------------+
    | Name                                   | Address                          | Bits   | r/w   | Default     | Description                                                   |
    +========================================+==================================+========+=======+=============+===============================================================+
    | RESET                                  | 0                                |        | wo    |             | reset                                                         |
    +----------------------------------------+----------------------------------+--------+-------+-------------+---------------------------------------------------------------+
    | VERSION                                | 0                                | [7:0]  | ro    | 0           | version                                                       |
    +----------------------------------------+----------------------------------+--------+-------+-------------+---------------------------------------------------------------+
    | ENABLE                                 | 1                                | [0]    | r/w   | 0           | enable TDC module                                             |
    +----------------------------------------+----------------------------------+--------+-------+-------------+---------------------------------------------------------------+
    | ENABLE_EXTERN                          | 1                                | [1]    | r/w   | 0           | external enable                                               |
    +----------------------------------------+----------------------------------+--------+-------+-------------+---------------------------------------------------------------+
    | EN_ARMING                              | 1                                | [2]    | r/w   | 0           | enable arming                                                 |
    +----------------------------------------+----------------------------------+--------+-------+-------------+---------------------------------------------------------------+
    | EN_WRITE_TIMESTAMP                     | 1                                | [3]    | r/w   | 0           | write timestamp to output data (see data format description ) |
    +----------------------------------------+----------------------------------+--------+-------+-------------+---------------------------------------------------------------+
    | EN_TRIGGER_DIST                        | 1                                | [4]    | r/w   | 0           | write trigger distance to output data                         |
    +----------------------------------------+----------------------------------+--------+-------+-------------+---------------------------------------------------------------+
    | EN_NO_WRITE_TRIG_ERR                   | 1                                | [5]    | r/w   | 0           |                                                               |
    +----------------------------------------+----------------------------------+--------+-------+-------------+---------------------------------------------------------------+
    | EN_INVERT_TDC                          | 1                                | [6]    | r/w   | 0           | invert TDC input                                              |
    +----------------------------------------+----------------------------------+--------+-------+-------------+---------------------------------------------------------------+
    | EN_INVERT_TRIGGER                      | 1                                | [7]    | r/w   | 0           | invert trigger input                                          |
    +----------------------------------------+----------------------------------+--------+-------+-------------+---------------------------------------------------------------+
    | EVENT_COUNTER                          | 2                                | [31:0] | ro    |             | event counter value                                           |
    +----------------------------------------+----------------------------------+--------+-------+-------------+---------------------------------------------------------------+
    | LOST_DATA_COUNTER                      | 6                                | [7:0]  | ro    |             | lost data counter                                             |
    +----------------------------------------+----------------------------------+--------+-------+-------------+---------------------------------------------------------------+

{'fraction_non_alphanumeric': 0.5057106146048969, 'fraction_numerical': 0.00885145263759012, 'mean_word_length': 0.3301842005317129, 'pattern_counts': {'":': 0, '<': 7, '<?xml version=': 0, '>': 7, 'https://': 4, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 230, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3932871', 'n_tokens_mistral': 4037, 'n_tokens_neox': 3380, 'n_words': 941}