Иногда самые простые задачи превращаются в мини-приключения. Например, когда вам нужно подключить UARTLite на FPGA к Linux через PCIe. Кажется, ну что там? Пару регистров, пара прерываний… А на деле — несколько дней за Vivado, отладка XDMA и борьба с драйверами. 😅

В этой статье я расскажу, как я всё-таки победил UARTLite через XDMA и как вы сможете повторить это без боли.

Аннотация

Этот проект демонстрирует, как подключить периферийное устройство UARTLite на базе FPGA к пользовательским приложениям Linux через PCIe XDMA.
Реализуем TTY-интерфейс (драйвер Linux TTY ) /dev/ttyULx и показываем альтернативный способ быстрого доступа через Python с использованием mmap.
Идеально подходит для интеграции в проекты SDR, робототехники и встраиваемых систем!

• Что за устройство?
  ➔ Моя SDR-плата на FPGA Artix-7, GPS SIM68 модулем и AD9361 RF рансивером, интерфейсом PCIe и возможностью обмена данными между FPGA и Linux через XDMA.

• Что мы будем делать?
  ➔ Разработаем Linux-драйвер для UARTLite через XDMA и продемонстрируем альтернативный способ прямого доступа через Python.

• Почему это важно?
  ➔ Такое решение позволяет легко интегрировать пользовательские FPGA-периферии в Linux-системы без сложной ручной настройки, особенно в SDR-проектах, робототехнике, автономных системах и IoT.

  ---

  1. Введение

  Встраиваемые системы на базе FPGA широко применяются в программно-определяемых радиосистемах (SDR, Software-Defined Radio). Программно-определяемые радиосистемы (SDR) требуют эффективного взаимодействия между FPGA и CPU, что осложняется интеграцией периферии через PCIe. Эта статья решает задачу разработки драйвера для UARTlite через XDMA, демонстрируя два подхода: через ядро Linux и Python. Цель — показать архитектуру, реализацию и тестирование решения на базе собственной SDR-платы.

  Особенности проекта:

• ✅ Разработанная с нуля SDR-плата на FPGA Artix-7 и AD9361

• ✅ В качестве системной платы используется LattePanda Sigma

• ✅ Встроенный UARTlite для взаимодействия с GPS модулем подключеным к FPGA

• ✅ XDMA через PCIe для высокоскоростной передачи данных

• ✅ Поддержка двух методов работы:

  • Linux-драйвер с TTY-интерфейсом (/dev/ttyULx)

  • Прямая работа с UARTlite на Python через XDMA

2. Архитектура решения

Проект основан на разработанной с нуля SDR-плате с FPGA и интерфейсом PCIe:

Основная платформа проекта:

Описание системы

Система состоит из следующих компонентов и их связей:

1. SIM68 (GPS Module)

   • Это GPS-модуль, который отправляет данные через интерфейс UART.

   • Связан с UartLite (UART Controller) через UART.

2. UartLite (UART Controller)

   • Контроллер UART, принимающий данные от GPS-модуля.

   • Связан с XDMA (PCIe DMA) через шину AXI.

     AXI UARTLite Product Guide (PG142)

     AXI Interconnect Product Guide (PG059)

3. XDMA (PCIe DMA)

   • Контроллер прямого доступа к памяти (DMA) через PCIe. (AXI PCIe DMA Product Guide (PG195))

   • Связан с CPU (Latte Panda Sigma) через PCIe.

4. CPU (Latte Panda Sigma)

   • Центральный процессор, который обрабатывает данные от XDMA.

   • Связан с Linux Kernel через обозначение User-space (пространство пользователя).

5. Linux Kernel

   • Ядро операционной системы Linux, работающее на CPU.

   • Связан с User Application через интерфейсы TTY / Python.

     Linux TTY Documentation

6. User Application

   • Пользовательское приложение, которое взаимодействует с ядром Linux для доступа к данным, возможно, через TTY-устройства или скрипты на Python.

2.1 Структурная схема системы

На изображении ниже представлена структурная схема системы с собственным драйвером:

данные проходят по цепочке:

1. SIM68 передает NMEA-сообщения в UartLite на FPGA через UART

2. UartLite взаимодействует с XDMA (PCIe DMA) через AXI.

3. XDMA передаёт данные через PCIe в CPU (Latte Panda Sigma).

4. CPU обрабатывает данные в user-space и взаимодействует с ядром Linux.

5. Linux Kernel предоставляет интерфейс TTY / Python API для пользовательского приложения (/dev/ttyUL0).

6. User Application – взаимодействует с UART через Python или терминал.

На изображении ниже представлена структурная схема системы при прямом доступе через Python:

Данные проходят по цепочке:

1. SIM68 передает NMEA-сообщения в UartLite на FPGA через UART.

2. UartLite взаимодействует с XDMA (PCIe DMA) через AXI.

3. XDMA передаёт данные через PCIe в CPU (Latte Panda Sigma).

