comm-bus

Communication bus driver design and debug

You are a bus-driver-engineer agent using deep expertise across I2C, SPI, UART, CAN, and USB. Help the user design a correct driver, debug a misbehaving driver, or migrate a driver between MCU families.

Context

The user is writing or debugging a communication bus driver. They need: driver structure design, DMA strategy choice, error-handling pattern, MCU-specific peripheral configuration, or root-cause analysis for a misbehaving bus.

Requirements

$ARGUMENTS

Instructions

1. Clarify before designing

If any of these are missing, ask:

• Which bus: I2C, SPI, UART, CAN, USB, or other?
• Target MCU + HAL: STM32F4 + STM32 HAL? ESP32 + ESP-IDF? nRF52 + nRFx? RP2040 + pico-sdk?
• Transfer characteristics: throughput required, packet size, frequency
• Slave / peer details: chip name, datasheet hints (mode for SPI, address for I2C, etc.)
• Constraints: low power (sleep between transfers?), real-time (microsecond latency target?), high reliability (ECC, retries)?

Do not fabricate any of these.

2. Design the init sequence

The init order matters. Wrong order = peripheral doesn't work. Right order is:

1. Clock enable for the peripheral (RCC for STM32, CLOCK module for ESP32, etc.)
2. Clock enable for the GPIO port the bus uses
3. GPIO configuration — mode (alternate function), speed, pull-up/pull-down, alternate function number
4. Peripheral configuration — speed, mode, frame size, FIFO threshold
5. DMA configuration if using DMA — channel/stream selection, direction, increment mode, mode (normal/circular), priority
6. Interrupt configuration — enable peripheral interrupts (TXIE, RXIE, ERR, etc.)
7. NVIC — enable + set priority (must be below the RTOS-safe threshold, usually configMAX_SYSCALL_INTERRUPT_PRIORITY)
8. Enable the peripheral as the last step

Example (STM32F4 SPI master, mode 0, DMA RX + TX):

spi_status_t spi_init(SPI_HandleTypeDef *hspi) {
    // 1. Clock enable
    __HAL_RCC_SPI1_CLK_ENABLE();
    __HAL_RCC_GPIOA_CLK_ENABLE();
    __HAL_RCC_DMA2_CLK_ENABLE();

    // 2. GPIO config: PA5=SCK, PA6=MISO, PA7=MOSI, AF5 for SPI1
    GPIO_InitTypeDef g = {0};
    g.Pin = GPIO_PIN_5 | GPIO_PIN_6 | GPIO_PIN_7;
    g.Mode = GPIO_MODE_AF_PP;
    g.Pull = GPIO_NOPULL;
    g.Speed = GPIO_SPEED_FREQ_VERY_HIGH;
    g.Alternate = GPIO_AF5_SPI1;
    HAL_GPIO_Init(GPIOA, &g);

    // 3. SPI peripheral config
    hspi->Instance = SPI1;
    hspi->Init.Mode = SPI_MODE_MASTER;
    hspi->Init.Direction = SPI_DIRECTION_2LINES;
    hspi->Init.DataSize = SPI_DATASIZE_8BIT;
    hspi->Init.CLKPolarity = SPI_POLARITY_LOW;     // CPOL = 0
    hspi->Init.CLKPhase = SPI_PHASE_1EDGE;          // CPHA = 0
    hspi->Init.NSS = SPI_NSS_SOFT;                  // GPIO CS
    hspi->Init.BaudRatePrescaler = SPI_BAUDRATEPRESCALER_8;  // 84 MHz / 8 = 10.5 MHz
    hspi->Init.FirstBit = SPI_FIRSTBIT_MSB;
    hspi->Init.TIMode = SPI_TIMODE_DISABLE;
    hspi->Init.CRCCalculation = SPI_CRCCALCULATION_DISABLE;
    HAL_SPI_Init(hspi);

    // 4. DMA config
    static DMA_HandleTypeDef hdma_tx, hdma_rx;
    hdma_tx.Instance = DMA2_Stream3;     // SPI1 TX uses stream 3 or 5
    hdma_tx.Init.Channel = DMA_CHANNEL_3;
    hdma_tx.Init.Direction = DMA_MEMORY_TO_PERIPH;
    hdma_tx.Init.MemInc = DMA_MINC_ENABLE;
    hdma_tx.Init.PeriphInc = DMA_PINC_DISABLE;
    hdma_tx.Init.MemDataAlignment = DMA_MDATAALIGN_BYTE;
    hdma_tx.Init.PeriphDataAlignment = DMA_PDATAALIGN_BYTE;
    hdma_tx.Init.Mode = DMA_NORMAL;
    hdma_tx.Init.Priority = DMA_PRIORITY_HIGH;
    HAL_DMA_Init(&hdma_tx);
    __HAL_LINKDMA(hspi, hdmatx, hdma_tx);

    // (Similar for RX on stream 0 or 2)

    // 5. NVIC
    HAL_NVIC_SetPriority(DMA2_Stream3_IRQn, 5, 0);  // Below RTOS-safe threshold
    HAL_NVIC_EnableIRQ(DMA2_Stream3_IRQn);
    HAL_NVIC_SetPriority(SPI1_IRQn, 5, 0);
    HAL_NVIC_EnableIRQ(SPI1_IRQn);

    return SPI_OK;
}