Chapter 14 — Datagram Protocol

The Datagram protocol provides reliable 0-72 byte addressed transfers. It is the primary mechanism for configuration memory access (read/write) and is used by CDI, ACDI, and firmware upgrade features.

14.1 Two-Phase ACK Protocol

Every datagram request follows a two-phase acknowledgement pattern. The Reply Pending bit (0x80) is always set in the Datagram Received OK reply, indicating that a response datagram will follow:

14.2 Address Space Routing

The datagram handler routes incoming datagrams to per-address-space callbacks based on the address space byte. The standard spaces are:

14.3 Command Structure

The first byte of the datagram payload identifies the command type, and the second byte identifies the sub-command:

14.4 Read Handler Flow

When a Read command arrives, the handler:

1. Sends Datagram Received OK (Reply Pending = 1).
2. Extracts the address space byte from the datagram.
3. Routes to the matching read callback (e.g., memory_read_space_configuration_memory).
4. If the callback is NULL, sends a Datagram Rejected with SUBCOMMAND_UNKNOWN.

14.5 Write Handler Flow

Write commands follow the same pattern: acknowledge, extract address space, route to the write callback. The Write Under Mask variant allows bitwise modification of configuration memory (useful for flag bytes).

14.6 Retry Logic

When a Datagram Rejected reply is received:

• Temporary error (0x2xxx): The resend_datagram flag is set on the node, and the stored datagram will be retried.
• Permanent error (0x1xxx): The stored datagram is freed and the retry state is cleared.

A Datagram Received OK clears the resend flag and frees the stored datagram buffer. The check_timeouts() function scans for timed-out pending datagrams that have exceeded their maximum retry count.

14.7 Configuration Memory Operations

Beyond read/write, the datagram handler supports several configuration management commands: