path: root/usb/device/hid-keyboard/hid-keyboard.dir

/* ----------------------------------------------------------------------------
 *         ATMEL Microcontroller Software Support 
 * ----------------------------------------------------------------------------
 * Copyright (c) 2008, Atmel Corporation
 *
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions are met:
 *
 * - Redistributions of source code must retain the above copyright notice,
 * this list of conditions and the disclaimer below.
 *
 * Atmel's name may not be used to endorse or promote products derived from
 * this software without specific prior written permission.
 *
 * DISCLAIMER: THIS SOFTWARE IS PROVIDED BY ATMEL "AS IS" AND ANY EXPRESS OR
 * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT ARE
 * DISCLAIMED. IN NO EVENT SHALL ATMEL BE LIABLE FOR ANY DIRECT, INDIRECT,
 * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA,
 * OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
 * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
 * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
 * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 * ----------------------------------------------------------------------------
 */

//------------------------------------------------------------------------------
/// \dir
///
/// !!!Purpose
///
/// This directory provides definitions, structs and functions for a USB HID
/// %device - USB HID Keyboard driver, to implement an USB keyboard %device.
///
/// !!!Contents
///
/// There are three things for the implement of the USB HID Keyboard driver:
/// - Implement the USB HID driver structs and functions for the %device,
///   to initialize, to handle HID-specific requests and dispach
///   standard requests in USBD callbacks, to read/write through assigned USB
///   endpoints,
/// - Create the HID Keyboard device's descriptors that should be passed to
///   the USBDDriver instance on initialization, so that the host can 
///   recognize the %device as a USB Keyboard %device.
/// - Implement methods to update the keyboard keys status, so that host can
///   get it through USB.
///
/// For more information about what a particular group contains, please refer to
/// "USB HID Keyboard".
//------------------------------------------------------------------------------

