TEST/ZStack-2.5.1a/Components/hal/target/CC2530USB/usb/library/usb_standard_requests.h

/***********************************************************************************

    Filename:     usb_standard_request.h

    Description:  Handle USB standard requests.

***********************************************************************************/

#ifndef USBSTANDARDREQUESTS_H
#define USBSTANDARDREQUESTS_H
/** \addtogroup module_usb_standard_requests  USB Standard Requests (usbsr)
 * \brief This module contains automated functions for processing USB standard requests
 *
 * The processing functions are based on the \ref module_usb_framework, and access to the user-provided
 * USB descriptors through the \ref module_usb_descriptor_parser. All device classes and descriptor
 * combinations are supported, with no need to write or modify any source code. However, as described
 * below, some standard request must be fully or partially implemented by the user.
 *
 * \section section_usbsr_hooks Hooks
 * Standard requests that are not supported by the USB library or that refer to non-standard features,
 * are forwarded to the application via function hooks. This includes:
 * \li All \ref SET_DESCRIPTOR requests (see \ref usbsrHookSetDescriptor())
 * \li All \ref SYNCH_FRAME requests (see \ref usbsrHookSynchFrame())
 * \li \ref CLEAR_FEATURE requests that refer to unknown features (see \ref usbsrHookClearFeature())
 * \li \ref SET_FEATURE requests that refer to unknown features (see \ref usbsrHookSetFeature())
 *
 * These hooks must always be provided, however if the application does not either support the requests,
 * it should just stall endpoint 0. The processing uses the same mechanisms as for class and vendor
 * requests (refer to the \ref module_usb_framework module for detailed description and examples).
 *
 * When the \ref GET_STATUS request is received, the \ref usbsrHookModifyGetStatus() hook is always
 * called, so that additional status bits may be added.
 *
 * To have any practical purpose, "OUT data phase" standard requests need to notify the application of
 * certain events. This is done by passing the event via yet another function hook,
 * \ref usbsrHookProcessEvent(uint8 event, uint8 index). For events related to interfaces and endpoints,
 * the \c index parameter refers to an interface number or the least significant nibble of the endpoint
 * address. The following events can be generated:
 * \li \ref USBSR_EVENT_CONFIGURATION_CHANGING (the device configuration is about to change)
 * \li \ref USBSR_EVENT_CONFIGURATION_CHANGED (the device configuration has changed)
 * \li \ref USBSR_EVENT_INTERFACE_CHANGING (the alternate setting of the given interface is about to
 *     change)
 * \li \ref USBSR_EVENT_INTERFACE_CHANGED (the alternate setting of the given interface has changed)
 * \li \ref USBSR_EVENT_REMOTE_WAKEUP_ENABLED (remote wakeup has been enabled by the host)
 * \li \ref USBSR_EVENT_REMOTE_WAKEUP_DISABLED (remote wakeup has been disabled by the host)
 * \li \ref USBSR_EVENT_EPIN_STALL_CLEARED (the given IN endpoint's stall condition has been cleared the
 *     host)
 * \li \ref USBSR_EVENT_EPIN_STALL_SET (the given IN endpoint has been stalled by the host)
 * \li \ref USBSR_EVENT_EPOUT_STALL_CLEARED (the given OUT endpoint's stall condition has been cleared
 *     the host)
 * \li \ref USBSR_EVENT_EPOUT_STALL_SET (the given OUT endpoint has been stalled by the PC)
 * @{
 */


//-------------------------------------------------------------------------------------------------------
/// \name Standard Request Codes
//@{

/// Standard request that returns status for the specified recipient
#define GET_STATUS           0x00
/// Standard request that clears or disables a specific feature
#define CLEAR_FEATURE        0x01
/// Standard request that sets or enables a specific feature
#define SET_FEATURE          0x03
/// Standard request that sets the device address for all future device accesses
#define SET_ADDRESS          0x05
/// Standard request that returns the specified USB descriptor
#define GET_DESCRIPTOR       0x06
/// Standard request that may be used to update exitsting descriptors or new descriptors may be added
#define SET_DESCRIPTOR       0x07
/// Standard request that returns the current device configuration value
#define GET_CONFIGURATION    0x08
/// Standard request that sets the device configuration
#define SET_CONFIGURATION    0x09
/// Standard request that returns the selected alternate setting for the specified interface
#define GET_INTERFACE        0x0A
/// Standard request that selects an alternate setting for the specified interface
#define SET_INTERFACE        0x0B
/// Standard request that is used to set and then report an endpoint's synchronization frame
#define SYNCH_FRAME          0x0C
//@}
//-------------------------------------------------------------------------------------------------------


//-------------------------------------------------------------------------------------------------------
/// \name Features Indexes
//@{

/// Endpoint feature: Halt
#define ENDPOINT_HALT        0x00
/// Device feature: Remote wakeup
#define DEVICE_REMOTE_WAKEUP 0x01
//@}
//-------------------------------------------------------------------------------------------------------


//-------------------------------------------------------------------------------------------------------
/// \name Event Types
//@{

