Updated beamlet packet definition, now without lanes.

applications/lofar2/doc/prestudy/station2_sdp_icd.txt

@@ -31,6 +31,16 @@ From top L# level to implementation L# level the ICD should read like a document
 Eye opener: Hence the ICD is like a normal written document, the difference is that all sections are captured by numbered interfaces and definitions in Polarion, so that they can be traced and referred to.
 The template should only contain the structure and hidden information for the editor. The read only text should only contain a link to the ICD general explanations, to ensure that nearly all text is manually written tekst.
 
+###################################################################################################
+# Timestamps
+
+
+NTP: 32b unsigned seconds + 32b fraction, since 1 Jan 1900 --> overflow at 06:28:16 UTC on Thursday, 7 February 2036
+
+Unix: 32b signed seconds, since 1 Jan 1970 --> overflow at 03:14:08 UTC on Tuesday, 19 January 2038
+
+BSN: 64b subband periods, since 1 Jan 1970
+
 
 ###################################################################################################
 # L1 ICD 11108 STAT-NW
@@ -161,6 +171,38 @@ UDP link control
 
 --> Total 16 Bytes
 
+###################################################################################################
+# ASTRON_RP_1402_RSP_SDO_interface_specification
+
+DP channel:
+16b reserved
+ 8b RSP ID
+ 2b reserved
+ 1b RSP clock frequency
+ 2b SDO mode
+ 2b RSP lane ID
+ 
+DP BSN:
+ 1b sync
+13b reserved
+50b BSN
+ 
+###################################################################################################
+# ASTRON_RP_1403_UDP_SDO_interface_specification
+
+59b reserved 
+ 1b RSP clock frequency
+ 2b SDO mode
+ 2b RSP lane ID
+16b Station ID
+16b Nof words per block
+16b Nof blocks per packet
+ 1b sync
+13b reserved
+50b BSN
+
+--> Total 22 octets
+
 ###################################################################################################
 # L1 ICD 11109 STAT-CEP
 
@@ -224,14 +266,17 @@ so about 2 * NOF_LANES * packet size number of octets of RAM. For example 2 * 16
 The FPGA has 2713 M20k, so this is 128/2713 ~= 5% of the internal BRAM resources.
 
 The total number of streams to CEP then becomes NOF_BEAMSETS * NOF_LANES.
- 
+
+
+
 - 1 Byte, MARKER
   . Like in APERTIF and ARTS, may be useful to quickly recognize the data packet.
-  . Beamlets : 20
-  . Transient: 21
-  . SST      : 22
-  . BST      : 23
-  . XST      : 24
+  . Beamlets: 98 = 0x62 = 'b'
+  . Other UDP packets can use e.g:
+    . Transient: 't' = 116 = 0x74
+    . SST      : 'S' = 83 = 0x53
+    . BST      : 'B' = 66 = 0x42
+    . XST      : 'X' = 88 = 0x58
   
 - 1 Byte, VERSION_ID
   . 2,3,4 for LOFAR1
@@ -239,7 +284,7 @@ The total number of streams to CEP then becomes NOF_BEAMSETS * NOF_LANES.
   
 - 4 Byte, OBSERVATION_ID
     Instead of CONFIGURATION_ID 8b (used in LOFAR1? intended to refer to the parset that defines this observation)
-    The observation ID provides the hook to information on e.g. RCU mode, f_adc = 200 MHz, 160 MHz, Nyquist zone
+    The observation ID provides a hook to information on e.g. RCU mode, f_adc = 200 MHz, 160 MHz, Nyquist zone
     (0, 1, 2), critically PFB, oversampled PFB, nof antenna in array (core, LBA, HBA inner to make HBA international look like HBA remote), maximum S_ant = 192.
   . etc
 
@@ -251,9 +296,18 @@ The total number of streams to CEP then becomes NOF_BEAMSETS * NOF_LANES.
 - 4 Byte, SOURCE_INFO
     Only include info that can be inserted by SDP, without explicit write by SC. Therefore e.g. RCU mode,
     Nyquist zone, nof antenna in array are not included.
