HostStandardReq.h 13 KB
 Dean Camera committed May 08, 2010 1 2 /* LUFA Library  Dean Camera committed Jan 01, 2011 3  Copyright (C) Dean Camera, 2011.  4   Dean Camera committed May 08, 2010 5  dean [at] fourwalledcubicle [dot] com  Dean Camera committed Oct 28, 2010 6  www.lufa-lib.org  Dean Camera committed May 08, 2010 7 8 9 */ /*  Dean Camera committed Jan 01, 2011 10  Copyright 2011 Dean Camera (dean [at] fourwalledcubicle [dot] com)  Dean Camera committed May 08, 2010 11   12  Permission to use, copy, modify, distribute, and sell this  Dean Camera committed May 08, 2010 13  software and its documentation for any purpose is hereby granted  14  without fee, provided that the above copyright notice appear in  Dean Camera committed May 08, 2010 15  all copies and that both that the copyright notice and this  16 17 18  permission notice and warranty disclaimer appear in supporting documentation, and that the name of the author not be used in advertising or publicity pertaining to distribution of the  Dean Camera committed May 08, 2010 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33  software without specific, written prior permission. The author disclaim all warranties with regard to this software, including all implied warranties of merchantability and fitness. In no event shall the author be liable for any special, indirect or consequential damages or any damages whatsoever resulting from loss of use, data or profits, whether in an action of contract, negligence or other tortious action, arising out of or in connection with the use or performance of this software. */ /** \file * \brief USB host standard request management. *  Dean Camera committed Jun 16, 2010 34  * This file contains the function prototypes necessary for the issuing of outgoing standard control requests  Dean Camera committed May 08, 2010 35 36 37 38 39 40  * when the library is in USB host mode. * * \note This file should not be included directly. It is automatically included as needed by the USB driver * dispatch header located in LUFA/Drivers/USB/USB.h. */  Dean Camera committed Jul 21, 2010 41 42 #ifndef __HOSTSTDREQ_H__ #define __HOSTSTDREQ_H__  Dean Camera committed May 08, 2010 43 44  /* Includes: */  Dean Camera committed Feb 19, 2011 45  #include "../../../Common/Common.h"  Dean Camera committed Jul 21, 2010 46 47  #include "USBMode.h" #include "StdRequestType.h"  Dean Camera committed Feb 19, 2011 48  #include "USBController.h"  49   Dean Camera committed May 08, 2010 50 51 52 53 54 55 56 57 58  /* Enable C linkage for C++ Compilers: */ #if defined(__cplusplus) extern "C" { #endif /* Preprocessor Checks: */ #if !defined(__INCLUDE_FROM_USB_DRIVER) #error Do not include this file directly. Include LUFA/Drivers/USB/USB.h instead. #endif  59   Dean Camera committed May 08, 2010 60  /* Public Interface - May be used in end-application: */  61 62 63 64 65 66 67 68 69 70 71 72  /* Macros: */ #if !defined(USB_HOST_TIMEOUT_MS) || defined(__DOXYGEN__) /** Constant for the maximum software timeout period of sent USB control transactions to an attached * device. If a device fails to respond to a sent control request within this period, the * library will return a timeout error code. * * This value may be overridden in the user project makefile as the value of the * \ref USB_HOST_TIMEOUT_MS token, and passed to the compiler using the -D switch. */ #define USB_HOST_TIMEOUT_MS 1000 #endif  Dean Camera committed May 08, 2010 73 74 75 76 77 78 79 80 81 82  /* Enums: */ /** Enum for the \ref USB_Host_SendControlRequest() return code, indicating the reason for the error * if the transfer of the request is unsuccessful. * * \ingroup Group_PipeControlReq */ enum USB_Host_SendControlErrorCodes_t { HOST_SENDCONTROL_Successful = 0, /**< No error occurred in the request transfer. */ HOST_SENDCONTROL_DeviceDisconnected = 1, /**< The attached device was disconnected during the  Dean Camera committed Nov 24, 2011 83  * request transfer.  Dean Camera committed May 08, 2010 84 85 86  */ HOST_SENDCONTROL_PipeError = 2, /**< An error occurred in the pipe while sending the request. */ HOST_SENDCONTROL_SetupStalled = 3, /**< The attached device stalled the request, usually  Dean Camera committed Nov 24, 2011 87 88  * indicating that the request is unsupported on the device. */  Dean Camera committed May 08, 2010 89 90  HOST_SENDCONTROL_SoftwareTimeOut = 4, /**< The request or data transfer timed out. */ };  91   Dean Camera committed Jul 08, 2011 92 93 94 95 96 97 98 99 100 101 102 103 104  /* Global Variables: */ /** Indicates the currently set configuration number of the attached device. This indicates the currently * selected configuration value if one has been set sucessfully, or 0 if no configuration has been selected. * * To set a device configuration, call the \ref USB_Host_SetDeviceConfiguration() function. * * \note This variable should be treated as read-only in the user application, and never manually * changed in value. * * \ingroup Group_Host */ extern uint8_t USB_Host_ConfigurationNumber;  Dean Camera committed May 08, 2010 105 106 107 108 109 110 111 112  /* Function Prototypes: */ /** Sends the request stored in the \ref USB_ControlRequest global structure to the attached device, * and transfers the data stored in the buffer to the device, or from the device to the buffer * as requested. The transfer is made on the currently selected pipe. * * \ingroup Group_PipeControlReq * * \param[in] BufferPtr Pointer to the start of the data buffer if the request has a data stage, or  Dean Camera committed Jan 08, 2011 113  * \c NULL if the request transfers no data to or from the device.  Dean Camera committed May 08, 2010 114 115 116  * * \return A value from the \ref USB_Host_SendControlErrorCodes_t enum to indicate the result. */  Dean Camera committed Jul 21, 2010 117  uint8_t USB_Host_SendControlRequest(void* const BufferPtr);  118   Dean Camera committed Jul 12, 2011 119  /** Sends a SET CONFIGURATION standard request to the attached device, with the given configuration index.  Dean Camera committed Jul 08, 2011 120 121 122 123 124 125 126 127 128 129 130 131 132  * * This routine will automatically update the \ref USB_HostState and \ref USB_Host_ConfigurationNumber * state variables according to the given function parameters and the result of the request. * * \note After this routine returns, the control pipe will be selected. * * \ingroup Group_PipeControlReq * * \param[in] ConfigNumber Configuration index to send to the device. * * \return A value from the \ref USB_Host_SendControlErrorCodes_t enum to indicate the result. */ uint8_t USB_Host_SetDeviceConfiguration(const uint8_t ConfigNumber);  133 134 135 136 137 138 139 140 141 142 143 144 145  /** Sends a GET CONFIGURATION standard request to the attached device, to retrieve the currently selected * device configuration index. * * \note After this routine returns, the control pipe will be selected. * * \ingroup Group_PipeControlReq * * \param[out] ConfigNumber Pointer to a location where the retrieved configuration index should be stored. * * \return A value from the \ref USB_Host_SendControlErrorCodes_t enum to indicate the result. */ uint8_t USB_Host_GetDeviceConfiguration(uint8_t* const ConfigNumber) ATTR_NON_NULL_PTR_ARG(1);  Dean Camera committed Jul 08, 2011 146   Dean Camera committed Nov 24, 2011 147 148  /** Sends a GET DESCRIPTOR standard request to the attached device, requesting the descriptor of the * specified type and index.  Dean Camera committed Jul 08, 2011 149 150 151 152 153  * * \note After this routine returns, the control pipe will be selected. * * \ingroup Group_PipeControlReq *  Dean Camera committed Nov 24, 2011 154 155 156 157  * \param[in] Type Type of descriptor to retrieve, a value from the \ref USB_DescriptorTypes_t enum. * \param[in] Index Index of the descriptor to retrieve. * \param[out] Buffer Pointer to the destination buffer where the retrieved string descriptor is to be stored. * \param[in] BufferLength Maximum size of the string descriptor which can be stored into the buffer.  Dean Camera committed Jul 08, 2011 158 159 160  * * \return A value from the \ref USB_Host_SendControlErrorCodes_t enum to indicate the result. */  Dean Camera committed Nov 24, 2011 161 162 163 164  uint8_t USB_Host_GetDescriptor(const uint8_t Type, const uint8_t Index, void* const Buffer, const uint8_t BufferLength) ATTR_NON_NULL_PTR_ARG(3);  Dean Camera committed Jul 08, 2011 165   Dean Camera committed Jul 12, 2011 166 167 168 169 170 171 172 173 174 175 176 177  /** Retrieves the current feature status of the attached device, via a GET STATUS standard request. The * retrieved feature status can then be examined by masking the retrieved value with the various * FEATURE_* masks for bus/self power information and remote wakeup support. * * \note After this routine returns, the control pipe will be selected. * * \ingroup Group_PipeControlReq * * \param[out] FeatureStatus Location where the retrieved feature status should be stored. * * \return A value from the \ref USB_Host_SendControlErrorCodes_t enum to indicate the result. */  Dean Camera committed Jul 12, 2011 178  uint8_t USB_Host_GetDeviceStatus(uint8_t* const FeatureStatus) ATTR_NON_NULL_PTR_ARG(1);  Dean Camera committed Jul 12, 2011 179   Dean Camera committed Jul 08, 2011 180 181 182 183 184 185  /** Clears a stall condition on the given pipe, via a CLEAR FEATURE standard request to the attached device. * * \note After this routine returns, the control pipe will be selected. * * \ingroup Group_PipeControlReq *  Dean Camera committed Jul 11, 2011 186  * \param[in] EndpointAddress Address of the endpoint to clear, including the endpoint's direction.  Dean Camera committed Jul 08, 2011 187 188 189  * * \return A value from the \ref USB_Host_SendControlErrorCodes_t enum to indicate the result. */  Dean Camera committed Aug 24, 2011 190  uint8_t USB_Host_ClearEndpointStall(const uint8_t EndpointAddress);  Dean Camera committed Jul 08, 2011 191 192 193 194 195 196 197 198 199 200 201 202 203 204  /** Selects a given alternative setting for the specified interface, via a SET INTERFACE standard request to * the attached device. * * \note After this routine returns, the control pipe will be selected. * * \ingroup Group_PipeControlReq * * \param[in] InterfaceIndex Index of the interface whose alternative setting is to be altered. * \param[in] AltSetting Index of the interface's alternative setting which is to be selected. * * \return A value from the \ref USB_Host_SendControlErrorCodes_t enum to indicate the result. */ uint8_t USB_Host_SetInterfaceAltSetting(const uint8_t InterfaceIndex,  Dean Camera committed Nov 24, 2011 205  const uint8_t AltSetting);  Dean Camera committed Jul 08, 2011 206   207 208 209 210 211 212 213 214 215 216 217 218 219 220 221  /** Retrieves the current alternative setting for the specified interface, via a GET INTERFACE standard request to * the attached device. * * \note After this routine returns, the control pipe will be selected. * * \ingroup Group_PipeControlReq * * \param[in] InterfaceIndex Index of the interface whose alternative setting is to be altered. * \param[out] AltSetting Pointer to a location where the retrieved alternative setting value should be stored. * * \return A value from the \ref USB_Host_SendControlErrorCodes_t enum to indicate the result. */ uint8_t USB_Host_GetInterfaceAltSetting(const uint8_t InterfaceIndex, uint8_t* const AltSetting) ATTR_NON_NULL_PTR_ARG(2);  Dean Camera committed Nov 24, 2011 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236  /* Inline Functions: */ /** Sends a GET DESCRIPTOR standard request to the attached device, requesting the device descriptor. * This can be used to easily retrieve information about the device such as its VID, PID and power * requirements. This is a convenience wrapper for \ref USB_Host_GetDescriptor(). * * \note After this routine returns, the control pipe will be selected. * * \ingroup Group_PipeControlReq * * \param[out] DeviceDescriptorPtr Pointer to the destination device descriptor structure where * the read data is to be stored. * * \return A value from the \ref USB_Host_SendControlErrorCodes_t enum to indicate the result. */  Dean Camera committed Nov 24, 2011 237  static inline uint8_t USB_Host_GetDeviceDescriptor(USB_Descriptor_Device_t* const DeviceDescriptorPtr) ATTR_NON_NULL_PTR_ARG(1);  Dean Camera committed Nov 24, 2011 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258  static inline uint8_t USB_Host_GetDeviceDescriptor(USB_Descriptor_Device_t* const DeviceDescriptorPtr) { return USB_Host_GetDescriptor(DTYPE_Device, 0, DeviceDescriptorPtr, sizeof(USB_Descriptor_Device_t)); } /** Sends a GET DESCRIPTOR standard request to the attached device, requesting the string descriptor * of the specified index. This can be used to easily retrieve string descriptors from the device by * index, after the index is obtained from the Device or Configuration descriptors. This is a convenience * wrapper for \ref USB_Host_GetDescriptor(). * * \note After this routine returns, the control pipe will be selected. * * \ingroup Group_PipeControlReq * * \param[in] Index Index of the string descriptor to retrieve. * \param[out] Buffer Pointer to the destination buffer where the retrieved string descriptor is * to be stored. * \param[in] BufferLength Maximum size of the string descriptor which can be stored into the buffer. * * \return A value from the \ref USB_Host_SendControlErrorCodes_t enum to indicate the result. */  Dean Camera committed Nov 24, 2011 259 260 261  static inline uint8_t USB_Host_GetDeviceStringDescriptor(const uint8_t Index, void* const Buffer, const uint8_t BufferLength) ATTR_NON_NULL_PTR_ARG(2);  Dean Camera committed Nov 24, 2011 262 263 264 265 266 267 268  static inline uint8_t USB_Host_GetDeviceStringDescriptor(const uint8_t Index, void* const Buffer, const uint8_t BufferLength) { return USB_Host_GetDescriptor(DTYPE_String, Index, Buffer, BufferLength); }  Dean Camera committed May 08, 2010 269 270 271 272 273 274 275 276 277  /* Private Interface - For use in library only: */ #if !defined(__DOXYGEN__) /* Enums: */ enum USB_WaitForTypes_t { USB_HOST_WAITFOR_SetupSent, USB_HOST_WAITFOR_InReceived, USB_HOST_WAITFOR_OutReady, };  278   Dean Camera committed May 08, 2010 279  /* Function Prototypes: */  Dean Camera committed Jul 21, 2010 280  #if defined(__INCLUDE_FROM_HOSTSTDREQ_C)  Dean Camera committed May 08, 2010 281 282 283 284 285 286 287 288  static uint8_t USB_Host_WaitForIOS(const uint8_t WaitType); #endif #endif /* Disable C linkage for C++ Compilers: */ #if defined(__cplusplus) } #endif  289   Dean Camera committed May 08, 2010 290 #endif  291