Pull to refresh

Два в одном: USB хост и составное USB устройство

Reading time 12 min
Views 33K

image



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

Основная суть Пастильды заключается в том, что она является своеобразным переходником между клавиатурой и ПК. Таким образом, она должна уметь:
  • быть USB хостом для клавиатуры, которая к ней подключается,
  • быть клавиатурой для ПК, чтобы либо перенаправлять сообщения от реальной клавиатуры, либо самой быть клавиатурой,
  • быть дисковым накопителем, чтобы можно было редактировать базу данных паролей в удобном для человека виде.

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


Реализация USB хоста

Итак, во-первых мне нужно было реализовать на устройстве USB хост, чтобы оно могло распознавать и общаться с подключенной к нему клавиатурой. Так как в работе я использую связку Eclipse + GNU ARM Eclipse + libopencm3, то очень хотелось найти уже что-то готовое и желательно написанное с использованием библиотеки libopencm3. Желание мое было очень жирным, до последнего момента не верила, что мои поиски увенчаются успехом. Однако под конец рабочего дня, проскролив интернет до самого дна, я вдруг наткнулась вот на это. libusbhost? Серьезно? И это был не просто написанный на основе libopencm3 usb хост, он еще и был написан под STM32F4, под тот самый, который мы решили использовать в проекте. В общем, звезды сошлись и радости моей не было предела. Кстати, оказалось, что этот проект создавался как часть libopencm3, однако его так и не добавили в библиотеку.

Как библиотеку, libusbhost я не собирала, просто взяла необходимые мне исходники, написала драйвер для клавиатуры и, в общем-то все, погнали! Но обо всем по-порядку.

Из libusbhost я взяла следующие файлы:
  • usbh_device_driver.h
  • usbh_config.h
  • usbh_hubbed.[ch]
  • usbh_lld_stm32f4.[ch]

Там был еще файл usart_helpers.[ch], с его помощью можно было по UART передавать в терминал все сообщения, приходящие от устройства в хост и еще много различной отладочной информации. Я с этим функционалом поигралась, но из проекта его убрала.

По аналогии с usbh_driver_hid_mouse.[ch], я написала драйвер для клавиатуры (usbh_driver_hid_kbd.[ch]).

Далее был реализован простенький класс, для работы с хостом:

USB Host Class
constexpr uint8_t  USB_HOST_TIMER_NUMBER     = 6;
constexpr uint16_t USB_HOST_TIMER_PRESCALER  = (8400 - 1);
constexpr uint16_t USB_HOST_TIMER_PERIOD     = (65535);

typedef void (*redirect)(uint8_t *data, uint8_t len);
typedef void (*control_interception)();

static redirect redirect_callback;
static control_interception control_interception_callback;

class USB_host
{
public:
	USB_host(redirect redirect_callback, control_interception control_interception_callback);
	void poll();

	static void kbd_in_message_handler(uint8_t data_len, const uint8_t *data);

	static constexpr hid_kbd_config_t kbd_config = { &kbd_in_message_handler };
	static constexpr usbh_dev_driver_t *device_drivers[] =
	{
		(usbh_dev_driver_t *)&usbh_hid_kbd_driver
	};

private:
	TIMER_ext *_timer;
	void timer_setup();
	uint32_t get_time_us();
	void oth_hs_setup();
};


Здесь все прозрачно. Устройство должно слушать клавиатуру и ждать набора специальной комбинации клавиш, для перехода в режим выбора логина и пароля. Это происходит в обработчике прерывания от клавиатуры kbd_in_message_handler(uint8_t data_len, const uint8_t *data). Тут есть два варианта развития событий:
  • Если комбинации нет, то нам нужно пропустить сообщение от клавиатуры дальше в ПК. Для обработки данного события, в конструктор передана функция _redirect_callback.
  • Если комбинация нажата, то нам нужно оповестить систему о том, что мы перешли в режим выбора логина и пароля, следовательно, мы больше не транслируем сообщения от клавиатуры в ПК. Теперь само устройство является клавиатурой, а сообщения от настоящей клавиатуры теперь интерпретируются как команды устройству. Для обработки такого события, в конструктор передана функция _control_interception_callback.


