PacketDiag

PacketDiag turns bit ranges into a wire format diagram: a grid of the right width with each field spanning the right number of bits.

It removes the entire class of errors that comes from drawing header diagrams by hand.

#What it is good at

• Protocol specifications and RFC-style documentation.

• Custom binary protocols where offsets must be exact.

• Explaining an existing header in a design document.

#What it draws

#A worked example

A custom message header, 32 bits wide:

The source, which you can paste into a new diagram and edit:

packetdiag {
  colwidth = 32;
  node_height = 60;

  0-7: Version;
  8-15: Type;
  16-31: Length;
  32-63: Message id;
  64-95: Timestamp;
  96-103: Flags;
  104-127: Reserved;
}

#A few things that catch people out

• colwidth must match the real word size or every offset misleads the reader.

• Ranges are inclusive on both ends, so 0-15 is sixteen bits.

• For byte-oriented structures with nesting, Bytefield is the better fit.

#Related

Thirty-one languages. Nobody knows them all.