Add UDP packet format docs by Tom-Willemsen · Pull Request #205 · ISISComputingGroup/ibex_developers_manual

Tom-Willemsen · 2026-05-20T08:24:30Z

No description provided.

Tom-Willemsen · 2026-05-20T08:26:06Z

+- **Bits 0..=3**: Reserved for header type
+- **Bits 4..=8**: Length of header
+- **Bits 9..=10**: Not used
+- **Bit 11**: Bad frame


What exactly constitutes a "bad frame"?

This was what that bit was used for in DAE2/3. Not sure if it was actually implemented on those designs.
So far it isn't used and I have no plans to at the moment.
Could probably make bits 31-9 "not used"

do we need a version number in the header for if we do change layout? Or can we be sure we will always be able to update all possible clients and not need to read any old data?

or that a board with old firmware gets used and confuses/crashes new clients

I think having a header type makes sense if it helps provides some flexibility in the future.
Not sure if we do want a separate marker for header length or if we combine the two.

Isn't word 2 bits 4..=8 already "length of header"?

We could almost certainly accomodate different-length headers later if they had e.g. a different "header information" word (maybe later we have a 'EndOfRunHeaderV2' header type)?

I guess i had a bit of a general design question here in that should we have a standard ISIS UDP header format that we use for anything we might do, be it detector streaming or something else in future, with the idea to be extensible and avoid the problem of some software misinterpreting a UDP packet. Maybe word 0 (marker byte) could do this to some level. Currently word 0 is fixed, word 1 is some detector specific flags, word 2 has a header type (4 bits) plus some other detector/dae specific stuff. It feels header type should be earlier on in the structure as it is more general than the information in word 1 if we think of header type as not just being "detector header type" but a general packet type?

Tom-Willemsen · 2026-05-20T08:29:41Z

+- **Bit 0**: FIFO veto
+- **Bit 1**: SMP veto
+- **Bit 2**: TS2 pulse veto
+- **Bit 3**: Wrong pulse veto


What exactly is a "wrong pulse"?

Is this e.g. not the first TS1 pulse when someone has selected "First TS1" timing source?

Tom-Willemsen · 2026-05-20T08:29:52Z

+- **Bit 2**: TS2 pulse veto
+- **Bit 3**: Wrong pulse veto
+- **Bit 4**: Unused
+- **Bit 5**: ISIS slow


What exactly does this mean?

Tom-Willemsen · 2026-05-20T08:31:14Z

+
+### Word 15: checksum
+
+- **Bits 0..=31**: Pre-DDR checksum


Think we decided to drop this checksum at this level...

FreddieAkeroyd · 2026-05-20T08:51:59Z

+### Word 8: protons-per-pulse
+
+- **Bits 0..=7**: protons-per-pulse in this ISIS frame.
+- **Bits 8..=31**: unused


DAE3 seems to send a 10 bit PPP looking at the packet definition, but i guess we don't expect to need that amount?

The DAE3 maybe sends a 10 bit PPP but the two lowest bits are padded with 0s. If required I can pad it with 0s to make it 10 bit?

FreddieAkeroyd · 2026-05-20T08:52:59Z

+### Word 6: period number
+
+- **Bits 0..=15**: Period number
+- **Bits 16..=31**: Not used


in event mode period number is just an extra metadata tag - is it worth just letting it be 32 bits?

Yea, just an extra metadata tag in event mode so I don't really mind either was on this.
Leaving it as 16 bits leaves us another 16 bits to do something else with at a later date without having to change the header length so keeps it a bit more flexible.

FreddieAkeroyd · 2026-05-20T08:59:41Z

+- **Bits 6..=9**: External vetoes
+- **Bits 10..=13**: Fast chopper vetoes
+- **Bits 14..=15**: Reserved vetoes
+- **Bits 16..=23**: Unused


Is there also a "isis not at 50hz" veto? (or is that "isis slow")

DaveTempleman

A few comments on some of the questions raised

DaveTempleman · 2026-05-28T09:10:20Z