Реализация составного USB устройства

Далее мне нужно было сделать так, чтобы наше устройство отображалось в диспетчере устройств и как клавиатура, и как дисковый накопитель. Тут вся магия в дескрипторах=) В этом документе, в главе 9, подробно описан USB Device Framework. Эту главу нужно очень внимательно прочитать и в соответствии с ней описать дескрипторы устройства. В моем случае получилось следующее:

Composite USB Descriptors

	static constexpr uint8_t keyboard_report_descriptor[]  =
	{
			0x05, 0x01, 0x09, 0x06, 0xA1, 0x01, 0x05, 0x07, 0x19, 0xE0, 0x29, 0xE7, 0x15, 0x00, 0x25, 0x01,
			0x75, 0x01, 0x95, 0x08, 0x81, 0x02, 0x95, 0x01, 0x75, 0x08, 0x81, 0x01, 0x95, 0x03, 0x75, 0x01,
			0x05, 0x08, 0x19, 0x01, 0x29, 0x03, 0x91, 0x02, 0x95, 0x05, 0x75, 0x01, 0x91, 0x01, 0x95, 0x06,
			0x75, 0x08, 0x15, 0x00, 0x26, 0xFF, 0x00, 0x05, 0x07, 0x19, 0x00, 0x2A, 0xFF, 0x00, 0x81, 0x00,
			0xC0
	};

	static constexpr char  usb_strings[][30] =
	{
			"Third Pin",
			"Composite Device",
			"Pastilda"
	};

	static constexpr struct usb_device_descriptor dev =
	{
			USB_DT_DEVICE_SIZE, //bLength
			USB_DT_DEVICE,      //bDescriptorType
			0x0110,             //bcdUSB
			0x0,                //bDeviceClass
			0x00,               //bDeviceSubClass
			0x00,               //bDeviceProtocol
			64,                 //bMaxPacketSize0
			0x0483,             //idVendor
			0x5741,             //idProduct
			0x0200,             //bcdDevice
			1,                  //iManufacturer
			2,                  //iProduct
			3,                  //iSerialNumber
			1                   //bNumConfigurations
	};

	typedef struct __attribute__((packed))
	{
		struct usb_hid_descriptor hid_descriptor;
		struct
		{
			uint8_t bReportDescriptorType;
			uint16_t wDescriptorLength;
		} __attribute__((packed)) hid_report;
	} type_hid_function;

	static constexpr type_hid_function  keyboard_hid_function =
	{
		{
			9,          //bLength
			USB_DT_HID, //bDescriptorType
			0x0111,     //bcdHID
			0,          //bCountryCode
			1           //bNumDescriptors
		},

		{
			USB_DT_REPORT,
			sizeof(keyboard_report_descriptor)
		}
	};

	static constexpr struct usb_endpoint_descriptor hid_endpoint =
	{
		USB_DT_ENDPOINT_SIZE,        //bLength
		USB_DT_ENDPOINT,             //bDescriptorType
		Endpoint::E_KEYBOARD,        //bEndpointAddress
		USB_ENDPOINT_ATTR_INTERRUPT, //bmAttributes
		64,                          //wMaxPacketSize
		0x20                         //bInterval
	};

	static constexpr struct usb_endpoint_descriptor msc_endpoint[] =
	{
		{
			USB_DT_ENDPOINT_SIZE,        //bLength
			USB_DT_ENDPOINT,             //bDescriptorType
			Endpoint::E_MASS_STORAGE_IN, //bEndpointAddress
			USB_ENDPOINT_ATTR_BULK,      //bmAttributes
			64,                          //wMaxPacketSize
			0                            //bInterval
		},

		{
			USB_DT_ENDPOINT_SIZE,         //bLength
			USB_DT_ENDPOINT,              //bDescriptorType
			Endpoint::E_MASS_STORAGE_OUT, //bEndpointAddress
			USB_ENDPOINT_ATTR_BULK,       //bmAttributes
			64,                           //wMaxPacketSize
			0                             //bInterval
		}
	};

	static constexpr struct usb_interface_descriptor iface[] =
	{
		{
			USB_DT_INTERFACE_SIZE,   //bLength
			USB_DT_INTERFACE,        //bDescriptorType
			Interface::I_KEYBOARD,   //bInterfaceNumber
			0,                       //bAlternateSetting
			1,                       //bNumEndpoints
			USB_CLASS_HID,           //bInterfaceClass
			1,                       //bInterfaceSubClass
			1,                       //bInterfaceProtocol
			0,                       //iInterface
			&hid_endpoint, &keyboard_hid_function,
			sizeof(keyboard_hid_function)
		},

		{
			USB_DT_INTERFACE_SIZE,     //bLength
			USB_DT_INTERFACE,          //bDescriptorType
			Interface::I_MASS_STORAGE, //bInterfaceNumber
			0,                         //bAlternateSetting
			2,                         //bNumEndpoints
			USB_CLASS_MSC,             //bInterfaceClass
			USB_MSC_SUBCLASS_SCSI,     //bInterfaceSubClass
			USB_MSC_PROTOCOL_BBB,      //bInterfaceProtocol
			0x00,                      //iInterface
			msc_endpoint, 0, 0
		},
	};

	static constexpr struct usb_config_descriptor::usb_interface ifaces[]
	{
		{
			(uint8_t *)0,                   //cur_altsetting
			1,                              //num_altsetting
			(usb_iface_assoc_descriptor*)0, //iface_assoc
			&iface[Interface::I_KEYBOARD]   //altsetting
		},

		{
			(uint8_t *)0,                     //cur_altsetting
			1,                                //num_altsetting
			(usb_iface_assoc_descriptor*)0,   //iface_assoc
			&iface[Interface::I_MASS_STORAGE] //altsetting
		},
	};

	static constexpr struct usb_config_descriptor config_descr =
	{
		USB_DT_CONFIGURATION_SIZE, //bLength
		USB_DT_CONFIGURATION,      //bDescriptorType
		0,                         //wTotalLength
		2,                         //bNumInterfaces
		1,                         //bConfigurationValue
		0,                         //iConfiguration
		0x80,                      //bmAttributes
		0x50,                      //bMaxPower
		ifaces
	};