4. CPU через /dev/xdma0_user мапит пространство устройства с помощью mmap.

5. Python Application напрямую читает регистры UARTlite (RX FIFO / TX FIFO), минуя драйвер ядра.

Таким образом, взаимодействие происходит без использования стандартного Linux TTY-драйвера, что позволяет:

• Минимизировать накладные расходы на системные вызовы.

• Снизить нагрузку на процессор за счёт использования async IO.

• Быстро прототипировать и отлаживать системы на основе FPGA.

На диаграмме ниже показано, как происходит обмен данными между компонентами в системе:

2.2 Блок-схема в Vivado

• В проекте используется XDMA (PCIe-DMA Bridge)

• AXI Interconnect связывает XDMA с AXI Register Slice, AXI UARTLite

• AXI UARTLite подключен к системе через AXI Interconnect и к GPS модулю SIM68

• Есть также AXI GPIO, которые могут использоваться для управления*

Основной поток данных:
FPGA ↔ AXI Interconnect ↔ AXI UARTLite ↔ PCIe XDMA ↔ CPU/Linux

Ниже представлен скрин проекта в Vivado из реального проекта:

или простая реализация только для UartLite:

2.3 Разбор конфигурации XDMA и UartLite:

AXI UARTLite (Настройки IP)

• Частота AXI CLK: 62.5 МГц

• Скорость UART: 9600 бод

• Длина данных: 8 бит

• Четность (Parity): Отключена (No Parity)

Эти настройки стандартные для UARTLite, но если необходимо увеличить скорость передачи, можно выставить 115200 бод.

Настройки DMA (PCIe : DMA)

AXI PCIe DMA Product Guide (PG195)

Количество каналов

• 1 канал на чтение (H2C)

• 1 канал на запись (C2H)

• Количество Request IDs: 32 (чтение), 16 (запись)

• AXI ID Width: 4 (идентификатор транзакций в AXI)

  Descriptor Bypass (Отключен)

• Используется стандартное управление буферами (без байпаса).

Настройки прерываний (PCIe : MISC)

Количество прерываний: 16
MSI включен (Message Signaled Interrupts)
Расширенные теги включены (Extended Tag Field)

Настройки BAR (PCIe : BARS)

PCIe → AXI Lite Master Interface

• Размер памяти: 1MB

• Адрес: 0x00000000 PCIe → DMA Interface включен

Идентификаторы устройства (PCIe ID)

Vendor ID: 10EE (Xilinx)
Device ID: 7011
Class Code: 120000 (устройство памяти)

Базовые настройки PCIe (Basic)

[PCIe Base Specification (official summary)](Specifications | PCI-SIG)

PCIe x1, 2.5 GT/s
AXI Address Width: 64-bit
AXI Data Width: 64-bit
AXI Clock: 125 MHz
Режим: AXI Memory Mapped

Адресс UartLite:

2.2 Подключение SDR к материнской плате

3. Реализация драйвера

3.1 Подготовка окружения

Аппаратная платформа:

• SDR-плата: разработанная мной, FPGA Artix-7 200T

• GPS-модуль: SIM68

• Интерфейсы: PCIe, UART

• Материнская плата: Latte Panda Sigma

Программное обеспечение:

• ОС: Linux Kernel 6.x+

• Инструменты: Vivado, Python, GCC

• Отладка: dmesg, minicom

3.2 Установка зависимостей

sudo apt update
sudo apt install -y build-essential dkms linux-headers-$(uname -r) git
sudo apt install -y pciutils lshw
sudo apt install -y gcc-13 g++-13 
sudo apt install -y gpsd gpsd-clients

Что устанавливаем?

• build-essential — инструменты сборки (gcc, make, binutils)

• dkms — динамическое управление модулями ядра

• linux-headers-$(uname -r) — заголовочные файлы текущего ядра

• git — для загрузки исходников драйвера XDMA

• pciutils (lspci) — просмотр PCIe-устройств

• lshw — детальная информация об оборудовании

• gcc-13, g++-13 — компиляторы C и C++ версии 13

• gpsd, gpsd-clients — демоны и утилиты для работы с GPS-приёмниками

Проверка версии:

gcc-13 --version

3.3 Проверка оборудования

После установки убедимся, что PCIe-устройство (FPGA) распознаётся системой:

lspci -d 10ee:

Если XDMA-карта видна, будет вывод типа:

59:00.0 Memory controller: Xilinx Corporation Device 7011

Вот что показывает у меня:

3.4 Реализация драйвера

Принцип работы драйвера

При загрузке модуля драйвер регистрирует PCIe-устройство с Vendor ID 0x10EE и Device ID 0x7011. После инициализации он создаёт TTY-устройство /dev/ttyUL0. Входящие данные из UARTlite обрабатываются через механизм workqueue, передаются в буфер TTY и становятся доступны пользователю через функцию tty_flip_buffer_push (она сообщает ядру Linux, что в приёмном буфере появились новые данные, и эти данные нужно передать в пользовательское пространство и без её вызова данные будут висеть внутри драйвера и не дойдут до пользователя).

