Packet and protocol headers

A header diagram is a grid of fields with bit widths, and drawing it by hand is miserable. PacketDiag and Bytefield both generate one from a short text description, and they get the offsets right.

This is the diagram that makes a binary protocol specification readable.

#When to reach for one

• Documenting a custom binary protocol or file format.

• Explaining an existing protocol header in a design document.

• Debugging, where the field boundaries are the question.

#How to draw it in Capable

#A worked example

A TCP header, generated from field widths:

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

packetdiag {
  colwidth = 32;
  node_height = 72;

  0-15: Source port;
  16-31: Destination port;
  32-63: Sequence number;
  64-95: Acknowledgement number;
  96-99: Data offset;
  100-105: Reserved;
  106-111: Flags;
  112-127: Window;
  128-143: Checksum;
  144-159: Urgent pointer;
}

#A few things that catch people out

• Set the column width to the real word size or the offsets will mislead.

• Say whether you are counting bits or bytes, once, at the top.

• Variable-length fields need a note; the grid cannot express them on its own.

#Related

Somebody will read this at 3am. Be kind.