/**
 \page "USB HID Keyboard"
 This page describes how to use the "AT91 USB device framework" to produce a USB
 HID Keyboard driver, which appears as a USB keyboard on host.

 Details about the USB and the HID class can be found in the }USB specification
 2.0} and the }HID specification 1.11}, respectively.

 !!!References
 - "AT91 USB device framework"
 - "USB Device Enumeration"
 - <a href="http://www.usb.org/developers/docs/usb_20_040908.zip">
   Universal Serial Bus Revision 2.0 specification
   </a> (.zip file format, size 9.80 MB)
 - <a href="http://www.usb.org/developers/devclass_docs/HID1_11.pdf">
   Device Class Definition for HID 1.11</a>
 - <a href="http://www.usb.org/developers/devclass_docs/Hut1_12.pdf">
   HID Usage Tables 1.12</a>

 !!!HID Basic
 See "USB HID Basic".

 !!!Architecture
 See "USB Device Framework Architecture".

 !!!Descriptors

 ...

 !!Device Descriptor
 The Device descriptor of an HID %device is very basic, since the HID class
 code is only specified at the Interface level. Thus, it only contains
 standard values, as shown below:
\code
static const USBDeviceDescriptor deviceDescriptor = {

    sizeof(USBDeviceDescriptor),
    USBGenericDescriptor_DEVICE,
    USBDeviceDescriptor_USB2_00,
    HIDDeviceDescriptor_CLASS,
    HIDDeviceDescriptor_SUBCLASS,
    HIDDeviceDescriptor_PROTOCOL,
    BOARD_USB_ENDPOINTS_MAXPACKETSIZE(0),
    HIDDKeyboardDriverDescriptors_VENDORID,
    HIDDKeyboardDriverDescriptors_PRODUCTID,
    HIDDKeyboardDriverDescriptors_RELEASE,
    1, // Index of manufacturer description
    2, // Index of product description
    3, // Index of serial number description
    1  // One possible configuration
};
\endcode
 Note that the Vendor ID is a special value attributed by the USB-IF
 organization. The product ID can be chosen freely by the vendor.

 !!Configuration Descriptor
 Since one interface is required by the HID specification, this must be
 specified in the Configuration descriptor. There is no other value of
 interest to put here.
\code
// Configuration descriptor
{
    sizeof(USBConfigurationDescriptor),
    USBGenericDescriptor_CONFIGURATION,
    sizeof(HIDDKeyboardDriverConfigurationDescriptors),
    1, // One interface in this configuration
    1, // This is configuration #1
    0, // No associated string descriptor
    BOARD_USB_BMATTRIBUTES,
    USBConfigurationDescriptor_POWER(100)
},
\endcode
 When the Configuration descriptor is requested by the host (by using the
 GET_DESCRIPTOR command), the %device must also sent all the related
 descriptors, i.e. Interface, Endpoint and Class-Specific descriptors. It is
 convenient to create a single structure to hold all this data, for sending
 everything in one chunk. In the example software, a
 HIDDKeyboardDriverConfigurationDescriptors structure has been declared for
 that.

 !!HID Class Interface Descriptor
 Since a keyboard %device needs to transmit as well as receive data, two
 Interrupt (IN & OUT) endpoints are needed. This must be indicated in the
 Interface descriptor. Conversely to the mouse example, the Boot protocol is
 not implemented here, since there are more constraints on a keyboard %device.
\code
// Interface descriptor
{
    sizeof(USBInterfaceDescriptor),
    USBGenericDescriptor_INTERFACE,
    0, // This is interface #0
    0, // This is alternate setting #0
    2, // Two endpoints used
    HIDInterfaceDescriptor_CLASS,
    HIDInterfaceDescriptor_SUBCLASS_NONE,
    HIDInterfaceDescriptor_PROTOCOL_NONE,
    0  // No associated string descriptor
},
\endcode

 !!HID Descriptor
 While a HID keyboard produces two different reports, one Input and one Output,
 only one Report descriptor can be used to describe them. Since having Physical
 descriptors is also useless for a keyboard, there will only be one HID class
 descriptor specified here.

 For a keyboard, the }bCountryCode} field can be used to specify the language
 of the key caps. As this is optional, it is simply set to 00h in the example:
\code
// HID descriptor
{
    sizeof(HIDDescriptor),
    HIDGenericDescriptor_HID,
    HIDDescriptor_HID1_11,
    0, // Device is not localized, no country code
    1, // One HID-specific descriptor (apart from this one)
    HIDGenericDescriptor_REPORT,
    HIDDKeyboardDriverDescriptors_REPORTSIZE
},
\endcode

 !!Report Descriptor
 Two current reports are defined in the Report descriptor. The first one is
 used to notify the host of which keys are pressed, with both modifier keys
 (alt, ctrl, etc.) and alphanumeric keys. The second report is necessary for
 the host to send the LED (num lock, caps lock, etc.) states.

 The Report descriptor starts with the global %device functionality, described
 with a #Usage Page# and a #Usage# items:
\code
const unsigned char hiddReportDescriptor[] = {

    HIDReport_GLOBAL_USAGEPAGE + 1, HIDGenericDesktop_PAGEID,
    HIDReport_LOCAL_USAGE + 1, HIDGenericDesktop_KEYBOARD,
\endcode

 As in the mouse example, the }Generic Desktop} page is used. This time, the
 specific usage is the }Keyboard} one. An Application collection is then
 defined to group the reports together:
\code
    HIDReport_COLLECTION + 1, HIDReport_COLLECTION_APPLICATION,
\endcode

 The first report to be defined is the modifier keys. They are represented as a
 bitmap field, indicating whether or not each key is pressed. A single byte is
 used to map keys \#224-231 defined in the }HID Usage Tables} document:
 LeftControl, LeftShift, LeftAlt, LeftGUI (e.g. Windows key),
 RightControl, RightShift, RightAlt and RightGUI.
 The }Keypad} usage page must be specified for this report, and since this is a
 bitmap value, the data is flagged as }Variable}:
\code
        // Input report: modifier keys
        HIDReport_GLOBAL_REPORTSIZE + 1, 1,
        HIDReport_GLOBAL_REPORTCOUNT + 1, 8,
        HIDReport_GLOBAL_USAGEPAGE + 1, HIDKeypad_PAGEID,
        HIDReport_LOCAL_USAGEMINIMUM + 1,
            HIDDKeyboardDriverDescriptors_FIRSTMODIFIERKEY,
        HIDReport_LOCAL_USAGEMAXIMUM + 1,
            HIDDKeyboardDriverDescriptors_LASTMODIFIERKEY,
        HIDReport_GLOBAL_LOGICALMINIMUM + 1, 0,
        HIDReport_GLOBAL_LOGICALMAXIMUM + 1, 1,
        HIDReport_INPUT + 1, HIDReport_VARIABLE,
\endcode

 Then, the actual alphanumeric key report is described. This is done by
 defining several bytes of data, one for each pressed key. In the example,
 up to three keys can be pressed at the same time (and detected) by the user.
 Once again, the usage page is set to }Keypad}. This time however, the data
 must be specified as an }Array}, since the same control (the keypad) produces
 several values:
\code
        // Input report: standard keys
        HIDReport_GLOBAL_REPORTCOUNT + 1, 3,
        HIDReport_GLOBAL_REPORTSIZE + 1, 8,
        HIDReport_GLOBAL_LOGICALMINIMUM + 1,
            HIDDKeyboardDriverDescriptors_FIRSTSTANDARDKEY,
        HIDReport_GLOBAL_LOGICALMAXIMUM + 1,
            HIDDKeyboardDriverDescriptors_LASTSTANDARDKEY,
        HIDReport_GLOBAL_USAGEPAGE + 1, HIDKeypad_PAGEID,
        HIDReport_LOCAL_USAGEMINIMUM + 1,
            HIDDKeyboardDriverDescriptors_FIRSTSTANDARDKEY,
        HIDReport_LOCAL_USAGEMAXIMUM + 1,
            HIDDKeyboardDriverDescriptors_LASTSTANDARDKEY,
        HIDReport_INPUT + 1, 0 /* Data array */,
