Hardware reference

Reading this reference

On this page

The reference describes the XR819 from the point of view of the firmware’s ARM core. Addresses are the ones that core uses, not the host’s SDIO register space.

Where the facts come from

The manual separates four kinds of statement:

Kind Meaning Marked as
Layout Offsets, widths and bit positions from the firmware’s Rust declarations. Generated, so it always matches the code. Register tables and bit diagrams
Observed A recorded read, write, value or hardware experiment, or the vendor code’s behaviour. Unmarked
Inferred A role proposed from observations but not tested on its own. inferred
Hypothesis An interpretation that still needs a distinguishing test. hypothesis

A successful association exercises a path; it does not validate every bit programmed along it. Open questions lists the tests that would settle the main gaps.

Register tables

Every typed register block has a generated table with these columns:

Offset, Address
Offset from the block base and the CPU address. Descriptor-like layouts that live in memory show sizes instead of addresses.
Register
The Rust field name in capitals. A link means the bit layout is known and drawn below the table.
Type
Width and the accessor the firmware declares: RO if it only reads the register, WO if it only writes it, RW if both. A register declared for reference but not used, such as RAW_STATE, keeps the accessor it would need. This records the firmware’s use, not what the silicon permits. The download control block, a plain memory structure shared with the host, shows only the width; its descriptions say who writes each word.
Description
The doc comment from the Rust declaration: usually the value the firmware writes and why.

A line under each generated table or diagram links to the Rust source file, names the declaration and gives its size. Offsets that the firmware never touches are omitted rather than marked reserved: nothing is known about them. Reset values are not known either; the tables give the values the firmware writes.

The MAC and PHY are sparse windows that the firmware reaches by offset. Their tables are maintained by hand from the code, with an Access column instead of Type: W written, R read, RW both.

Names such as CLEAR_14, MASK_44 or PARAMETER_A0 end in their offset because the register’s function is not known beyond the value the firmware writes. Other names come from the firmware routine or variable that writes the register, such as SLOT_TIMING_428 or DEBUG_CONTEXT; they say where the register is used, not what it does, and the description says when the function is unknown.

Bit diagrams

Bits Field Description
31:24 FIELD An eight-bit field
16 FLAG A one-bit field
3:0 COUNT A four-bit field

A register is drawn in rows of eight bits, most significant first, with bits 31:24 and 15:8 on the left. A row with nothing described is drawn as a thin strip. Shaded cells are described fields, and the table under the diagram gives each field’s bits and meaning. Hatched bits are undocumented: their function is unknown. They are not necessarily reserved, and the firmware may still write them as part of a constant, which the description then gives.

A name of the form BITn marks a bit the firmware programs without knowing its function. The description says when the firmware sets or clears it.

Vendor code

The reference describes the hardware and what the firmware does with it. Which vendor routine each step reproduces is collected in the vendor cross-reference.

Notation