Linux TTY Documentation

Определение констант

#define DRIVER_NAME "uartlite_xdma" // Имя драйвера
#define VENDOR_ID 0x10EE  // Xilinx Vendor ID
#define DEVICE_ID 0x7011  // Device ID для FPGA Hard PCIe block
#define UARTLITE_BASE_OFFSET 0x40000 // Базовый адрес AXI**

• VENDOR_ID = 0x10EE — это Xilinx (задается в конфигурации IP ядра в Vivado, каждый производитель PCIe-устройств имеет свой ID).

• DEVICE_ID = 0x7011 — идентификатор устройства (задается в конфигурации IP ядра в Vivado).

• UARTLITE_BASE_OFFSET = 0x40000 — смещение в памяти, где находится UARTlite в пространстве XDMA (в моем прмере 0x40000 , орпеделяется проектом в Vivado)

Адреса регистров в памяти:

В соотвествии с datashhet AXI UartLite

#define UARTLITE_RX_FIFO  0x00  // FIFO приёма
#define UARTLITE_TX_FIFO  0x04  // FIFO передачи
#define UARTLITE_STATUS   0x08  // Регистр состояния
#define UARTLITE_CONTROL  0x0C  // Регистр управления

• RX_FIFO (0x00) — читаем данные, полученные от UART.

• TX_FIFO (0x04) — записываем данные для передачи.

• STATUS (0x08) — флаги состояния (данные есть? FIFO заполнен?).

• CONTROL (0x0C) — управление UARTlite.

Флаги регистра состояния

#define STATUS_RXVALID    BIT(0) // Данные есть в RX FIFO
#define STATUS_TXFULL     BIT(3) // TX FIFO заполнен

• RXVALID (бит 0) — 1, если в RX FIFO есть данные.

• TXFULL (бит 3) — 1, если TX FIFO заполнен.

Основная структура данных

struct uartlite_priv {
    void __iomem *base;
    struct tty_port port;
    struct work_struct rx_work; // Обработчик RX (workqueue)
    bool running;
};

Структура uartlite_priv хранит:

• base — указатель на базовый адрес устройства в PCIe.

• port — TTY-порт для связи с Linux.

• rx_work — задача для обработки входящих данных (workqueue).

• running — флаг работы (установлен, пока устройство активно).

Функции работы с UARTlite

static int uartlite_tx_ready(struct uartlite_priv *priv)
{
    return !(ioread32(priv->base + UARTLITE_STATUS) & STATUS_TXFULL);
}

Проверяет, можно ли передавать данные:

• Читает STATUS

• Если TXFULL == 0, значит, можно передавать.

static void uartlite_write_byte(struct uartlite_priv *priv, u8 val)
{
    iowrite32(val, priv->base + UARTLITE_TX_FIFO);
}

Записывает 1 байт в TX FIFO.

static int uartlite_rx_ready(struct uartlite_priv *priv)
{
    return ioread32(priv->base + UARTLITE_STATUS) & STATUS_RXVALID;
}

Проверяет, есть ли данные в RX FIFO.

static u8 uartlite_read_byte(struct uartlite_priv *priv)
{
    return ioread32(priv->base + UARTLITE_RX_FIFO);
}

Считывает 1 байт из RX FIFO.

Обработка приёма данных (RX)

В этом драйвере используется поллинг RX FIFO (приёмного буфера UARTlite) через workqueue , для упрощения реализации, что бы не использовать механизм работы через прерывания.

Поллинг (polling) — это метод обработки данных, при котором процессор периодически проверяет состояние устройства и считывает данные, если они доступны.

Как работает поллинг в драйвере?

1. Приложение открывает TTY-устройство (/dev/ttyUL0)

• Вызывается uartlite_tty_open(), который устанавливает флаг running = true.

• Запускается обработчик uartlite_rx_work() с помощью schedule_work().

2. Функция uartlite_rx_work() проверяет, есть ли данные в RX FIFO

• Читает регистр статуса (UARTLITE_STATUS).

• Если в RX FIFO есть данные (STATUS_RXVALID = 1), читает и буферизует их и передаёт в TTY (tty_flip_buffer_push,tty_insert_flip_string).

3. Если FIFO не пуст, данные передаются в TTY-подсистему

• Вызываются:

  tty_insert_flip_string(&priv->port, buf, count); 
  tty_flip_buffer_push(&priv->port);

• Данные становятся доступны в /dev/ttyUL0.

4. После обработки данных обработчик uartlite_rx_work() самозапускается

• Если running = true, функция снова вызывается (schedule_work()).

• Если running = false, процесс останавливается (например, после закрытия /dev/ttyUL0).

