loopback_test.c

/*
 * loopback_test.c
 *
 * UART Loopback Test
 * ------------------
 * Transmits 0x12 and 0x34 through the TX FIFO service algorithm
 * (12.6.2.3), loops them back into the RX FIFO (via the simulated
 * core model below), receives them via the RX FIFO service algorithm
 * (12.6.2.4), compares, and prints PASS or FAIL.
 *
 * Two build targets:
 *
 *   SIMULATED (default, runs on host PC, no hardware needed):
 *     gcc -Wall -Wextra -std=c11 \
 *         axi_uart_lite.c loopback_test.c -o loopback_test
 *     ./loopback_test
 *
 *   REAL HARDWARE (bare-metal cross-compile):
 *     <cross-gcc> -DREAL_HARDWARE -DUART_BASEADDR=0xYOURBASEADDR \
 *         -Wall -Wextra -std=c11 \
 *         axi_uart_lite.c loopback_test.c -o loopback_test.elf
 *     (Requires a physical TX->RX loopback wire on the UART port.)
 *
 * Register map used (from uart_registers.sv):
 *   0x00  RX_FIFO   (pop on read)
 *   0x04  TX_FIFO   (push on byte-lane[0] write)
 *   0x08  STAT_REG  [0]=RX_VALID [1]=RX_FULL [2]=TX_EMPTY [3]=TX_FULL
 *                   [5]=OVERRUN  [6]=FRAME   [7]=PARITY
 *   0x0C  CTRL_REG  [3]=TX_INTR_EN [4]=RX_INTR_EN
 *                   [5]=RST_TX(self-clr) [6]=RST_RX(self-clr)
 */

#include <stdio.h>
#include <string.h>
#include "axi_uart_lite.h"

/* ------------------------------------------------------------------ */
/* Build selector                                                       */
/* ------------------------------------------------------------------ */

#ifndef REAL_HARDWARE
#define SIMULATED_BUILD  1
#endif

/* ================================================================== */
/* SIMULATED CORE MODEL                                                */
/* (only compiled when REAL_HARDWARE is not defined)                   */
/* ================================================================== */
#ifdef SIMULATED_BUILD

/* A register-behavior-level model of the RTL, matching the exact
 * STAT_REG bit positions and FIFO push/pop semantics from
 * uart_registers.sv. Not a cycle-accurate waveform simulation. */

#define SIM_FIFO_DEPTH 16

typedef struct {
    uint8_t  rx_fifo[SIM_FIFO_DEPTH];
    uint32_t rx_head, rx_tail, rx_count;

    uint8_t  tx_fifo[SIM_FIFO_DEPTH];
    uint32_t tx_head, tx_tail, tx_count;

    uint8_t  overrun_err;
    uint8_t  frame_err;
    uint8_t  parity_err;
    uint8_t  rx_intr_en;
    uint8_t  tx_intr_en;
} sim_core_t;

static sim_core_t g_core;
static uint8_t    g_reg_space[16];  /* 4 x 4-byte registers */

/* Recompute STAT_REG from current model state and write into the
 * memory region the driver reads via raw pointer. */
static void sim_sync_stat(void)
{
    uint32_t stat = 0u;
    if (g_core.rx_count > 0u)              stat |= UART_STAT_RX_VALID_DATA;
    if (g_core.rx_count == SIM_FIFO_DEPTH) stat |= UART_STAT_RX_FIFO_FULL;
    if (g_core.tx_count == 0u)             stat |= UART_STAT_TX_FIFO_EMPTY;
    if (g_core.tx_count == SIM_FIFO_DEPTH) stat |= UART_STAT_TX_FIFO_FULL;
    if (g_core.rx_intr_en)                 stat |= UART_STAT_RX_INTR_EN;
    if (g_core.overrun_err)                stat |= UART_STAT_OVERRUN_ERR;
    if (g_core.frame_err)                  stat |= UART_STAT_FRAME_ERR;
    if (g_core.parity_err)                 stat |= UART_STAT_PARITY_ERR;
    *(volatile uint32_t *)(g_reg_space + UART_REG_STAT) = stat;
}

/* Present the head of the RX FIFO at the RX_FIFO offset so the
 * driver's raw pointer read sees the correct next byte. */
static void sim_sync_rxfifo(void)
{
    uint8_t b = (g_core.rx_count > 0u) ? g_core.rx_fifo[g_core.rx_tail] : 0u;
    *(volatile uint32_t *)(g_reg_space + UART_REG_RX_FIFO) = b;
}

/* Advance the RX FIFO model after the driver pops a byte. */
static void sim_pop_rx(void)
{
    if (g_core.rx_count > 0u) {
        g_core.rx_tail = (g_core.rx_tail + 1u) % SIM_FIFO_DEPTH;
        g_core.rx_count--;
    }
}

/* Fold a driver write to TX_FIFO into the model. */
static void sim_apply_tx_write(void)
{
    uint8_t byte = (uint8_t)(*(volatile uint32_t *)(g_reg_space + UART_REG_TX_FIFO));
    if (g_core.tx_count < SIM_FIFO_DEPTH) {
        g_core.tx_fifo[g_core.tx_head] = byte;
        g_core.tx_head = (g_core.tx_head + 1u) % SIM_FIFO_DEPTH;
        g_core.tx_count++;
    }
}

/* Fold a driver write to CTRL_REG into the model. */
static void sim_apply_ctrl_write(void)
{
    uint32_t ctrl = *(volatile uint32_t *)(g_reg_space + UART_REG_CTRL);
    if (ctrl & UART_CTRL_RST_TX_FIFO) {
        g_core.tx_head = g_core.tx_tail = g_core.tx_count = 0u;
    }
    if (ctrl & UART_CTRL_RST_RX_FIFO) {
        g_core.rx_head = g_core.rx_tail = g_core.rx_count = 0u;
        g_core.overrun_err = 0u;
        g_core.frame_err   = 0u;
        g_core.parity_err  = 0u;
    }
    g_core.rx_intr_en = (ctrl & UART_CTRL_RX_INTR_EN) ? 1u : 0u;
    g_core.tx_intr_en = (ctrl & UART_CTRL_TX_INTR_EN) ? 1u : 0u;
}

/* Loopback: move every byte in the TX FIFO into the RX FIFO, in
 * order. This models a physical TX->RX wire or internal loopback mux. */
static void sim_loopback_tx_to_rx(void)
{
    while (g_core.tx_count > 0u) {
        uint8_t b = g_core.tx_fifo[g_core.tx_tail];
        g_core.tx_tail = (g_core.tx_tail + 1u) % SIM_FIFO_DEPTH;
        g_core.tx_count--;

        if (g_core.rx_count < SIM_FIFO_DEPTH) {
            g_core.rx_fifo[g_core.rx_head] = b;
            g_core.rx_head = (g_core.rx_head + 1u) % SIM_FIFO_DEPTH;
            g_core.rx_count++;
        } else {
            g_core.overrun_err = 1u;
        }
    }
    sim_sync_stat();
}

/*
 * Pre-fold the soft-reset outcome into the model before calling
 * uart_init(), because uart_init() issues several sequential CTRL
 * writes internally and reads STAT_REG back on the SAME call. On
 * real hardware STAT_REG updates combinatorially on every CTRL write;
 * in our static-memory model we bridge this gap by pre-reflecting the
 * fully-reset state before handing control to the driver.
 */
static void sim_apply_init_reset(void)
{
    /* Mirrors what uart_init() will do: clear, RST_TX, RST_RX. */
    g_core.tx_head = g_core.tx_tail = g_core.tx_count = 0u;
    g_core.rx_head = g_core.rx_tail = g_core.rx_count = 0u;
    g_core.overrun_err = 0u;
    g_core.frame_err   = 0u;
    g_core.parity_err  = 0u;
    g_core.rx_intr_en  = 0u;
    g_core.tx_intr_en  = 0u;
    sim_sync_stat();
}

#endif /* SIMULATED_BUILD */

/* ================================================================== */
/* Main loopback test                                                  */
/* ================================================================== */

