Здесь приведен перевод документации Atmel AVR4950: ASF - USB Host Stack [1], посвященной библиотеке для реализации хоста USB с помощью микроконтроллеров AVR. Для этой библиотеки подойдут не все, а строго определенные модели микроконтроллеров AVR и AVR32, которые имеют на борту аппаратный интерфейс USB со встроенной поддержкой функции хоста USB. Список поддерживаемых микроконтроллеров приведен ниже во врезках.
Для удобного выбора различных моделей микроконтроллеров см. табличный селектор Atmel [3].
Основные возможности библиотеки:
• Совместимость со стандартом USB 2.0, часть 9. Поддерживаются следующие типы передач: Control (управление), Bulk (пакетное блоками), Isochronous (изохронное, с привязкой по времени) и Interrupt (наподобие прерываний), на скоростях Low Speed (1.5 мегабит/сек), Full Speed (12 мегабит/сек), High Speed (480 мегабит/сек). • Малый размер кода стека протоколов USB. • Работа в реальном масштабе времени (совместимость с OS, практически без задержек). • Работа по прерываниям. • Повышенная производительность с использованием USB DMA. • Режимы пониженного энергопотребления. • Поддержка хаба USB (USB HUB). • Поддержка основных классов USB, готовая к использованию (HID, CDC, MSC, PHDC, AUDIO). • Поддержка составного устройства USB (composite USB device). • Целевые платформы библиотеки 8-битные и 32-битные AVR®. • Компилируется в среде GCC и IAR™.
Пока что альтернатив этой библиотеке практически нет, за исключением LUFA.
Стек USB хоста (библиотека), описываемый в этом документе, включен в фреймворк ASF Atmel® (сокращение от AVR Software Framework), и он предназначен для предоставления пользователю самого быстрого и простого пути построения приложения хоста USB на основе микроконтроллеров. Также этот стек хоста USB ориентирован на малый объем кода и низкое потребление энергии. Все непонятные термины и сокращения см. в разделе Словарик, к конце статьи.
[Документация по теме приложений хоста USB]
Компания Atmel предоставила несколько примеров приложений хоста USB. К каждому примеру имеется несколько апноутов (см. рисунок ниже).
Рис. 3-1. Апноуты примеров приложений хоста USB.
Для изучения этих апноутов требуются базовые знания по классам хоста USB (классы HID, CDC, MSC, PHDC, AUDIO). Для создания хоста USB для одного из предоставленных в ASF классов, обращайтесь напрямую к апноуту, посвященному соответствующему классу USB. Апноуты стека хоста USB и класса вендора хоста (USB host vendor class) разработаны для опытных разработчиков приложений USB.
[Обзор архитектуры библиотек]
Стек хоста USB функционально разделен на 3 части:
• USB Host Controller (UHC), предоставляющий совместимость со стандартном USB часть 9. • USB Host Interface (UHI), предоставляющий совместимость с классом USB. • USB Host Driver (UHD), предоставляющий интерфейс USB для каждого продукта Atmel (имеются в виду микроконтроллеры с аппаратным интерфейсом, имеющими поддержку хоста USB).
Примечание: драйверы хоста USB реализованы в режиме полной поддержки прерываний, так что этот UHD отличная база для создания драйвера USB для стеков USB от сторонних производителей. Это относится либо к пользовательскому интерфейсу, либо к интерфейсу OHCI/EHCI.
Рис. 4-1. Архитектура стека хоста USB.
В случае двойного режима (устройство/хост) имеется описание стека устройства USB в апноуте "AVR4900: ASF – USB Device stack".
Затраты памяти на стек USB зависят от:
• Используемого ядра Atmel (megaAVR®, UC3). • Версии аппаратуры USB. • Используемого класса USB. • Используемого компилятора и уровня оптимизации.
Различные комбинации этих параметров дают разные затраты на используемую память, но обычно стек хоста USB требует не больше 10 килобайт FLASH и 1 килобайт RAM при использовании самого высокого уровня оптимизации компилятора.
Файлы стека хоста USB. Примеры стека доступны в Atmel AVR Studio® 5, если запустить визард создания нового проекта (New Example Project wizard) и выбрать ASF Modules wizard. Можно выбрать примеры хоста из списка или ввести в поле поиска host. Совет: выберите раздел Technology USB чтобы уменьшить список отображаемых примеров в AVR Studio 5.
Примечание: имена примеров, включающих "From ASF V1" относятся к предыдущей реализации стека хоста USB из ASF v1.7, которая выходит за рамки этого апноута.
Файлы, общие для всех микроконтроллеров, описаны в таблице ниже.
Файлы
Пути
Описание
usb_protocol.h* (от usb.org) usb_atmel.h* (от Atmel)
common/services/usb/
Определение констант USB.
uhc.c/h uhi.h uhd.h
common/services/usb/uhc/
Файлы UHC.
usb_protocol_< класс >.h*
common/services/usb/class/класс/
Файлы протоколов классов.
uhi_foo.c/h
common/services/usb/class/foo/host/
Файлы UHI.
Примечание *: эти файлы используются совместно со стеком устройств USB.
Файлы UHD, зависящие от выбранного микроконтроллера:
Примечание *: эти файлы используются совместно со стеком устройств USB.
Файл, относящийся к специфике каждого определенного приложения. Для конфигурации стека хоста USB используется файл приложения (см. часть "Конфигурация" и таблицу 5-3) usb_conf_host.h.
[API]
В этой части описывается все API, кроме UHI API, которому посвящен отдельный документ [4, 5].
Рис. 5-1. Модули USB.
Внешнее API от UHC. Внешнее UHC API позволяет приложению обслуживать общее поведение хоста USB и принимать общие события хоста USB. Это управление и обработка событий являются общими для всех приложений USB.
Таблица 5-1. Внешнее API UHC – функции ввода.
Декларация
Описание
uhc_start ();
Запуск режима хоста.
uhc_stop (bool b_id_stop);
Остановка режима хоста и остановка управления от USB ID pin, если это запрошено b_id_stop.
uhc_suspend (bool b_remotewakeup);
Приостановка (suspend) линии USB. Это авторизует или нет функции пробуждения (remote wakeup) каждого устройства.
uhc_is_suspend ();
Проверка - разрешено ли состояние приостановки линии USB.
uhc_resume ();
Возобновление работы линии USB.
Таблица 5-2. Внешнее API UHC – функции ввода, относящиеся к подключенным устройствам.
Для оповещения о событиях подключения или отключения устройства.
UHC_WAKEUP_EVENT ();
Вызывается, когда устройство USB или хост USB разбудил линию USB.
UHC_SOF_EVENT ();
Вызывается для каждого принятого SOF, каждые 1 мс. Примечание: доступно в режимах High Speed и Full Speed.
UHC_DEVICE_CONF (uhc_device_t* dev);
Вызывается, когда должна быть выбрана конфигурация устройства USB. При этом приложение может выбрать либо номер конфигурации для этого устройства, либо 0, чтобы отклонить устройство. Если callback не определен, то происходит выбор конфигурации 1.
Вызывается, когда завершается завершена энумерация устройства USB. Статус может быть: UHC_ENUM_SUCCESS устройство прошло энумерацию по шине с как минимум одним поддерживаемым интерфейсом. UHC_ENUM_UNSUPPORTED все интерфейсы не поддерживаются блоками UHI. UHC_ENUM_OVERCURRENT мощность, которую запросила устройство, не поддерживается. UHC_ENUM_FAIL произошла проблема при энумерации USB. UHC_ENUM_HARDWARE_LIMIT USB аппаратура не может поддержать это - нет свободных каналов (pipes). UHC_ENUM_SOFTWARE_LIMIT USB программное обеспечение не может поддержать это из-за ограничений реализации. UHC_ENUM_MEMORY_LIMIT USB программное обеспечение не может поддерживать это - недостаточно памяти.
Внутреннее API. Следующие определения применяются для квалифицированных пользователей, которые нуждаются в разработке специфического хоста USB, который не предоставлен в ASF.
Рис. 5-2. Обзор внутреннего API хоста USB.
Примечание: цифры на рисунке относятся к таблицам ниже.
Таблица 5-4. Ввод UHI из UHC (1).
Декларация
Описание
uhc_enum_status_t (*install)(uhc_device_t*);
Установка интерфейса, если это поддерживается новым устройством (выделение конечных точек).
void (*uninstall)(uhc_device_t*);
Деинсталляция интерфейса, если он установлен для этого устройство.
void (*enable)(uhc_device_t*);
Вызывается для запуска интерфейса USB устройства.
void (*sof_notify)(bool b_micro);
Вызывается блоком UHC для оповещения о событии SOF на разрешенном интерфейсе USB.
Примечание: UHI API сохранено в массиве USB_HOST_UHI, см. таблицу 7-1.
Таблица 5-5. Ввод UHC из UHD (3).
Декларация
Описание
uhc_start ();
Запуск режима хоста.
uhc_stop (bool b_id_stop);
Остановка режима хоста и обработки USB ID pin, если это запрошено b_id_stop.
uhc_notify_connection (bool b_plug);
Вызывается, когда устройство было подключено или отключено.
uhc_notify_sof (bool b_micro);
Вызывается, когда был отправлен SOF.
uhc_notify_resume ();
Вызывается, когда происходит возобновление работы шины. После возобновления потока в прямом или обратном направлении (downstream или upstream).
Таблица 5-6. Ввод UHD (4).
Декларация
Откуда вызывается
Описание
uhd_enable ();
UHC
Разрешает режим хоста USB и обработку управления переключением ролей, если доступен ID pin.
uhd_disable (bool b_id_stop);
UHC
Запрещает режим хоста USB и обработку ID pin, если это запрошено b_id_stop.
uhd_speed_t uhd_get_speed ();
UHC/UHI
Для проверки скорости устройства, подключенного к интерфейсу USB (не для случая, когда устройство подключено к хабу USB).
uint16_t uhd_get_frame_number ();
Приложение
Вернет текущий номер начала фрейма (SOF).
uint16_t uhd_get_microframe_number ();
Приложение
Вернет текущий номер начала микрофрейма.
uhd_send_reset (uhd_callback_reset_t callback);
UHC
Драйвер USB разрешает состояние сброса на линии USB.
uhd_suspend ();
UHC
Драйвер USB разрешает состояние приостановки на линии USB.
uhd_is_suspend ();
UHC
Проверка - разрешено ли состояние приостановки на линии USB.
uhd_resume ();
UHC
Драйвер USB разрешает состояние IDLE на линии USB ("Downstream Resume").
Запускает/останавливает передачу данных конечной точки в направлениях IN или OUT Планирование передач управляется блоком UHD. Примечание: управляющая конечная точка здесь не авторизована.
uhd_ep_abort (usb_add_t add, usb_ep_t endp);
UHI
Таблица 5-7. UHD callback (5).
Декларация
Описание
typedef void (*uhd_callback_reset_t)(void);
Вызывается, когда завершено событие сброса, запрошенное вызовом uhd_send_reset().
Вызывается, когда буфер полезной нагрузки, назначенный вызовом uhd_setup_request(), заполнен или пуст. Тогда запрос настройки (setup request) захвачен. Новый буфер может быть предоставлен для перезапуска запроса настройки, или запрос настройки будет оборван.
Вызывается, когда запрос передачи завершен или отменен. Этот запрос регистрируется через uhd_ep_run().
uhd_trans_status_t
Эта структура обновляется после каждой попытки транзакции, независимо от того, успешна она или нет. Если транзакция была успешна, то поле status будет установлено в значение UHD_TRANS_NOERROR. Иначе оно будет установлено в один из следующих типов ошибки: UHD_TRANS_CRC, ошибка CRC в пакете данных. UHD_TRANS_DISCONNECT, устройство отключено. UHD_TRANS_DT_MISMATCH, data toggle PID не соответствует ожидаемому значению. UHD_TRANS_STALL, конечная точка вернула STALL PID. UHD_TRANS_NOT_RESPONDING, устройство не отвечает на токен (IN) или не предоставляет сигнал рукопожатия handshake (OUT). UHD_TRANS_PID_FAILURE, потерпела неудачу проверка бит PID из конечной точки. UHD_TRANS_TIMEOUT, передача данных не завершена из-за истечения времени таймаута. UHD_TRANS_ABORTED, передача данных была оборвана.
Таблица 5-8. Ввод UHD, только для совместимости с приложением High Speed (4).
Декларация
Откуда вызывается
Описание
uhd_test_mode_j ();
UHC
Функции для разрешения специфического сигнала на порту USB HS. Они запрашиваются для запуска в сертификации хоста USB HS.
uhd_test_mode_k ();
UHC
uhd_test_mode_se0_nak ();
UHC
uhd_test_mode_packet ();
UHC
Информация о подключенном устройстве USB. UHC обслуживает устройства через структуру uhc_device_t, которая сохраняет множество данных об устройствах, подключенных к дереву USB.
Глобальная переменная g_uhc_device_root содержит информацию о первом подключенном устройстве, и это первый элемент в списке устройств.
Приложение пользователя может читать этот список, чтобы получить информацию о текущем состоянии дерева USB.
Примечание: здесь нет ограничения на дерево USB, потому что список устройств и выделение памяти на поля дескрипторов USB динамические, и требуют наличия стандартной библиотеки для выделения памяти (например alloc()).
Структура uhc_device_t включает:
• Указатель на дескриптор устройства USB. • Указатель на дескриптор конфигурации устройства USB. • Адрес устройства USB. • Скорость устройства USB. • Указатели на родительское устройство хаба USB HUB (только для поддержки USB HUB). • Номер порта HUB, с которым осуществлено соединение (только для поддержки USB HUB).
Рис. 5-3. Определение uhc_device_t.
[Поведение стека хоста USB]
В этой части содержатся ответы на вопросы продвинутого использования USB, и здесь описано поведение стека хоста USB. Последующие секции описывают взаимодействие между разными слоями вот этих шагов:
• Управление двойной ролью USB. • Управление USB VBUS. • Управление соединением с устройством USB. • Управление энумерацией устройств USB.
Двойные роли. Когда аппаратура USB может работать в режиме устройства USB и в режиме хоста USB, пользователь может реализовать приложение с двойной ролью. Это приложение будет переключаться задачами между устройства USB и хоста USB в зависимости от уровня на выводе идентификации (USB ID pin, в соответствии со стандартом USB OTG).
Стек хоста USB предоставляет 3 возможности управления двойной ролью: ручное, полуавтоматическое и автоматическое. Ручной вариант управления ролью должен использоваться тогда, когда нет вывода идентификации (ID pin). В этом случае процесс пользователя управляет выбором роли. Полуавтоматический и автоматический варианты должны использоваться тогда, когда ID pin обслуживается аппаратурой интерфейса USB.
Полуавтоматический вариант управления двойной ролью позволяет отложить запуск режима устройства USB и режима хоста USB, когда меняется состояние ID pin. Эта возможность разрешается, когда имеется определение UHD_START_MODE_MANUAL (см. таблицу 7-2).
Рис. 6-1. Ручное управление двойной ролью USB.
Рис. 6-2. Полуавтоматическое управление двойной ролью USB.
Рис. 6-3. Автоматическое управление двойной ролью USB.
Управление VBUS.
Рис. 6-4. Управление VBUS.
Соединение с устройством USB.
Рис. 6-5. Соединение с устройством USB.
Примечание: эта последовательность одинакова для устройств, подключенных через хаб USB HUB, но события соединения и сброса управляются через запрос USB HUB setup. Когда энумерация устройства USB терпит неудачу 4 раза, сигнальная линия USB устройства устанавливается в режим приостановки (USB SUSPEND mode).
Энумерация устройства.
Рис. 6-6. Энумерация устройства USB (одиночная конфигурация USB).
Примечание: здесь не определен callback UHC_DEVICE_CONF(), так что по умолчанию выбирается конфигурация 1 устройства.
Рис. 6-7. Энумерация устройства USB (с несколькими конфигурациями USB).
Ниже приведен пример кода для поддержки известного устройства с несколькими конфигурациями:
uint8_t user_choose_usb_conf(uhc_device_t* dev)
{
if ((dev->dev_desc.idVendor ==0x1234)
&& (dev->dev_desc.idProduct ==0x5678))
{
Assert(dev->dev_desc.bNumConfigurations>=2);
return2; // Выбрана конфигурация 2.
}
return0; // Не выбрана ни одна из конфигураций, потому что принято// решение, что устройство не известно (unknown device).
}
[Конфигурация]
Конфигурации приложения определяются в файле conf_usb_host.h. Этот файл должен быть создан для каждого приложения, и это действие требует базовых знаний принципов работы USB.
Файл conf_usb_host.h определяет следующие конфигурации:
Конфигурация хоста USB. Следующая конфигурация должна быть включена в файл conf_usb.h приложения, и здесь содержится основная конфигурация поддерживаемого устройства USB.
Таблица 7-1. Конфигурация хоста USB.
Имя определения
Тип
Описание
USB_HOST_UHI
Массив UHI API
Определяет список UHI, поддерживаемых хостом USB. Пример: #define USB_HOST_UHI UHI_MSC, UHI_HID_MOUSE
USB_HOST_POWER_MAX
mA
Максимальный ток, разрешенный на VBUS.
USB_HOST_HUB_SUPPORT(1)
Только определение
Авторизует поддержку USB HUB (доступно для релиза ASF3).
USB_HOST_HS_SUPPORT(1)
Только определение
Авторизует хост USB для запуска в режиме High Speed.
Примечание 1: опциональная конфигурация. Для того, чтобы запретить это, закомментируйте строку с определением (например: // #define USB_HOST_X).
Конфигурация интерфейса хоста USB. Конфигурации UHI описаны в отдельных апноутах классов хоста USB.
Конфигурация драйвера хоста USB. Аппаратный интерфейс USB может предоставить отдельные возможности, что управляется файлами conf_usb_host.h, conf_board.h и опциями проекта.
Таблица 7-2. Конфигурация драйвера хоста USB в файле conf_usb_host.h.
Имя определения
Значения
UHD
Описание
UHD_NO_SLEEP_MGR
Только определение
Все
Удаляет управление службы sleepmgr.
UHD_ISOCHRONOUS_NB_BANK
1, 2, 3
USBB
Уменьшает или увеличивает буферизацию изохронной конечной точки. Значение по умолчанию, если определение не задано: 2.
UHD_BULK_NB_BANK
1, 2, 3
USBB
Уменьшает или увеличивает буферизацию конечной точки типа bulk. Значение по умолчанию, если определение не задано: 2.
UHD_INTERRUPT_NB_BANK
1, 2, 3
USBB
Уменьшает или увеличивает буферизацию конечной точки типа interrupt. Значение по умолчанию, если определение не задано: 1.
UHD_INT_LEVEL
от 0 до 3
USBB USBC
Устанавливает уровень прерывания USB на ядрах AVR32. Значение по умолчанию, если определение не задано: 0 (рекомендуемое значение).
UHD_START_MODE_MANUAL
Только определение
USBB USBC
По умолчанию, когда ID pin доступен (имеется определение USB_ID), режим хоста или устройства останавливается и запускается автоматически, когда меняется уровень на ID. Этот автоматический старт может быть запрещен, но автоматическая остановка режима остается.
Таблица 7-3. Конфигурация драйвера хоста USB в файле conf_board.h.
Имя определения
Значения
UHD
Описание
USB_ID
AVR32_USBB_USB_ID_x_x
AVR32 - USBB
Определяет входной вывод, подключенный к ID pin коннектора USB. Это разрешает использование USB ID коннектора OTG. Если не определено, то использование ID pin запрещено.
USB_ID
AVR32_USBC_USB_ или AVR32_USBC_USB_x
AVR32 - USBC
USB_VBOF
AVR32_USBB_USB_VBOF_x_x
AVR32 - USBB
Определяет выходной вывод, подключенный к сигналу разрешения генератора напряжения VBUS. Это разрешает использование управления VBUS со стороны аппаратного интерфейса USB. Если не определено, то управление VBUS запрещено.
USB_VBOF
AVR32_USBC_USB_VBOF или AVR32_USBC_USB_VBOF_x
AVR32 - USBC
USB_VBOF_ACTIVE_LEVEL
LOW или HIGH
AVR32 - USBB AVR32 - USBC
Активный уровень на выводе выхода USB_VBOF.
Таблица 7-4. Конфигурация драйвера хоста/устройства USB в проекте.
Имя определения
Значения
UHD
Описание
UHD_ENABLE
Определено
USBB USBC
Это определяет, разрешена ли двойная роль (хост и устройство).
UDD_ENABLE
Определено
[Поддержка USB HUB]
Стек хоста USB может поддерживать дерево USB через функцию USB HUB. Однако аппаратура интерфейса USB, предоставленная в микроконтроллерах Atmel, может ограничить дерево USB.
Таблица 8-1. Ограничение аппаратуры USB HUB.
Аппаратный интерфейс USB
Описание
USBB
Количество каналов (pipes) ограничивается значением 7 или 8, но управляющая конечная точка мультиплексируется в одном канале (pipe). Не поддерживается одновременно несколько скоростей USB на дереве USB.
USBC
Количество каналов (pipes) ограничено значением 7, но управляющая конечная точка мультиплексируется в одном канале. Поддерживается мультиплексирование каналов(1). Не поддерживается одновременно несколько скоростей USB на дереве USB.
Примечание (1): чтобы избежать ограничения на количество каналов (pipes), возможно их мультиплексирование. Однако в этом случае планирование передач должно осуществляться программно (драйвером UHD) вместо аппаратуры USB.
[Энергопотребление]
Режимы энергопотребления, доступные в микроконтроллерах Atmel, поддерживаются аппаратурой USB. Все драйверы USB реализуют эту возможность из службы sleepmgr. Таким образом, должна быть выполнена инициализация этой службы вызовом sleepmgr_init() из приложения перед любым вызовом API стека USB.
Ядро AVR32. Для ядра AVR32 такты и генераторы могут быть автоматически выключены в периодах ожидания (idle) при выполнении инструкции sleep процессора CPU.
Таблица 9-1. Уровни сна, поддерживаемые драйверами хоста USBB и USBC.
Состояние USB
Максимальный авторизованный режим сна
ID pin не активен (ожидание режима хоста)
STATIC
Нет VBUS (ожидание события VBUS)
STOP или FROZEN на моделях UTMI (UTMI = совместимость с High Speed)
VBUS присутствует, и устройство отключено
IDLE
VBUS присутствует, и устройство подключено
Приостановка (Suspend)
STATIC
IDLE без DMA
IDLE
IDLE + работа DMA
IDLE
Примечание: режимы сна, перечисленные здесь, не могут быть запущены, если любой другой программный модуль, не относящийся к стеку USB, требует менее глубокого режима сна.
[Словарик]
ACK Acknowledge, положительное подтверждение по шине USB (подробнее см. [3]).
API Application programming interface, интерфейс программирования.
ASF AVR Software Framework, библиотека для реализации различных функций от Atmel.
CBW Command Block Wrapper, обертка блока команды (термин относится к Mass Storage Class устройств USB).
CDC Communication Device Class, класс CDC устройств USB, предназначенных для обмена данными.
CSW Command Status Wrapper, обертка статуса команды (термин относится к Mass Storage Class устройств USB).
DP или D+ один из сигналов дифференциальной линии данных USB.
DM или D- второй сигнал дифференциальной линии данных USB.
IN ACK подтверждение передачи типа IN (подробнее см. [2]).
MSC Mass Storage Class, класс USB для устройств хранения данных (флешки, внешние жесткие диски).
OHCI Open Host Controller Interface, открытый интерфейс контроллера хоста.
OTG On The Go, переводится "на лету". Термин означает, что система может при подключении выбирать режим работы интерфейса USB - т. е. может работать либо в качестве устройства USB, либо как хост USB. Режим работы определяется уровнем напряжения на специальном выводе идентификации режима (ID pin) на коннекторе USB.
OUT ACK подтверждение передачи типа OUT (подробнее см. [2]).
PHDC Peripheral Health Device Class.
PIPE буфер данных для обслуживания передачи конечной точки в режиме хоста.
sleepmgr Sleep management service, служба управления режимом сна из библиотеки ASF.
UDC USB Device Controller, контроллер устройства USB.
UDD USB Device Descriptor, дескриптор устройства USB.
UDI USB Device Interface, интерфейс устройства USB.
UHC USB Host Controller, контроллер хоста USB.
UHD USB Host Descriptor, дескриптор хоста USB.
UHI USB Host Interface, интерфейс хоста USB.
USB Universal Serial Bus.
USBB версия аппаратного интерфейса USB для платформы 32-битного ядра Atmel.
USBC версия аппаратного интерфейса USB на языке C для платформы 32-битного ядра Atmel.
SOF Start Of Frame, начало фрейма.
STALL токен USB, используемый для остановки транзакции по шине USB.
ZLP Zero length packet, пакет нулевой длины.
VBUS шина питания +5V интерфейса USB.
Примечание: дополнительную информацию по протоколу USB и его терминологии см. в статье [2].