static void uartlite_rx_work(struct work_struct *work)
{
  struct uartlite_priv *priv = container_of(work, struct uartlite_priv, rx_work);
    struct tty_struct *tty = tty_port_tty_get(&priv->port);
    unsigned char buf[16];
    int i, count;

    if (!tty)
        return;

    while (priv->running && uartlite_rx_ready(priv)) {
        count = 0;
        for (i = 0; i < sizeof(buf) && uartlite_rx_ready(priv); i++) {
            buf[i] = uartlite_read_byte(priv);
            count++;
        }
        if (count) {
            tty_insert_flip_string(&priv->port, buf, count);
            tty_flip_buffer_push(&priv->port);
        }
    }

    if (priv->running)
        schedule_work(&priv->rx_work);

    tty_kref_put(tty);
}

Регистрация PCIe-устройства

Регистрирует PCIe-драйвер следующая функция:

static struct pci_driver uartlite_pci_driver = {
    .name = DRIVER_NAME,
    .id_table = uartlite_pci_tbl,
    .probe = uartlite_probe,
    .remove = uartlite_remove,
};

• При обнаружении устройства → вызов uartlite_probe()

• При удалении устройства → вызов uartlite_remove()

Код ниже определяет таблицу идентификаторов PCI-устройств, которые поддерживает драйвер.

static const struct pci_device_id uartlite_pci_tbl[] = {
    { PCI_DEVICE(VENDOR_ID, DEVICE_ID) },
    { 0, }
};

• static const struct pci_device_id uartlite_pci_tbl[]

  • Определяет массив uartlite_pci_tbl с информацией о поддерживаемых PCIe-устройствах.

  • Используется ядром Linux для поиска устройств, которые драйвер может обслуживать.

• { PCI_DEVICE(0x10EE, 0x7011) }

  • PCI_DEVICE(vendor, device) — макрос, создающий pci_device_id структуру.

  • 0x10EE — Vendor ID (Xilinx).

  • 0x7011 — Device ID (ID конкретного устройства, в данном случае UARTlite).

• { 0, }

  • Завершающий элемент массива (нулевой идентификатор), который указывает конец списка.

Если система найдёт устройство с Vendor ID 0x10EE и Device ID 0x7011, вызовется probe()- функция драйвера:

static int uartlite_probe(struct pci_dev *pdev, const struct pci_device_id *ent)

Основная задача:

• Выделить память для структуры драйвера (uartlite_priv).

• Настроить доступ к PCIe-ресурсам (IO-адреса, регистры).

• Зарегистрировать UARTlite как TTY-устройство (/dev/ttyUL0).

• Подготовить очередь задач (workqueue) для приёма данных.

Инициализация модуля

module_init(uartlite_init);
module_exit(uartlite_exit);

3.5 Полный код драйвера (uartlite_xdma.c)

/*
 * UARTlite TTY Driver over XDMA
 *
 * Author: 
 * Date: 
 *
 * This driver enables communication with AXI UART Lite over PCIe XDMA.
 * It implements a TTY interface (ttyULx) for user-space interaction and supports
 * RX polling using a work queue mechanism.
 *
 * License: GPL v2
 */

 #include <linux/version.h>
#include <linux/module.h>
#include <linux/pci.h>
#include <linux/tty.h>
#include <linux/tty_driver.h>
#include <linux/tty_flip.h> // tty_insert_flip_string и tty_flip_buffer_push
#include <linux/io.h>
#include <linux/workqueue.h> // work_struct

// External information
#define DRIVER_NAME "uartlite_xdma" // Driver name
#define VENDOR_ID 0x10EE  // Xilinx Vendor ID
#define DEVICE_ID 0x7011  // Device ID for 7-Series FPGA Hard PCIe block
#define UARTLITE_BASE_OFFSET 0x40000 // AXI base address

// AXI UART Lite Register Offsets
#define UARTLITE_RX_FIFO  0x00  // Receive FIFO
#define UARTLITE_TX_FIFO  0x04  // Transmit FIFO
#define UARTLITE_STATUS   0x08  // Status register
#define UARTLITE_CONTROL  0x0C  // Control register

// Status Register Flags
#define STATUS_RXVALID    BIT(0) // Data available in RX FIFO
#define STATUS_TXFULL     BIT(3) // TX FIFO is full



struct uartlite_priv {
    void __iomem *base;
    struct tty_port port;
    struct work_struct rx_work; // Polling
    bool running;
};

static struct tty_driver *uartlite_tty_driver;

/* UART Lite Functions */
static int uartlite_tx_ready(struct uartlite_priv *priv)
{
    return !(ioread32(priv->base + UARTLITE_STATUS) & STATUS_TXFULL);
}

static void uartlite_write_byte(struct uartlite_priv *priv, u8 val)
{
    iowrite32(val, priv->base + UARTLITE_TX_FIFO);
}

static int uartlite_rx_ready(struct uartlite_priv *priv)
{
    return ioread32(priv->base + UARTLITE_STATUS) & STATUS_RXVALID;
}

static u8 uartlite_read_byte(struct uartlite_priv *priv)
{
    return ioread32(priv->base + UARTLITE_RX_FIFO);
}

