2 * @brief USB host standard request management
\r
5 * Copyright(C) NXP Semiconductors, 2012
\r
6 * Copyright(C) Dean Camera, 2011, 2012
\r
7 * All rights reserved.
\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
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
33 #ifndef __HOSTSTDREQ_H__
\r
34 #define __HOSTSTDREQ_H__
\r
37 #include "../../../Common/Common.h"
\r
38 #include "USBMode.h"
\r
39 #include "StdRequestType.h"
\r
40 #include "USBController.h"
\r
42 /* Enable C linkage for C++ Compilers: */
\r
43 #if defined(__cplusplus)
\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
52 /* Public Interface - May be used in end-application: */
\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
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
62 #define USB_HOST_TIMEOUT_MS 1000
\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
69 * @ingroup Group_PipeControlReq
\r
71 enum USB_Host_SendControlErrorCodes_t
\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
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
81 HOST_SENDCONTROL_SoftwareTimeOut = 4, /**< The request or data transfer timed out. */
\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
88 * To set a device configuration, call the @ref USB_Host_SetDeviceConfiguration() function.
\r
90 * @note This variable should be treated as read-only in the user application, and never manually
\r
93 * @ingroup Group_Host
\r
95 extern uint8_t USB_Host_ConfigurationNumber;
\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
102 * @ingroup Group_PipeControlReq
\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
108 * @return A value from the @ref USB_Host_SendControlErrorCodes_t enum to indicate the result.
\r
110 uint8_t USB_Host_SendControlRequest(const uint8_t corenum, void* const BufferPtr);
\r
112 /** @brief Sends a SET CONFIGURATION standard request to the attached device, with the given configuration index.
\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
117 * @note After this routine returns, the control pipe will be selected.
\r
119 * @ingroup Group_PipeControlReq
\r
121 * @param corenum : USB port number
\r
122 * @param ConfigNumber : Configuration index to send to the device.
\r
124 * @return A value from the @ref USB_Host_SendControlErrorCodes_t enum to indicate the result.
\r
126 uint8_t USB_Host_SetDeviceConfiguration(const uint8_t corenum, const uint8_t ConfigNumber);
\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
132 * @note After this routine returns, the control pipe will be selected.
\r
134 * @ingroup Group_PipeControlReq
\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
140 * @return A value from the @ref USB_Host_SendControlErrorCodes_t enum to indicate the result.
\r
142 uint8_t USB_Host_GetDeviceDescriptor(const uint8_t corenum, void* const DeviceDescriptorPtr) ATTR_NON_NULL_PTR_ARG(2);
\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
148 * @note After this routine returns, the control pipe will be selected.
\r
150 * @ingroup Group_PipeControlReq
\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
156 * @param BufferLength : Maximum size of the string descriptor which can be stored into the buffer.
\r
158 * @return A value from the @ref USB_Host_SendControlErrorCodes_t enum to indicate the result.
\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
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
169 * @note After this routine returns, the control pipe will be selected.
\r
171 * @ingroup Group_PipeControlReq
\r
173 * @param corenum : USB port number
\r
174 * @param FeatureStatus : Location where the retrieved feature status should be stored.
\r
176 * @return A value from the @ref USB_Host_SendControlErrorCodes_t enum to indicate the result.
\r
178 uint8_t USB_Host_GetDeviceStatus(const uint8_t corenum, uint8_t* const FeatureStatus) ATTR_NON_NULL_PTR_ARG(2);
\r
180 /** @brief Clears a stall condition on the given pipe, via a CLEAR FEATURE standard request to the attached device.
\r
182 * @note After this routine returns, the control pipe will be selected.
\r
184 * @ingroup Group_PipeControlReq
\r
186 * @param corenum : USB port number
\r
187 * @param EndpointAddress : Address of the endpoint to clear, including the endpoint's direction.
\r
189 * @return A value from the @ref USB_Host_SendControlErrorCodes_t enum to indicate the result.
\r
191 uint8_t USB_Host_ClearEndpointStall(const uint8_t corenum, const uint8_t EndpointAddress);
\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
196 * @note After this routine returns, the control pipe will be selected.
\r
198 * @ingroup Group_PipeControlReq
\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
204 * @return A value from the @ref USB_Host_SendControlErrorCodes_t enum to indicate the result.
\r
206 uint8_t USB_Host_SetInterfaceAltSetting(const uint8_t corenum,
\r
207 const uint8_t InterfaceIndex,
\r
208 const uint8_t AltSetting);
\r
210 /* Private Interface - For use in library only: */
\r
211 #if !defined(__DOXYGEN__)
\r
213 enum USB_WaitForTypes_t
\r
215 USB_HOST_WAITFOR_SetupSent,
\r
216 USB_HOST_WAITFOR_InReceived,
\r
217 USB_HOST_WAITFOR_OutReady,
\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
226 /* Disable C linkage for C++ Compilers: */
\r
227 #if defined(__cplusplus)
\r
projects / freertos / blob