STM32 - организация виртуального COM-порта

Раз у камня есть аппаратный USB, то грех им не пользоваться. Один из способов плюнуть байтом в компьютер и чтобы он при этом не очень обиделся — это организация виртуального COM-порта.
Все в железе пробовалось на камне STM32F103ZE, на аналогах тоже должно взлететь.

Забиваем.

Как я уже говорил, пока я сторонник библиотечных решений. Памяти хватает, байтовыцарапыванием заниматься рано. Так что пойдем по легкому пути.

STM предоставила нам библиотеку STM32F10x and STM32L1xx USB full-speed device library, версия 3.3.0
Описание к ней: документ CD00158241 — UM0424 User manual

Точные названия я привожу на случай если на сайте производителя будет какая-нибудь реорганизация и ссылки станут невалидными.

Не забываем дрова виртуального ком-порта. У меня вообще-то оно само все нашлось, но я много чего ставил от STM, может там в комплекте и пришлись.

Также нам пригодятся следующие стандарты
USB 2.0 Specification
USB CDC

В составе библиотеки есть пример как раз организации виртуального COM-порта. Правда там он сделан как мост USART-USB, но мы же не боимся трудностей?

Цель этой статьи — разобрать приложение, делающее следующее:

Поджигаем

Собираем проект из нужных нам библиотек: CMSIS, SPD, USB. Дерево проекта прилагаю.

Как обычно, самое интересное в папочке /src. Вот её-то и будем разбирать.

Неторопливо курим

Начнем с раскуривания библиотеки от STM



Эта библиотека предназначена и для connectivity-line устройств (это STM32F105/107), у них не просто USB FS, а USB OTG. Поскольку камней с OTG у меня пока нет, сконцентрируемся на простом USB FS.
В примере, который мы взяли за основу, есть куча дефайнов, как раз на случай отличить connectivity-line от других демоплат. Я эти дефайны повырезал, чтобы глаза не мозолили.

Cо всей картинки нас интересует High Layer — синенькие квадратики, которые и составляют, собственно, пользовательскую часть библиотеки. Их мы меняем под свои нужды, все остальное остается неизменным. Если заглянуть в папочку /src, то видно, что все эти файлики там и собраны.

Первая затяжка — usb_conf.h

Самые общие настройки библиотеки.
Указано сколько у нас будет endpoints (а нам их надо 4 штуки — нулевой для начального конфигурирования устройства, один для команд, один для приема и один для передачи).
Также расписаны, какие нам будут нужны коллбэки. Все взаимодействие библиотеки и пользовательской программы построено на обратных вызовах: в случае возникновения какого-либо события вызывается функция с заданным названием. А уже содержание этой функции — проблема разработчика.
Нам будет нужен SOF_CALLBACK – сигнал начала фрейма (Start Of Frame). По нему будем выплевывать то, что накопилось в буфере передачи.
Также резервируем еще два коллбэка — на прием и передачу. По приему символа будем мигать светодиодами, чтобы уж как-нибудь задействовать канал приема.

Упс, кончился файл. Короткая получилась затяжка.

Файл берем из примера, ничего не меняем.

Вторая затяжка — usb_desc.h / usb_desc.c

В этих файлах находятся дескрипторы устройства и эндпоинтов.
Информация по стандартным дескрипторам есть в стандарте USB, в разделе 9.6 Standard USB Descriptor Definitions
Специфические дескрипторы описаны в USB CDC, раздел 5 (так и называется Descriptors),

Эти все тонны текста в стандартах для того, чтобы USB стала действительно Universal. Поэтому тщательно выведена классификация устройств и интерфейсов — чтобы глянув на дескриптор хост сразу понял, что с этим делать.

Особо подробно разбирать смысла не вижу — это не характерно для STM32, это общая боль разработчиков USB устройств.

Файл берем из примеров, ничего не меняем.

Продолжение дескрипторов — usb_prop.h / usb_prop.c

В этих файлах описана таблица реакции на запросы. Все запросы к устройству пронумерованы и стандартизованы. В этих файлах определяется массивы функций Device_Property, User_Standard_Requests и просто массивы String_Descriptor, например. Это все используется ядром. Когда в устройство приходит определенный запрос, например «Выдай мне дескриптор устройства», то ядро посмотрит в таблице, какая функция обрабатывает этот запрос, вызовет эту функцию, а оно уже отработает:

uint8_t *Virtual_Com_Port_GetDeviceDescriptor(uint16_t Length)
{
  return Standard_GetDescriptorData(Length, &Device_Descriptor);
}

Опять же, берем файл из примеров.

Прерываемся — usb_istr.h / usb_istr.c

Тоже два коротеньких файла. В них находится то, что надо вызывать при приходе прерывания от USB. Поскольку прерывание одно, то по значениям флагов определяется событие и вызывается соответствующий коллбэк.

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

void USB_LP_CAN1_RX0_IRQHandler(void)
{
USB_Istr();
}

его можно разместить в файлах stm32f10x_it.*, а в данном проекте, чтобы не растекаться мысью по древу, я его включил в файл main.c

И тут особо ничего не меняем, все как в примере.

Питание — usb_pwr.h / usb_pwr.c

Здесь все, что касается питания. По стандарту, устройство может быть переведено в режим спячки, тогда, если оно питается от порта, нужно позаботиться об отключении жрущей периферии. Поскольку у нас плата питается отдельно, то особого смысла в управлении питанием нет. Просто устройство формально переводится в состояние SUSPENDED.

Ничего не меняем, файл из примеров.

Коллбэки — usb_endp.c

Этот файл я переписал, поскольку у нас не будет работы с USART, как это было в примере. Приведу код с комментариями:

/* Сколько фреймов будет между отсылкой наших пакетов. */
#define VCOMPORT_IN_FRAME_INTERVAL             5

// буфер приема данных из USB, исходя из этих данных будем мигать светодиодами
uint8_t USB_Rx_Buffer[VIRTUAL_COM_PORT_DATA_SIZE];

// для нас отправка, для хоста IN. Путает немного название, но справимся
// выполняем отправку данных, накопленных в буфере USART_Rx_Buffer
// название буфера не менял, так и осталось историческое
void EP1_IN_Callback (void)
{
	Handle_USBAsynchXfer();
}

// коллбэк при приеме данных от хоста. Анализируем посимвольно и мигаем светодиодами
void EP3_OUT_Callback(void)
{
  uint16_t USB_Rx_Cnt;
  uint16_t i;
  
  /* Get the received data buffer and update the counter */
  USB_Rx_Cnt = USB_SIL_Read(EP3_OUT, USB_Rx_Buffer);

  for (i=0; i<USB_Rx_Cnt; i++) {
	  USB_SetLeds(USB_Rx_Buffer[i]);
  }
  
  /* Enable the receive of data on EP3 */
  SetEPRxValid(ENDP3);
}

// коллбэк по началу фрейма. 
// Через определенное количество фреймов сбрасываем накопившийся буфер.
void SOF_Callback(void)
{
  static uint32_t FrameCount = 0;
  
  if(bDeviceState == CONFIGURED)
  {
    if (FrameCount++ == VCOMPORT_IN_FRAME_INTERVAL)
    {
      /* Reset the frame counter */
      FrameCount = 0;
      
      /* Check the data to be sent through IN pipe */

      Handle_USBAsynchXfer();

    }
  }  
}

Работа с железом — hw_config.h / hw_config.c

В этом файле собраны функции инициализации периферии, прерываний, функции управления светодиодами и работы с буфером отправки.

USB-порт и подтяжки на моей плате сделаны по такой схеме:


И USB_EN заведен на пин PF11. Значит надо не забыть его проинициализировать и дернуть вовремя.

void Set_System(void);
void Set_USBClock(void);
void Enter_LowPowerMode(void);
void Leave_LowPowerMode(void);
void USB_Interrupts_Config(void);
void USB_Cable_Config (FunctionalState NewState);
void Get_SerialNum(void);


void Handle_USBAsynchXfer (void);
void USB_Send_Data(uint8_t data);
void USB_SetLeds(uint8_t LED_Command);

По сравнению с примером, выкинуты функции инициализации и работы с USART, добавлена функция мигания светодиодом.