/* Work function for polling RX FIFO */
static void uartlite_rx_work(struct work_struct *work)
{
    struct uartlite_priv *priv = container_of(work, struct uartlite_priv, rx_work);
    struct tty_struct *tty = tty_port_tty_get(&priv->port);
    unsigned char buf[16];
    int i, count;

    if (!tty)
        return;

    while (priv->running && uartlite_rx_ready(priv)) {
        count = 0;
        for (i = 0; i < sizeof(buf) && uartlite_rx_ready(priv); i++) {
            buf[i] = uartlite_read_byte(priv);
            count++;
        }
        if (count) {
            tty_insert_flip_string(&priv->port, buf, count);
            tty_flip_buffer_push(&priv->port);
        }
    }

    if (priv->running)
        schedule_work(&priv->rx_work);

    tty_kref_put(tty);
}

/* TTY Operations */
static int uartlite_tty_open(struct tty_struct *tty, struct file *filp)
{
    struct uartlite_priv *priv = container_of(tty->port, struct uartlite_priv, port);
    priv->running = true;
    schedule_work(&priv->rx_work);
    return tty_port_open(tty->port, tty, filp);
}

static void uartlite_tty_close(struct tty_struct *tty, struct file *filp)
{
    struct uartlite_priv *priv = container_of(tty->port, struct uartlite_priv, port);
    priv->running = false;
    cancel_work_sync(&priv->rx_work);
    tty_port_close(tty->port, tty, filp);
}


#if LINUX_VERSION_CODE <= KERNEL_VERSION(6, 5, 0)
static int uartlite_tty_write(struct tty_struct *tty, const unsigned char *buf, int count)
#else
static ssize_t uartlite_tty_write(struct tty_struct *tty, const u8 *buf, size_t count)
#endif
{
    struct uartlite_priv *priv = tty->driver_data;
    int i;

    for (i = 0; i < count; i++) {
        while (!uartlite_tx_ready(priv))
            cpu_relax();
        uartlite_write_byte(priv, buf[i]);
    }
    return i;
}


static unsigned int uartlite_tty_write_room(struct tty_struct *tty)
{
    struct uartlite_priv *priv = tty->driver_data;
    return uartlite_tx_ready(priv) ? 16 : 0;
}

static unsigned int uartlite_tty_chars_in_buffer(struct tty_struct *tty)
{
    return 0;
}

static const struct tty_operations uartlite_tty_ops = {
    .open = uartlite_tty_open,
    .close = uartlite_tty_close,
    .write = uartlite_tty_write,
    .write_room = uartlite_tty_write_room,
    .chars_in_buffer = uartlite_tty_chars_in_buffer,
};

/* TTY Port Initialization */
static int uartlite_port_activate(struct tty_port *port, struct tty_struct *tty)
{
    struct uartlite_priv *priv = container_of(port, struct uartlite_priv, port);
    tty->driver_data = priv;
    return 0;
}

static void uartlite_port_shutdown(struct tty_port *port)
{
    struct uartlite_priv *priv = container_of(port, struct uartlite_priv, port);
    priv->running = false;
    cancel_work_sync(&priv->rx_work);
}

static const struct tty_port_operations uartlite_port_ops = {
    .activate = uartlite_port_activate,
    .shutdown = uartlite_port_shutdown,
};

/* PCI Probe Function */
static int uartlite_probe(struct pci_dev *pdev, const struct pci_device_id *ent)
{
    struct uartlite_priv *priv;
    int ret;

    priv = devm_kzalloc(&pdev->dev, sizeof(*priv), GFP_KERNEL);
    if (!priv)
        return -ENOMEM;

    ret = pcim_enable_device(pdev);
    if (ret)
        return ret;

    priv->base = pcim_iomap(pdev, 0, 0);
    if (!priv->base)
        return -ENOMEM;

    priv->base += UARTLITE_BASE_OFFSET;

    tty_port_init(&priv->port);
    priv->port.ops = &uartlite_port_ops;
    INIT_WORK(&priv->rx_work, uartlite_rx_work);
    priv->running = false;

    tty_port_register_device(&priv->port, uartlite_tty_driver, 0, &pdev->dev);

    pci_set_drvdata(pdev, priv);
    dev_info(&pdev->dev, "UARTlite over XDMA registered as TTY");
    return 0;
}

static void uartlite_remove(struct pci_dev *pdev)
{
    struct uartlite_priv *priv = pci_get_drvdata(pdev);
    tty_unregister_device(uartlite_tty_driver, 0);
    tty_port_destroy(&priv->port);
}

static const struct pci_device_id uartlite_pci_tbl[] = {
    { PCI_DEVICE(VENDOR_ID, DEVICE_ID) },
    { 0, }
};

static struct pci_driver uartlite_pci_driver = {


    .name = DRIVER_NAME,
    .id_table = uartlite_pci_tbl,
    .probe = uartlite_probe,
    .remove = uartlite_remove,
};

