Warning, /L1Trigger/DemonstratorTools/notes.md is written in an unsupported language. File is not indexed.
0001 Common L1T utilities for demonstrators
0002 ======================================
0003
0004 This package contains a prototype implementation of subsystem-agnostic utility functions and
0005 classes for converting between emulator input/output objects (i.e. C++ objects representing
0006 tracks, calo clusters, muon TPs, vertices etc) and the I/O buffer text files (i.e. the files
0007 that are used to store data that is loaded into or captured from FPGAs, and used to play/capture
0008 data in HDL simulations). The motivation for these tools and their scope was briefly summarised
0009 in the L1T meeting on 16th February (see slides [here](https://indico.cern.ch/event/1008519/contributions/4234188/attachments/2191061/3703176/l1tPhase2_cmsswBufferIO_20210216.pdf))
0010
0011 A brief tour of the code:
0012
0013 * One example EDAnalyzer - `GTTFileWriter` - that creates text files for loading into
0014 input buffers of the GTT board (as well as reference files for outputs of GTT boards)
0015 * Source: `plugins/GTTFileWriter.cc`
0016 * Test cmsRun config: `test/gtt/createFirmwareInputFiles_cfg.py`
0017 * One example EDProducer - `GTTFileReader` - that reads text files that would be
0018 produced by GTT vertex-finding FW
0019 * Source: `plugins/GTTFileReader.cc`
0020 * Test cmsRun config: `test/gtt/verifyFirmwareOutput_cfg.py`
0021 * Main utility classes:
0022 - `BoardData`: Represents the data stored in I/O buffers
0023 - `ChannelSpec`: Simple struct containing parameters that define a link's packet
0024 structure (e.g. TMUX period, gap between packets)
0025 - `EventData`: Represents the data corresponding to a single event, with links
0026 labelled using logical channel IDs (`LinkId` class instances) that are local
0027 to any given time slice (e.g. ["tracks", 0] -> ["tracks", 17] for links from
0028 TF). Used to provide an event-index-independent interface to the
0029 `BoardDataWriter` & `BoardDataReader` classes - i.e. to avoid any need to keep
0030 track of `eventIndex % tmux` when using the reader & writer classes for boards
0031 whose TMUX period is less than any of their upstream systems.
0032 - `BoardDataReader`: This class ...
0033 1. reads a set of buffer files
0034 2. verifies data conforms to expected structure
0035 3. splits out each event; and
0036 4. returns data for each event in turn via `getNextEvent()` method
0037 - `BoardDataWriter`: Essentially, does the opposite of the reader -
0038 1. accepts per-event data via `addEvent` method
0039 2. concatenates events according to specified structure; and
0040 3. automatically writes out pending data to file whenever the limit on the
0041 number of frames per file is reached.
0042
0043 (Note: For simplicity this code has been put in its own package during development,
0044 but this might not be its final location.)
0045
0046 Given the above, the contents of `GTTFileWriter.cc` and `GTTFileReader.cc`
0047 should be mostly self-explanatory, but a couple of additional notes:
0048
0049 * These `.cc` files each contain some hardcoded constants defining the link TM periods,
0050 TM indices, packet structure etc. that are used to create the `BoardDataReader`/`BoardDataWriter`
0051 instance (so that it can correctly separate/concatenate events).
0052 * At least some (if not all) of these types of constants should eventually be read from
0053 config files, to avoid e.g. needing to recompile code when the latency of an algo changes
0054 * The EDAnalyzer/EDProducer analyze/produce methods use functions from the 'codecs' directory
0055 to convert between EDM collections and vectors of `ap_uint<64>`.
0056
0057 Finally: Suggestions (and implementations) for improvements most welcome, but please get in
0058 touch with Tom Williams about these before writing large amounts of code, to avoid duplicating
0059 efforts or divergent solutions to the same problem.
