Microcode HLE

During MAC initialization, WL uploads a microcode image to the wireless core. The microcode runs on the core's programmable state machine and handles medium access and transmission, acknowledgements, receive filtering and building the receive header that precedes every frame in the receive FIFO. WL never calls into the microcode directly. It talks to it through shared memory, MAC control, the MAC command register, interrupt status and the FIFOs. A high-level emulation (HLE) of the microcode has to provide these interfaces.

Image

g_microcode (0x13F29DF0) holds 0x5D00 bytes, which is 2976 instructions of 8 bytes each. WL uploads it to offset 0 of microcode memory. On this page, microcode addresses are byte offsets into microcode memory and WL addresses are Starlet virtual addresses in IOS80. Execution starts at reset (0x0000), which clears the GPIO output and jumps to init (0x4078).

During startup, the microcode publishes its version in shared memory:

Shared memory

Shared memory is an array of 16 bit words. The microcode addresses it by word index, while the host uses byte offsets, so word n sits at byte offset 2n. The host selects a word through the object address register and then accesses one halfword of the object data register. write_shm (0x13ED01C4) and read_shm (0x13ED03F4) take an even byte offset and work like this, with the driver argument omitted:

void write_shm(uint32_t offset, uint16_t value)
{
    write32(0x18001160, 0x00010000 | (offset >> 2));
    write16((offset & 2) ? 0x18001166 : 0x18001164, value);
}

uint16_t read_shm(uint32_t offset)
{
    write32(0x18001160, 0x00010000 | (offset >> 2));
    return read16((offset & 2) ? 0x18001166 : 0x18001164);
}

These words make up the host interface:

init_mac (0x13EDF148) reads the version words after its startup wait and combines them into one word, with UCODEREV in the high halfword and UCODEPATCH in the low halfword. The wait also ends on timeout, so these reads can happen before startup has actually finished.

UCODESTAT

update_power_save (0x13ED045C) updates MAC control bits 25 and 26. If it sets bit 26 while bit 25 was already set and bit 26 was clear, it waits 40 microseconds and then polls UCODESTAT until it reads a value other than 4. It reads at most 27 times with a 10 microsecond delay between reads and gives up after the last read without delaying again. Both waits go through the WL delay helper.

MAC control

WL accesses MAC control at backplane address 0x18001120. The microcode reads its upper half through register 0x041.

Host flags

Interrupts raised by the microcode

The microcode raises interrupt status bits at 0x18001128 by writing microcode register 0x042 for bits 15:0 and 0x043 for bits 31:16. The routines on this page raise these bits:

The measurement commands raise their own completion interrupts only once a requested measurement finishes.

The microcode never raises bit 15 or bit 29 itself, even though WL relies on both. Bit 15 tells WL to drain the receive FIFO and bit 29 tells it to read transmit status. They are separate from bits 8 and 7, which the microcode raises on receive and transmit respectively.

Startup and suspension

init runs after reset. The pseudocode below covers its shared memory setup and leaves out internal engine setup. Here and in later examples, helpers and header fields without a firmware address are pseudocode names. read_external() is the microcode's indirect read of a core register, where index 0 is the PHY version.

// 0x4078
void init(void)
{
    for (int word = 0x7FF; word >= 0; word--)
        shm[word] = 0;

    shm[UCODESTAT] = 1;

    uint16_t phy_version = read_external(0);
    shm[PHYVER] = phy_version & 0xFF;
    shm[PHYTYPE] = (phy_version >> 8) & 0xF;

    shm[0x0C0] = 0x0039;
    shm[0x0C2] = 0x0050;
    shm[0x0C4] = 0xFC00;
    shm[0x011] = 0xFF00;
    if (shm[PHYTYPE] == 2 && (microcode_register[0x01C] & 0x0100) && shm[PHYVER] == 0)
        shm[0x011] = 0;

    shm[UCODEREV] = 0x014B;
    shm[UCODEPATCH] = 0x0196;
    shm[UCODEDATE] = 0x7915;
    shm[UCODETIME] = 0x915D;

    goto suspend;
}

Clearing shared memory wipes anything the host wrote to words 0x000 through 0x7FF before startup. WL writes its shared memory configuration after the startup wait in init_mac.

