Управление устройством USB

Enumerations
enum	USB_DescriptorMemorySpaces_t {   MEMSPACE_FLASH = 0,   MEMSPACE_EEPROM = 1,   MEMSPACE_RAM = 2 }
enum	USB_Device_States_t {   DEVICE_STATE_Unattached = 0,   DEVICE_STATE_Powered = 1,   DEVICE_STATE_Default = 2,   DEVICE_STATE_Addressed = 3,   DEVICE_STATE_Configured = 4,   DEVICE_STATE_Suspended = 5 }
Functions
void	USB_Device_SendRemoteWakeup (void)
static uint16_t	USB_Device_GetFrameNumber (void)
static void	USB_Device_EnableSOFEvents (void) ATTR_ALWAYS_INLINE
static void	USB_Device_DisableSOFEvents (void) ATTR_ALWAYS_INLINE
uint16_t	CALLBACK_USB_GetDescriptor (const uint16_t wValue, const uint8_t wIndex, const void **const DescriptorAddress, uint8_t *MemoryAddressSpace) ATTR_WARN_UNUSED_RESULT ATTR_NON_NULL_PTR_ARG(3)
Variables
uint8_t	USB_ConfigurationNumber
bool	USB_RemoteWakeupEnabled
bool	USB_CurrentlySelfPowered
volatile uint8_t	USB_DeviceState
Маски опций режима устройства USB
#define	USB_DEVICE_OPT_LOWSPEED   (1 << 0)
#define	USB_DEVICE_OPT_FULLSPEED   (0 << 0)

---

Detailed Description

Макросы и перечисления, связанные с устройством USB. Этот модуль содержит макросы и перечисления, которые используются, когда контроллер USB инициализирован в режиме устройства USB.

---

Define Documentation

#define USB_DEVICE_OPT_FULLSPEED   (0 << 0)

Маска для параметра Options функции USB_Init(). Показывает, что интерфейс USB должен быть инициализирован в режим полной скорости full speed (12 мегабит/сек).

#define USB_DEVICE_OPT_LOWSPEED   (1 << 0)

Маска для параметра Options функции USB_Init(). Показывает, что интерфейс USB должен быть инициализирован в режим низкой скорости low speed (1.5 мегабит/сек).

Note:

Режим Low Speed доступен не на всех моделях USB AVR.

Ограничения распространяются на количество, размер и тип конечных точек, которые можно использовать в работе режима low speed - см. спецификацию USB 2.0.

---

Enumeration Type Documentation

enum USB_DescriptorMemorySpaces_t

Перечисление для возможных областей памяти, для MemoryAddressSpace функции CALLBACK_USB_GetDescriptor(). Может использоваться, когда не используются опции времени компиляции USE_*_DESCRIPTORS, чтобы показать, в какой области памяти сохранен дескриптор.

Enumerator:

MEMSPACE_FLASH	показывает, что запрошенный дескриптор размещен в памяти FLASH.
MEMSPACE_EEPROM	показывает, что запрошенный дескриптор размещен в памяти EEPROM.
MEMSPACE_RAM	показывает, что запрошенный дескриптор размещен в памяти RAM.

enum USB_Device_States_t

Enumerator:

DEVICE_STATE_Unattached	Внутренне реализовано в библиотеке. Это состояние показывает, что устройство сейчас не подключено к хосту.
DEVICE_STATE_Powered	Внутренне реализовано в библиотеке. Это состояние показывает, что устройство подключено к хосту, но энумерация еще не началась.
DEVICE_STATE_Default	Внутренне реализовано в библиотеке. Это состояние показывает, что шина USB устройства сброшена хостом, и устройство сейчас ожидает от хоста начала процесса энумерации.
DEVICE_STATE_Addressed	Внутренне реализовано в библиотеке. Это состояние показывает, что устройство адресовано хостом USB, но пока не сконфигурировано.
DEVICE_STATE_Configured	Может быть реализовано в проекте пользователя. Это состояние показывает, что устройство прошло энумерацию хостом USB и готово к началу обмена данными.
DEVICE_STATE_Suspended	Может быть реализовано в проекте пользователя. Это состояние показывает, что работа шины USB приостановлена хостом, и устройство должно перейти в режим минимального энергопотребления, пока не будет возобновлена работа шины.

---

Function Documentation

uint16_t CALLBACK_USB_GetDescriptor	(	const uint16_t	wValue,
		const uint8_t	wIndex,
		const void **const	DescriptorAddress,
		uint8_t *	MemoryAddressSpace
	)