\endcode

 The LED array is then defined, with the associated usage page. The Report
 descriptor is formatted in this order to avoid redefining unchanged }Global}
 items, in order to save memory. This time again, the LED status is reported as
 a bitmap field. Three LEDs are used here: Num Lock, Caps Lock and Scroll Lock
 (IDs 01h to 03h). It is important to note that this is an #Output# report:
\code
        // Output report: LEDs
        HIDReport_GLOBAL_REPORTCOUNT + 1, 3,
        HIDReport_GLOBAL_REPORTSIZE + 1, 1,
        HIDReport_GLOBAL_USAGEPAGE + 1, HIDLeds_PAGEID,
        HIDReport_GLOBAL_LOGICALMINIMUM + 1, 0,
        HIDReport_GLOBAL_LOGICALMAXIMUM + 1, 1,
        HIDReport_LOCAL_USAGEMINIMUM + 1, HIDLeds_NUMLOCK,
        HIDReport_LOCAL_USAGEMAXIMUM + 1, HIDLeds_SCROLLLOCK,
        HIDReport_OUTPUT + 1, HIDReport_VARIABLE,
\endcode

 Since the previous report only contains 3 bits, the data must be padded to a
 multiple of one byte. This is done by using constant Output data, as follows:
\code
        // Output report: padding
        HIDReport_GLOBAL_REPORTCOUNT + 1, 1,
        HIDReport_GLOBAL_REPORTSIZE + 1, 5,
        HIDReport_OUTPUT + 1, HIDReport_CONSTANT,
\endcode

 The last item, }End Collection}, is necessary to close the previously opened
 }Application Collection}.
\code
    HIDReport_ENDCOLLECTION
};
\endcode

 The Input and Output reports defined by this descriptor can be modeled by the
 following structures:
\code
// HID Input Report
typedef struct {

  // State of modifier keys.
  unsigned char bmModifierKeys:8;
  // Key codes of pressed keys.
  unsigned char pressedKeys[HIDDKeyboardInputReport_MAXKEYPRESSES];

} __attribute__ ((packed)) HIDDKeyboardInputReport; // GCC
// HID Output Report
typedef struct {

  unsigned char numLockStatus:1, // State of the num. lock LED.
    capsLockStatus:1,   // State of the caps lock LED.
    scrollLockStatus:1, // State of the scroll lock LED.
    padding:5;          // Padding bits.

} __attribute__ ((packed)) HIDDKeyboardOutputReport; // GCC
\endcode

 An instance of each one of the reports is stored in a HIDDKeyboardDriver
 structure, which holds the standard class driver and HID keyboard-specific
 data.

 !!Physical Descriptor
 A Physical descriptor is useless for a keyboard %device, so none are defined
 in this example.

 !!Endpoint Descriptor
 Following the Interface and HID-specific descriptors, the two necessary
 endpoints are defined.