suspend (0x3778) reports the suspended state and waits for the host. resume (0x37B8) follows directly:

// 0x3778
suspend:
    raise_interrupt(0);
    shm[UCODESTAT] = 3;
    while (!mac_enabled())
        ;
    shm[UCODESTAT] = 2;

// 0x37B8
resume:
    reset_rx();
    goto main_events;

mac_enabled() tests MAC control bit 0. The first pass through suspend raises interrupt status bit 0, which init_mac polls for after starting the microcode.

reset_rx (0x37F0) clears the microcode's internal branch state and condition latches, resets receive processing and empties the queue of pending probe responses.

When the main loop sees MAC enabled clear, it branches to mac_disabled (0x3760), which leads into suspend. suspend_mac (0x13ED0EDC) waits for the resulting interrupt before it proceeds. Setting MAC enabled again writes UCODESTAT 2 and resumes execution.

Main loop

main_loop (0x0010) checks hardware and software work flags before sleeping. main_events (0x0048) checks for the following work in order. A taken branch can skip the remaining checks.

1. The radio hardware switch, when the host flag enables its check.
2. Deferred transmit status and acknowledgements.
3. MAC enabled. When it is clear, the loop enters mac_disabled.
4. A transmit FIFO flush request.
5. Transmit events at tx_events (0x0140).
6. Receive events at rx_events (0x0180), including begin_rx (0x27A0) and finish_rx (0x2D88).
7. The MAC commands for noise measurement and clear channel assessment.
8. Beacon interval events and the start of the next transmission.

Receive

begin_rx (0x27A0) runs at the start of a frame. It latches the 64 bit timing synchronization function (TSF) timer, builds the receive header's channel word and waits until 0x26 bytes have arrived or the frame is complete. It then clears both MAC status words. If at least 0x10 bytes arrived, it reads the frame control field and classifies the frame.

finish_rx (0x2D88) runs at the end of the frame. It records the receive timestamp, checks the frame check sequence, applies address filtering and fills in the remaining header fields. A frame that fails address filtering is dropped before it reaches the FIFO. A frame with a bad frame check sequence is only kept when MAC control bit 23 is set. It is then marked with MAC status bit 0, which makes pio_receive (0x13F0D284) discard it.

The normal header path starts at 0x3090. This excerpt shows the length and PHY status writes. Internal receive state can still divert execution before the header transfer.

// finish_rx, normal header construction
shm[RXHDR_LENGTH] = rx_byte_count;
if (padding_inserted) {
    shm[RXHDR_LENGTH] += shm[0x01A];
    shm[RXHDR_MAC_STATUS_LOW] |= 0x0004;
}
shm[RXHDR_PHY_STATUS_0] = phy_status[0];
shm[RXHDR_PHY_STATUS_1] = phy_status[1];
shm[RXHDR_PHY_STATUS_2] = phy_status[2];
shm[RXHDR_PHY_STATUS_3] = phy_status[3];
transfer_rx_header();

transfer_rx_header (0x41E0) hands the prepared receive header to the receive engine without the frame body. It returns immediately if bit 9 of internal register r45 is set. Otherwise it points the engine at the 10 word header in shared memory, starts the transfer and waits for the busy condition to set and then clear. It checks for receive overflow throughout this wait and once more before raising interrupt status bit 8.

void transfer_rx_header(void)
{
    if (skip_rx_header)
        return;

    rx_header_source = 0x548;
    rx_header_words = 10;
    rx_header_control = 1;

    do {
        if (receive_overflow_pending())
            goto overflow;
    } while (!header_transfer_busy());
    do {
        if (receive_overflow_pending())
            goto overflow;
    } while (header_transfer_busy());
    if (receive_overflow_pending())
        goto overflow;
    raise_interrupt(8);
    return;

overflow:
    handle_receive_overflow();
}

The pseudocode names map to these internal fields:

header_transfer_busy() tests microcode condition 0x0B and receive_overflow_pending() tests condition 0x0D. handle_receive_overflow() is a branch to rx_overflow (0x3728), which leaves the helper without raising the interrupt or returning normally.

Receive header

The header occupies shared memory words 0x548 to 0x551 and forms the first 20 bytes of the receive record:

Transmit completion

