Wiznet makers

A Custom, Interrupt-Driven W5500 Driver Built for Real-Time STM32 Applications

Most developers reaching for the WIZnet W5500 rely on the official ioLibrary — a polling-based driver that works well for simple projects but becomes a bottleneck when an RTOS-based system demands non-blocking, high-throughput Ethernet. This project takes a fundamentally different approach: a fully asynchronous, DMA-driven W5500 driver that serializes all SPI access through a command queue and never blocks an RTOS task during I/O.

The result is a standalone C/C++ library (~5,600 lines) that exposes a BSD-style socket API (socket, connect, send, recv, sendto, recvfrom, disconnect, close) along with four application-layer clients — DNS resolver, NTP time sync, WebSocket, and a UDP convenience wrapper — all built on top of the asynchronous core.

The Command Queue: Heart of the Architecture

The central design element is a circular command queue (1,000 slots) that serializes every SPI transaction to the W5500. The application layer never touches SPI directly; instead, it pushes command structs onto the queue. A single running_cmd variable tracks the in-flight DMA transfer. When a transfer completes, the DMA callback processes the result and immediately pops the next command:

Commands enter from three sources. RTOS tasks push to the back at normal priority, protected by taskENTER_CRITICAL(). The W5500 INT pin (via GPIO EXTI) pushes a READ_SIR command to the front, ensuring interrupt events are handled before queued bulk transfers. A hardware timer ISR running at ~50 Hz periodically checks TX free-space registers and re-reads the interrupt register as a safety net against missed INT edges.

From Src/w5500.cpp:L253-L268:

void wiznetInterruptCallback(void)
{
    uint32_t isrm = taskENTER_CRITICAL_FROM_ISR();
    command_t cmd;
    generateGetRegCmd(&cmd, 0xFF, W5500_SIR, &common_regs.SIR, 1);
    cmd.cmd_type = READ_SIR;
    // Push to front of queue for immediate processing
    if (!queuePushFront(&command_queue, cmd)) {
        enqueueFailsInISR++;
    }
    taskEXIT_CRITICAL_FROM_ISR(isrm);
}

Zero-Copy DMA Transfers and Buffer Management

Every SPI transaction uses STM32 HAL DMA (HAL_SPI_Transmit_DMA, HAL_SPI_TransmitReceive_DMA), meaning the CPU is free during transfers. Each socket has its own ring-buffer pair (TX and RX) in STM32 RAM, managed by segment descriptor queues. The getTXBufferIndex() and getRXBufferIndex() functions implement wraparound-aware allocation:

From Src/w5500.cpp:L338-L373:

int16_t getTXBufferIndex(socket_t* socket, uint16_t len)
{
    if (queueIsEmpty(&socket->tx_buf_queue)) {
        return (len <= socket->tx_buf_len) ? 0 : -1;
    }
    int16_t queue_start = queueFront(&socket->tx_buf_queue)->start_index;
    int16_t queue_end = queueBack(&socket->tx_buf_queue)->end_index;

    if (queue_end >= queue_start) {
        int16_t space_at_end = socket->tx_buf_len - queue_end;
        int16_t space_at_beginning = queue_start;
        if (len <= space_at_end) return queue_end;
        else if (len <= space_at_beginning) return 0;
        else return -1;
    } else {
        if (len <= queue_start - queue_end) return queue_end;
        else return -1;
    }
}

This approach avoids dynamic memory allocation entirely — critical for deterministic real-time behavior.

Why W5500 Fits This Architecture

The W5500's hardware TCP/IP stack is what makes this async architecture viable. The chip handles retransmission, ARP, ICMP, and TCP state management internally, so the STM32 only needs to move data in and out of the chip's 32 KB buffer via SPI. This offloads protocol processing that would otherwise consume significant MCU cycles and RAM.

The 8 independent hardware sockets map directly to the driver's sockets[8] array, each with separate TX/RX ring buffers. The W5500's SIR (Socket Interrupt Register) bitmap allows the driver to identify which sockets need attention in a single register read — the READ_SIR → READ_SOC two-step sequence handles this efficiently.

A notable detail is the CR (Command Register) busy-check in dmaTXCompleteCallback() (Src/w5500.cpp:L444-L479): before writing a socket command, the driver checks if the previous command has been processed by the W5500. If the CR register is still non-zero, it re-enqueues the write and reads CR again. This prevents command collisions that could silently drop socket operations.