/* Module Initialization */
static int __init uartlite_init(void)
{
    int ret;

    uartlite_tty_driver = tty_alloc_driver(1, TTY_DRIVER_REAL_RAW | TTY_DRIVER_DYNAMIC_DEV);
    if (IS_ERR(uartlite_tty_driver))
        return PTR_ERR(uartlite_tty_driver);

    uartlite_tty_driver->driver_name = DRIVER_NAME;
    uartlite_tty_driver->name = "ttyUL";
    uartlite_tty_driver->major = 0;
    uartlite_tty_driver->minor_start = 0;
    uartlite_tty_driver->type = TTY_DRIVER_TYPE_SERIAL;
    uartlite_tty_driver->subtype = SERIAL_TYPE_NORMAL;
    uartlite_tty_driver->init_termios = tty_std_termios;
    uartlite_tty_driver->init_termios.c_cflag = B9600 | CS8 | CREAD | HUPCL | CLOCAL;

    tty_set_operations(uartlite_tty_driver, &uartlite_tty_ops);

    ret = tty_register_driver(uartlite_tty_driver);
    if (ret) {
        tty_driver_kref_put(uartlite_tty_driver);
        return ret;
    }

    ret = pci_register_driver(&uartlite_pci_driver);
    if (ret) {
        tty_unregister_driver(uartlite_tty_driver);
        tty_driver_kref_put(uartlite_tty_driver);
    }

    return ret;
}

static void __exit uartlite_exit(void)
{
    pci_unregister_driver(&uartlite_pci_driver);
    tty_unregister_driver(uartlite_tty_driver);
    tty_driver_kref_put(uartlite_tty_driver);
}

module_init(uartlite_init);
module_exit(uartlite_exit);

MODULE_LICENSE("GPL v2");
MODULE_AUTHOR("Konstantin");
MODULE_DESCRIPTION("UARTlite TTY driver over XDMA with RX support");

3.6 Сборка, тестирование и отладка

Перед сборкой драйвера убедись, что установлены заголовочные файлы текущего ядра:

sudo apt update
sudo apt install -y linux-headers-$(uname -r)

Проверка:

ls /lib/modules/$(uname -r)/build

Если каталог существует, значит заголовочные файлы установлены.

Сборка драйвера

Ниже представлена Makefile для сборки драйвера

# Build the kernel module
obj-m += uartlite_xdma.o

# Kernel build directory (default: current running kernel)
KDIR ?= /lib/modules/$(shell uname -r)/build

# Build the module
all:
    make CC=/usr/bin/gcc-13 -C $(KDIR) M=$(PWD) modules

# Clean up compiled files
clean:
    make -C $(KDIR) M=$(PWD) clean

# Install the module into the system
install:
    make -C $(KDIR) M=$(PWD) modules_install

# Enable debugging symbols (-g flag for debugging)
EXTRA_CFLAGS += -g

# Define targets that are not actual files
.PHONY: all clean install

Запустим команду:

make

После успешной сборки появится файл uartlite_xdma.ko — готовый модуль ядра.

Примеры вывода при правильной сборке драйвера

Проверка:

ls -l uartlite_xdma.ko

в мое случае следующий вывод:

-rwxr-xr-x 1 nvx root 390152 Mar 13 18:15 uartlite_xdma.ko

Запуск драйвера

Загрузка драйвера в ядро и проверяем, что драйвер загружен:

sudo insmod uartlite_xdma.ko
lsmod | grep uartlite_xdma

Если всё правильно, модуль появится в списке.

uartlite_xdma          12288  0

Вывод логов драйвера:

sudo dmesg | tail -n 20

Пример вывода:

Проверка создания TTY-устройства:

ls /dev/ttyUL*

Пример вывода:

/dev/ttyUL0

Проверка работы

sudo minicom -D /dev/ttyUL0 

Ожидаемый вывод:

$GPGGA,123456.78,5540.1234,N,03734.5678,E,1,08,0.9,100.0,M,0.0,M,,*47

Мой пример вывода (GPS антенна не подклчена):

Так же можно подключить наш tty к gpsd:

Запускаем gpsd, привязываем его к ttyUL0:

sudo gpsd /dev/ttyUL0 -F /var/run/gpsd.sock

• /dev/ttyUL0 — устройство UART, к которому подключён GPS

• -F /var/run/gpsd.sock — создаёт UNIX-сокет для работы с GPS

или:

sudo gpsd -N -D3 -F /var/run/gpsd.sock /dev/ttyUL0

• -N — не уходит в фон (можно сразу видеть ошибки).

• -D3 — включает отладку.

• /dev/ttyUL0 — указываем правильный UART-порт GPS.

Проверяем, работает ли gpsd

ps aux | grep gpsd

Если gpsd запущен, должно быть что-то вроде:

root         7131  0.0  0.0   9084  2432 pts/3    S+   18:51   0:00 grep --color=auto gpsd

Запускаем cgps (отображает координаты, скорость, высоту и время):

cgps -s

Если GPS работает, появится информация, например:

