git.sur5r.net Git - freertos/blob - FreeRTOS-Plus/Demo/FreeRTOS_Plus_UDP_and_CLI_LPC1830_GCC/ThirdParty/LPCOpen/LPCUSBLib/Drivers/USB/Core/HostStandardReq.h

   1 /*\r
   2  * @brief USB host standard request management\r
   3  *\r
   4  * @note\r
   5  * Copyright(C) NXP Semiconductors, 2012\r
   6  * Copyright(C) Dean Camera, 2011, 2012\r
   7  * All rights reserved.\r
   8  *\r
   9  * @par\r
  10  * Software that is described herein is for illustrative purposes only\r
  11  * which provides customers with programming information regarding the\r
  12  * LPC products.  This software is supplied "AS IS" without any warranties of\r
  13  * any kind, and NXP Semiconductors and its licensor disclaim any and\r
  14  * all warranties, express or implied, including all implied warranties of\r
  15  * merchantability, fitness for a particular purpose and non-infringement of\r
  16  * intellectual property rights.  NXP Semiconductors assumes no responsibility\r
  17  * or liability for the use of the software, conveys no license or rights under any\r
  18  * patent, copyright, mask work right, or any other intellectual property rights in\r
  19  * or to any products. NXP Semiconductors reserves the right to make changes\r
  20  * in the software without notification. NXP Semiconductors also makes no\r
  21  * representation or warranty that such application will be suitable for the\r
  22  * specified use without further testing or modification.\r
  23  *\r
  24  * @par\r
  25  * Permission to use, copy, modify, and distribute this software and its\r
  26  * documentation is hereby granted, under NXP Semiconductors' and its\r
  27  * licensor's relevant copyrights in the software, without fee, provided that it\r
  28  * is used in conjunction with NXP Semiconductors microcontrollers.  This\r
  29  * copyright, permission, and disclaimer notice must appear in all copies of\r
  30  * this code.\r
  31  */\r
  32 \r
  33 #ifndef __HOSTSTDREQ_H__\r
  34 #define __HOSTSTDREQ_H__\r
  35 \r
  36         /* Includes: */\r
  37                 #include "../../../Common/Common.h"\r
  38                 #include "USBMode.h"\r
  39                 #include "StdRequestType.h"\r
  40                 #include "USBController.h"\r
  41 \r
  42         /* Enable C linkage for C++ Compilers: */\r
  43                 #if defined(__cplusplus)\r
  44                         extern "C" {\r
  45                 #endif\r
  46 \r
  47         /* Preprocessor Checks: */\r
  48                 #if !defined(__INCLUDE_FROM_USB_DRIVER)\r
  49                         #error Do not include this file directly. Include lpcroot/libraries/LPCUSBlib/Drivers/USB/USB.h instead.\r
  50                 #endif\r
  51 \r
  52         /* Public Interface - May be used in end-application: */\r
  53                 /* Macros: */\r
  54                         #if !defined(USB_HOST_TIMEOUT_MS) || defined(__DOXYGEN__)\r
  55                                 /** Constant for the maximum software timeout period of sent USB control transactions to an attached\r
  56                                  *  device. If a device fails to respond to a sent control request within this period, the\r
  57                                  *  library will return a timeout error code.\r
  58                                  *\r
  59                                  *  This value may be overridden in the user project makefile as the value of the\r
  60                                  *  @ref USB_HOST_TIMEOUT_MS token, and passed to the compiler using the -D switch.\r
  61                                  */\r
  62                                 #define USB_HOST_TIMEOUT_MS                1000\r
  63                         #endif\r
  64                         \r
  65                 /* Enums: */\r
  66                         /** Enum for the @ref USB_Host_SendControlRequest() return code, indicating the reason for the error\r
  67                          *  if the transfer of the request is unsuccessful.\r
  68                          *\r
  69                          *  @ingroup Group_PipeControlReq\r
  70                          */\r
  71                         enum USB_Host_SendControlErrorCodes_t\r
  72                         {\r
  73                                 HOST_SENDCONTROL_Successful         = 0, /**< No error occurred in the request transfer. */\r
  74                                 HOST_SENDCONTROL_DeviceDisconnected = 1, /**< The attached device was disconnected during the\r
  75                                                                         *   request transfer.\r
  76                                                                         */\r
  77                                 HOST_SENDCONTROL_PipeError          = 2, /**< An error occurred in the pipe while sending the request. */\r
  78                                 HOST_SENDCONTROL_SetupStalled       = 3, /**< The attached device stalled the request, usually\r
  79                                                                         *   indicating that the request is unsupported on the device.\r
  80                                                                         */\r
  81                                 HOST_SENDCONTROL_SoftwareTimeOut    = 4, /**< The request or data transfer timed out. */\r
  82                         };\r
  83 \r
  84                 /* Global Variables: */\r
  85                         /** Indicates the currently set configuration number of the attached device. This indicates the currently\r
  86                          *  selected configuration value if one has been set sucessfully, or 0 if no configuration has been selected.\r
  87                          *\r
  88                          *  To set a device configuration, call the @ref USB_Host_SetDeviceConfiguration() function.\r
  89                          *\r
  90                          *  @note This variable should be treated as read-only in the user application, and never manually\r
  91                          *        changed in value.\r
  92                          *\r
  93                          *  @ingroup Group_Host\r
  94                          */\r
  95                         extern uint8_t USB_Host_ConfigurationNumber;\r
  96                         \r
  97                 /* Function Prototypes: */\r
  98                         /** @brief Sends the request stored in the @ref USB_ControlRequest global structure to the attached device,\r
  99                          *  and transfers the data stored in the buffer to the device, or from the device to the buffer\r
 100                          *  as requested. The transfer is made on the currently selected pipe.\r
 101                          *\r
 102                          *  @ingroup Group_PipeControlReq\r
 103                          *\r
 104                          *  @param      corenum         : USB port number\r
 105                          *  @param              BufferPtr       : Pointer to the start of the data buffer if the request has a data stage, or\r
 106                          *                        \c NULL if the request transfers no data to or from the device.\r
 107                          *\r
 108                          *  @return A value from the @ref USB_Host_SendControlErrorCodes_t enum to indicate the result.\r
 109                          */\r
 110                         uint8_t USB_Host_SendControlRequest(const uint8_t corenum, void* const BufferPtr);\r
 111 \r
 112                         /** @brief Sends a SET CONFIGURATION standard request to the attached device, with the given configuration index.\r
 113                          *\r
 114                          *  This routine will automatically update the @ref USB_HostState and @ref USB_Host_ConfigurationNumber\r
 115                          *  state variables according to the given function parameters and the result of the request.\r
 116                          *\r
 117                          *  @note After this routine returns, the control pipe will be selected.\r
 118                          *\r
 119                          *  @ingroup Group_PipeControlReq\r
 120                          *\r
 121                          *  @param      corenum                 : USB port number\r
 122                          *  @param              ConfigNumber    : Configuration index to send to the device.\r
 123                          *\r
 124                          *  @return A value from the @ref USB_Host_SendControlErrorCodes_t enum to indicate the result.\r
 125                          */\r
 126                         uint8_t USB_Host_SetDeviceConfiguration(const uint8_t corenum, const uint8_t ConfigNumber);\r
 127 \r
 128                         /** @brief Sends a GET DESCRIPTOR standard request to the attached device, requesting the device descriptor.\r
 129                          *  This can be used to easily retrieve information about the device such as its VID, PID and power\r
 130                          *  requirements.\r
 131                          *\r
 132                          *  @note After this routine returns, the control pipe will be selected.\r
 133                          *\r
 134                          *  @ingroup Group_PipeControlReq\r
 135                          *\r
 136                          *  @param      corenum                         : USB port number\r
 137                          *  @param              DeviceDescriptorPtr     : Pointer to the destination device descriptor structure where\r
 138                          *                                   the read data is to be stored.\r
 139                          *\r
 140                          *  @return A value from the @ref USB_Host_SendControlErrorCodes_t enum to indicate the result.\r
 141                          */\r
 142                         uint8_t USB_Host_GetDeviceDescriptor(const uint8_t corenum, void* const DeviceDescriptorPtr) ATTR_NON_NULL_PTR_ARG(2);\r
 143 \r
 144                         /** @brief Sends a GET DESCRIPTOR standard request to the attached device, requesting the string descriptor\r
 145                          *  of the specified index. This can be used to easily retrieve string descriptors from the device by\r
 146                          *  index, after the index is obtained from the Device or Configuration descriptors.\r
 147                          *\r
 148                          *  @note After this routine returns, the control pipe will be selected.\r
 149                          *\r
 150                          *  @ingroup Group_PipeControlReq\r
 151                          *\r
 152                          *  @param      corenum         : USB port number\r
 153                          *  @param              Index           : Index of the string index to retrieve.\r
 154                          *  @param              Buffer          : Pointer to the destination buffer where the retrieved string descriptor is\r
 155                          *                           to be stored.\r
 156                          *  @param              BufferLength : Maximum size of the string descriptor which can be stored into the buffer.\r
 157                          *\r
 158                          *  @return A value from the @ref USB_Host_SendControlErrorCodes_t enum to indicate the result.\r
 159                          */\r
 160                         uint8_t USB_Host_GetDeviceStringDescriptor(const uint8_t corenum,\r
 161                                                                                                            const uint8_t Index,\r
 162                                                                    void* const Buffer,\r
 163                                                                    const uint8_t BufferLength) ATTR_NON_NULL_PTR_ARG(3);\r
 164 \r
 165                         /** @brief Retrieves the current feature status of the attached device, via a GET STATUS standard request. The\r
 166                          *  retrieved feature status can then be examined by masking the retrieved value with the various\r
 167                          *  FEATURE_* masks for bus/self power information and remote wakeup support.\r
 168                          *\r
 169                          *  @note After this routine returns, the control pipe will be selected.\r
 170                          *\r
 171                          *  @ingroup Group_PipeControlReq\r
 172                          *\r
 173                          *  @param      corenum                 : USB port number\r
 174                          *  @param              FeatureStatus   : Location where the retrieved feature status should be stored.\r
 175                          *\r
 176                          *  @return A value from the @ref USB_Host_SendControlErrorCodes_t enum to indicate the result.\r
 177                          */\r
 178                         uint8_t USB_Host_GetDeviceStatus(const uint8_t corenum, uint8_t* const FeatureStatus) ATTR_NON_NULL_PTR_ARG(2);\r
 179 \r
 180                         /** @brief Clears a stall condition on the given pipe, via a CLEAR FEATURE standard request to the attached device.\r
 181                          *\r
 182                          *  @note After this routine returns, the control pipe will be selected.\r
 183                          *\r
 184                          *  @ingroup Group_PipeControlReq\r
 185                          *\r
 186                          *  @param      corenum                 : USB port number\r
 187                          *  @param              EndpointAddress : Address of the endpoint to clear, including the endpoint's direction.\r
 188                          *\r
 189                          *  @return A value from the @ref USB_Host_SendControlErrorCodes_t enum to indicate the result.\r
 190                          */\r
 191                         uint8_t USB_Host_ClearEndpointStall(const uint8_t corenum, const uint8_t EndpointAddress);\r
 192 \r
 193                         /** @brief Selects a given alternative setting for the specified interface, via a SET INTERFACE standard request to\r
 194                          *  the attached device.\r
 195                          *\r
 196                          *  @note After this routine returns, the control pipe will be selected.\r
 197                          *\r
 198                          *  @ingroup Group_PipeControlReq\r
 199                          *\r
 200                          *  @param      corenum                 : USB port number\r
 201                          *  @param              InterfaceIndex  : Index of the interface whose alternative setting is to be altered.\r
 202                          *  @param              AltSetting              : Index of the interface's alternative setting which is to be selected.\r
 203                          *\r
 204                          *  @return A value from the @ref USB_Host_SendControlErrorCodes_t enum to indicate the result.\r
 205                          */\r
 206                         uint8_t USB_Host_SetInterfaceAltSetting(const uint8_t corenum,\r
 207                                                                                                         const uint8_t InterfaceIndex,\r
 208                                                                                                         const uint8_t AltSetting);\r
 209 \r
 210         /* Private Interface - For use in library only: */\r
 211         #if !defined(__DOXYGEN__)\r
 212                 /* Enums: */\r
 213                         enum USB_WaitForTypes_t\r
 214                         {\r
 215                                 USB_HOST_WAITFOR_SetupSent,\r
 216                                 USB_HOST_WAITFOR_InReceived,\r
 217                                 USB_HOST_WAITFOR_OutReady,\r
 218                         };\r
 219 \r
 220                 /* Function Prototypes: */\r
 221                         #if defined(__INCLUDE_FROM_HOSTSTDREQ_C)\r
 222                                 // static uint8_t USB_Host_WaitForIOS(const uint8_t WaitType); Deprecated\r
 223                         #endif\r
 224         #endif\r
 225 \r
 226         /* Disable C linkage for C++ Compilers: */\r
 227                 #if defined(__cplusplus)\r
 228                         }\r
 229                 #endif\r
 230 \r
 231 #endif\r
 232 \r