From 15ba30df5d6ecc9b01c4bbf4f63a9b342cae13ce Mon Sep 17 00:00:00 2001
From: Jan Michel <michel@physik.uni-frankfurt.de>
Date: Thu, 8 Dec 2022 16:54:11 +0100
Subject: [PATCH] add data format document, slight change to header word

---
 code/ReadoutHandler.vhd | 14 ++++-----
 dataformat.md           | 70 +++++++++++++++++++++++++++++++++++++++++
 2 files changed, 76 insertions(+), 8 deletions(-)
 create mode 100644 dataformat.md

diff --git a/code/ReadoutHandler.vhd b/code/ReadoutHandler.vhd
index 48b0c98..deb51db 100644
--- a/code/ReadoutHandler.vhd
+++ b/code/ReadoutHandler.vhd
@@ -151,7 +151,7 @@ begin
     when IDLE =>
       channel := 0;
       if collect_start_tdc = '1' then
-        cdc_data_in <= x"1DC0" & "000" & REFERENCE_IN;
+        cdc_data_in <= x"DC00" & "000" & REFERENCE_IN;
         if GROUP_NUM = '0' then
           cdc_write <= '1';        
         end if;  
@@ -164,13 +164,11 @@ begin
         hit_valid <= '1';
         DATA_READ_OUT(channel) <= '1';
       end if;  
---       else
-        if channel < 15 then
-          channel := channel + 1;
-        else
-          state_data <= END1;
-        end if;
---       end if;  
+      if channel < 15 then
+        channel := channel + 1;
+      else
+        state_data <= END1;
+      end if;
       
     when END1 =>
       state_data <= END2;
diff --git a/dataformat.md b/dataformat.md
new file mode 100644
index 0000000..aa66a4a
--- /dev/null
+++ b/dataformat.md
@@ -0,0 +1,70 @@
+Clocked TDC (MDC edition)
+==
+
+
+
+
+General Remarks
+--
+
+* Each FPGA contains 32 TDC channels
+  * Counting starts from 0, the reference channel has no channel number
+
+* Data is not output in ordered fashion, hits are sent mixed between channels, not ordered by time.
+* There might be up to 10 hits per channel
+
+* TDC calibration is not necessary by default
+* TDC calibration is implemented in two options (usual 0xd trigger type):
+  * Internal calibration with a 50 ns long pulse
+  * Calibration pulse using the analog front-end chips 
+    * about 110 ns long, depending on front-end settings
+    * Might give several hits especially with low thresholds
+  
+
+Data Format (v0)
+--
+* All time information is encoded in units of 0.4 ns.
+* All timestamps have 13 Bit
+  * Overflow happens after 3276.8 ns
+* All hits can be assumed to be in a window between -2000 and +1200 ns relative to the reference time
+
+* Header word
+  * always sent as first word
+  * (31..24) TDC Header marker 0xDC
+  * (19..16) data format version 0
+  * (12..0) Reference Time timestamp
+
+* Hit data words
+  * all remaining words after header
+  * (12..0) Trailing Edge timestamp
+  * (25..13) Leading Edge timestamp
+  * (26) Error Flag
+  * (31..27) Channel number (0 - 31)
+  
+  
+Data Format (v1)
+--
+
+* Same as v0, but channel numbers are encoded differently
+  * to support setups with more than 32 channels
+  * not to be used in MDC, but e.g. on Trb5sc
+  * The Header word followed by an arbitrary amount of data is repeated N = ceil(channels/3) times, e.g. 3 times for a 48 channel TDC.
+  * Bit 31 distinguishes between Header words and hit words
+
+* Header word
+  * 0xDC01rrrr
+  * (31..24) TDC Header marker 0xDC
+  * **(23..20) TDC Channel group number**
+  * **(19..16) data format version 1**
+  * (12..0) Reference Time timestamp
+
+* Hit data words
+  * (12..0) Trailing Edge timestamp
+  * (25..13) Leading Edge timestamp
+  * (26) Error Flag
+  * **(30..27) Channel number (0 - 15)**
+  * **(31) TDC Hit word marker (always 0)**
+  
+
+  
+  
-- 
2.43.0