hid-keyboard.dir

本代bootloader通过usb下载代码首先存放在sdram中

/* ----------------------------------------------------------------------------
 *         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,