int main(void)
{
    uart_dev_t dev;
    uint8_t    tx_q_mem[64];
    uint8_t    rx_q_mem[64];
    uart_status_t st;

    const uint8_t tx_data[2] = {0x12u, 0x34u};
    uint8_t       rx_data[2] = {0u, 0u};
    int32_t       sent_total = 0;
    int32_t       recv_total = 0;

#ifdef SIMULATED_BUILD
    /* -------------------------------------------------------------- */
    /* Simulated setup                                                  */
    /* -------------------------------------------------------------- */
    uintptr_t base = (uintptr_t)g_reg_space;
    memset(&g_core, 0, sizeof(g_core));
    memset(g_reg_space, 0, sizeof(g_reg_space));

    /* Pre-resolve the reset outcome so uart_init's internal STAT_REG
     * readback sees a correct post-reset state immediately. */
    sim_apply_init_reset();
    st = uart_init(&dev, base, 0, 0,
                   tx_q_mem, sizeof(tx_q_mem),
                   rx_q_mem, sizeof(rx_q_mem));
    sim_apply_ctrl_write();
    sim_sync_stat();

#else /* REAL_HARDWARE */
    /* -------------------------------------------------------------- */
    /* Real hardware setup                                              */
    /* -------------------------------------------------------------- */
    st = uart_init(&dev, (uintptr_t)UART_BASEADDR, 0, 0,
                   tx_q_mem, sizeof(tx_q_mem),
                   rx_q_mem, sizeof(rx_q_mem));
#endif

    if (st != UART_SUCCESS) {
        printf("FAIL (init error: %d)\n", (int)st);
        return 1;
    }

    /* ---------------------------------------------------------------- */
    /* Transmit 0x12 then 0x34 via TX FIFO Service (12.6.2.3)          */
    /* ---------------------------------------------------------------- */
    printf("Transmitting: 0x%02X 0x%02X\n", tx_data[0], tx_data[1]);

    for (int i = 0; i < 2; i++) {
#ifdef SIMULATED_BUILD
        sim_sync_stat();
#endif
        int32_t sent = uart_tx_fifo_service(&dev, &tx_data[i], 1);
        if (sent == 1) {
#ifdef SIMULATED_BUILD
            sim_apply_tx_write();
            sim_sync_stat();
#endif
            sent_total++;
        }
    }

    /* ---------------------------------------------------------------- */
    /* Loopback: TX FIFO -> RX FIFO                                     */
    /* ---------------------------------------------------------------- */
#ifdef SIMULATED_BUILD
    sim_loopback_tx_to_rx();
#else
    /*
     * On real hardware the UART serialises and deserialises the bytes
     * over actual TX/RX pins. Ensure a loopback wire connects TX to RX
     * on your board. Poll for the bytes to arrive in the RX FIFO.
     */
    {
        uint32_t timeout = 1000000u; /* adjust for your baud rate */
        while (!(uart_read_stat(&dev) & UART_STAT_RX_VALID_DATA) && timeout > 0u) {
            timeout--;
        }
        if (timeout == 0u) {
            printf("FAIL (timeout waiting for loopback bytes)\n");
            uart_shutdown(&dev);
            return 1;
        }
    }
#endif

    /* ---------------------------------------------------------------- */
    /* Receive via RX FIFO Service (12.6.2.4)                           */
    /* ---------------------------------------------------------------- */
    for (int i = 0; i < 2; i++) {
#ifdef SIMULATED_BUILD
        sim_sync_stat();
        sim_sync_rxfifo();
#endif
        int32_t got = uart_rx_fifo_service(&dev, &rx_data[i], 1);
        if (got == 1) {
#ifdef SIMULATED_BUILD
            sim_pop_rx();
            sim_sync_stat();
#endif
            recv_total++;
        }
    }
    printf("Received:     0x%02X 0x%02X\n", rx_data[0], rx_data[1]);

    /* ---------------------------------------------------------------- */
    /* Compare and report                                               */
    /* ---------------------------------------------------------------- */
    int match = (sent_total == 2) && (recv_total == 2) &&
                (memcmp(tx_data, rx_data, sizeof(tx_data)) == 0);

    printf("%s\n", match ? "PASS" : "FAIL");

    uart_shutdown(&dev);
    return match ? 0 : 1;
}