Bytefield examples

This page reproduces all diagrams from the bytefield package documentation. Every example uses the .. bytefield:: directive — the \begin{bytefield} / \end{bytefield} wrapper is added automatically from :bitwidth:. The custom commands \colorbitbox, \bitlabel, \rotbitheader, \memsection, and \descbox are always available without any extra :packages: option.

Basic bit fields

The simplest possible diagram — a header row followed by named fields.

Simple 16-bit word

IPv4 header

A full IPv4 packet header, spanning four 32-bit rows.

IPv4 header

IPv6 header

IPv6 uses a fixed 40-byte header with no options.

IPv6 header

TCP header

TCP with all flag bits labelled using rotated single-bit headers.

TCP header

UDP header

A simple 8-byte fixed header.

UDP header

Big-endian bit numbering

Use :options: endianness=big to place bit 0 on the right and the highest bit number on the left, as is common in many hardware reference manuals.

32-bit register (big-endian bit numbering)

Custom bit height

Use bitheight to make rows taller, giving more room for multi-line labels.

Tall rows with multi-line field names

Right word group

\begin{rightwordgroup} draws a curly brace with a label to the right of the diagram, grouping one or more rows.

Grouped rows with right label

Left word group

\begin{leftwordgroup} places the curly brace and label on the left.

Left-labelled groups

Skipped words

\skippedwords draws a cross-hatched stripe indicating that a variable number of rows has been omitted.

Variable-length field with skipped words

Selective borders

Pass a border-side string as the optional first argument to \bitbox or \wordbox. Lowercase enables a side; uppercase disables it. Here adjacent cells share a border by disabling the right edge of the left cell.

Cells with selective borders

Coloured bit boxes

\colorbitbox (always available, no extra :packages: needed) draws a solid background colour behind the cell.

Coloured fields

Rotated bit labels

\bitlabel{width}{text} renders a borderless cell with the text rotated 45° upward. Use it in a header row above narrow fields. \rotbitheader is a shorthand for single-bit labels.

Status register with rotated single-bit labels

Description boxes

\descbox{width}{text} wraps long text in a centred \parbox inside the cell, allowing multi-line descriptions in wide fields.

Fields with wrapped descriptions

Memory map

\memsection{name}{size}{startaddr}{endaddr} renders a single row of a 32-bit memory map diagram. The address labels appear in the 6-bit-wide left column; the region name and size fill the remaining 26 bits.

System memory map

MTP protocol (hyperref usage)

Warning

hyperref usage is not recommended.

Regular Sphinx labels and :ref: can be used to link to a specific bytefield figure with the :name: option. E.g. TCP header.

This example is taken directly from the bytefield package documentation. It shows how hyperlinks can be embedded inside bit fields using the hyperref package.

MTP packet format

Multiple bit-header ranges

\bitheader accepts comma-separated values and ranges. Only the listed bit positions receive a label.

Sparse bit header

bitboxes shorthand

\bitboxes{n}{labels} is shorthand for a sequence of equal-width boxes. Each character of the string produces one cell.

Eight 1-bit flag fields

Little-endian numbering with lsb offset

Set endianness=little and lsb to start numbering from a value other than zero, matching hardware reference manual conventions.

Bits 16–31 of a 32-bit register