X-Git-Url: http://git.linex4red.de/pub/USBasp.git/blobdiff_plain/137ce280c1e9c33e9393f1dfd6bb160c131bd1a4..0da99447d3e88e83f9977501bee56af5c7aa56c0:/LUFA/Drivers/USB/Core/HostStandardReq.h diff --git a/LUFA/Drivers/USB/Core/HostStandardReq.h b/LUFA/Drivers/USB/Core/HostStandardReq.h index b74aa3a3e..6ad0d2e58 100644 --- a/LUFA/Drivers/USB/Core/HostStandardReq.h +++ b/LUFA/Drivers/USB/Core/HostStandardReq.h @@ -1,13 +1,13 @@ /* LUFA Library - Copyright (C) Dean Camera, 2011. + Copyright (C) Dean Camera, 2012. dean [at] fourwalledcubicle [dot] com www.lufa-lib.org */ /* - Copyright 2011 Dean Camera (dean [at] fourwalledcubicle [dot] com) + Copyright 2012 Dean Camera (dean [at] fourwalledcubicle [dot] com) Permission to use, copy, modify, distribute, and sell this software and its documentation for any purpose is hereby granted @@ -58,6 +58,18 @@ #endif /* Public Interface - May be used in end-application: */ + /* 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 + /* Enums: */ /** Enum for the \ref USB_Host_SendControlRequest() return code, indicating the reason for the error * if the transfer of the request is unsuccessful. @@ -68,28 +80,28 @@ { HOST_SENDCONTROL_Successful = 0, /**< No error occurred in the request transfer. */ HOST_SENDCONTROL_DeviceDisconnected = 1, /**< The attached device was disconnected during the - * request transfer. + * request transfer. */ 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 - * indicating that the request is unsupported on the device. - */ + * indicating that the request is unsupported on the device. + */ HOST_SENDCONTROL_SoftwareTimeOut = 4, /**< The request or data transfer timed out. */ }; /* 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. + * selected configuration value if one has been set successfully, 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. + * \attention 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; - + /* 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 @@ -104,9 +116,7 @@ */ uint8_t USB_Host_SendControlRequest(void* const BufferPtr); - /** Convenience function. This routine sends a SET CONFIGURATION standard request to the attached - * device, with the given configuration index. This can be used to easily set the device - * configuration without creating and sending the request manually. + /** Sends a SET CONFIGURATION standard request to the attached device, with the given configuration index. * * 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. @@ -121,40 +131,51 @@ */ uint8_t USB_Host_SetDeviceConfiguration(const uint8_t ConfigNumber); - /** Convenience function. This routine 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. + /** 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] DeviceDescriptorPtr Pointer to the destination device descriptor structure where - * the read data is to be stored. + * \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_GetDeviceDescriptor(void* const DeviceDescriptorPtr); + uint8_t USB_Host_GetDeviceConfiguration(uint8_t* const ConfigNumber) ATTR_NON_NULL_PTR_ARG(1); - /** Convenience function. This routine 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. + /** Sends a GET DESCRIPTOR standard request to the attached device, requesting the descriptor of the + * specified type and index. * * \note After this routine returns, the control pipe will be selected. * * \ingroup Group_PipeControlReq * - * \param[in] Index Index of the string index 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. + * \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. + * + * \return A value from the \ref USB_Host_SendControlErrorCodes_t enum to indicate the result. + */ + 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); + + /** 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 + * \c 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. */ - uint8_t USB_Host_GetDeviceStringDescriptor(const uint8_t Index, - void* const Buffer, - const uint8_t BufferLength); + uint8_t USB_Host_GetDeviceStatus(uint8_t* const FeatureStatus) ATTR_NON_NULL_PTR_ARG(1); /** Clears a stall condition on the given pipe, via a CLEAR FEATURE standard request to the attached device. * @@ -162,11 +183,11 @@ * * \ingroup Group_PipeControlReq * - * \param[in] EndpointIndex Index of the endpoint to clear, including the endpoint's direction. + * \param[in] EndpointAddress Address of the endpoint to clear, including the endpoint's direction. * * \return A value from the \ref USB_Host_SendControlErrorCodes_t enum to indicate the result. */ - uint8_t USB_Host_ClearPipeStall(const uint8_t EndpointIndex); + uint8_t USB_Host_ClearEndpointStall(const uint8_t EndpointAddress); /** Selects a given alternative setting for the specified interface, via a SET INTERFACE standard request to * the attached device. @@ -181,7 +202,69 @@ * \return A value from the \ref USB_Host_SendControlErrorCodes_t enum to indicate the result. */ uint8_t USB_Host_SetInterfaceAltSetting(const uint8_t InterfaceIndex, - const uint8_t AltSetting); + const uint8_t AltSetting); + + + /** 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); + + /* 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. + */ + static inline uint8_t USB_Host_GetDeviceDescriptor(USB_Descriptor_Device_t* const DeviceDescriptorPtr) ATTR_NON_NULL_PTR_ARG(1); + 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. + */ + static inline uint8_t USB_Host_GetDeviceStringDescriptor(const uint8_t Index, + void* const Buffer, + const uint8_t BufferLength) ATTR_NON_NULL_PTR_ARG(2); + 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); + } /* Private Interface - For use in library only: */ #if !defined(__DOXYGEN__) @@ -195,6 +278,7 @@ /* Function Prototypes: */ #if defined(__INCLUDE_FROM_HOSTSTDREQ_C) + static uint8_t USB_Host_SendControlRequest_PRV(void* const BufferPtr); static uint8_t USB_Host_WaitForIOS(const uint8_t WaitType); #endif #endif