core: add description at the beginning of sources

80c7bfed · Sebastien Bourdeauducq · 9595cf58 · 80c7bfed · 80c7bfed · 80c7bfed
Commit 80c7bfed authored Aug 30, 2011 by Sebastien Bourdeauducq
11 changed files
--- a/core/tdc.vhd
+++ b/core/tdc.vhd
@@ -17,6 +17,10 @@

 -- Copyright (C) 2011 Sebastien Bourdeauducq

+-- DESCRIPTION:
+-- Top level module of the TDC core, contains all logic except the optional
+-- host interface.
+
 library ieee;
 use ieee.std_logic_1164.all;


--- a/core/tdc_channel.vhd
+++ b/core/tdc_channel.vhd
@@ -17,6 +17,14 @@

 -- Copyright (C) 2011 Sebastien Bourdeauducq

+-- DESCRIPTION:
+-- This contains the elements needed for each channel:
+--  * Delay line
+--  * Encoder
+--  * LUT
+--  * Deskew stage
+--  * Online calibration ring oscillator
+
 library ieee;
 use ieee.std_logic_1164.all;
 use ieee.numeric_std.all;

--- a/core/tdc_channelbank.vhd
+++ b/core/tdc_channelbank.vhd
@@ -19,6 +19,22 @@

 -- Copyright (C) 2011 Sebastien Bourdeauducq

+-- DESCRIPTION:
+-- This module instantiates all the channels and provides a control interface
+-- independent of the number of channels.
+-- It provides a simple two-wire interface to select the current channel to
+-- operate one, using the next_i (switch to next channel) and last_o (current
+-- channel is the current channel, next channel is the first channel).
+-- It provides multiplexed access to the LUT of the current channel, to the
+-- histogram of the current channel, and to the ring oscillator frequency
+-- of the current channel.
+--
+-- To save resources:
+--  * the histogram is implemented as one large block RAM common to all
+--    channels
+--  * the frequency counter logic is shared among all channels, each channel
+--    only implements a ring oscillator.
+
 library ieee;
 use ieee.std_logic_1164.all;
 use ieee.numeric_std.all;

--- a/core/tdc_controller.vhd
+++ b/core/tdc_controller.vhd
@@ -17,6 +17,11 @@

 -- Copyright (C) 2011 Sebastien Bourdeauducq

+-- DESCRIPTION:
+-- This is the controller for the channel bank. It is in charge of sequencing
+-- and performing the startup and online calibrations for all channels.
+-- It books the histograms and computes and loads the LUTs of the channels.
+
 library ieee;
 use ieee.std_logic_1164.all;
 use ieee.numeric_std.all;

--- a/core/tdc_delayline.vhd
+++ b/core/tdc_delayline.vhd
@@ -17,6 +17,17 @@

 -- Copyright (C) 2011 Sebastien Bourdeauducq

+-- DESCRIPTION:
+-- The delay line uses a carry chain. It is made up of CARRY4 primitives whose
+-- CO outputs are registered by the dedicated D flip flops of the same slices.
+-- The signal is injected at the CYINIT pin at the bottom of the carry chain.
+-- The CARRY4 primitives have their S inputs hardwired to 1, which means the
+-- carry chain becomes a delay line with the signal going unchanged through the
+-- MUXCY elements. Since each CARRY4 contains four MUXCY elements, the delay
+-- line has four times as many taps as there are CARRY4 primitives.
+--
+-- There is a second layer of registers to prevent metastability.
+
 library ieee;
 use ieee.std_logic_1164.all;


--- a/core/tdc_divider.vhd
+++ b/core/tdc_divider.vhd
@@ -17,6 +17,11 @@

 -- Copyright (C) 2011 Sebastien Bourdeauducq

+-- DESCRIPTION:
+-- Sequentially computes the Euclidean division of dividend_i by divisor_i.
+-- Returns quotient and remainder. Works with unsigned integers of g_WIDTH
+-- bits each.
+
 library ieee;
 use ieee.std_logic_1164.all;
 use ieee.numeric_std.all;

--- a/core/tdc_freqc.vhd
+++ b/core/tdc_freqc.vhd
@@ -2,7 +2,7 @@
 -- TDC Core / CERN
 -------------------------------------------------------------------------------
 --
-- unit name: tdc_freqm
+-- unit name: tdc_freqc
 --
 -- author: Sebastien Bourdeauducq, sebastien@milkymist.org
 --
@@ -17,6 +17,10 @@

 -- Copyright (C) 2011 Sebastien Bourdeauducq

+-- DESCRIPTION:
+-- Counts the number of rising edges in clk_m_i for 2^g_TIMER_WIDTH-1 periods
+-- of clk_i and returns the result. All signals are synchronous to clk_i.
+
 library ieee;
 use ieee.std_logic_1164.all;
 use ieee.numeric_std.all;

--- a/core/tdc_lbc.vhd
+++ b/core/tdc_lbc.vhd
@@ -17,6 +17,11 @@

 -- Copyright (C) 2011 Sebastien Bourdeauducq

+-- DESCRIPTION:
+-- Encoder for the delay line. Counts the number of leading bits equal to the
+-- current polarity. The current polarity is the opposite of the most
+-- significant bit of the input vector from the previous cycle.
+
 library ieee;
 use ieee.std_logic_1164.all;


--- a/core/tdc_package.vhd
+++ b/core/tdc_package.vhd
@@ -17,6 +17,11 @@

 -- Copyright (C) 2011 Sebastien Bourdeauducq

+-- DESCRIPTION:
+-- This contains component declarations for all the modules of the TDC core.
+-- It is used both internally to instantiate modules, and by the user to
+-- instantiate the top-level "tdc" module.
+
 library ieee;
 use ieee.std_logic_1164.all;


--- a/core/tdc_psync.vhd
+++ b/core/tdc_psync.vhd
@@ -17,6 +17,13 @@

 -- Copyright (C) 2011 Sebastien Bourdeauducq

+-- DESCRIPTION:
+-- Converts a single clock cycle pulse in the clk_src_i domain into a single
+-- clock cycle pulse in the clk_dst_i domain.
+-- It does so by converting the pulse into a level change, synchronizing
+-- this level change into the destination domain by double latching, and
+-- finally restoring the pulse in the destination domain.
+
 library ieee;
 use ieee.std_logic_1164.all;


--- a/core/tdc_ringosc.vhd
+++ b/core/tdc_ringosc.vhd
@@ -17,6 +17,13 @@

 -- Copyright (C) 2011 Sebastien Bourdeauducq

+-- DESCRIPTION:
+-- Ring oscillator built by chaining together an odd number of LUTs used
+-- as inverters. The first LUT has a second input which forces its output
+-- to 0. This is useful to initialize the ring oscillator and make sure
+-- that only one wave is traveling through it, and to force the output of the
+-- oscillator to 0 at any time.
+
 library ieee;
 use ieee.std_logic_1164.all;