finish_tx (0x1F58) handles the frame at the head of the current transmit FIFO. On the status reporting path, it sets status bit 6 if the frame has to stay at the head and otherwise asks for it to be released. It then raises interrupt status bit 7. MAC control bit 29 skips the status entry writes but not the interrupt.

count_tx_attempt (0x4248) increments one of the status word's two 4 bit attempt counters, selected by the transmit state. Each counter wraps within its 4 bits. Probe responses take a separate path that increments shared memory word 0x560 instead.

At 0x1FF8, finish_tx copies bit 0 of the internal status into bit 1 of the status entry. Before handling the current entry, it calls report_saved_tx_status (0x4B10) to write out any previously saved one. If host flag 0x02F bit 15 is set, the current entry is saved in shared memory for that helper to report later. Otherwise it is written immediately:

uint16_t status = header.status;
status = (status & ~0x0002) | ((status & 0x0001) << 1);
report_saved_tx_status();
if (defer_tx_status) {
    save_tx_status(status & ~0x0001, header);
} else {
    tx_status[3] = header.word_28;
    tx_status[2] = header.word_27;
    tx_status[1] = header.word_24;
    tx_status[0] = status | 0x0001;
}

save_tx_status() stands for the shared memory writes and setting the pending flag. The header.word_* suffixes are word offsets into the microcode's copy of the current transmit header, where the status word sits at offset 0x25. An entry goes to these registers when written immediately and to these shared memory words when saved:

report_saved_tx_status does nothing if r45 bit 0 is clear. Otherwise it writes the saved words to the registers in the order above and clears the pending flag.

On interrupt status bit 29, WL's process_mac_interrupts (0x13EF468C) reads transmit status entries. For each one, it reads 0x18001170 and stops if bit 0 is clear. Otherwise it reads the entry from 0x18001174 and processes it. With a nonzero work limit argument, it reads at most eight entries per call.

The two reads provide these fields to WL's process_transmit_status (0x13EE17AC):

MAC commands

The main loop reads host commands from the MAC command register (microcode register 0x047). Each measurement routine below returns immediately unless its command bit is set. When the measurement completes, it writes the bit back to clear it and raises the matching interrupt.

measure_noise (0x5328) measures background noise. The pseudocode shows the path for PHY types other than 0. All shared memory words and TSF timer halves are unsigned 16 bit values. wait_for_noise_sample(us, ignore_ifs) waits until the low half of the TSF timer reaches its starting value plus us, modulo 65536. It returns false early if condition 0x20 is set or if interframe space status bit 11 is set while ignore_ifs is false.

void measure_noise(void)
{
    if (!(mac_command & 0x0010))
        return;
    if (!noise_pending) {
        noise_pending = true;
        read_tsf_low();
        shm[0x569] = read_tsf_high();
    }
    read_tsf_low();
    uint16_t elapsed_high = read_tsf_high() - shm[0x569];

    shm[JSSI_AUX] = (read_external(0x08) & 0xFF)
        | ((read_external(gmode ? 0x45F : 0x05F) & 0xFF) << 8);

    int word = 0x044;
    for (int i = 0; i < 4; i++) {
        if (!wait_for_noise_sample(2, elapsed_high >= 2))
            return;
        shm[word] = (shm[word] & ~0x01FF) | (read_external(0x27) & 0x01FF);
        shm[word] = rotate_right_16(shm[word], 8);
        word ^= 1;
    }
    if (elapsed_high < 2 && !wait_for_noise_sample(24, false))
        return;

    mac_command = 0x0010;
    raise_interrupt(18);
    noise_pending = false;
}

The four samples alternate between JSSI 0 and JSSI 1. gmode is MAC control bit 31 as latched when the microcode left suspend. The final 24 microsecond wait is skipped when elapsed_high, computed once on entry, is at least 2. An interrupted pass leaves the command bit and pending flag set, so the next call takes a fresh set of samples while keeping the original timestamp.

measure_cca (0x54F8) performs clear channel assessment. On completion it writes 0x4000 to microcode register 0x133, updates registers 0x136 and 0x137, clears command bit 3 and raises interrupt status bit 17. It does not modify the JSSI words.

HLE

An HLE has to provide the following behavior to WL and keep the microcode's own interrupts separate from the FIFO notifications:

HLE frame reception describes how to deliver scan results through the receive FIFO.