White Rabbit, 12-bit ID

4-bit collaboration ID (NUSTAR defined)
8-bit subcollaboration defined

31	24	23	20	19	16	15	8	7	0
0		Collaboration		Flags		Subcollaboration Defined		0

Flags

Bit	Hex Mask	Definition
1	0x1	Timestamp Error
2	0x2	Undefined
3	0x4	Undefined
4	0x8	Undefined

Collaboration ID

ID (Hex)	ID Decimal	Name
0	0	Reserved (covers original IDs)
1	1	NUSTAR General
2	2	Super-FRS Machine
3	3	R3B
4	4	HISPEC/DESPEC
5	5	Super-FRS EC
6	6	NUSTAR Other
7	7	Reserved
8	8	Reserved
9	9	Reserved
a	10	Reserved
b	11	Reserved
c	12	Reserved
d	13	Reserved
e	14	Reserved
f	15	Reserved

LMD Subevent Header (64-bit)

31		16		15		0
Subtype				Type
Version				Hardware
31	24	23	16	15		0
Control		Subcrate		ProcID
Collaboration ID		Location		Subcollaboration Free

Control (8-bit): Collaboration ID (lower 4-bits), 0 (upper 4-bits)
ProcID (16-bit) for Subcollaboration Use
Subcrate (8-bit): Location ID
Type (16-bit): 8-bit Hardware (lower 8-bits), 0 (upper 8-bits)
Subtype (16-bit): 8-bit Version (lower 8-bits), 0 (upper 8-bits)

LMD subevent header is used to steer unpacker.
If header is identical, should be able to use same unpacker (.spec file for example)
-- Philipp: counterproposal: the tuple (Version, Hardware) should fully define the data format of the payload, with the exception of the number of modules. The data format should be defined in terms of a ucesb unpacker which takes the maximum amount of available modules, though people are free to also use more constrained unpackers (which enforce e.g. that there were exactly three FEBEX cards on SFP2).

Unpacker can also be defined to ignore certain fields

Collaboration ID

Same as WR above

Proc ID

Value free for subcollaboration to allocate, presumably some ID for unpacker identification

Location

Upper 4-bits	Lower 4-bits	Meaning
0	0	Location not recorded
1	0	Super-FRS FPF Misc.
	n	Super-FRS FPFn
2	0	Super-FRS FMF Misc
	n	Super-FRS FMFn
3	0	Super-FRS FHF Misc
	n	Super-FRS FHFn
4	0	Super-FRS FLF Misc
	n	Super-FRS FLFn
5	0	Super-FRS FRF Misc
	n	Super-FRS FRFn
14/0xe	0	GSI Misc
	1	GSI FRS Target Area
	2..9	GSI FRS S1..S8
15/0xf	0	Other
	1	Test Location (Lab, etc)
	15/0xf	Virtual/Fake DAQ

Hardware

Thought upper 4-bit flags:

Bit	Hex Mask	Meaning
15	0x80	White Rabbit Timestamped
14	0x40	"Low Quality" WR (e.g. Faked from NTP)
13	0x20	Reserved
12	0x10	Reserved

QUESTION How much detail of hardware: Controller technology (VME CPU, VME MVLC, PCIe/GOSIP, etc) or hardware (VME with TDCs, etc) /

ID (0-F)	Hardware Type
0	Unknown
1	VME via CPU
2	VME via MVLC
3	GOSIP via PCIe
4	"ASIC" (e.g. AIDA, FOOT, ALPIDE,etc). Better name? -- Philipp: Ethernet from FPGA?
5	MUPPET/DOFI/SEP. (Better Name?)
0xF	Virtual/Fake hardware

Philipp: If a subevent+type should be uniquely decodable, then it might make sense to have very specific types. For example, "GOSIP data, SFP0: FEBEX4, SFP1: TAMEX4, SFP2: MPPC ROBs, SFP3: NC". These types could be allocated on demand -- if someone wants to run like this, they first create a hardware type for that.
Philipp: The VME controller does not generally affect the data format, so one might not want to specify it here.

Standard compliance verification (idea from Philipp)

We have one shared unpacker which contains all the variable-payload-length versions of subevent unpackers for (version, hardware) tuples in a git repository. This compiles into a specific standard-compliance unpacker which just matches subevents on these fields using revisit. At the start of the experiment, one would run that unpacker (upstream version) against the full data stream of all detectors. If it is happy, that means that the data format is fully specified for posteriority.
Note 0: Paranoid people might insist on running this unpacker against all data of the beamtime.
Note 1: It might be useful to deprecate old versions (e.g. with #ifdefs), so (A) we do not run an unpacker with a zillion subevents defined and (B) we enforce that deprecated versions do not accidentially get used.

Version

Subcollaboration free, should distinguish changes in data-format where unpacker is not compatible

Triggers

In general triggers can be 1-15, with comment that TAMEX/FEBEX etc only support 1-3 (Clarification needed limit)

Trigger (in MBS header) is also lost during event stitching - only one trigger can be included. If trigger contains information that is important after event stitching it should be recorded somewhere in event (e.g. TRLO-II readout)

Trigger is the standard "sync" trigger-type used in MBS and drasi and all groups. Suggested rate is 10 Hz and should be supported by all DAQs. A common source is useful for quick sync checks.

BoS /EoS spill triggers come from SuperFRS (?) and should contain WR timestamp of time when extraction starts/stops.
It could be that signal+timestamp comes directly from White Rabbit network (https://wiki.gsi.de/TOS/Timing/TimingSystemEventNumbers)

Trigger	Meaning	Notes
1	Physics/Standard
3	Pulser/Sync	Mandatory for time-sorting
2,4-11	Alternate	Available for any use
12	Beginning of Spill	From SuperFRS?
13	End of Spill	From SuperFRS?
14	Start Acq	Must not appear in data
15	Stop Acq	Must not appear in data

Philipp's notes:
0: Triggers are a field of the events, not subevents. After time-stitching, one event will have one trigger number.
1: The trloii priority encoder (and presumably ucesb --time-stitch) prioritize higher trigger numbers.
2: BoS /EoS presumably come from the ring accelerator doing the extraction? (Stephane: yes)
3: In R3B, BoS /EoS events were traditionally generated from the MTL, with the spill state being kept independently and used for gating trigger patterns and enabling/disabling Rio4 network transport.
4: Extraction-related events from the accelerator would also be a great candidate for a category of sticky events (if we get an API to read them). (Stephane: isn't it in the TDR? ;b, I used them as sticky analogue event in AGATA@PRESPEC by having a "wookpecker" electornic with a circular logic sending every 10 us a trigger until it was accepted, issue with sticky for this case is the WR could have a gitter, I mean the spill length comes then from when the trigger is accepted making people measuring it with the WR timestand attached of the accepted event gittering in a non realistic way)

Examples

DEGAS

Collaboration: HISPEC/DESPEC
Hardware: FEBEX via PCIe/GOSIP
Location: FHF1
White Rabbit: Yes

White Rabbit ID: 0x400400 - Collab (HISPEC/DESPEC), Local ID: 0x400
Type: 0x83 (131): PCie with WR
Subtype: 1 (Version 1)
Control: 4: HISPEC/DESPEC
Subcrate: 0x31 (49): FHF1
ProcID: 40

Add Example

Collaboration: ...
Hardware...
Location:
White Rabbit:

Open Questions

Comments on Hardware section welcome, what information is helpful?

Are there any "flags" worth defining?

-- NicolasHubbard - 2026-08-19