\code
// Interrupt IN endpoint descriptor
{
    sizeof(USBEndpointDescriptor),
    USBGenericDescriptor_ENDPOINT,
    USBEndpointDescriptor_ADDRESS(
        USBEndpointDescriptor_IN,
        HIDDKeyboardDriverDescriptors_INTERRUPTIN),
    USBEndpointDescriptor_INTERRUPT,
    sizeof(HIDDKeyboardInputReport),
    HIDDKeyboardDriverDescriptors_INTERRUPTIN_POLLING
},
// Interrupt OUT endpoint descriptor
{
    sizeof(USBEndpointDescriptor),
    USBGenericDescriptor_ENDPOINT,
    USBEndpointDescriptor_ADDRESS(
        USBEndpointDescriptor_OUT,
        HIDDKeyboardDriverDescriptors_INTERRUPTOUT),
    USBEndpointDescriptor_INTERRUPT,
    sizeof(HIDDKeyboardOutputReport),
    HIDDKeyboardDriverDescriptors_INTERRUPTIN_POLLING
}
\endcode

 !!String Descriptors
 Please refer to "Usage: USBD VID, PID & Strings".

 !!!Class-specific requests
 A driver request handler should first differentiate between class-specific and
 standard requests using the corresponding bits in the }bmRequestType} field.
 In most cases, standard requests can be immediately forwarded to the standard
 request handler method; class-specific methods must be decoded and treated by
 the custom handler.

 !!GetDescriptor
 Three values have been added by the HID specification for the #GET_DESCRIPTOR#
 request. The high byte of the }wValue} field contains the type of the
 requested descriptor; in addition to the standard types, the #HID
 specification# adds the #HID descriptor# (21h), the #Report descriptor#
 (22h) and the #Physical descriptor# (23h) types.

 There is no particular action to perform besides sending the descriptor. This
 can be done by using the USBD_Write method, after the requested descriptor has
 been identified:
\code
switch (USBGenericRequest_GetRequest(request)) {

  case USBGenericRequest_GETDESCRIPTOR:
    // Check if this is a HID descriptor,
    // otherwise forward it to
    // the standard driver
    if (!HIDDKeyboardDriver_GetDescriptor(
        USBGetDescriptorRequest_GetDescriptorType(request),
        USBGenericRequest_GetLength(request))) {

      USBDDriver_RequestHandler(&(hiddKeyboardDriver.usbdDriver),
                              request);
    }
    break;

  default:
    USBDDriver_RequestHandler(&(hiddKeyboardDriver.usbdDriver),
                                  request);
}
\endcode
 A slight complexity of the GET_DESCRIPTOR and SET_DESCRIPTOR requests is that
 those are standard requests, but the standard request handler
 (USBDDriver_RequestHandler) must not always be called to treat them (since
 they may refer to HID descriptors). The solution is to first identify
 GET/SET_DESCRIPTOR requests, treat the HID-specific cases and, finally,
 forward any other request to the standard handler.

 In this case, a GET_DESCRIPTOR request for the Physical descriptor is first
 forwarded to the standard handler, and STALLed there because it is not
 recognized. This is done because the %device does not have any Physical
 descriptors, and thus, does not need to handle the associated request.

 !!SetDescriptor
 This request is optional and is never issued by most hosts. It is not
 implemented in this example.

 !!GetReport
 Since the HID keyboard defines two different reports, the Report Type value
 specified by this request (upper byte of the }wValue} field) must be examined
 to decide which report to send. If the type value is 01h, then the Input
 report must be returned; if it is 02h, the Output report is requested:
\code
case HIDGenericRequest_GETREPORT:
//-------------------------------
  type = HIDReportRequest_GetReportType(request);
  length = USBGenericRequest_GetLength(request);
  switch (type) {

      case HIDReportRequest_INPUT:

        // Adjust size and send report
        if (length > sizeof(HIDDKeyboardInputReport)) {

          length = sizeof(HIDDKeyboardInputReport);
        }
        USBD_Write(0, // Endpoint #0
           &(hiddKeyboardDriver.inputReport),
           length,
           0, // No callback
           0);
        break;

      case HIDReportRequest_OUTPUT:

        // Adjust size and send report
        if (length > sizeof(HIDDKeyboardOutputReport)) {

          length = sizeof(HIDDKeyboardOutputReport);
        }
        USBD_Write(0, // Endpoint #0
           &(hiddKeyboardDriver.outputReport),
           length,
           0, // No callback
           0);
        break;

      default:
        USBD_Stall(0);
  }