keyboard_report_descriptor был взят из документа Device Class Definition for Human Interface Devices (HID) , Appendix E.6 Report Descriptor (Keyboard). Честно, сильно не разбиралась со структурой отчета, поверила документу) В целом, вот пара моментов, на которые нужно обратить особое внимание:
  • usb_config_descriptor: поле bNumInterfaces должно отражать столько интерфейсов, сколько реально реализовано. В нашем случае два: HID и MSD
  • usb_interface_descriptor: поле bInterfaceNumber обозначает номер интерфейса, но отсчет начинается с нуля, следовательно, номер первого интерфейса — 0.

Вот, с описательной точки зрения, наверно, и все. Не могу не отметить, как грамотно в библиотеке описаны дескрипторы (их описание находится в файле usbstd.h). Все четко по документации. Полагаю, это значительно упростило мне задачу, так как не возникало вопросов «Как же мне описать составное устройство?». Все сразу было понятно.

Для работы с составным устройством был написан класс USB_composite, представленный ниже.

Composite USB Class
extern "C" void USB_OTG_IRQ();

int USB_control_callback(usbd_device *usbd_dev, struct usb_setup_data *req,
		                 uint8_t **buf, uint16_t *len, usbd_control_complete_callback *complete);

void USB_set_config_callback(usbd_device *usbd_dev, uint16_t wValue);

static uint8_t keyboard_protocol = 1;
static uint8_t keyboard_idle = 0;
static uint8_t keyboard_leds = 0;

class USB_composite
{
public:
	uint8_t usbd_control_buffer[500];
	UsbCompositeDescriptors *descriptors;
	uint8_t usb_ready = 0;
	usbd_device *my_usb_device;

	USB_composite(const uint32_t block_count,
	 	 	 	  int (*read_block)(uint32_t lba, uint8_t *copy_to),
			          int (*write_block)(uint32_t lba, const uint8_t *copy_from));

