Драйвер контроллера SWIC для микросхемы 1892ВМ14Я. Руководство программиста

О документе

Документ содержит описание Linux-драйвера для контроллера SWIC микросхемы 1892ВМ14Я.

Общее описание

Драйвер elvees-swic предоставляет поддержку работы на канальном уровне SpaceWire:

1. Установка/разрыв соединения.
2. Получение статуса соединения.
3. Приём/передача пакетов SpaceWire.
4. Получение скорости приёма.
5. Установка/получение скорости передачи.
6. Установка размера пакета.

Драйвер реализует интерфейс символьного устройства Linux.

Ограничения драйвера:

1. Максимальный размер пакета (MTU) равен 1 МиБ (спецификация SpaceWire не регламентирует максимальный размер пакета).
2. Не поддерживается передача данных из/в пространство пользователя без копирования (zero-copy).
3. Не поддерживается передача коммуникационного пакета.
4. Не поддерживается работа с управляющими кодами.
5. Не поддерживается работа в дуплексном режиме.
6. Из-за ограничения rf#7224 возможна некорректная работа драйвера если к контроллеру DDRMC1 подключено более 1 ГиБ памяти.

Стандартные системные вызовы

Функция open()

Данная функция принимает в качестве аргумента имя устройства /dev/spacewireX, которое необходимо открыть и возвращает в пространство пользователя файловый дескриптор устройства.

Функция write()

При вызове функции write() драйвер выполняет:

1. Проверку на наличие соединения. Если соединение неактивно, вызов функции завершается с ошибкой ENOLINK.
2. Передачу входных пользовательских данных в канал SpaceWire. Если размер пользовательских данных больше установленного размера пакета (MTU), драйвер автоматически разбивает данные на порции размером не больше MTU. Каждая порция данных отправляется отдельным пакетом.

Если во время передачи данных произошел разрыв соединения, write() прекращает работу и возвращает количество байт, которое было передано на момент разрыва соединения.

Функция write() потокобезопасна.

Предупреждение

Из-за ограничения контроллера SWIC rf#11325 при завершении функции write() драйвер не гарантирует, что все пользовательские данные были отправлены. В результате при разрыве соединения после завершения write() возможна потеря данных.

Функция read()

При вызове функции read() драйвер выполняет:

1. Проверку на наличие соединения. Если соединение неактивно, вызов функции завершается с ошибкой ENOLINK.
2. Проверку размера пользовательского буфера. Если он меньше максимального размера пакета, функция завершается с ошибкой ENOBUFS.
3. Приём данных одного пакета из канала SpaceWire в пользовательский буфер.

Если во время приема данных произошел разрыв соединения, read() прекращает работу и возвращает количество байт, которое было принято на момент разрыва соединения.

Функция read() потокобезопасна.

Описание IOCTL

Перед вызовом функций ioctl() необходимо получить файловый дескриптор устройства, см. Функция open().

SWICIOC_SET_LINK

Установка/сброс соединения:

int ioctl(int fd, SWICIOC_SET_LINK, unsigned int link_status);

Данный вызов применим к файловому дескриптору устройства.

Аргументы:

• link_status — тип выполняемой операции: 0 — сброс соединения, 1 — установка соединения.

При сбросе соединения драйвер выполняет:

1. Сброс link-интерфейса контроллера.
2. Остановку RX DATA DMA.
3. Очистку всех FIFO.

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

1. Сброс соединения.
2. Включение PLL TX SWIC, LVDS SWIC.
3. Установку коэффициента для подсчёта таймаутов установки соединения.
4. Запуск TX DATA DMA в режиме самоинициализации.

Данный вызов возвращает управление, не дожидаясь установки соединения. Для чтения статуса соединения необходимо вызвать SWICIOC_GET_LINK_STATE.

SWICIOC_GET_LINK_STATE

Получение статуса соединения:

enum swic_link_state {
    LINK_ERROR_RESET,
    LINK_ERROR_WAIT,
    LINK_READY,
    LINK_STARTED,
    LINK_CONNECTING,
    LINK_RUN
};

int ioctl(fd, SWICIOC_GET_LINK_STATE, enum swic_link_state *link_status);

Данный вызов применим к файловому дескриптору устройства.

Статусы соединения:

• LINK_ERROR_RESET — соединение отсутствует.
• LINK_ERROR_WAIT — ошибка ожидания соединения.
• LINK_READY — узлы готовы к соединению.
• LINK_STARTED — установка соединения началась.
• LINK_CONNECTING — соединение устанавливается.
• LINK_RUN — соединение установлено.

При вызове драйвер возвращает в пространство пользователя один из статусов соединения.

SWICIOC_GET_SPEED

Получение скорости приёма и передачи:

struct elvees_swic_speed {
    unsigned int rx;
    unsigned int tx;
};

int ioctl(fd, SWICIOC_GET_SPEED, struct elvees_swic_speed *speed);

Данный вызов применим к файловому дескриптору устройства.

При вызове драйвер возвращает в пространство пользователя значения скоростей (в Кбит/с) приёма и передачи.

SWICIOC_SET_TX_SPEED

Установка скорости соединения:

enum swic_tx_speed {
    TX_SPEED_2P4,
    TX_SPEED_4P8,
    TX_SPEED_72 ,
    TX_SPEED_120,
    TX_SPEED_168,
    TX_SPEED_216,
    TX_SPEED_264,
    TX_SPEED_312,
    TX_SPEED_360,
    TX_SPEED_408
};

int ioctl(fd, SWICIOC_SET_TX_SPEED, enum swic_tx_speed tx_speed);

Данный вызов применим к файловому дескриптору устройства.

Возможные скорости передачи:

• TX_SPEED_2P4 — 2.4 Мбит/с,
• TX_SPEED_4P8 — 4.8 Мбит/с,
• TX_SPEED_72 — 72 Мбит/с,
• TX_SPEED_120 — 120 Мбит/с,
• TX_SPEED_168 — 168 Мбит/с,
• TX_SPEED_216 — 216 Мбит/с,
• TX_SPEED_264 — 264 Мбит/с,
• TX_SPEED_312 — 312 Мбит/с,
• TX_SPEED_360 — 360 Мбит/с,
• TX_SPEED_408 — 408 Мбит/с.

При вызове драйвер устанавливает скорость передачи, равную значению входного аргумента tx_speed.

Если значение входного аргумента ioctl() не входит в вышеперечисленный набор возможных скоростей, драйвер возвращает ошибку EINVAL.

SWICIOC_SET_MTU

Установка размера пакета:

int ioctl(fd, SWICIOC_SET_MTU, unsigned long mtu);

Данный вызов применим к файловому дескриптору устройства.

При вызове драйвер устанавливает размер пакета, равный значению входного аргумента mtu.

Если значение входного аргумента ioctl() превышает определённый в драйвере максимальный размер пакета, драйвер возвращает ошибку EINVAL.