test benches: add description at the beginning of sources

tb/controller/tb_controller.vhd

@@ -17,6 +17,32 @@
 
 -- Copyright (C) 2011 Sebastien Bourdeauducq
 
+-- DESCRIPTION:
+-- This test verifies the correct operation of the controller in the following
+-- scenario:
+-- 1. The test bench resets the controller, which begins to perform startup
+-- calibration operations.
+-- 2. The test bench sends a series of pulses with incrementing fine time
+-- stamps into the controller.
+-- 3. The test bench provides a model of the histogram memory to the
+-- controller. Because of the continuously incrementing time stamps provided by
+-- the test bench, the controller books a histogram with the same
+-- 2^(g_FP_COUNT-g_RAW_COUNT) value everywhere.
+-- 4. The controller reads the frequency of the calibration ring oscillator,
+-- and the test bench returns 1.
+-- 5. The controller performs a first round of online calibration. It reads
+-- again the frequency of the ring oscillator, and the test bench returns 2.
+-- This means that all delays should be halved.
+-- 6. The controller builds the LUT. The test bench provides a model of the
+-- memory for this purpose.
+-- 7. The controller asserts the ready signal, and this terminates the
+-- simulation.
+--
+-- The test bench then verifies that the LUT entries from i = 1 to 
+-- i = 2^g_RAW_COUNT-1 all have the correct value, and reports a failed
+-- assertion otherwise:
+-- LUT(i) = 1/2 * (i-1) * 2^(g_FP_COUNT-g_RAW_COUNT)
+
 library ieee;
 use ieee.std_logic_1164.all;
 use ieee.numeric_std.all;

tb/divider/tb_divider.vhd

@@ -17,6 +17,11 @@
 
 -- Copyright (C) 2011 Sebastien Bourdeauducq
 
+-- DESCRIPTION:
+-- This test validates the integer divider by making it compute the quotient
+-- and remainder of all 0 ... 2^g_WIDTH positive integer values by all
+-- 1 ... 2^g_WIDTH values. It then checks for the correct results.
+
 library ieee;
 use ieee.std_logic_1164.all;
 use ieee.numeric_std.all;

tb/freqc/tb_freqc.vhd

@@ -17,6 +17,14 @@
 
 -- Copyright (C) 2011 Sebastien Bourdeauducq
 
+-- DESCRIPTION:
+-- This test bench generates a system clock and a measured clock, measures the
+-- latter using the frequency counter module, and verifies the result.
+--
+-- It verifies that the counter has enough accuracy; i.e. that the measured
+-- clock cycle counter does not differ by more than one unit from the best
+-- possible value.
+
 library ieee;
 use ieee.std_logic_1164.all;
 use ieee.numeric_std.all;

tb/lbc/tb_lbc.vhd

@@ -18,6 +18,27 @@
 
 -- Copyright (C) 2011 Sebastien Bourdeauducq
 
+-- DESCRIPTION:
+-- This test verifies the pipelined encoder by presenting a new test vector
+-- with an alternating polarity at each clock cycle.
+--
+-- The encoder should count the number of leading bits of the input that have a
+-- value opposite to the polarity of the previous vector, until it reaches the
+-- first bit with a different value. It should ignore the subsequent bits. The
+-- polarity of a vector is the value of its most significant bit (and it
+-- defines whether a leading or a falling edge is being detected by the TDC
+-- core).
+--
+-- To validate this behaviour, the test bench generates multiple vectors of
+-- 2^g_N-1 bits each, built by concatenating i bits of the current polarity,
+-- one bit with the opposite polarity (except for the last vector), and
+-- 2^g_N-i-2 random bits, for all 1 <= i < 2^g_N. The polarity alternates at
+-- each cycle, which means the encoder should always detect a new event.
+--
+-- The test bench verifies that the encoder produces the correct integer
+-- sequence 1, ..., 2^g_N-1 after its two cycles of latency, and that the
+-- polarity detection output is toggling.
+
 library ieee;
 use ieee.std_logic_1164.all;
 use ieee.numeric_std.all;