FILE packets.txt VERSION 1.00 DATE 22-feb-1991 E789 DA Upgrade Packets In the upgraded E789 Data Acquisition (DA) System data flow is encapsulated in "Packets." For backwards compatibility with existing online sampling and offline analysis systems it is imperative that a Packet be a straightforward generalization of the E605/E772 Logical Record construct. Also, existing Logical Record Types must not be reformatted and new Logical Record Types must be compatible with them, such that data streams containing mixtures of old and new types will not break existing software. A Logical Record consists of a Logical Recorder Header followed by the Logical Record Body, with the format: bit # 15 . . . . . . 8 7 . . . . . . 0 ------------------------------------- word # 0 | 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 | \ |-----------------------------------| \ 1 | 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 | \ |-----------------------------------| - LR Header 2 | LR Type (x)|IWC (hi 8 bits) | / |-----------------------------------| / 3 |Inclusive Word Count (lo 12 bits) | / |-----------------------------------| --- | | \ . | | \ | | \ . | | \ | | - LR Body . | | / | | / | | / N-1 | | / ------------------------------------- where (x) indicates a possible 1-bit overflow of the IWC for Data Logical Records only. Note that Logical Records are built with unsigned short int's, from historical connections to the PDP-based data acquisition system. We retain this structure for compatibility with existing offline analysis software. The first two words with all bits on provide the basic flag for a Logical Record. The Inclusive Word Count (IWC) is the number of (16-bit) words, including the IWC itself, contained in the current Logical Record. This, together with the Logical Record Type, a simple identifier, speeds searches for particular types of information. The Inclusive Word Count and the Logical Record Type will be further detailed below. Finally, note that the LR Body should always be self-describing. Usually it consists of a sequence of blocks each preceded by a count of the number of words to follow in the corresponding block. A Packet consists of at least two Logical Records, a Packet Header followed by the Packet Body. A Packet Header has the format: bit # 15 . . . . . . 8 7 . . . . . . 0 ------------------------------------- word # 0 | 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 | \ |-----------------------------------| \ 1 | 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 | \ |-----------------------------------| - LR Header 2 | LR Type | IWC (hi 8 bits) | / |-----------------------------------| / 3 | Inclusive Word Count (lo 12 bits) | / |-----------------------------------| --- 4 | Serial Number (hi 15 bits) | \ |-----------------------------------| \ 5 | Serial Number (lo 15 bits) | \ |-----------------------------------| | 6 | Time Stamp (hi 15 bits) | | |-----------------------------------| | 7 | Time Stamp (lo 15 bits) | | |-----------------------------------| | 8 | Source ID (hi 15 bits) | | |-----------------------------------| | 9 | Source ID (lo 15 bits) | | |-----------------------------------| \ 10 | Destination ID (hi 15 bits) | - LR Body |-----------------------------------| / 11 | Destination ID (lo 15 bits) | | |-----------------------------------| | 12 | Flags (hi 15 bits) | | |-----------------------------------| | 13 | Flags (lo 15 bits) | | |-----------------------------------| | . | | | . | Packet-Type-specific | | . | | / | Information | / N-1 | | / ------------------------------------- The various elements of this header structure will be discussed in more detail below. Here we emphasize that the number N of (16-bit) words must always be even so that these records can always be moved within the VME portion of the new DA system by an integer number of longword (D32) transfers. The Packet Body may consist of one or more Logical Records. This arises because each step of processing/moving data from place to place in the system will generally add "framing" information, much as in modern, layered, network communications models. For our DA system an adequate amount of framing can be obtained while also maintaining backwards compatibility by merely prefixing an additional, new LR to make a Packet Header for the new Packet. For example, a Formatted Events Packet consists of a Formatted Events Packet Header followed by a "Subsumed" Raw Events Packet Header concatenated with a Minispill Table Of Contents Logical Record concatenated with a Formatted Events Data Logical Record: ------------------------------------ | Formatted Events Packet Header | Packet Header |==================================| --- | (Subsumed) Raw Events Pkt Hdr | \ |----------------------------------| \ | Minispill Table of Contents LR | - Packet Body |----------------------------------| / | Formatted Events Data LR | / ------------------------------------ --- I.e., raw data from the data acquisition front end is collected in "minispill" buffers. Each such buffer is processed by the Raw Packet Builder task into a Raw Events Packet and passed into a repository called the Raw Packet Pool. Raw Events Packets are fetched from the Raw Packet Pool and processed by the Packet Formatter task into Formatted Events Packets which are then deposited into a Formatted Packets Pool. To provide audit trails (for both software and hardware monitoring and validation) the input-Packet Header is retained but "subsumed" so as to become part of the output-Packet Body. The input-Packet Body similarly may be retained to become part of the output-Packet Body. Such conditions are flagged by fields in the Logical Record Type (LRT) contained in the upper byte of the third (16-bit) word of the Logical Record Header: bit # 15 14 13 12 . . . 8 ---------------------------------- | 0 | R | S | H n n n n | ---------------------------------- Bits 11-8 provide the base logical record "type." Bit 12 H is set if the current Logical Record is a Packet Header. Bit 13 S is set if the current Logical Record is a Packet Header, but the original Packet has been subsumed into a new Packet. Bit 14 R is set if the current Logical Record is a Subsumed-Packet Header, but the original Packet Body has been retained and immediately follows (presumably for diagnostics only). Bit 15==0 always, to avoid conflicts with event data First/Last Word (FW/LW) tags. To date online and offline software have assumed the following Logical Record Types: Type Definition ---- ---------- 1 Begin Run 2 End Of Spill 3 MegaMemory Table Of Contents 4 MegaMemory (formatted) event Data 5 MegaMemory (formatted) event Data 6 Comment (old? offline only?) With the aforementioned encoding scheme we may now have: PH LR Type PB LR Type Definition ---------- ---------- ---------- 17. 1. Begin Run 18. 2. End Of Spill 19. 3. (Minispill) Table Of Contents 20. 4. Formatted Event Data 21. 5. --- defunct --- 22. 6. Comment 23. 7. --- unused --- 24. 8. Raw Event Data 25. 9. End Of Run 26. 10. Exception 27. 11. available for future 28. 12. " " " 29. 13. " " " 30. 14. " " " 31. 15. " " " All old LR types are thus maintained and all new LR types are greater than 8. Note that Type-5 will no longer arise because the largest IWC for any Event Data LR should be < 2**(17) since the minispill buffers only have 2**(16) 16-bit words of memory, whereas in the past this was not necessarily the case with the MegaMemory. Also, we will explicitly avoid usage of PB LR Type-7 to provide a boundary between old and new acquisition systems. Note that if we reuse LR Type-3 for Minispill TOC we must be sure to format (at least) the first 8 words precisely as for the MegaMemory, since it is known that the offline analysis codes already use this information. Otherwise we must utilize a new LR type (complete backwards compatibility would actually demand the latter approach). Finally, we note that the Packet Header LRT is merely 16. greater than, and the Subsumed Packet Header LRT is merely 48. greater than, the corresponding Packet Body LRT. The Inclusive Word Count in any Logical Record is defined to be the total number of (16-bit) words in the record, including those used for the Logical Record Header. The specific format detailed above is required for backwards compatibility with existing software. Again, because the minispill buffers only have 2**(16) 16-bit words of memory, all LR's should have an IWC < 2**(17). The Packet Header Serial Number, Time Stamp, Source ID, Destination ID, and Flags are newly defined elements specific to Packet Header Logical Records. The Serial Number is any pattern that can be used together with the Packet Header LR Type to uniquely identify any one Packet. The Time Stamp (probably system kernel ticks) provides information on the creation time of the Packet. The Source and Destination ID's are meant to provide some indication of the origin and disposition of the Packet within the DA system; their specific definitions may vary from Packet-type to Packet-type as required for relevance. The Flags element provides a compact means for rapidly accessing additional information concerning the Packet without parsing the Packet-Type-Specific elements. I.e., this Packet Header element is intended to convey information nonspecific to any particular Packet Type. We admit at most 30 one-bit flags to avoid conflicts with event data FW/LW tag words. Here we define Flag-0 (i.e., the 2**0 bit of Packet Header Word-13) to be a Packet Complete Flag. Until this flag is set (1 or True) a Packet Consumer is not permitted to remove the associated Packet from the source Packet Pool. The Packet Producer will set this flag once it has completed insertion of all necessary data into the associated structure(s), to make a Valid Packet. This, for example, gives the Raw Packet Builder a simple means of inserting a "bubble" into the Raw Packet Pool, such as will be necessary to reserve space for an End Of Spill Packet, and gives the Packet Formatter an equally simple means of waiting for that bubble to be "filled" with a completed End Of Spill Packet. Here we note that the Raw-Events Packet-Body Logical Record data will have two internal features which demand attention for its proper interpretation. They arise because (a) the current minispill raw data buffering hardware (Creative Electronics Systems HSM 8170/1/5 high-speed memories) is "word-little-endian" whereas all the rest of the DA system VME hardware is thoroughly "big-endian" in addressing scheme; and (b) to maximize DA system throughput the HSM's will be drained by D32 transfers. Thus, within any longword an included pair of raw data words will be swapped with respect to all other "processed" words (the Packet Formatter will undo this word swap to put Formatted Events data words in an internal order commensurate with all other quantities). And for events generating an odd number of 16-bit data words the raw events data will include a "garbage" word in the lower-VME-address-word of the final longword (the Packet Formatter will trash this garbage word as it is building the associated Formatted Events Packet). The latter will be detectable through comparison of information from the HSM Address Pointer and Word Count registers (in the Packet-Type-Specific elements of the Raw Events Packet Header) with the associated Raw Events Packet Data LR IWC. For speed in subsequent processing we allocate additional Flags to indicate such conditions, as follows: bit # 15 . . . . . . 8 7 . . 4 3 2 1 0 --------------------------------------------------- word # 12 | 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 | |-------------------------------------------------| word # 13 | 0 0 0 0 0 0 0 0 0 0 0 BP TG WS BS PC | --------------------------------------------------- PC == 1 ==> Packet is Complete BS == 1 ==> Bytes are Swapped within words WS == 1 ==> Words are Swapped within longwords TG == 1 ==> last logical word is Trailing Garbage BP == 1 ==> Broadcast Packet (e.g, End Of Spill, Comment, ...) The swapping implied by the BS & WS bits is relative to the standard (big-endian) VME addressing mode. Note that the BS/WS/TG bits refer to the data elements and not the LR header elements in the associated Packet Data Logical Record(s). Clearly, the location of the "last logical word" is dependent on the BS & WS bits. Finally, we also note that a similar condition might arise with Formatted Events Packet Body Logical Records, depending on both the number of data words and the number of events within the corresponding minispill(s). But here, because of the word swap performed by the Packet Formatter, such a garbage word will appear in the higher-VME-address-word of the final longword. Therefore, if we admit a possibility for one (or at most a few) D16 transfers at the trailing end of a block of D32 transfers or the possibility of starting Logical Records on word as opposed to longword boundaries, and always keep all counts with respect to (16-bit) words, then we can always trash such garbage words by simply not transferring them (with, of course, a commensurate adjustment of the LR IWC). In fact, for backwards compatibility with existing analysis software any Formatted Events Logical Records transferred to archive _must_ have such garbage words stripped.