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 → Descrambler

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 which is currently not used

¹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
  • Future ASIC supports will follow the same interface with varying data field width
    • CRYO ASIC 
      • Single ASIC with 2 streams, 32 samples per row
    • ePixHRM
      • single ASIC with 16 streams, 32 samples per row

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 1: 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).

NOTE 2: Currently this is not the case. In particular the usage of last does not follow this convention. It marks the end of each row, not the end of the frame.

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 word has the same width as the AxiStreamInterface therefore a single transfer is needed to transfer a complete header information from the sanitizer to the descrambler

The header shall contain fields identifying

• Frame Sequence Number (32 bits ?)
• ASICs 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?

Not as this point, but one can envision to add the ASIC ID inside a carrier and the carrier serial number (or at least part of it)

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. 

TBDs

1. The exact format of each field in the header word
2. The current usage of SOF, EOFE and last is not the same as surf
   1. In particular, last as it is currently used, marks the end of the data in a row. 
      1. Does it? I believe we have multiple row and last is only asserted at the end of a frame, like in surf
   2. In surf usage, last would mark the end of the 'image', i.e. the last bit of data from the last row. 
3. 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)
   1. at the output the gain bit has to be the msb, during the processing stages it can be used as LSB
4. Should we call the data word a 'pixel'
   1. In LCLS usage this seems appropriate, but not in other uses like nEXO.
   2. We should not call it pixel, as described above it fails for some ASICs
5. 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)
      2. Future ASICs will have ADCs that are 12 bits, we currently have a 14 bit as the maximum so for the upcoming ASICS we can define 1 bit as error flag and 1 bit as gain
6. What should the descrambler do when
   1. SOF is not seen on what is expected to be the first word in the frame?
      1. The  descrambler sees data from the sanitizer which is a fw module in the same FPGA. Can this be an issue. I would not think so.
   2. Or, more generally, when SOF, EOFE, last=1 are not as expected.
      1. I think we should try to solve this at the sanitizer level and simplify the logic of the descrambler to assume these errors have been solved before. The sanitizer already handles (at least some of them) so I would move this responsibility there.