-  . 1b f_adc = 200 MHz, 160 MHz, sample rate
-  . 1b t_pfb = PBF type, 0 critically PFB, 1 oversampled PFB (rather than p, q for R_os = p/q)
-  . 1b payload_ok, 0 payload ok, 1 one or more blocks in payload have data errors
+    The packet header does not contain all info to derive the RF frequency, because it does not contain the
+    subband-beamlet mapping R_bsub. Therefore it is not necessary to include the Nyquist zone information in 
+    the header. However, just for information the Nyquist zone is useful to have in the header. 
+  . 1b f_adc, sample clock frequency of the ADC, 0 = 160 MHz, 1 = 200 MHz
+  . 2b nyuist_zone
+  . 1b pfb_type, 0 = critically PFB, 1 = oversampled PFB (rather than p, q for R_os = p/q)
+       - The f_adc and t_pfb are in the header, because this information is sufficent to know the subband
+         frequency grid (f_sub = f_adc / N_fft = 195312.5 or 156250 Hz) and the subband sample rate
+         (R_os * f_sub). 
+  . 1b payload_error, 0 payload ok, 1 one or more blocks in payload have data errors
+       - a single payload error bit means that all blocks in the payload get discarded if only only block
+         has an error.
        - no need for indicator bit per block, assuming errors are rare and will result in loss of
          multiple blocks anyway
   . 5b beamlet_width in number of bits
@@ -263,38 +317,75 @@ The total number of streams to CEP then becomes NOF_BEAMSETS * NOF_LANES.
   . 6b pn_id = UniBoard2 FPGA ID
        - Instead of RSP_ID in LOFAR1
        - 16 FPGAs for LBA, 16 for HBA in International Station, so maximum 32, but use one bit extra
+       - The PN ID is useful for fault diagnoses, to know the PN in SDP from which the data originated.
        - The pn_id implicitly also reveals the antenna array ID (core station 1 LBA, 2 HBAS, 3 HBA0, 4 HBA1, ...)
          Therefore it is not necessary to define an explicit antenna ARRAY_ID field that would need to be
          filled in by SC.
   . 12b beamlet_scale
-    - 18b --> 8b, scale = 1 yields lowest bits, scale = 1024 (= 11b) yields highest bits
-    - 18b --> 4b, scale = 1 yields lowest bits, scale = 4096 (= 13b) yields highest bits
-    - scale = 1 --> suitable if only one antenna input was used for the beamlet
-    - scale = 12, 24, 48, 96 --> to account for number of antennas in beam 
-    - scale > 96 --> to have more dynamic range, but less sensitivity. More dynamic range only makes
+    - 18b --> 8b, beamlet_scale = 1 yields lowest bits, beamlet_scale = 1024 (= 11b) yields highest bits
+    - 18b --> 4b, beamlet_scale = 1 yields lowest bits, beamlet_scale = 4096 (= 13b) yields highest bits
+    - beamlet_scale = 1 --> suitable if only one antenna input was used for the beamlet
+    - beamlet_scale = 12, 24, 48, 96 --> to account for number of antennas in beam 
+    - beamlet_scale > 96 --> to have more dynamic range, but less sensitivity. More dynamic range only makes
                      sense in 8b mode (or 16b mode, but not in 4b or 2b mode), therefore given the
