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