void USB_SetLeds(uint8_t LED_Command) {
	switch (LED_Command) {
	case 'A': {
	    GPIO_SetBits(GPIOF, GPIO_Pin_6);
	    break;
	}
	case 'B': {
	    GPIO_SetBits(GPIOF, GPIO_Pin_7);
	    break;
	}
	case 'C': {
	    GPIO_SetBits(GPIOF, GPIO_Pin_8);
	    break;
	}
	case 'D': {
	    GPIO_SetBits(GPIOF, GPIO_Pin_9);
	    break;
	}
	case 'a': {
	    GPIO_ResetBits(GPIOF, GPIO_Pin_6);
	    break;
	}
	case 'b': {
	    GPIO_ResetBits(GPIOF, GPIO_Pin_7);
	    break;
	}
	case 'c': {
	    GPIO_ResetBits(GPIOF, GPIO_Pin_8);
	    break;
	}
	case 'd': {
	    GPIO_ResetBits(GPIOF, GPIO_Pin_9);
	    break;
	}
	case '1': {
	    GPIO_SetBits(GPIOF, GPIO_Pin_6 | GPIO_Pin_7 |GPIO_Pin_8 |GPIO_Pin_9);
	    break;
	}
	case '0': {
	    GPIO_ResetBits(GPIOF, GPIO_Pin_6 | GPIO_Pin_7 |GPIO_Pin_8 |GPIO_Pin_9);
	    break;
	}
	}
}

По приему символов 'A', 'B', 'C', 'D' – зажигаются соответствующие светодиоды, 'a', 'b', 'c', 'd' – гасятся.
'1' и '0' — соответственно зажигают и гасят все светодиоды.

Ну и все, что будет передано функции USB_Send_Data() попадает в буфер, а затем и через USB – в комп.

Уфф. С USB вроде закончили.

Теперь в головной программе можно просто вызывать USB_Send_Data() и посимвольно передавать данные в комп.

Если мы на этом остановимся, то размер кода будет порядка 11 кБ:

arm-none-eabi-size  --format=berkeley test03.elf
   text	   data	    bss	    dec	    hex	filename
  11660	    236	   2744	  14640	   3930	test03.elf

Более двух килобайт bss – это буферы приема и передачи. Понятное дело, их можно уменьшить.

Выдыхаем — printf()

Но мы же хотим, чтобы вывод функции printf() перенаправлялся в наш свежесозданный COM-порт. Подключаем <stdio.h> и офигеваем от количества ошибок линковки:

sbrkr.c:(.text+0x12): undefined reference to `_sbrk'
writer.c:(.text+0x16): undefined reference to `_write'
closer.c:(.text+0x12): undefined reference to `_close'
lseekr.c:(.text+0x16): undefined reference to `_lseek'
readr.c:(.text+0x16): undefined reference to `_read'
fstatr.c:(.text+0x14): undefined reference to `_fstat'
isattyr.c:(.text+0x12): undefined reference to `_isatty'
collect2: ld returned 1 exit status
cs-make: *** [test03.elf] Error 1

А тут все просто — стандартная библиотека ввода-вывода подразумевает работу с файлами, но в больших системах есть ОС, которая собственно и занимается организацией файлов для программ пользователя. А поскольку у нас нет никакой ОС, то библиотека вполне справедливо недоумевает «А что же мне делать-то?»

Вот, чтобы это обойти, в проект включается файл newlib_stubs.c
В нем находятся функции-заглушки ко всем вышеперечисленным ошибкам. Но и кроме этого, есть одна функция, которую нам и надо переписать, чтобы весь вывод шел в USB:

int _write(int file, char *ptr, int len)
{
    int n;
    switch (file)
    {
    case STDOUT_FILENO: /*stdout*/
        for (n = 0; n < len; n++)
        {
        	USB_Send_Data((uint8_t) * ptr++);
        }
        break;
    case STDERR_FILENO: /* stderr */
        for (n = 0; n < len; n++)
        {
        	USB_Send_Data((uint8_t) * ptr++);
        }
        break;
    default:
        errno = EBADF;
        return -1;
    }
    return len;
}

Видим, что как раз и вызывается наша функция USB_Send_Data()

Все, компилим, собираем, запускаем.

arm-none-eabi-size  --format=berkeley test03.elf
   text	   data	    bss	    dec	    hex	filename
  19744	   1520	   2808	  24072	   5e08	test03.elf
Finished building: test03.siz

Архив с проектом прилагаю — это на случай, если кто не заметит маленькие буковки внизу :)