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:

Host handshake shows how the HIF is brought up, and Programming checklists how one output message is published.