	void usb_send_packet(const void *buf, int len);

	int hid_control_request(usbd_device *usbd_dev, struct usb_setup_data *req, uint8_t **buf, uint16_t *len,
			                void (**complete)(usbd_device *usbd_dev, struct usb_setup_data *req));

	void hid_set_config(usbd_device *usbd_dev, uint16_t wValue);
};


Ключевыми в этом классе являются две функции:
  • Функция hid_control_request нужна для общения Пастильды как клавиатуры с хостом (в данном случае, хост — это ПК). Вне класса данная функция вызывается через USB_control_callback.
  • Функция hid_set_config нужна для того, чтобы настроить конечные точки (endpoints) и зарегистрировать USB_control_callback, описанный в предыдущем пункте. Вне класса данная функция вызывается через USB_set_config_callback.

Ниже представлен вариант их реализации:

Callbacks
int USB_composite::hid_control_request(usbd_device *usbd_dev, struct usb_setup_data *req, uint8_t **buf, uint16_t *len,
					            void (**complete)(usbd_device *usbd_dev, struct usb_setup_data *req))
{
	(void)complete;
	(void)usbd_dev;

	if ((req->bmRequestType & USB_REQ_TYPE_DIRECTION) == USB_REQ_TYPE_IN)
	{
		if ((req->bmRequestType & USB_REQ_TYPE_TYPE) == USB_REQ_TYPE_STANDARD)
		{
			if (req->bRequest == USB_REQ_GET_DESCRIPTOR)
			{
				if (req->wValue == 0x2200)
				{
					*buf = (uint8_t *)descriptors->keyboard_report_descriptor;
					*len = sizeof(descriptors->keyboard_report_descriptor);
					return (USBD_REQ_HANDLED);
				}
				else if (req->wValue == 0x2100)
				{
					*buf = (uint8_t *)&descriptors->keyboard_hid_function;
					*len = sizeof(descriptors->keyboard_hid_function);
					return (USBD_REQ_HANDLED);
				}
				return (USBD_REQ_NOTSUPP);
			}
		}
		else if ((req->bmRequestType & USB_REQ_TYPE_TYPE) == USB_REQ_TYPE_CLASS)
		{
			if (req->bRequest == HidRequest::GET_REPORT)
			{
				*buf = (uint8_t*)&boot_key_report;
				*len = sizeof(boot_key_report);
				return (USBD_REQ_HANDLED);
			}
			else if (req->bRequest == HidRequest::GET_IDLE)
			{
				*buf = &keyboard_idle;
				*len = sizeof(keyboard_idle);
				return (USBD_REQ_HANDLED);
			}
			else if (req->bRequest == HidRequest::GET_PROTOCOL)
			{
				*buf = &keyboard_protocol;
				*len = sizeof(keyboard_protocol);
				return (USBD_REQ_HANDLED);
			}
			return (USBD_REQ_NOTSUPP);
		}
	}

	else
	{
		if ((req->bmRequestType & USB_REQ_TYPE_TYPE) == USB_REQ_TYPE_CLASS)
		{
			if (req->bRequest == HidRequest::SET_REPORT)
			{
				if (*len == 1)
				{
					keyboard_leds = (*buf)[0];
				}
				return (USBD_REQ_HANDLED);
			}
			else if (req->bRequest == HidRequest::SET_IDLE)
			{
				keyboard_idle = req->wValue >> 8;
				return (USBD_REQ_HANDLED);
			}
			else if (req->bRequest == HidRequest::SET_PROTOCOL)
			{
				keyboard_protocol = req->wValue;
				return (USBD_REQ_HANDLED);
			}
		}
		return (USBD_REQ_NOTSUPP);
	}

	return (USBD_REQ_NEXT_CALLBACK);
}

int USB_control_callback(usbd_device *usbd_dev,
		struct usb_setup_data *req, uint8_t **buf, uint16_t *len,
		usbd_control_complete_callback *complete)
{
	return(usb_pointer->hid_control_request(usbd_dev, req, buf, len, complete));
}

