USB Device Enumeration
Default mainpageat91libusbUSB Device Enumeration
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.

callback function filecallback function
USBDCallbacks_Initialized.oUSBDCallbacks_Initialized
USBDCallbacks_Reset.oUSBDCallbacks_Reset
USBDCallbacks_Suspended.oUSBDCallbacks_Suspended
USBDCallbacks_Resumed.oUSBDCallbacks_Resumed
- MUST be definedUSBDCallbacks_RequestReceived

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.
USBDDriver usbdDriver;


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.


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.
void ISR_Usb()
{
   USBD_InterruptHandler();
}
Currently the default USBDCallbacks_Initialized will initialize the interrupt service routine automatically:
void USBDCallbacks_Initialized()
{
    AIC_ConfigureIT(AT91C_ID_UDP, 0, USBD_InterruptHandler);
    AIC_EnableIT(AT91C_ID_UDP);
}
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:
void ISR_Vbus(const Pin *pPin)
{
    // Check current level on VBus
    if (PIO_Get(&pinVbus)) {
        USBD_Connect();
    }
    else {
        USBD_Disconnect();
    }
}


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:
void USBDCallbacks_Initialized()
{
    // Configure and enable the UDP interrupt
    AIC_ConfigureIT(AT91C_ID_UDP, 0, USBD_InterruptHandler);
    AIC_EnableIT(AT91C_ID_UDP);
}
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.
void USBDCallbacks_Suspended(void)
{
    // Turn off LEDs
    LED_Clear(USBD_LEDPOWER);
    LED_Clear(USBD_LEDUSB);
}
The Resume callback has to perform the reverse operation. The default callback is defined in USBDCallbacks_Resumed.c.
void USBDCallbacks_Resumed(void)
{
    // Initialize LEDs
    LED_Configure(USBD_LEDPOWER);
    LED_Set(USBD_LEDPOWER);
    LED_Configure(USBD_LEDUSB);
    LED_Clear(USBD_LEDUSB);
}



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:
void USBDCallbacks_RequestReceived(const USBGenericRequest *request)
{
    USBDDriver_RequestHandler(&usbdDriver, request);
}


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:

int main()
{
    // If they are present, configure Vbus & Wake-up pins
    PIO_InitializeInterrupts(0);

    // USB initialization
    USBDDriver_Initialize(&usbdDriver, &usbdDriverDescriptors, 0);
    USBD_Init();

    // connect if needed
    VBUS_CONFIGURE();
    while (USBD_GetState() < USBD_STATE_CONFIGURED);
    
    // Main loop
    while(1)
    {
        // Put USB class driver implementaion here
    }
}

 
Source
The documentation for this Page was generated from the following file:
  • usb.dir