usb_core.h

00001 /******************** (C) COPYRIGHT 2010 STMicroelectronics ********************
00002 * File Name          : usb_core.h
00003 * Author             : MCD Application Team
00004 * Version            : V3.2.1
00005 * Date               : 07/05/2010
00006 * Description        : Standard protocol processing functions prototypes
00007 ********************************************************************************
00008 * THE PRESENT FIRMWARE WHICH IS FOR GUIDANCE ONLY AIMS AT PROVIDING CUSTOMERS
00009 * WITH CODING INFORMATION REGARDING THEIR PRODUCTS IN ORDER FOR THEM TO SAVE TIME.
00010 * AS A RESULT, STMICROELECTRONICS SHALL NOT BE HELD LIABLE FOR ANY DIRECT,
00011 * INDIRECT OR CONSEQUENTIAL DAMAGES WITH RESPECT TO ANY CLAIMS ARISING FROM THE
00012 * CONTENT OF SUCH FIRMWARE AND/OR THE USE MADE BY CUSTOMERS OF THE CODING
00013 * INFORMATION CONTAINED HEREIN IN CONNECTION WITH THEIR PRODUCTS.
00014 *******************************************************************************/
00015 
00016 /* Define to prevent recursive inclusion -------------------------------------*/
00017 #ifndef __USB_CORE_H
00018 #define __USB_CORE_H
00019 
00020 /* Includes ------------------------------------------------------------------*/
00021 /* Exported types ------------------------------------------------------------*/
00022 typedef enum _CONTROL_STATE
00023 {
00024   WAIT_SETUP,       /* 0 */
00025   SETTING_UP,       /* 1 */
00026   IN_DATA,          /* 2 */
00027   OUT_DATA,         /* 3 */
00028   LAST_IN_DATA,     /* 4 */
00029   LAST_OUT_DATA,    /* 5 */
00030   WAIT_STATUS_IN,   /* 7 */
00031   WAIT_STATUS_OUT,  /* 8 */
00032   STALLED,          /* 9 */
00033   PAUSE             /* 10 */
00034 } CONTROL_STATE;    /* The state machine states of a control pipe */
00035 
00036 typedef struct OneDescriptor
00037 {
00038   uint8_t *Descriptor;
00039   uint16_t Descriptor_Size;
00040 }
00041 ONE_DESCRIPTOR, *PONE_DESCRIPTOR;
00042 /* All the request process routines return a value of this type
00043    If the return value is not SUCCESS or NOT_READY,
00044    the software will STALL the correspond endpoint */
00045 typedef enum _RESULT
00046 {
00047   USB_SUCCESS = 0,    /* Process sucessfully */
00048   USB_ERROR,
00049   USB_UNSUPPORT,
00050   USB_NOT_READY       /* The process has not been finished, endpoint will be
00051                          NAK to further rquest */
00052 } RESULT;
00053 
00054 
00055 /*-*-*-*-*-*-*-*-*-*-* Definitions for endpoint level -*-*-*-*-*-*-*-*-*-*-*-*/
00056 typedef struct _ENDPOINT_INFO
00057 {
00058   /* When send data out of the device,
00059    CopyData() is used to get data buffer 'Length' bytes data
00060    if Length is 0,
00061     CopyData() returns the total length of the data
00062     if the request is not supported, returns 0
00063     (NEW Feature )
00064      if CopyData() returns -1, the calling routine should not proceed
00065      further and will resume the SETUP process by the class device
00066    if Length is not 0,
00067     CopyData() returns a pointer to indicate the data location
00068    Usb_wLength is the data remain to be sent,
00069    Usb_wOffset is the Offset of original data
00070   When receive data from the host,
00071    CopyData() is used to get user data buffer which is capable
00072    of Length bytes data to copy data from the endpoint buffer.
00073    if Length is 0,
00074     CopyData() returns the available data length,
00075    if Length is not 0,
00076     CopyData() returns user buffer address
00077    Usb_rLength is the data remain to be received,
00078    Usb_rPointer is the Offset of data buffer
00079   */
00080   uint16_t  Usb_wLength;
00081   uint16_t  Usb_wOffset;
00082   uint16_t  PacketSize;
00083   uint8_t   *(*CopyData)(uint16_t Length);
00084 }ENDPOINT_INFO;
00085 
00086 /*-*-*-*-*-*-*-*-*-*-*-* Definitions for device level -*-*-*-*-*-*-*-*-*-*-*-*/
00087 
00088 typedef struct _DEVICE
00089 {
00090   uint8_t Total_Endpoint;     /* Number of endpoints that are used */
00091   uint8_t Total_Configuration;/* Number of configuration available */
00092 }
00093 DEVICE;
00094 
00095 typedef union
00096 {
00097   uint16_t w;
00098   struct BW
00099   {
00100     uint8_t bb1;
00101     uint8_t bb0;
00102   }
00103   bw;
00104 } uint16_t_uint8_t;
00105 
00106 typedef struct _DEVICE_INFO
00107 {
00108   uint8_t USBbmRequestType;       /* bmRequestType */
00109   uint8_t USBbRequest;            /* bRequest */
00110   uint16_t_uint8_t USBwValues;         /* wValue */
00111   uint16_t_uint8_t USBwIndexs;         /* wIndex */
00112   uint16_t_uint8_t USBwLengths;        /* wLength */
00113 
00114   uint8_t ControlState;           /* of type CONTROL_STATE */
00115   uint8_t Current_Feature;
00116   uint8_t Current_Configuration;   /* Selected configuration */
00117   uint8_t Current_Interface;       /* Selected interface of current configuration */
00118   uint8_t Current_AlternateSetting;/* Selected Alternate Setting of current
00119                                      interface*/
00120 
00121   ENDPOINT_INFO Ctrl_Info;
00122 }DEVICE_INFO;
00123 
00124 typedef struct _DEVICE_PROP
00125 {
00126   void (*Init)(void);        /* Initialize the device */
00127   void (*Reset)(void);       /* Reset routine of this device */
00128 
00129   /* Device dependent process after the status stage */
00130   void (*Process_Status_IN)(void);
00131   void (*Process_Status_OUT)(void);
00132 
00133   /* Procedure of process on setup stage of a class specified request with data stage */
00134   /* All class specified requests with data stage are processed in Class_Data_Setup
00135    Class_Data_Setup()
00136     responses to check all special requests and fills ENDPOINT_INFO
00137     according to the request
00138     If IN tokens are expected, then wLength & wOffset will be filled
00139     with the total transferring bytes and the starting position
00140     If OUT tokens are expected, then rLength & rOffset will be filled
00141     with the total expected bytes and the starting position in the buffer
00142 
00143     If the request is valid, Class_Data_Setup returns SUCCESS, else UNSUPPORT
00144 
00145    CAUTION:
00146     Since GET_CONFIGURATION & GET_INTERFACE are highly related to
00147     the individual classes, they will be checked and processed here.
00148   */
00149   RESULT (*Class_Data_Setup)(uint8_t RequestNo);
00150 
00151   /* Procedure of process on setup stage of a class specified request without data stage */
00152   /* All class specified requests without data stage are processed in Class_NoData_Setup
00153    Class_NoData_Setup
00154     responses to check all special requests and perform the request
00155 
00156    CAUTION:
00157     Since SET_CONFIGURATION & SET_INTERFACE are highly related to
00158     the individual classes, they will be checked and processed here.
00159   */
00160   RESULT (*Class_NoData_Setup)(uint8_t RequestNo);
00161 
00162   /*Class_Get_Interface_Setting
00163    This function is used by the file usb_core.c to test if the selected Interface
00164    and Alternate Setting (uint8_t Interface, uint8_t AlternateSetting) are supported by
00165    the application.
00166    This function is writing by user. It should return "SUCCESS" if the Interface
00167    and Alternate Setting are supported by the application or "UNSUPPORT" if they
00168    are not supported. */
00169 
00170   RESULT  (*Class_Get_Interface_Setting)(uint8_t Interface, uint8_t AlternateSetting);
00171 
00172   uint8_t* (*GetDeviceDescriptor)(uint16_t Length);
00173   uint8_t* (*GetConfigDescriptor)(uint16_t Length);
00174   uint8_t* (*GetStringDescriptor)(uint16_t Length);
00175 
00176   /* This field is not used in current library version. It is kept only for 
00177    compatibility with previous versions */
00178   void* RxEP_buffer;
00179    
00180   uint8_t MaxPacketSize;
00181 
00182 }DEVICE_PROP;
00183 
00184 typedef struct _USER_STANDARD_REQUESTS
00185 {
00186   void (*User_GetConfiguration)(void);       /* Get Configuration */
00187   void (*User_SetConfiguration)(void);       /* Set Configuration */
00188   void (*User_GetInterface)(void);           /* Get Interface */
00189   void (*User_SetInterface)(void);           /* Set Interface */
00190   void (*User_GetStatus)(void);              /* Get Status */
00191   void (*User_ClearFeature)(void);           /* Clear Feature */
00192   void (*User_SetEndPointFeature)(void);     /* Set Endpoint Feature */
00193   void (*User_SetDeviceFeature)(void);       /* Set Device Feature */
00194   void (*User_SetDeviceAddress)(void);       /* Set Device Address */
00195 }
00196 USER_STANDARD_REQUESTS;
00197 
00198 /* Exported constants --------------------------------------------------------*/
00199 #define Type_Recipient (pInformation->USBbmRequestType & (REQUEST_TYPE | RECIPIENT))
00200 
00201 #define Usb_rLength Usb_wLength
00202 #define Usb_rOffset Usb_wOffset
00203 
00204 #define USBwValue USBwValues.w
00205 #define USBwValue0 USBwValues.bw.bb0
00206 #define USBwValue1 USBwValues.bw.bb1
00207 #define USBwIndex USBwIndexs.w
00208 #define USBwIndex0 USBwIndexs.bw.bb0
00209 #define USBwIndex1 USBwIndexs.bw.bb1
00210 #define USBwLength USBwLengths.w
00211 #define USBwLength0 USBwLengths.bw.bb0
00212 #define USBwLength1 USBwLengths.bw.bb1
00213 
00214 /* Exported macro ------------------------------------------------------------*/
00215 /* Exported functions ------------------------------------------------------- */
00216 uint8_t Setup0_Process(void);
00217 uint8_t Post0_Process(void);
00218 uint8_t Out0_Process(void);
00219 uint8_t In0_Process(void);
00220 
00221 RESULT Standard_SetEndPointFeature(void);
00222 RESULT Standard_SetDeviceFeature(void);
00223 
00224 uint8_t *Standard_GetConfiguration(uint16_t Length);
00225 RESULT Standard_SetConfiguration(void);
00226 uint8_t *Standard_GetInterface(uint16_t Length);
00227 RESULT Standard_SetInterface(void);
00228 uint8_t *Standard_GetDescriptorData(uint16_t Length, PONE_DESCRIPTOR pDesc);
00229 
00230 uint8_t *Standard_GetStatus(uint16_t Length);
00231 RESULT Standard_ClearFeature(void);
00232 void SetDeviceAddress(uint8_t);
00233 void NOP_Process(void);
00234 
00235 extern DEVICE_PROP Device_Property;
00236 extern  USER_STANDARD_REQUESTS User_Standard_Requests;
00237 extern  DEVICE  Device_Table;
00238 extern DEVICE_INFO Device_Info;
00239 
00240 /* cells saving status during interrupt servicing */
00241 extern __IO uint16_t SaveRState;
00242 extern __IO uint16_t SaveTState;
00243 
00244 #endif /* __USB_CORE_H */
00245 
00246 /******************* (C) COPYRIGHT 2010 STMicroelectronics *****END OF FILE****/