void USB_composite::hid_set_config(usbd_device *usbd_dev, uint16_t wValue)
{
	(void)wValue;
	(void)usbd_dev;

	usbd_ep_setup(usbd_dev, Endpoint::E_KEYBOARD, USB_ENDPOINT_ATTR_INTERRUPT, 8, 0);
	usbd_register_control_callback(usbd_dev, USB_REQ_TYPE_INTERFACE, USB_REQ_TYPE_RECIPIENT, USB_control_callback );
}

void USB_set_config_callback(usbd_device *usbd_dev, uint16_t wValue)
{
	usb_pointer->hid_set_config(usbd_dev, wValue) ;
}


Как правило, функции control_request и set_config должны быть явно описаны для каждого устройства. Однако из этого правила есть исключение: Mass Storage Device. Итак, разберемся с конструктором класса USB_Composite.

Во-первых, мы инициализируем ноги USB OTG FS:

	GPIO_ext uf_p(PA11);
	GPIO_ext uf_m(PA12);

	uf_p.mode_setup(Mode::ALTERNATE_FUNCTION, PullMode::NO_PULL);
	uf_m.mode_setup(Mode::ALTERNATE_FUNCTION, PullMode::NO_PULL);

	uf_p.set_af(AF_Number::AF10);
	uf_m.set_af(AF_Number::AF10);

Во-вторых, нам нужно проинициализировать наше составное устройство, зарегистрировать USB_set_config_callback, о котором шла речь выше, и разрешить прерывание:
	my_usb_device = usbd_init(&otgfs_usb_driver, &(UsbCompositeDescriptors::dev),
			&(UsbCompositeDescriptors::config_descr), (const char**)UsbCompositeDescriptors::usb_strings, 3,
			  usbd_control_buffer, sizeof(usbd_control_buffer));

	usbd_register_set_config_callback(my_usb_device, USB_set_config_callback);
	nvic_enable_irq(NVIC_OTG_FS_IRQ);

Этого достаточно для того, чтобы в диспетчере устройств наше устройство распознавалось:
  • Во вкладке «Контроллеры USB»: как составное устройство,
  • В этой же вкладке, как «Запоминающее устройство для USB»,
  • Во вкладке «Клавиатуры», как «Клавиатура HID».

Однако «Запоминающее устройство для USB» будет помечено предупреждением о том, что устройство работает неправильно. Все дело в том, что в отличие от других USB устройств, Mass Storage инициализируется немного иначе, через функцию usb_msc_init, описанную в файле usb_msc.c библиотеки libopencm3. Выше я уже упоминала о том, что для MSD нет необходимости явно описывать функции control_request и set_config. Это потому, что функция usb_msc_init все сделает за нас: и конечные точки настроит, и все колбэки зарегистрирует. Таким образом, нам нужно дополнить конструктор еще одной строчкой:
	usb_msc_init(my_usb_device, Endpoint::E_MASS_STORAGE_IN, 64, Endpoint::E_MASS_STORAGE_OUT, 64,
			"ThirdPin", "Pastilda", "0.00", block_count, read_block, write_block);

Тут можно заметить, что при инициализации MSD, нам нужно передать ему минимальное API для работы с памятью:
  • block_count: количество секторов памяти,
  • read_block: функция для чтения сектора,
  • write_block: функция для записи сектора.

В Пастильде мы используем внешний флеш SST25VF064C. Драйвер для этой микросхемы можно посмотреть здесь. В дальнейшем, на основе этого драйвера, во флеше будет реализована файловая система. Скорее всего, об этом как-нибудь подробно напишет мой коллега. Но так как я хотела поскорее протестировать работу MSD, я написала зародыш файловой системы=) Над ним можно поплакать здесь.

Так вот. Теперь, когда конструктор класса USB_Composite дописан, можно собрать проект, прошить устройство и увидеть, что «Запоминающее устройство для USB» больше не помечено предупреждением, а во вкладке «Дисковые устройства» можно обнаружить «ThirdPin Pastilda USB Device». И, казалось бы, все хорошо. Но нет=) Проблем стало больше:

