Description
usb.dir::USB Device Enumeration
This page is a step-by-step guide on how to use the USB Device framework to produce a simple program that performs USB enumeration.
In this example, everything is put into a single file. You can look at the
main.c file provided with the framework to view the end result.
Including the Necessary Headers
Prior to using the framework, several header files have to be included. Please refer to
"USB Device Framework Usage" for more information.
Declaring Global Varibles
Several object instances are necessary to use the various functions and methods of the USB framework. As following.
USBD Driver
The very first step is declare the USB driver which is then used by the Class driver. The
USBDDriver structure is used as a container for several variables, which must therefore be created first.
Endpoints
Depending on the application, a particular number of endpoints have to be defined. For example, an MSD driver needs three endpoints whereas a CDC driver needs four. Refer to the corresponding specification for more information about the required number of endpoints. Since this example should only perform the USB enumeration, it will declare only one endpoint: Control endpoint 0.
Endpoints is configrued by USBEndpointDescriptor in
USBDDriverDescriptors for the driver. The FIFO banks is automatically set to its maximum value.
Callbacks
To replace the default callback, you should remove the default callback file from makefile and add your own function defintion.
Driver
Depending on the chip used, there may or may not be a need to declare a low- level driver variable.
The default driver global variable is simply called
usbdDriver, and will sufficient for this example.
Descriptors
The USB specification 2.0 defines a set of descriptors used to give information about the device. Depending on the USB class implemented, different descriptors have to be used with varying values.
In this example program, only a few descriptors are required,. The device descriptor is always mandatory, so it will have to be defined. At least one configuration descriptor is required, so one is implemented. The described configuration must have at least one interface, so one more descriptor is needed. Finally, no string descriptors are used:
Device Descriptor
The
device descriptor used by this example looks like this:
const USBDeviceDescriptor usbDeviceDescriptor = {
sizeof(USBDeviceDescriptor),
USBGenericDescriptor_DEVICE,
USBDeviceDescriptor_USB2_00,
0, // No device class code
0, // No device subclass code
0, // No device protocol code
BOARD_USB_ENDPOINTS_MAXPACKETSIZE(0),
0x03EB, // Atmel vendor ID
0x0001, // Product ID
0x0001, // Product release 0.01
0, // No manufacturer string descriptor
0, // No product string descriptor
0, // No serial number string descriptor
1 // One possible configuration
};
|
The values are nothing special here. Note that the first three fields have the same
data in them (unless using USB 1.1). It is also very
common to define the class, subclass and protocol values at the interface level.
- Note: The vendor ID value is provided by the USB-IF organization. The product ID is vendor-specific and can be assigned any value.
Configuration & Interface
When the configuration descriptor is requested by the host, via the GET_DESCRIPTOR command, the
device must not only transmit this descriptor but also all the necessary interface and endpoint descriptors.
In order to do that easily, a structure must be defined for holding all the information. This way, the
data to send is contiguous, making the request much simpler to fulfill. In the current example, the configuration descriptor must be followed by the first interface descriptor. The following structure is declared for that:
// Configuration descriptors with one interface.
struct SimpleConfigurationDescriptors {
USBConfigurationDescriptor configuration;
USBInterfaceDescriptor interface;
};
|
Now, the actual descriptors can be declared:
// Configuration descriptors.
const struct SimpleConfigurationDescriptors configurationDescriptors = {
// Configuration descriptor
{
sizeof(USBConfigurationDescriptor),
USBGenericDescriptor_CONFIGURATION,
sizeof(struct SimpleConfigurationDescriptors),
0, // No interface in this configuration
1, // This is configuration #1
0, // No string descriptor for this configuration
BOARD_USB_BMATTRIBUTES,
USBConfigurationDescriptor_POWER(100)
},
// Interface descriptor
{
sizeof(USBInterfaceDescriptor),
USBGenericDescriptor_INTERFACE,
0, // This is interface #0
0, // This is setting #0 for interface
0, // Interface has no endpoint
0, // No interface class code
0, // No interface subclass code
0, // No interface protocol code
0, // No string descriptor
}
};
|
Again, those are very generic values. For the interface descriptor, most of them are zeroed. This is because this example does not implement any functionality other than doing the USB enumeration.
Class Driver
The demonstration program is going to use the standard request handler discussed in
"USBD Standard Request Handler" to perform the USB enumeration. To be able to do that, several structures must be declared.
Descriptors List
The
USBDDriver object needs a pointer to a list of descriptors. This is necessary to be able to answer the GET_DESCRIPTOR request. A
USBDDriverDescriptors can be used to do that.
The actual descriptors list can be instantiated:
// List of descriptors used by the device.
const USBDDriverDescriptors usbdDriverDescriptors = {
&usbDeviceDescriptor,
(const USBConfigurationDescriptor *) &configurationDescriptors,
#ifdef BOARD_USB_UDPHS
0, // No full-speed device qualifier descriptor
0, // No full-speed other speed configuration descriptor
&usbDeviceDescriptor,
(const USBConfigurationDescriptor *) &configurationDescriptors,
0, // No high-speed device qualifier descriptor
0, // No high-speed other speed configuration descriptor
#else
0, // No full-speed device qualifier descriptor
0, // No full-speed other speed configuration descriptor
0, // No high-speed device descriptor
0, // No high-speed configuration descriptor
0, // No high-speed device qualifier descriptor
0, // No high-speed other speed configuration descriptor
#endif
0, // No string descriptor
0 // No string descriptor
};
|
The
core configuration descriptor, which is actually made up of the configuation descriptor and the first interface descriptor, has to be cast to the USBConfigurationDescriptor type.
Interrupt Service Routines
!!USB Controller Interrupt The USB controller peripheral generates an interrupt when an event occurs. Since that event must be forwarded to the
USBD_InterruptHandler method, an interrupt service routine must be installed to do that.
Currently the default
USBDCallbacks_Initialized will initialize the interrupt service routine automatically:
So the only thing you should do to initialize the interrupt service is to call
USBD_Init() in
main().
VBus PIO Interrupt
The Vbus
power line can be monitored (if a PIO pin is connected to it) by the user application to enable or disable the USB controller peripheral when the device is connected/disconnected. To do that, an interrupt must be programmed when the status of Vbus changes. The ISR should call the
USBD_Connect or
USBD_Disconnect function as follows:
Callbacks
A typical application based on this USB framework needs to instantiate most of the callbacks available. This section describes how to do that for a simple enumeration program.
Init
When an OS is not being used, the primary function that the
Init callback must perform is interrupt handler installation. The previously defined ISR is thus configured and enabled:
The default callback is defined in
USBDCallbacks_Initialized.c.
Suspend & Resume
The Suspend callback is used by the USBD API to notify the
device that it should enter low-power mode if required. The default callback is defined in USBDCallbacks_Suspended.c.
The Resume callback has to perform the reverse operation. The default callback is defined in USBDCallbacks_Resumed.c.
- Note: It is not necessary to disable the USB controller logic (transceiver, clocks, peripheral) here. This is done directly by the USBD_InterruptHandler function prior to triggering the callback. Typically, the callback must carry out the following operations:
- Disable the PLL
- Switch to the slow 32 KHz clock
- Turn off the clocks of used peripherals
NewRequest
Since this example software should only perform the USB enumeration, the NewRequest callback can simply forward the call to the standard request handler method:
Main
The Main function of the program is used for PIO and driver (Class and USB) initialization, software connections of the
device (by using
USBD_Connect), and implementation of the product functionality.
In this case, the Main performs the first two steps. After that, since the enumeration is done through the event handler and the
device does not do anything, it can simply enter an infinite loop:
Source
The documentation for this Page was generated from the following file:
usb.dir