-                     18b beamlet sum the maximum scale = 1024.
-    - In SDP the beamlet scale function extracts the lowest 8b from the 18b beamlet sum, after having
-      multiplied the beamlet sum by 1/scale. Internally the beamlet scale function uses an 18b 
-      unsigned representaion of the 1/scale fraction, so 2**18 / scale. This yields:
-      scale = 1    --> 262144
-      scale = 96   -->   2731
-      scale = 1024 -->    256
-
-- 2 Byte, BEAMLET_INDEX = SET_INDEX * NOF_BEAMLETS_PER_SET + bl * NOF_LANES + LANE_INDEX
-  . NOF_BEAMLETS_PER_SET = 488
-  . SET_INDEX in range(number of beamsets, currenlty 1 beamset per antenna array)
-  . NOF_LANES 8b
-  . LANE_INDEX 8b in range(NOF_LANES)
+                     18b beamlet sum the maximum beamlet_scale = 1024.
+    - In SDP the beamlet beamlet_scale function extracts the lowest 8b from the 18b beamlet sum, after having
+      multiplied the beamlet sum by 1/beamlet_scale. Internally the beamlet beamlet_scale function uses an 18b 
+      unsigned representation of the 1/beamlet_scale fraction, so 2**18 / beamlet_scale. This yields:
+      beamlet_scale = 1    --> 262144
+      beamlet_scale = 96   -->   2731
+      beamlet_scale = 1024 -->    256
+
+- 1 Byte, reserved (= 0)
+
+- 2 Byte, BEAMLET_INDEX = beamset_index * nof_beamlets_per_set
+  . nof_beamlets_per_set = S_sub_bf = 488
+  . nof_beamsets = 1, fixed for LOFAR2.0 stage 1 one beamset per antenna array
+  . beamset_index = 0 in range(nof_beamsets).
   . global beamlet index of first beamlet in block
     -   0: 487 for beamset 0
     - 488: 975 for beamset 1, etc
     - can fit maximum 2**16 / 488 = 134 beamsets
+    
+- 1 Byte, NOF_BLOCKS_PER_PACKET
+  . Multiple beamlet time slots in one packet to increase payload efficiency.
+  . Maximum NOF_BLOCKS_PER_PACKET is 4, because: 4 * 1952 = 7808 octets < 9000 Jumbo
+
+- 2 Byte, NOF_BEAMLETS_PER_BLOCK
+   . Fixed 1 * N_pol * S_sub_bf = 976 for W_beamlet = 8b beamlets in LOFAR2.0 stage 1, but could be
+     used to send less beamlets.      
+   . Maximum NOF_BEAMLETS_PER_BLOCK:
+     - W_beamlet = 8b : 1 * N_pol * S_sub_bf = 2 * 488 =  976 beamlets, * 8b * N_complex = 1952 octets
+     - W_beamlet = 4b : 2 * N_pol * S_sub_bf = 4 * 488 = 1952 beamlets, * 4b * N_complex = 1952 octets
+     - W_beamlet = 2b : 4 * N_pol * S_sub_bf = 8 * 488 = 3904 beamlets, * 2b * N_complex = 1952 octets
+   . Instead of NOF_BEAMLETS_PER_BANK in LOFAR1
+   . LOFAR1 NOF_BEAMLETS_PER_BLOCK = 61 (dual pol beamlets, 4 streams):
+  
+- 2 Byte, BLOCK_PERIOD
+  . 13b Subband period T_sub in ns resolution, 5120 ns @ 200 MHz, Ros = 1
+  
+- 8 Byte, BSN
+  . 50b Block Sequence Number
+    - Instead of 32b seconds TIMESTAMP and 32b BLOCK_SEQUENCE_NUMBER within second of LOFAR1
+    - Block Sequence Number (BSN) used to detect lost blocks and to align blocks from different stations
+    - BSN unit T_sub, 50b yields > 100 year span (1970 - 2070)
+    
+--> Total 1 + 1 + 4 + 2 + 4 + 1 + 2 + 1 + 2 + 2 + 8 = 28 Bytes
+  
 
-  . stream index = SET_INDEX * NOF_LANES + LANE_INDEX
+  
+Obsolete fields:
+
+- 1 Byte, BEAMLET_STEP
+  . Index increment of subsequent beamlets in block
+  . NOF_LANES 8b
+  . LANE_INDEX 8b in range(NOF_LANES)
+  . BEAMLET_STEP = NOF_LANES
+  . BEAMLET_INDEX = beamset_index * nof_beamlets_per_set + bl * NOF_LANES + LANE_INDEX
+  . stream index = beamset_index * NOF_LANES + LANE_INDEX
     - Separate destination address per stream
-    - no need to have an stream index field, because the CEP only needs to know the beamlet index.
-    - the beamlet index for each sample follows from BEAMLET_INDEX, BEAMLET_STEP, NOF_BEAMLETS_PER_BLOCK
+    - No need to have an stream index field, because the CEP only needs to know the beamlet index.
+    - The beamlet index for each sample follows from BEAMLET_INDEX, BEAMLET_STEP, NOF_BEAMLETS_PER_BLOCK
       and NOF_BLOCKS_PER_PACKET
     - LOFAR1 supports 4 streams (4 lanes from RSP ring, staggered so rsp_id identifies lane)
     - LOFAR2.0 preferrably supports >> 4 streams