+- **Bits 0..=3**: Reserved for header type
+- **Bits 4..=8**: Length of header
+- **Bits 9..=10**: Not used
+- **Bit 11**: Bad frame


This was what that bit was used for in DAE2/3. Not sure if it was actually implemented on those designs.
So far it isn't used and I have no plans to at the moment.
Could probably make bits 31-9 "not used"

DaveTempleman · 2026-05-28T09:16:42Z

+### Word 6: period number
+
+- **Bits 0..=15**: Period number
+- **Bits 16..=31**: Not used


Yea, just an extra metadata tag in event mode so I don't really mind either was on this.
Leaving it as 16 bits leaves us another 16 bits to do something else with at a later date without having to change the header length so keeps it a bit more flexible.

DaveTempleman · 2026-05-28T10:55:07Z

+### Word 8: protons-per-pulse
+
+- **Bits 0..=7**: protons-per-pulse in this ISIS frame.
+- **Bits 8..=31**: unused


The DAE3 maybe sends a 10 bit PPP but the two lowest bits are padded with 0s. If required I can pad it with 0s to make it 10 bit?

…ed by SCB

Tom-Willemsen · 2026-06-03T17:17:19Z

+### Word 2: Information
+
+- **Bits 0..=3**: Reserved for header type
+- **Bits 4..=8**: Length of header


Bytes or words?

Tom-Willemsen · 2026-06-03T17:26:26Z

+- **Bit 0**: End of run header marker (active low)
+- **Bit 1**: Veto frame packet header marker (active low)
+- **Bit 2**: Sample environment packet header marker (active low)
+- **Bit 3**: Not used
+- **Bits 4..=31**: Always `0xFFFFFFF`


If all bits are high is that a neutron data packet?

Tom-Willemsen · 2026-06-04T09:12:42Z

+The data comes in over UDP packets, each of which is made up of 32-bit words. All data is transmitted in big-endian
+format.


We can have multiple "messages" (headers + their data) within a single UDP packet, right?

Tom-Willemsen · 2026-06-04T09:13:28Z

+The data comes in over UDP packets, each of which is made up of 32-bit words. All data is transmitted in big-endian
+format.


Can/will the UDP packets have trailing padding bytes?

Add UDP packet format docs

4e5be87

Tom-Willemsen marked this pull request as draft May 20, 2026 08:25

Tom-Willemsen commented May 20, 2026

View reviewed changes

DDR

7bd3a6f

FreddieAkeroyd reviewed May 20, 2026

View reviewed changes

typo

84746f7

DaveTempleman reviewed Jun 2, 2026

View reviewed changes

FreddieAkeroyd reviewed Jun 2, 2026

View reviewed changes

Comment thread doc/specific_iocs/datastreaming/Datastreaming_udp_packet_formats.md Outdated

Tom-Willemsen added 2 commits June 2, 2026 17:12

correct typo

03bea85

Clarify that 'bad frame' and 'run will continue' are not currently us…

9de5ed3

…ed by SCB

Tom-Willemsen marked this pull request as ready for review June 2, 2026 16:25

Tom-Willemsen commented Jun 3, 2026

View reviewed changes

Tom-Willemsen mentioned this pull request Jun 3, 2026

Migrate to new header format ISISComputingGroup/event_udp_to_kafka#15

Open

Tom-Willemsen commented Jun 4, 2026

View reviewed changes

		The data comes in over UDP packets, each of which is made up of 32-bit words. All data is transmitted in big-endian
		format.

Conversation

Tom-Willemsen commented May 20, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

FreddieAkeroyd Jun 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

FreddieAkeroyd May 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

FreddieAkeroyd May 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

DaveTempleman left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Tom-Willemsen Jun 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

FreddieAkeroyd Jun 3, 2026 •

edited

Loading

FreddieAkeroyd May 20, 2026 •

edited

Loading

FreddieAkeroyd May 20, 2026 •

edited

Loading

Tom-Willemsen Jun 4, 2026 •

edited

Loading