SHLSIP

This defines the interfaces between the various processing stages.  These are currently AXI streaming interface. The current processing stages are thought to be

• Sanitizer → Descrambler
• Descrambler → Corrector
• Corrector → Convolver/RoiSelector

It is assumed that the outbound stream of the previous stage is the inbound stage of the subsequent stage.

Sanitizer, Outbound Stream

The Sanitizer's outbound AXI stream is defined as

The widths of WUser, Wid and WDest  are taken from the surf defaults.

NOTE: shlsip only uses WUser, so WDest could be set to 0 to save resources.  I believe this used to support virtual destination channels.

¹The width of the Data field depends to the configuration.  

• • In a 2 x 1 configuration of the ASICS → 192 bits
    • 2 Asics * 6 Streams/Asic * 16 bit/data word   
  • In a 4 x 1 configuration of the ASICS → 384 bits
    • 4 Asics * 6 Streams/Asic * 16 bit/data word

Frame

The sanitizer will organize its output into frames composed of a number of the AXI streaming words as defined above.  Each frame will contain all the tile data associate with one 'image' plus a header word and, optionally (TBD), a trailer word. The sideband data fields, WUser and the last value are used to identify the Start Of Frame (SOF), End of Frame with Errors (EOFE) and the last word in the frame (last).  The values and usage of these fields follows the surf conventions.

NOTE: The value of TUser field on the last word in the frame depends of whether there are no errors in the frame (0) or has errors (1).

Frame Contents - Proposal

The first word of the frame shall be a header word, followed by the data and, optionally/potentially, a trailer.

Header Word

The header shall contain fields identifying

• Frame Sequence Number (32 bits ?)
• ASIC identification.           (TBD bits)
• TBD - Possibilities/Suggestions/Off-the-wall ideas
  •  A version number
  • The processing stage (0: sanitizer, 1: descrambler, 2: corrector, etc
  • Data Description (NRows, NCols, data word format style, etc.
    
    

QUESTION: Are there 'per ASIC fields' (i.e. each ASIC has its own value for that field) and 'per sanitizer' fields?

Data Word

Each data word will contain 1 set of 6 x 16 bit words for each ASIC, so 12 x 16 bits for a 2 x 1 and 24 x 16 bits for a 4 x 1 arrangement. The 16-bit word itself shall be formatted as

NOTE: Dionisio at one time indicated that the ASIC returns the data with the gain bit in bit 0 with the sanitizer moving it to bit 15. In fact, it is more convenient for the gain bit to be in bit 0.  When the correction, which involves subtracting a dark image value, is done, the result is that 14-bit unsigned ADC value goes to a 15-bit signed value.  It is more natural that the sign bit occurs in its customary MSB,  meaning the corrected ADC value occupies bits 1-15 and the gain bit, bit 0. 

The first data word shall contain the first valid data as read by the sanitizer.  This normally will be the data associated with the column 0 of each stream, except in ePixHR10k where the hardware presents column 30 of each stream first.  Said another way, the sanitizer need not pad error-free data with any dummy data.  

Trailer Word

While currently not used, a trailer word could also be defined.  This could be used to summarize any errors, provide a checksum, etc, basically any information that cannot be known until all the data has been seen/processed.

NOTE: Personally (I JJ) favors a trailer to summarize errors.  While counters are nice and even necessary, they provide little to no help in diagnosing the exact nature and cause of the error after the data has been received.  The descrambler, for example, could use this to note SOF not seen on the first word, error in the sequence number, incorrect value of last, etc. Any such error would set EOFE, but the trailer could provide additional information to help diagnose the error.  I suspect, if and when we get to classifying the data, the trailer word will be the ideal place for this information. 

TDBs

1. The exact format of each field in the header word
2. Whether to move the gain bit to the LSB with the ADC value in bits 1-14 and the MBZ (must be zero) bit in the MSB (bit 15)
3. Should we call the data word a 'pixel'
   1. In LCLS usage this seems appropriate, but not in other uses like nEXO.
4. What the sanitizer should send in case of errors.  Possibilities are
   1. If a problem with the read of the data from the ASIC
      1. the sanitizer could send the remaining data as all 1s (could repurpose the MBZ as an error bit)
5. What should the descrambler do when
   1. SOF is not seen on what is expected to be the first word in the frame?
   2. Or, more generally, when SOF, EOFE, last=1 are not as expected.