/// The device configuration is about to change
#define USBSR_EVENT_CONFIGURATION_CHANGING  0x01
/// The device configuration has changed
#define USBSR_EVENT_CONFIGURATION_CHANGED   0x02
/// The alternate setting of the given interface about to change (index = "interface index")
#define USBSR_EVENT_INTERFACE_CHANGING      0x03
/// The alternate setting of the given interface has changed (index = "interface index")
#define USBSR_EVENT_INTERFACE_CHANGED       0x04
/// Remote wakeup has been enabled by the host
#define USBSR_EVENT_REMOTE_WAKEUP_ENABLED   0x05
/// Remote wakeup has been disabled by the host
#define USBSR_EVENT_REMOTE_WAKEUP_DISABLED  0x06
/// The given IN endpoint has been unstalled by the PC (index = "endpoint address" & 0x0F)
#define USBSR_EVENT_EPIN_STALL_CLEARED      0x07 /* Endpoint index */
/// The given IN endpoint has been stalled by the PC (index = "endpoint address" & 0x0F)
#define USBSR_EVENT_EPIN_STALL_SET          0x08 /* Endpoint index */
/// The given OUT endpoint has been unstalled by the PC (index = "endpoint address" & 0x0F)
#define USBSR_EVENT_EPOUT_STALL_CLEARED     0x09 /* Endpoint index */
/// The given OUT endpoint has been stalled by the PC (index = "endpoint address" & 0x0F)
#define USBSR_EVENT_EPOUT_STALL_SET         0x0A /* Endpoint index */
//@}
//-------------------------------------------------------------------------------------------------------


//-------------------------------------------------------------------------------------------------------
/// \name Standard Request Hooks
//@{
/// Refer to the \ref section_setup_handler_usage section for a description on how to process standard
/// requests.

/// Hook which is called upon reception of a \ref SET_DESCRIPTOR request
void usbsrHookSetDescriptor(void);
/// Hook which is called upon reception of a \ref SYNCH_FRAME request (unsupported).
void usbsrHookSynchFrame(void);
/// Hook which is called when a \ref CLEAR_FEATURE request refers to a an unsupported featureted.
void usbsrHookClearFeature(void);
/// Hook which is called when a \ref SET_FEATURE request refers to a an unsupported feature.
void usbsrHookSetFeature(void);
/// Hook for modifying a \ref GET_STATUS request before the status value is returned to the PC.
void usbsrHookModifyGetStatus(uint8 recipient, uint8 index, uint16 __xdata *pStatus);
/// Hook which is called upon a standard request generated event (unsupported).
void usbsrHookProcessEvent(uint8 event, uint8 index);
//@}
//-------------------------------------------------------------------------------------------------------


//-------------------------------------------------------------------------------------------------------
/// \name Handled Standard Requests
//@{
void usbsrGetStatus(void);
void usbsrClearFeature(void);
void usbsrSetFeature(void);
void usbsrSetAddress(void);
void usbsrGetDescriptor(void);
void usbsrGetConfiguration(void);
void usbsrSetConfiguration(void);
void usbsrGetInterface(void);
void usbsrSetInterface(void);
//@}
//-------------------------------------------------------------------------------------------------------


//@}

/*
+------------------------------------------------------------------------------
|  Copyright 2004-2007 Texas Instruments Incorporated. All rights reserved.
|
|  IMPORTANT: Your use of this Software is limited to those specific rights
|  granted under the terms of a software license agreement between the user who
|  downloaded the software, his/her employer (which must be your employer) and
|  Texas Instruments Incorporated (the "License"). You may not use this Software
|  unless you agree to abide by the terms of the License. The License limits
|  your use, and you acknowledge, that the Software may not be modified, copied
|  or distributed unless embedded on a Texas Instruments microcontroller or used
|  solely and exclusively in conjunction with a Texas Instruments radio
|  frequency transceiver, which is integrated into your product. Other than for
|  the foregoing purpose, you may not use, reproduce, copy, prepare derivative
|  works of, modify, distribute, perform, display or sell this Software and/or
|  its documentation for any purpose.
|
|  YOU FURTHER ACKNOWLEDGE AND AGREE THAT THE SOFTWARE AND DOCUMENTATION ARE
|  PROVIDED “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED,
|  INCLUDING WITHOUT LIMITATION, ANY WARRANTY OF MERCHANTABILITY, TITLE,
|  NON-INFRINGEMENT AND FITNESS FOR A PARTICULAR PURPOSE. IN NO EVENT SHALL
|  TEXAS INSTRUMENTS OR ITS LICENSORS BE LIABLE OR OBLIGATED UNDER CONTRACT,
|  NEGLIGENCE, STRICT LIABILITY, CONTRIBUTION, BREACH OF WARRANTY, OR OTHER
|  LEGAL EQUITABLE THEORY ANY DIRECT OR INDIRECT DAMAGES OR EXPENSES INCLUDING
|  BUT NOT LIMITED TO ANY INCIDENTAL, SPECIAL, INDIRECT, PUNITIVE OR
|  CONSEQUENTIAL DAMAGES, LOST PROFITS OR LOST DATA, COST OF PROCUREMENT OF
|  SUBSTITUTE GOODS, TECHNOLOGY, SERVICES, OR ANY CLAIMS BY THIRD PARTIES
|  (INCLUDING BUT NOT LIMITED TO ANY DEFENSE THEREOF), OR OTHER SIMILAR COSTS.
|
|  Should you have any questions regarding your right to use this Software,
|  contact Texas Instruments Incorporated at www.TI.com.
|
+------------------------------------------------------------------------------
*/

#endif