Bytefield

Updated
View as text
Open in Confluence
Open in ChatGPT Open in Claude

Bytefield draws byte and bit field diagrams, including nested structures and variable-length gaps. It is written in a small Clojure-flavoured syntax, which looks unusual and is quickly learned.

It is the best tool here for file formats and register maps.

#What it is good at

  • File format documentation.

  • Embedded register maps and flash layouts.

  • Structures with variable-length sections, which fixed grids cannot express.

#What it draws

Element

Syntax

Column headers

(draw-column-headers)

Field

(draw-box "length" {:span 4})

Variable region

(draw-gap "payload")

Styling

(defattrs :bg-green {:fill "#a0ffa0"})

Close

(draw-bottom)

#A worked example

A file header with a fixed part and a variable body:

Bytefield

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

(defattrs :head {:fill "#e6eeff"})
(defattrs :body {:fill "#fff4e0"})

(draw-column-headers)

(draw-box "magic (0x43 0x41 0x50 0x44)" {:span 4 :attrs :head})
(draw-box "ver" {:span 1 :attrs :head})
(draw-box "flags" {:span 1 :attrs :head})
(draw-box "header len" {:span 2 :attrs :head})
(draw-box "body length" {:span 4 :attrs :head})
(draw-box "created at (unix seconds)" {:span 8 :attrs :head})
(draw-gap "body (body length bytes)" {:attrs :body})
(draw-box "crc32" {:span 4})
(draw-bottom)

#A few things that catch people out

  • State endianness once at the top of the page. The diagram cannot show it.

  • Draw padding explicitly, or the diagram implies fields are adjacent when they are not.

  • Use draw-gap for variable regions rather than guessing a size.

Thirty-one languages. Nobody knows them all.