break;
\endcode

 !!SetReport
 For an HID keyboard, the #SET_REPORT# command can be sent by the host to
 change the state of the LEDs. Normally, the dedicated Interrupt OUT endpoint
 will be used for this; but in some cases, using the default Control endpoint
 can save some bandwidth on the host side.

 Note that the SET_REPORT request can be directed at the Input report of the
 keyboard; in this case, it can be safely discarded, according to the HID
 specification. Normally, most host drivers only target the Output report. The
 Report Type value is stored in the upper byte of the }wValue} field.

 The length of the data phase to follow is stored in the }wLength} field of the
 request. It should be equal to the total length of the Output report. If it is
 different, the report status must still be updated with the received data as
 best as possible.

 When the reception of the new data is completed, some processing must be done
 to enable/disable the corresponding LEDs. This is done in the callback
 function passed as an argument to USBD_Read:
\code
case HIDGenericRequest_SETREPORT:
//-------------------------------
  type = HIDReportRequest_GetReportType(request);
  length = USBGenericRequest_GetLength(request);
  switch(type) {

    case HIDReportRequest_INPUT:
      // SET_REPORT requests on input reports are ignored
      USBD_Stall(0);
      break;

    case HIDReportRequest_OUTPUT:
      // Check report length
      if (length != sizeof(HIDDKeyboardOutputReport)) {

        USBD_Stall(0);
      }
      else {
      
        USBD_Read(0, // Endpoint #0
          &(hiddKeyboardDriver.outputReport),
          length,
          (TransferCallback) HIDDKeyboardDriver_ReportReceived,
          0); // No argument to the callback function
      }
      break;

    default:
      USBD_Stall(0);
  }
break;
\endcode

 !!SetIdle
 In this case study, the #SET_IDLE# request is used to set a delay before a key
 is repeated. This is common behavior on keyboard devices. Usually, this delay
 is set to about 500 ms by the host.

 The only action here is to store the new Idle rate. The management of this
 setting must be done in the main function, since Interrupt IN reports are sent
 from there.

 In practice, it is not necessary to perform any action, apart from sending a
 zero-length packet to acknowledge it. The main application however has to make
 sure that only new reports are sent by the %device.
\code
case HIDGenericRequest_SETIDLE:
//-----------------------------
  hiddKeyboardDriver.inputReportIdleRate =
           HIDIdleRequest_GetIdleRate(request);
  USBD_Write(0, 0, 0, 0, 0);
break;
\endcode

 !!GetIdle
 The only necessary operation for this request is to send the previously saved
 Idle rate. This is done by calling the USBD_Write method with the one-byte
 variable as its parameter:
\code
case HIDGenericRequest_GETIDLE:
//-----------------------------
  USBD_Write(0, &(hiddKeyboardDriver.inputReportIdleRate), 1, 0, 0);
break;
\endcode

 !!GetProtocol, SetProtocol
 This HID keyboard example does not support the Boot protocol, so there is no
 need to implement the SET_PROTOCOL and GET_PROTOCOL requests. This means they
 can be safely STALLed when received.

 !!!Main Application
 Like the mouse example, the main program must perform two different
 operations. First, it has to monitor the physical inputs used as keys. In the
 example software, the buttons present on the evaluation boards are used to
 produce several modifier and alphanumeric keys.

 Also, the main program is in charge of sending reports as they are modified,
 taking into account the Idle rate specified by the host. Idle rate management
 can be carried out by firing/resetting a timer once a new report is sent; if
 the timer expires, this means the Input report has not changed since.
 According to the HID specification, a single instance of the report must be
 sent in this case.

 Finally, the HID specification also defines that if too many keys are pressed
 at the same time, the %device should report an }ErrorRollOver} usage value
 (01h) in every byte of the key array. This has to be handled by the main
 application as well.

*/

/**
 \page "USB HID Mouse"
 This page describes how to implement a mouse %device using the HID class and
 the "AT91 USB device framework". Details about the USB and the HID class can
 be found in the }USB specification 2.0} and the }HID specification 1.11}
 documents, respectively.

 !!!References
 - "AT91 USB device framework"
 - "USB Device Enumeration"
 - <a href="http://www.usb.org/developers/docs/usb_20_040908.zip">
   Universal Serial Bus Revision 2.0 specification
   </a> (.zip file format, size 9.80 MB)
 - <a href="http://www.usb.org/developers/devclass_docs/HID1_11.pdf">
   Device Class Definition for HID 1.11</a>
 - <a href="http://www.usb.org/developers/devclass_docs/Hut1_12.pdf">
   HID Usage Tables 1.12</a>



*/