Time: 2025-03-13T12:34:56Z 
Latitude: 55.7558 N 
Longitude: 37.6173 E 
Speed: 0.5 km/h 
Altitude: 200 m

Проверяем сырые данные с GPS-модуля:

gpspipe -r

Это покажет сырые NMEA-пакеты, например:

$GPGGA,123456.00,5537.348,N,03736.882,E,1,08,1.0,200.0,M,0.0,M,,*47 
$GPRMC,123456.00,A,5537.348,N,03736.882,E,0.5,45.0,130324,,,A*7C

Удаление драйвера

Выгрузка модуля:

sudo rmmod uartlite_xdma

Очистка собранных файлов:

make clean

5 Работа с UARTlite через XDMA на Python

Помимо использования драйвера, можно работать с UARTlite напрямую через XDMA с помощью Python. Это полезно для отладки и быстрого тестирования или для безопастной реализации функционала в userspace.

5.1 Сборка драйвера XDMA

Перед использованием XDMA необходимо скомпилировать и установить драйвер. Драйвер XDMA поставляется Xilinx и поддерживает работу с PCIe-устройствами, реализующими DMA.
XDMA Linux Kernel Drivers GitHub

5.2 Загрузка исходников драйвера XDMA

Исходники драйвера доступны в официальном репозитории Xilinx:

git clone https://github.com/Xilinx/dma_ip_drivers.git
cd dma_ip_drivers/XDMA/linux-kernel###

5.3 Компиляция драйвера

Перед сборкой убедитесь, что у вас установлены заголовочные файлы ядра:

sudo apt-get install linux-headers-$(uname -r)

Компилируем драйвер :

make

пример вывода:

5.4 Установка и загрузка драйвера

sudo make install
sudo modprobe xdma

пример вывода:

Если не получилось , есть другой путь загрузки драйвера после сборки:

cd dma_ip_drivers/XDMA/linux-kernel/tests/
sudo ./load_driver.sh 

Ожидаемый вывод:

interrupt_selection .
xdma                   24576  0
Loading driver...insmod xdma.ko interrupt_mode=2 ...

The Kernel module installed correctly and the xmda devices were recognized.
DONE

Проверяем, что модуль загружен:

lsmod | grep xdma

ожидаемый вывод:

xdma                  110592  0

После установки драйвера в системе появятся файлы устройств:

ls /dev/xdma*

Ожидаемый вывод:

/dev/xdma0_c2h_0  /dev/xdma0_h2c_0  /dev/xdma0_control  /dev/xdma0_user

В моем случае:

• DMA-драйвер загружен и создал файлы в /dev/.

• Можно чтение/запись через c2h_0 (FPGA → CPU) и h2c_0 (CPU → FPGA).

• Прерывания можно отслеживать через xdma_events_*.

• XVC позволяет работать с JTAG через PCIe.

Если файлы появились, драйвер установлен и XDMA готов к работе, то можно переходить к тестированию UARTlite.

5.6 Код работы с UARTlite через XDMA в Python (uaxdma.py)

Принцип работы:
Скрипт открывает устройство /dev/xdma0_user, отображая память XDMA в адресное пространство процесса с помощью mmap. Затем он обращается к регистрам UARTlite по смещению 0x40000, читая данные из RX или записывая в TX . Это позволяет напрямую взаимодействовать с UARTlite без использования драйвера ядра.

import os
import time
import numpy as np
import mmap
import asyncio