1. Зайти на диск невозможно. При попытке сделать это все виснет, умирает, компьютеру очень плохо.
2. Распознавание устройства как дискового занимает более 2-х минут.

Об этих проблемах и о том, как их решить без вреда для здоровья написано здесь: USB mass storage device и libopencm3.

И, о, чудо! Никаких пятен=) Теперь все работает. У нас есть USB хост и составное USB устройство. Осталось только объединить их работу.

Объединение хоста и составного устройства

Наша цель:
  • Транслировать сообщения от клавиатуры в ПК до тех пор, пока не нажата комбинация Ctrl + Shift + ~.
  • После нажатия комбинации Ctrl + Shift + ~, Пастильда должна перехватить управление и отправить сообщение в ПК как клавиатура, после чего мы возвращаемся в режим трансляции и снова ожидаем комбинацию.


Код, реализующий все это, простой как палка:

App.cpp
App *app_pointer;

App::App()
{
	app_pointer = this;

	clock_setup();
	systick_init();

	_leds_api = new LEDS_api();
	_flash = new FlashMemory();
	usb_host = new USB_host(redirect, control_interception);
	usb_composite = new USB_composite(_flash->flash_blocks(), _flash->flash_read, _flash->flash_write);
}
void App::process()
{
	_leds_api->toggle();
	usb_host->poll();
}

void App::redirect(uint8_t *data, uint8_t len)
{
	app_pointer->usb_composite->usb_send_packet(data, len);
}

void App::control_interception()
{
	memset(app_pointer->key, 0, 8);
	app_pointer->key[2] = KEY_W;
	app_pointer->key[3] = KEY_O;
	app_pointer->key[4] = KEY_N;
	app_pointer->key[5] = KEY_D;
	app_pointer->key[6] = KEY_E;
	app_pointer->key[7] = KEY_R;
	app_pointer->usb_composite->usb_send_packet(app_pointer->key, 8);

	app_pointer->key[2] = 0;
	app_pointer->key[3] = 0;
	app_pointer->key[4] = 0;
	app_pointer->key[5] = 0;
	app_pointer->key[6] = 0;
	app_pointer->key[7] = 0;
	app_pointer->usb_composite->usb_send_packet(app_pointer->key, 8);

	app_pointer->key[2] = KEY_SPACEBAR;
	app_pointer->key[3] = KEY_W;
	app_pointer->key[4] = KEY_O;
	app_pointer->key[5] = KEY_M;
	app_pointer->key[6] = KEY_A;
	app_pointer->key[7] = KEY_N;
	app_pointer->usb_composite->usb_send_packet(app_pointer->key, 8);

	app_pointer->key[2] = 0;
	app_pointer->key[3] = 0;
	app_pointer->key[4] = 0;
	app_pointer->key[5] = 0;
	app_pointer->key[6] = 0;
	app_pointer->key[7] = 0;
	app_pointer->usb_composite->usb_send_packet(app_pointer->key, 8);
}


В конструкторе мы инициализируем все, что необходимо:
  1. Светодиоды, чтобы моргали;
  2. Флеш, чтобы можно было файлы на диске создавать / удалять;
  3. Хост, передав ему при этом функцию redirect (что делать, если комбинации нет) и control_interception (что делать, если комбинация нажата);
  4. Составное устройство, передав ему функции чтения / записи памяти;

И вот, собственно, и все. Начало положено, скелет нашего устройства создан. Совсем скоро будет доработана файловая система, по нажатию комбинации Ctrl + Shift + ~, мы будем попадать в однострочное меню, а во флеше будет храниться наша зашифрованная база данных паролей.

Буду рада любым комментариям и пожеланиям.

И, конечно же, ссылка на github.

UPD 27.06.2017:
  1. Репозиторий проекта Пастильда переехал сюда. Недавно был опубликован релиз 1.0.
  2. Последние новости по проекту можно смотреть здесь.
  3. А еще мы наконец-то запустили сайт проекта!
Tags:
Hubs:
+35
Comments 63
Comments Comments 63

Articles