/**
 \page "USB HID Basic"
 
 This page gives generic details on the HID class, including its purpose,
 architecture and how it is supported by various operating systems.

 !!!Purpose

 The HID class has been specifically designed for Human Interface Devices,
 i.e., devices which are manipulated by humans to control a computer or an
 electronic %device. This includes common peripherals such as a keyboard, a
 mouse or a joystick, as well as many other interfaces: remote controllers,
 switches, buttons, dedicated game controls, and so on.

 It is also possible to use the HID class for devices which do not require
 human interaction, but still deliver information in a similar format. For
 example, devices like a thermometer or a battery indicator are supported.

 In addition, the HID class also makes it possible to not only receive data
 from devices but also to send commands to them. Indeed, many devices offer
 some kind of display to give back information to the user, e.g., the LEDs on a
 keyboard.

 Finally, since it is quite simple to send and receive data using the HID
 class, it can be used as a generic means of communication between a %device
 and a host. This is made possible because of the very flexible framework
 defined in the HID specification.

 In this document, three uses of the HID class will be detailed step-by-step,
 each showing one particular feature of the class. The first example shows the
 interaction with a simple mouse. In the second example, a keyboard is
 implemented to demonstrate the possibility to send data to a peripheral. The
 last example explains how to use HID as a simple two-way communication
 channel.

 !!!Architecture
 ...

 !!Interface
 An HID %device only needs #one interface descriptor#. It should have the HID
 interface class code in its bInterfaceClass field. There are special subclass
 and protocol codes to specify if the HID %device is a mouse or a keyboard, and
 must be supported by the BIOS. In such a case, the interface must be declared
 as a Boot Interface, and the type of the %device (mouse or keyboard) must be
 given in the bInterfaceProtocol field.

 !!Endpoints
 Up to three endpoints can be used with an HID interface. The first two are the
 default Control endpoint 0, as well as an Interrupt IN endpoint. They are
 mandatory and shall always be declared. An optional Interrupt OUT endpoint can
 be added as well.

 Endpoint 0 is used for class-specific requests, as well as receiving data from
 the host if no Interrupt OUT endpoint has been defined. In addition, the host
 can also explicitly request or send report data through this endpoint.

 The Interrupt IN and OUT pipes are used for sending asynchronous data to the
 host, and to receive low-latency information.

 \image HIDClassArch.png "HID Class Driver Architecture"

 !!Class-Specific Descriptors
 There are three class-specific descriptors defined in the }HID specification
 1.11}: the HID descriptor, the report descriptor and the physical descriptor.

 !HID Descriptor
 The HID descriptor gives information about the HID specification revision
 used, the country for which a %device is localized, and lists the number of
 class-specific descriptors, including their length and type.

 HID Descriptor Format
||Field||Size(bytes)||Description
|bLength|1|Total length of the HID descriptor
|bDescriptorType|1|HID descriptor type (21h)
|bcdHID|2|HID specification release number in BCD format
|bCountryCode|1|Code of the country for which the %device is located.\n
                Should be 0 if the %device is not localized.
|bNumDescriptors|1|Number of class-specific descriptors used by the %device.
|bDescriptorType|1|Type of the first class-specific descriptor.
|bDescriptorLength|1|Total length of the first class-specific descriptor.
|[bDescriptorType]|1|Type of the second class-specific descriptor.
|[bDescriptorLength]|1|Total length of the second class-specific descriptor.
|...| | 

 There is always at least one Report descriptor for an HID %device, so the
 corresponding fields must be present in the HID descriptor. If other
 descriptors are defined, they must also be described here.

 !Report Descriptor
 A HID %device must have at least one #Report descriptor#. It defines the type
 of data manipulated by the %device, which is referred to as report. When the
 %device wants to notify that the cursor has moved, for example, it sends the
 corresponding report in the format previously defined in the Report
 descriptor.

 This descriptor is quite different from others, as it does not have a fixed
 table of values. Instead, it is made up of a variable number of items, which
 collectively identify the information that a host can expect from or send to
 the %device.

 There are five categories of items:
 - #Input# items, which define the format and type of the data sent by the
   %device.
 - #Output# items, which define the format and type of the data expected by
   the %device
 - #Feature# items, which define data sent to or received from the %device,
   and not intended for the end user, such as configuration parameters.
- #Collection# items, which identify a set of data as related to the same
   group.
- #End Collection# items, which close other Collection items.

 Usually, a Report descriptor defines only one use (report) for a %device, e.g.,
 a mouse. However, it is possible to declare several reports to perform
 different tasks, e.g., mouse & keyboard. This is done by assigning a different
 #Report ID# to each report; this makes it possible for the %device to send
 both reports through the same Interrupt endpoint, while still permitting the
 host to correctly identify the data. Using only a single endpoint for several
 functionalities is very powerful, as the remaining ones can then be used by
 other interfaces (CDC, MSD, etc.) for an even more versatile %device.

 More details about Report descriptors will be given in the implementation
 examples. For more information about the possible items, tags and values,
 please refer to the }HID specification 1.11.}

 !Physical Descriptor
 A #Physical descriptor# can be used to give information about which human body
 part is used to activate a particular control. While this is a useless piece
 of information for most devices, it can be relevant for complex devices which
 provide many similar controls. In such a case, a Physical descriptor allows an
 application to assign its functionalities more appropriately; for example, a
 game controller often has a large number of buttons, with some of them more
 accessible than the others. Those buttons would be assigned the most useful
 actions.

 Since physical descriptors are not used very often, and are not useful in the
 case studies described in this document, they will not be discussed further.

 !!Class-specific Requests
 ...

 !GetDescriptor
 While #GET_DESCRIPTOR# is a standard request (defined in the }USB
 specification 2.0}), new descriptor type values have been added for the HID
 class. They make it possible for the host to request the HID descriptor,
 Report descriptor and Physical descriptors used by the %device.

 When requesting a HID-specific descriptor, the }wIndex} field of the request
 must be set to the HID interface number. For standard requests, this field is
 either set to 0 or, for String descriptors, to the index of the language ID
 used.

 !SetDescriptor
 Similarly, #SET_DESCRIPTOR# is a standard request with added HID-specific
 values. It is used by the host to change the HID descriptors of a %device.
 This is an optional request, and has few practical uses.

 !GetReport
 The host can explicitly ask the %device for a report by using the #GET_REPORT#
 request. However, it should be used primarily to get the state of feature
 items and absolute values at initialization time, not for consistent %device
 polling.

 The requested report is identified either by its Report ID (if they are used),
 and/or by its type (Input, Output or Feature).

 Please note that a GET_REPORT request is different from a GET_DESCRIPTOR
 request for the Report descriptor. The latter returns the whole Report
 descriptor, i.e., all the items declared. The former returns the data defined
 by this descriptor.

 !SetReport
 #SET_REPORT# is similar to GET_REPORT, except this request is used for
 changing the state of a report, instead of simply retrieving it.

 For an Input report, this request can either be considered meaningless, or can
 be used to reset the current status of a control. For example, it could be
 used to calibrate the neutral position of a joystick.

 !SetIdle
 This request is used to specify the minimum amount of time, called #Idle
 rate#, that a %device must wait before transmitting a report if its state has
 not changed. This means the %device must NAK all polls on its Interrupt IN
 endpoint until the report state changes, or the guarding period expires.

 The SET_IDLE command can either be issued for a particular duration, or for an
 undefined period of time. The upper byte of the wValue field is used to
 specify this duration. In addition, if the %device generates multiple reports,
 the Report ID of the target report to affect can be specified in the lower
 byte.

 In practice, this request is often used with a keyboard to put a small delay
 before a key is repeated continuously. For a mouse, it must be set to 0,
 meaning that the %device should never report an unchanged state.

 !GetIdle
 The GET_IDLE request is issued by the host to retrieve the current Idle rate
 of the %device. A particular Report can be specified with its Report ID.

 !GetProtocol
 This request returns the protocol currently used by the %device. This can
 either be the Report protocol (}wValue} set to 0) or the Boot protocol
 (}wValue} set to 1). Since a %device supporting the Boot protocol can operate
 differently depending on which mode it is in, the host system can retrieve or
 change this mode with the GET_PROTOCOL and SET_PROTOCOL requests.

 This request is only need for devices supporting the Boot protocol.

 !SetProtocol
 Whenever an HID %device starts up, it should use the Report protocol by
 default. However, the host driver shall still use the SET_PROTOCOL
 request to specify if the %device should use the Report protocol or the
 Boot protocol.

 !!!Host Drivers
 Most operating systems provide a generic HID driver which automatically
 handles standard devices, such as keyboard, mice and joystick. In addition,
 the driver can also be used by the application to easily access custom and
 vendor-specific devices.

*/