@@ -302,45 +393,20 @@ The total number of streams to CEP then becomes NOF_BEAMSETS * NOF_LANES.
     - CEP with N processing nodes would like N streams, Cobalt has N = 22
     - S_sub_bf = 488 = 2*2*2* 61, so only NOF_LANES = 1, 2, 4, and 8 yield a fixed integer number
       of NOF_BEAMLETS_PER_BLOCK.
-
-    
-- 1 Byte, BEAMLET_STEP
-  . Index increment of subsequent beamlets in block
-  . BEAMLET_STEP = NOF_LANES
-  ? Is it useful to support BEAMLET_STEP = NOF_LANES > 1 at SDP but < 22 which is optimum for CEP?
-  
-  
-- 2 Byte, NOF_BEAMLETS_PER_BLOCK
-   . Equals floor or ceil of NOF_BEAMLETS_PER_SET / NOF_BEAM_LANES dependent on LANE_INDEX,
-     so redudant if all beamlets are send, but could be used to send less beamlets.
-   . Instead of NOF_BEAMLETS_PER_BANK in LOFAR1
-   . LOFAR1 NOF_BEAMLETS_PER_BLOCK = 61 (dual pol beamlets, 4 streams):
-   . Maximum NOF_BEAMLETS_PER_BLOCK when NOF_LANES = 1:
-     W_beamlet = 8b : N_pol * S_sub_bf = 2 * 488 =  976 beamlets, * N_complex = 1952 octets
-     W_beamlet = 4b :                              1952 beamlets
-     W_beamlet = 2b :                              3904 beamlets
-  
-- 1 Byte, NOF_BLOCKS_PER_PACKET
-  . Multiple beamlet time slots in one packet to increase payload efficiency.
+  . NOF_BEAMLETS_PER_BLOCK
+    - Equals floor or ceil of nof_beamlets_per_set / NOF_BEAM_LANES dependent on LANE_INDEX,
+      so redudant if all beamlets are send, but could be used to send less beamlets.      
   . Maximum NOF_BLOCKS_PER_PACKET is about 4 * NOF_LANES, because:
     NOF_LANES = 1: 4 --> 4 * 1952 = 7808 octets < 9000 Jumbo
   . LOFAR1 has 4 streams (lanes) and 16 blocks per packet
   . LOFAR1 has payload ok bit in SOURCE_INFO to indicate that at least one block in the packet
-    has incorrect data  
-
-- 8 Byte BSN
-  . 50b Block Sequence Number
-    - Instead of 32b seconds TIMESTAMP and 32b BLOCK_SEQUENCE_NUMBER within second of LOFAR1
-    - Block Sequence Number (BSN) used to detect lost blocks and to align blocks from different stations
-    - BSN unit T_sub, 50b yields > 100 year span (1970 - 2070)
-    
-- 2 Byte BLOCK_PERIOD
-  . 13b Subband period T_sub in ns resolution, 5120 ns @ 200 MHz, Ros = 1
+    has incorrect data. To support a block ok bit would require about 128 bits in the header, 
+    to fit maximum 4 * 32 = 128 blocks per payload.
+  Is it useful to support BEAMLET_STEP = NOF_LANES > 1 at SDP but < 22 which is optimum for CEP?
+  ==> Not used, fixed NOF_LANES = 1 for LOFAR2.0, so no need to distinghuis lanes
   
---> Total 1 + 1 + 4 + 2 + 2 + 1 + 2 + 1 + 8 + 2 = 28 Bytes
   
-Remark:
-  - TX_PACKET_COUNT
+- 4 Byte, TX_PACKET_COUNT
   ==> Not useful, because then CEP needs to count Rx packets. Better send filler packets to keep the
       packet rate at the nominal rate, so that any packet loss is due to the Network and already 
       clear at OSI 2 layer using lower level tools like Wireshark.