Функция получения для указанного дескриптора размера и размещения в памяти по указанному типу дескриптора, индексу и ID языка. Эта функция ДОЛЖНА быть переопределена в приложении пользователя (добавлена с полным, идентичным прототипом и именем, чтобы библиотека могла её вызвать для получения данных дескриптора.

Parameters:

[in]	wValue	Тип дескриптора для получения в старшем байте, и его индекс в младшем байте (когда имеется больше одного дескриптора указанного типа, как в случае строковых дескрипторов). Тип может быть одним из стандартных типов, заданных в перечислении DescriptorTypes_t, или может иметь специфичное для класса дескриптора значение типа.
[in]	wIndex	ID языка для возврата, если тип wValue указывает на DTYPE_String, иначе ноль для стандартных дескрипторов, или как задано в стандартах, специфичных для класса.
[out]	DescriptorAddress	Указатель на дескриптор в памяти. Это должно быть установлено в подпрограмме на адрес дескриптора.
[out]	MemoryAddressSpace	A value from the USB_DescriptorMemorySpaces_t enum to indicate the memory space in which the descriptor is stored. Этот параметр не существует, когда используется одна из опций времени компиляции USE_*_DESCRIPTORS.

Note:

По умолчанию, библиотека подразумевает, что все дескрипторы размещены в flash памяти с атрибутом PROGMEM. Если дескрипторы должны размещаться вместо этого в RAM или EEPROM (для ускорения доступа в случае RAM, или чтобы дескрипторы могли быть изменены динамически во время выполнения), могут быть заданы токены либо USE_RAM_DESCRIPTORS, либо USE_EEPROM_DESCRIPTORS в makefile проекта, и переданы компилятору через переключатель -D.

Returns:

Размер дескриптора в байтах, если он имеется, иначе ноль или NO_DESCRIPTOR.

static void USB_Device_DisableSOFEvents

(

void

)

[inline, static]

Запрещает события Start Of Frame режима устройства. Когда запрещено, останавливает запуск события EVENT_USB_Device_StartOfFrame(), когда прошла энумерация в режиме устройства USB.

Note:

Недоступно, когда задан токен времени компиляции NO_SOF_EVENTS.

static void USB_Device_EnableSOFEvents

(

void

)

[inline, static]

Разрешает события Start Of Frame (SOF, начало фрейма) при работе в режиме устройства USB. Когда разрешено, это приводит к запуску события EVENT_USB_Device_StartOfFrame() раз в милисекунду, синхронно с шиной USB, в начале каждого фрейма USB, когда прошла энумерация в режиме устройства USB.

Note:

Недоступно, когда задан токен времени компиляции NO_SOF_EVENTS.

static uint16_t USB_Device_GetFrameNumber

(

void

)

[inline, static]

Возвращает текущий номер фрейма USB в режиме работы устройства USB. Каждую милисекунду при активной шине USB (когда устройство прошло энумерацию хостом) номер фрейма увеличивается на единицу.

void USB_Device_SendRemoteWakeup

(

void

)

Отправляет на хост запрос Remote Wakeup. Сигнализирует хосту, что устройство должно выйти из режима приостановки (suspended mode), и обмен данными должен продолжиться.

Обычно это реализовано, чтобы устройства HID (мыши, клавиатуры и т. п.) могли разбудить компьютер хоста, когда хост находится в режиме сна, и все устройства USB находятся в состоянии низкого энергопотребления.

Note:

Этот макрос должен использоваться только если устройство показало хосту в дескрипторах устройства, что оно поддерживает возможность Remote Wakeup, и должно выдаваться только если хост в настоящий момент разрешил события remote wakeup, принимаемые от устройства (другими словами, установлен флаг USB_RemoteWakeupEnabled). Когда задана опция времени компиляции NO_DEVICE_REMOTE_WAKEUP, этот макрос недоступен.

Чтобы эта функция могла функционировать, должно работать тактирование USB. Исли стек инициализирован с разрешенной опцией USB_OPT_MANUAL_PLL, пользователь перед тем как вызвать эту функцию должен убедиться, что PLL работает.

See also:

См. Дескрипторы USB для подробностей по возможности RMWAKEUP и дескрипторам устройства.

---

Variable Documentation

uint8_t USB_ConfigurationNumber

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

Note:

Эта переменная должна быть обработана как только для чтения в пользовательском приложении, и никогда вручную не изменяться.

bool USB_CurrentlySelfPowered

Указывает, запитано ли устройство в настоящий момент от собственного источника питания, вместо того, чтобы быть запитанным от источника шины хоста USB. Этот флаг должен оставаться очищенным, если устройство не поддерживает режим самостоятельного питания, и его значение указывается в дескрипторах устройства.

volatile uint8_t USB_DeviceState

Показывает текущее состояние машины устройства USB. В режиме работы устройства USB, это показывает состояние через одно из значений перечисления USB_Device_States_t.

Это значение не должно быть изменено в приложении пользователя, поскольку оно автоматически обрабатывается библиотекой. Только одно исключение из этого правила - если используется токен NO_LIMITED_CONTROLLER_CONNECT (см. события EVENT_USB_Device_Connect() и EVENT_USB_Device_Disconnect()).

Чтобы уменьшить размер программы и ускорения проверки этой глобальной переменной, она может быть размещена в аппаратные регистры GPIOR AVR вместо RAM, путем задания токена DEVICE_STATE_AS_GPIOR в значение между 0 и 2 в makefile проекта и передачи его компилятору через ключ -D. Когда токен задан, то соответствующий регистр GPIOR не может быть использован программой пользователя, за исколючением неявного использования через API библиотеки.

Note:

Эта глобальная переменная имеется только в случае реализации в программе пользователя устройства USB.

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

See also:

См. USB_Device_States_t для списка возможных состояний устройства USB.

bool USB_RemoteWakeupEnabled

Показывает, разрешено ли в настоящий момент хостом выдача устройством событий удаленного пробуждения (remote wakeup events). Если этот флаг очищен, то устройство не должно выдавать хосту события удаленного пробуждения.

Note:

Эта переменная должна быть обработана как только для чтения в пользовательском приложении, и никогда вручную не изменяться.

Для уменьшения затрат FLASH в компилированных приложениях, где не используется Remote Wakeup, этот глобальный и низлежащий код может быть запрещен путем задания токена NO_DEVICE_REMOTE_WAKEUP в makefile проекта и передачи его комилятору через переключатель -D.