1---2name: protocol-layout-diagram3description: Use when a diagram must explain the bit, byte, or word layout of a protocol message, file header, register, or binary record.4---56# Protocol layout diagram78## What it is910A protocol layout diagram maps wire-order positions to named fields. It tells the reader how many bits or bytes each field occupies, where boundaries fall, which values are interpreted together, and which parts are conditional or repeated.1112## Choose it when1314- the question is “what is at offset N?” or “how is this message encoded?”15- implementation, interoperability, packet capture, or security review depends on exact widths and ordering;16- a prose table would hide alignment, reserved bits, endianness, or optional extensions.1718Use a sequence or flow diagram for message behavior. Use a data-flow diagram for movement between components. Do not use this diagram to imply that fields are sent in the order they are drawn unless wire order is explicitly stated.1920## Story and modeling21221. State the unit and orientation: bits per row, byte order, bit numbering convention, and whether offsets are absolute or relative.232. Draw the fixed header first, then conditional, repeated, and payload regions. Mark variable-length fields with their length rule.243. Give every field a name, width/range, and interpretation. Show reserved bits and whether they must be zero, ignored, or preserved.254. Separate normative wire facts from explanatory annotations. Record the specification version and section beside the title or in a legend.265. Check examples against the encoding: widths must sum to the row width, offsets must not overlap, and endianness must agree with the prose.2728## Styling and customization2930Use a restrained palette: one color for fixed framing, one for payload, one for control/flags, and a visibly distinct treatment for reserved or deprecated fields. Put bit numbers above the row and byte offsets below it. Keep labels short and move long semantics into notes. For accessibility, do not communicate field meaning by color alone; use text, patterns, or a legend.3132## Renderer routing3334- `packetdiag` is the direct diagram.zip fit for bit-field layouts; preserve its column width and field-range semantics.35- `bytefield` is useful for byte-oriented headers and payloads when a code-defined, repeatable layout is preferred.36- `wavedrom` can express registers and bus transactions when timing is part of the story, but it is not a substitute for a normative packet layout.37- `tikz` or `pikchr` can be a bespoke escape hatch when a standards-specific notation exceeds those renderers.3839Keep the user's explicit renderer choice. If no renderer is specified, choose the smallest source that preserves exact widths and explain the choice. diagram.zip does not currently provide a dedicated parser/validator for every protocol standard; a standards-aware packet editor or automatic field-sum validation would be a useful integration opportunity.4041## Review checklist4243- Is wire order, bit numbering, and unit unambiguous?44- Do widths, offsets, and alignment add up?45- Are optional, repeated, reserved, and extension fields explicit?46- Are byte order and value encoding documented?47- Is the cited specification/version recoverable?48- Can a reader distinguish normative fields from commentary without color?4950## References5152- [RFC 2360, section 3.3](https://www.rfc-editor.org/rfc/rfc2360.html#section-3.3) summarizes conventions for protocol diagrams and field representations.53- [RFC 791, section 3.1](https://www.rfc-editor.org/rfc/rfc791.html#section-3.1) is a canonical example of an Internet header bit layout and field description.54- [RFC 8200, section 3](https://www.rfc-editor.org/rfc/rfc8200.html#section-3) shows the IPv6 base-header field layout and extension-header model.55- [PacketDiag documentation](http://blockdiag.com/en/nwdiag/packetdiag-examples.html) documents the diagram.zip-supported PacketDiag source model.56- [Bytefield SVG documentation](https://bytefield-svg.deepsymmetry.org/) documents byte-oriented source forms.