Hardware reference
Host interface
On this page
The host interface (HIF) is a descriptor-driven DMA engine between the SDIO function and packet RAM. One ring carries messages from the host, a second carries messages to it, and a separate emergency descriptor serves the fatal-exception path. Every message is a WSM message.
Descriptor format
Both rings use the same 8-byte descriptor.
| Offset | Size | Register | Type | Description |
|---|---|---|---|---|
+0x00 |
4 B | ADDRESS |
u32 RW | Bus address of the buffer (cpu & 0xf6ff_ffff). |
+0x04 |
4 B | CONTROL |
u32 RW | Length, ownership and sequence. |
Source: Descriptor · 8 bytes · offsets are relative to the structure
Descriptor CONTROL
The firmware writes ((length + 1) & 0x1ffe) | 1 with the sequence, which rounds the length up to even and sets OWN.
| Bits | Field | Description |
|---|---|---|
| 14:13 | SEQUENCE |
Bits 14:13 of the message’s WSM ID, before the firmware rewrites the ID’s sequence number. |
| 12:1 | LENGTH |
Transfer length in 2-byte units. |
| 0 | OWN |
Set to hand the descriptor to the engine; the engine clears it once it has fetched the descriptor. |
Source: DescriptorControl · 4 bytes
Input ring
Thirty-two host-to-firmware descriptors at 0x0ab0_0000, refilled in turn as the firmware returns buffers. The host writes a message into an input buffer; the firmware reads the 4-byte WSM header (length, then ID, both little-endian 16-bit) at the buffer start and the payload at +4.
| Offset | Address | Register | Type | Description |
|---|---|---|---|---|
+0x00 |
0x0ab0_0000 |
DESCRIPTORS |
32 × Descriptor | Host-to-firmware descriptors. Descriptors 0–29 start with the 0x660-byte input buffers and 30 and 31 start empty; as the firmware returns buffers it refills the ring in turn, so all 32 come into use. |
Source: RxShared · 256 bytes
Output ring and control
Four firmware-to-host descriptors and the shared control registers at 0x0ab0_0100. A descriptor points either at an output buffer or, for a received frame, directly at the frame’s RX FIFO slot.
| Offset | Address | Register | Type | Description |
|---|---|---|---|---|
+0x00 |
0x0ab0_0100 |
TX |
4 × Descriptor | Firmware-to-host descriptors. Each points at a 0x180-byte output buffer or, for a received frame, straight at its RX FIFO slot. |
+0x20 |
0x0ab0_0120 |
CONTROL |
u32 RW | Length mask. |
+0x24 |
0x0ab0_0124 |
STATUS |
u32 RO | Pending causes; raise IRQ 13. |
+0x28 |
0x0ab0_0128 |
INTERRUPT_ACK |
u32 WO | Write the causes read from STATUS to clear them. Re-arming IRQ 13 before every cause is acknowledged loses events. |
+0x2c |
0x0ab0_012c |
EMERGENCY_ADDRESS |
u32 RW | Bus address of the fatal-exception message buffer. |
+0x30 |
0x0ab0_0130 |
EMERGENCY_CONTROL |
u32 RW | Descriptor control word for the fatal-exception message. |
+0x34 |
0x0ab0_0134 |
STARTUP_STATUS |
u32 RO | Startup handshake. |
+0x40 |
0x0ab0_0140 |
ACTIVATION |
u32 RO | Read once during the host handshake; the value is discarded. |
Source: HifShared · 68 bytes
CONTROL
| Bits | Field | Description |
|---|---|---|
| 10:0 | LENGTH_MASK |
Written 0x7ff, or 0x7f7 if bit 10 of this register already reads set before the write. The firmware records the written value ANDed with 0x7f8 but does not apply it to output lengths. |
Source: HifControl · 4 bytes
STATUS, INTERRUPT_ACK
Only these two causes schedule work.
| Bits | Field | Description |
|---|---|---|
| 2 | RX_READY |
A host-to-firmware message is ready. |
| 1 | TX_DONE |
A firmware-to-host transfer finished. |
Source: HifStatus · 4 bytes
STARTUP_STATUS
| Bits | Field | Description |
|---|---|---|
| 10 | WAIT |
Polled until clear before the startup indication is sent. The agent that clears it has not been identified. |
Source: HifStartup · 4 bytes
Ring geometry
| Parameter | Value | Notes |
|---|---|---|
| Input buffers | 30 × 0x660 |
Announced to the host in the startup indication |
| Input descriptors | 32 | Two start empty; refills rotate through all 32 |
| Output descriptors | 4 | At most four messages in flight to the host |
| Output queue | 64 entries | Software staging, independent of the hardware ring |
| Sequence | 2 bits per descriptor | Wraps independently of the queue |
Ownership
A cleared descriptor is not a completion. The engine may clear a descriptor’s control word after fetching it but before the host has finished reading the buffer. Reuse an output buffer only after STATUS.TX_DONE.
When TX_DONE is seen, the firmware walks the output descriptors in order and treats each one whose OWN bit has already cleared as complete. The reasoning: TX_DONE is raised after the host has read the buffers, so a descriptor released before it was raised has been read too inferred. For each, it first makes the slot reusable and stages the next queued message, and only then releases the completed message’s buffer. On the input side, RX_READY schedules the firmware to take one request. It takes it only when a reply could be sent at once: an output buffer is free and the 64-entry output queue has room. Otherwise the request waits. After taking one, the firmware checks the next input descriptor: if its OWN bit has cleared, it schedules that request as well, without waiting for another RX_READY.
Sequence numbers
Two sequence numbers travel with each output message:
- The message’s WSM ID carries a 3-bit sequence number in bits 15:13. The firmware writes it into the buffer when it stages the message; it counts staged messages, skipping the numbers used by emergency messages, because the host counts both.
- The descriptor’s
SEQUENCEfield carries bits 14:13 of the ID as the message was queued, before that rewrite.
Host handshake shows how the HIF is brought up, and Programming checklists how one output message is published.