SAM3S8/SD8 Software Package: USB Device Enumeration

SAM3S8/SD8 Software Package 1.2

# 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 configured by USBEndpointDescriptor in ref 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 definition.

callback function file | callback function
USBDCallbacks_Initialized.o | USBDCallbacks_Initialized()
USBDCallbacks_Reset.o | USBDCallbacks_Reset()
USBDCallbacks_Suspended.o | USBDCallbacks_Suspended()
USBDCallbacks_Resumed.o | USBDCallbacks_Resumed()
- MUST be defined | USBDCallbacks_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:

#### State Diagram

The device descriptor used by this example looks like this:

      Device descriptor.
    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.

#### Descriptor

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

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.

## Service Routines

### Device Framework Architecture

The USB controller peripheral generates an interrupt when an event occurs. Since that event must be forwarded to the USBD_IrqHandler method, an interrupt service routine must be installed to do that.

     void ISR_Usb()
     {
        USBD_IrqHandler();
     }

Currently the default USBDCallbacks_Initialized will initialize the interrupt service routine automatically:

    void USBDCallbacks_Initialized()
    {
        AIC_ConfigureIT(AT91C_ID_UDP, 0, USBD_IrqHandler);
        AIC_EnableIT(AT91C_ID_UDP);
    }

So the only thing you should do to initialize the interrupt service is to call USBD_Init() in main().

### 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_IrqHandler);
        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);
    }

- Note: It is not necessary to disable the USB controller logic (transceiver, clocks, peripheral) here. This is done directly by the USBD_IrqHandler 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:

    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
        }
    }

All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Defines