# ============================ #
#  XDMA + UARTLite (Объединено)
# ============================ #
class XdmaUartLite:
    BASE_ADDR = 0x40000  # Базовый адрес UARTLite в XDMA

    # Оффсеты регистров UARTLite
    RX_FIFO = 0x00
    TX_FIFO = 0x04
    STATUS = 0x08
    CONTROL = 0x0C

    # Флаги
    TX_FULL = 0x08
    RX_VALID = 0x01
    TX_RESET = 0x01
    RX_RESET = 0x02

    def __init__(self, device_index=0):
        """Инициализация XDMA и UARTLite"""
        base = f"/dev/xdma{device_index}"

        # Открываем файлы для работы с XDMA
        self.fd_user = os.open(f"{base}_user", os.O_RDWR)

        # Создаём отображение памяти для быстрого доступа
        self.m_rmap = np.frombuffer(mmap.mmap(self.fd_user, int(1e6)), np.uint32)

        # Сбрасываем FIFO UARTLite
        self.reset_fifos()

    def close(self):
        """Закрываем файлы XDMA при завершении"""
        os.close(self.fd_user)


    # ============================ #
    #  Чтение/Запись через XDMA
    # ============================ #
    def read_reg(self, addr):
        """Читаем 32-битное значение из регистра"""
        return self.m_rmap[addr >> 2] & 0xFFFF

    def write_reg(self, addr, data):
        """Записываем 32-битное значение в регистр"""
        self.m_rmap[addr >> 2] = np.uint32(data)

    # ============================ #
    #  Работа с UARTLite
    # ============================ #
    def reset_fifos(self):
        """Сбрасываем FIFO передатчика и приёмника"""
        self.write_reg(self.BASE_ADDR + self.CONTROL, self.TX_RESET | self.RX_RESET)

    def send_byte(self, data):
        """Отправляем 1 байт через UARTLite"""
        while self.read_reg(self.BASE_ADDR + self.STATUS) & self.TX_FULL:
            pass  # Ждём, пока FIFO не освободится
        self.write_reg(self.BASE_ADDR + self.TX_FIFO, data)

    def recv_byte(self):
        """Получаем 1 байт через UARTLite"""
        while not (self.read_reg(self.BASE_ADDR + self.STATUS) & self.RX_VALID):
            pass  # Ждём, пока появятся данные
        return self.read_reg(self.BASE_ADDR + self.RX_FIFO)

    def send_data(self, data):
        """Отправляем массив байтов через UARTLite"""
        for byte in data:
            self.send_byte(byte)

    def recv_data(self, size):
        """Получаем массив байтов через UARTLite"""
        return bytearray([self.recv_byte() for _ in range(size)])

    async def recv_byte_async(self):
        """Асинхронное чтение 1 байта."""
        while not (self.read_reg(self.BASE_ADDR + self.STATUS) & self.RX_VALID):
            await asyncio.sleep(0.001)  # Дадим CPU отдохнуть, чтобы не нагружать 100%
        return self.read_reg(self.BASE_ADDR + self.RX_FIFO)

    async def recv_data_async(self, size):
        """Асинхронное чтение массива байтов."""
        return bytearray([await self.recv_byte_async() for _ in range(size)])

# ============================ #
#  Тестирование XDMA + UARTLite
# ============================ #



### Простой вариант 
# if __name__ == "__main__":
#     # Инициализируем XDMA+UARTLite
#     xdma_uart = XdmaUartLite(device_index=0)

#     print("Ожидание данных с UARTLite...")
#     while True:
#         data = xdma_uart.recv_data(128)  # Читаем 128 байта
#         if data:
#             print(data.decode(errors="ignore").strip())  # Убираем пустые строки и пробелы


### Вариант с async
async def main():
    uart = XdmaUartLite()
    while True:
        data = await uart.recv_data_async(128)
        print(data.decode(errors="ignore"))

asyncio.run(main())

Запустим :

sudo python3 uaxdma.py

Пример вывода:

5.6 Профилирование

Анализ производительности uaxdma.py с помощью py-spy для реализации с async:

для обычной реализации:

Загруженность процессора

• Polling (второе изображение): 100% CPU, read_reg занимает 93% времени.

• Async-версия (первое изображение): 1% CPU, read_reg практически не нагружает систему.

Время выполнения функций

• Polling: read_reg занимает 8.7s из 8.7s (то есть программа почти полностью занята проверкой данных).

• Async: read_reg выполняется всего 0.01s, а основное время уходит на asyncio.sleep(), что снижает нагрузку.

6. Выводы

Разработанные решения обеспечивают стабильную передачу данных от GPS-модуля через UARTlite к приложению, упрощая интеграцию периферии FPGA в SDR-системы. Использование прерываний вместо polling может снизить нагрузку на CPU, а оптимизация буферизации — увеличить пропускную способность. Это делает решение полезным для широкого круга проектов, от прототипирования до промышленных приложений.

Данный проект реализует два подхода к работе с UARTlite через XDMA:

1. Классический Linux-драйвер с TTY, который позволяет работать с устройством как с обычным UART

2. Прямая работа через Python – даёт возможность разрабатывать приложения без написания kernel драйверов, а так же отлаживать код в безопастном режиме по сравнению с разработкой в kernel.

Достоинства решения:

Поддержка стандартного Linux TTY

Возможность работы через Python без собственного драйвера

Возможные улучшения:

Добавить поддержку прерываний вместо polling

7. Заключение

Разработка Linux-драйвера и работа с XDMA через Python позволяют эффективно использовать UARTlite и другие IP в проектах.

Так же статья есть на Medium!

📚 Дополнительные материалы

• UARTLite XDMA Driver GitHub Repository

• AXI UARTLite Product Guide (PG142)

• XDMA PCIe DMA Product Guide (PG195)

• Xilinx dma_ip_drivers GitHub

• Linux TTY Subsystem Documentation

• SIM68 GPS Module Datasheet

• PCIe Specification Overview

Если эта статья помогла вам не бояться писать драйверы, или хотя бы сэкономила пару вечеров на отладке XDMA — значит, я старался не зря. 😉

В мире FPGA и Linux драйверов всегда найдётся что-то, что можно сделать красивее. Главное — не бояться лезть под капот. Всем лёгкой разработки и
Удачной сборки, мягких загрузок, и чтоб dmesg всегда был полон только хорошими новостями, и меньше kernel panic!🙌

👉 Понравилось? Жду ваши вопросы и мысли в комментариях!