X-Git-Url: http://git.linex4red.de/pub/USBasp.git/blobdiff_plain/73d9fafc0fe42741ad8f609dd4762e2bc14cbd01..cf610c5c91c3eee02dec7ca848acc8da831ad98a:/LUFA/Drivers/USB/LowLevel/Endpoint.h diff --git a/LUFA/Drivers/USB/LowLevel/Endpoint.h b/LUFA/Drivers/USB/LowLevel/Endpoint.h index 2caea8343..4dfa1ef9b 100644 --- a/LUFA/Drivers/USB/LowLevel/Endpoint.h +++ b/LUFA/Drivers/USB/LowLevel/Endpoint.h @@ -33,7 +33,7 @@ * * Functions, macros and enums related to endpoint management when in USB Device mode. This * module contains the endpoint management macros, as well as endpoint interrupt and data - * send/recieve functions for various data types. + * send/receive functions for various data types. * * @{ */ @@ -331,6 +331,12 @@ * \return The currently selected endpoint's direction, as a ENDPOINT_DIR_* mask. */ static inline uint8_t Endpoint_GetEndpointDirection(void); + + /** Sets the direction of the currently selected endpoint. + * + * \param[in] DirectionMask New endpoint direction, as a ENDPOINT_DIR_* mask. + */ + static inline void Endpoint_SetEndpointDirection(uint8_t DirectionMask); #else #if defined(USB_SERIES_4_AVR) || defined(USB_SERIES_6_AVR) || defined(USB_SERIES_7_AVR) || defined(__DOXYGEN__) #define Endpoint_BytesInEndpoint() UEBCX @@ -399,6 +405,8 @@ #define Endpoint_ResetDataToggle() MACROS{ UECONX |= (1 << RSTDT); }MACROE #define Endpoint_GetEndpointDirection() (UECFG0X & ENDPOINT_DIR_IN) + + #define Endpoint_SetEndpointDirection(dir) MACROS{ UECFG0X = ((UECFG0X & ~ENDPOINT_DIR_IN) | dir); }MACROE #endif /* Enums: */ @@ -431,14 +439,14 @@ ENDPOINT_RWSTREAM_EndpointStalled = 1, /**< The endpoint was stalled during the stream * transfer by the host or device. */ - ENDPOINT_RWSTREAM_DeviceDisconnected = 1, /**< Device was disconnected from the host during + ENDPOINT_RWSTREAM_DeviceDisconnected = 2, /**< Device was disconnected from the host during * the transfer. */ - ENDPOINT_RWSTREAM_Timeout = 2, /**< The host failed to accept or send the next packet + ENDPOINT_RWSTREAM_Timeout = 3, /**< The host failed to accept or send the next packet * within the software timeout period set by the * \ref USB_STREAM_TIMEOUT_MS macro. */ - ENDPOINT_RWSTREAM_CallbackAborted = 3, /**< Indicates that the stream's callback function + ENDPOINT_RWSTREAM_CallbackAborted = 4, /**< Indicates that the stream's callback function * aborted the transfer early. */ }; @@ -451,6 +459,9 @@ { ENDPOINT_RWCSTREAM_NoError = 0, /**< Command completed successfully, no error. */ ENDPOINT_RWCSTREAM_HostAborted = 1, /**< The aborted the transfer prematurely. */ + ENDPOINT_RWCSTREAM_DeviceDisconnected = 2, /**< Device was disconnected from the host during + * the transfer. + */ }; /* Inline Functions: */ @@ -500,12 +511,16 @@ static inline uint16_t Endpoint_Read_Word_LE(void) ATTR_WARN_UNUSED_RESULT ATTR_ALWAYS_INLINE; static inline uint16_t Endpoint_Read_Word_LE(void) { - uint16_t Data; + union + { + uint16_t Word; + uint8_t Bytes[2]; + } Data; - Data = UEDATX; - Data |= (((uint16_t)UEDATX) << 8); + Data.Bytes[0] = UEDATX; + Data.Bytes[1] = UEDATX; - return Data; + return Data.Word; } /** Reads two bytes from the currently selected endpoint's bank in big endian format, for OUT @@ -518,12 +533,16 @@ static inline uint16_t Endpoint_Read_Word_BE(void) ATTR_WARN_UNUSED_RESULT ATTR_ALWAYS_INLINE; static inline uint16_t Endpoint_Read_Word_BE(void) { - uint16_t Data; + union + { + uint16_t Word; + uint8_t Bytes[2]; + } Data; - Data = (((uint16_t)UEDATX) << 8); - Data |= UEDATX; + Data.Bytes[1] = UEDATX; + Data.Bytes[0] = UEDATX; - return Data; + return Data.Word; } /** Writes two bytes to the currently selected endpoint's bank in little endian format, for IN @@ -686,9 +705,9 @@ /* Function Prototypes: */ #if !defined(NO_STREAM_CALLBACKS) || defined(__DOXYGEN__) - #define _CALLBACK_PARAM , StreamCallbackPtr_t Callback + #define __CALLBACK_PARAM , StreamCallbackPtr_t Callback #else - #define _CALLBACK_PARAM + #define __CALLBACK_PARAM #endif /** Configures the specified endpoint number with the given endpoint type, direction, bank size @@ -726,6 +745,12 @@ * \return A value from the \ref Endpoint_WaitUntilReady_ErrorCodes_t enum. */ uint8_t Endpoint_WaitUntilReady(void); + + /** Completes the status stage of a control transfer on a CONTROL type endpoint automatically, + * with respect to the data direction. This is a convenience function which can be used to + * simplify user control request handling. + */ + void Endpoint_ClearStatusStage(void); /** Reads and discards the given number of bytes from the endpoint from the given buffer, * discarding fully read packets from the host as needed. The last packet is not automatically @@ -747,7 +772,7 @@ * * \return A value from the \ref Endpoint_Stream_RW_ErrorCodes_t enum. */ - uint8_t Endpoint_Discard_Stream(uint16_t Length _CALLBACK_PARAM); + uint8_t Endpoint_Discard_Stream(uint16_t Length __CALLBACK_PARAM); /** Writes the given number of bytes to the endpoint from the given buffer in little endian, * sending full packets to the host as needed. The last packet filled is not automatically sent; @@ -770,9 +795,9 @@ * * \return A value from the \ref Endpoint_Stream_RW_ErrorCodes_t enum. */ - uint8_t Endpoint_Write_Stream_LE(void* Buffer, uint16_t Length _CALLBACK_PARAM) ATTR_NON_NULL_PTR_ARG(1); + uint8_t Endpoint_Write_Stream_LE(const void* Buffer, uint16_t Length __CALLBACK_PARAM) ATTR_NON_NULL_PTR_ARG(1); - /** EEPROM buffer source version of \ref Endpoint_Write_Stream_LE. + /** EEPROM buffer source version of \ref Endpoint_Write_Stream_LE(). * * \ingroup Group_EndpointStreamRW * @@ -782,9 +807,9 @@ * * \return A value from the \ref Endpoint_Stream_RW_ErrorCodes_t enum. */ - uint8_t Endpoint_Write_EStream_LE(void* Buffer, uint16_t Length _CALLBACK_PARAM) ATTR_NON_NULL_PTR_ARG(1); + uint8_t Endpoint_Write_EStream_LE(const void* Buffer, uint16_t Length __CALLBACK_PARAM) ATTR_NON_NULL_PTR_ARG(1); - /** FLASH buffer source version of \ref Endpoint_Write_Stream_LE. + /** FLASH buffer source version of \ref Endpoint_Write_Stream_LE(). * * \note The FLASH data must be located in the first 64KB of FLASH for this function to work correctly. * @@ -796,7 +821,7 @@ * * \return A value from the \ref Endpoint_Stream_RW_ErrorCodes_t enum. */ - uint8_t Endpoint_Write_PStream_LE(void* Buffer, uint16_t Length _CALLBACK_PARAM) ATTR_NON_NULL_PTR_ARG(1); + uint8_t Endpoint_Write_PStream_LE(const void* Buffer, uint16_t Length __CALLBACK_PARAM) ATTR_NON_NULL_PTR_ARG(1); /** Writes the given number of bytes to the endpoint from the given buffer in big endian, * sending full packets to the host as needed. The last packet filled is not automatically sent; @@ -819,9 +844,9 @@ * * \return A value from the \ref Endpoint_Stream_RW_ErrorCodes_t enum. */ - uint8_t Endpoint_Write_Stream_BE(void* Buffer, uint16_t Length _CALLBACK_PARAM) ATTR_NON_NULL_PTR_ARG(1); + uint8_t Endpoint_Write_Stream_BE(const void* Buffer, uint16_t Length __CALLBACK_PARAM) ATTR_NON_NULL_PTR_ARG(1); - /** EEPROM buffer source version of \ref Endpoint_Write_Stream_BE. + /** EEPROM buffer source version of \ref Endpoint_Write_Stream_BE(). * * \ingroup Group_EndpointStreamRW * @@ -831,9 +856,9 @@ * * \return A value from the \ref Endpoint_Stream_RW_ErrorCodes_t enum. */ - uint8_t Endpoint_Write_EStream_BE(void* Buffer, uint16_t Length _CALLBACK_PARAM) ATTR_NON_NULL_PTR_ARG(1); + uint8_t Endpoint_Write_EStream_BE(const void* Buffer, uint16_t Length __CALLBACK_PARAM) ATTR_NON_NULL_PTR_ARG(1); - /** FLASH buffer source version of \ref Endpoint_Write_Stream_BE. + /** FLASH buffer source version of \ref Endpoint_Write_Stream_BE(). * * \note The FLASH data must be located in the first 64KB of FLASH for this function to work correctly. * @@ -845,7 +870,7 @@ * * \return A value from the \ref Endpoint_Stream_RW_ErrorCodes_t enum. */ - uint8_t Endpoint_Write_PStream_BE(void* Buffer, uint16_t Length _CALLBACK_PARAM) ATTR_NON_NULL_PTR_ARG(1); + uint8_t Endpoint_Write_PStream_BE(const void* Buffer, uint16_t Length __CALLBACK_PARAM) ATTR_NON_NULL_PTR_ARG(1); /** Reads the given number of bytes from the endpoint from the given buffer in little endian, * discarding fully read packets from the host as needed. The last packet is not automatically @@ -868,9 +893,9 @@ * * \return A value from the \ref Endpoint_Stream_RW_ErrorCodes_t enum. */ - uint8_t Endpoint_Read_Stream_LE(void* Buffer, uint16_t Length _CALLBACK_PARAM) ATTR_NON_NULL_PTR_ARG(1); + uint8_t Endpoint_Read_Stream_LE(void* Buffer, uint16_t Length __CALLBACK_PARAM) ATTR_NON_NULL_PTR_ARG(1); - /** EEPROM buffer source version of \ref Endpoint_Read_Stream_LE. + /** EEPROM buffer source version of \ref Endpoint_Read_Stream_LE(). * * \ingroup Group_EndpointStreamRW * @@ -880,7 +905,7 @@ * * \return A value from the \ref Endpoint_Stream_RW_ErrorCodes_t enum. */ - uint8_t Endpoint_Read_EStream_LE(void* Buffer, uint16_t Length _CALLBACK_PARAM) ATTR_NON_NULL_PTR_ARG(1); + uint8_t Endpoint_Read_EStream_LE(void* Buffer, uint16_t Length __CALLBACK_PARAM) ATTR_NON_NULL_PTR_ARG(1); /** Reads the given number of bytes from the endpoint from the given buffer in big endian, * discarding fully read packets from the host as needed. The last packet is not automatically @@ -903,9 +928,9 @@ * * \return A value from the \ref Endpoint_Stream_RW_ErrorCodes_t enum. */ - uint8_t Endpoint_Read_Stream_BE(void* Buffer, uint16_t Length _CALLBACK_PARAM) ATTR_NON_NULL_PTR_ARG(1); + uint8_t Endpoint_Read_Stream_BE(void* Buffer, uint16_t Length __CALLBACK_PARAM) ATTR_NON_NULL_PTR_ARG(1); - /** EEPROM buffer source version of \ref Endpoint_Read_Stream_BE. + /** EEPROM buffer source version of \ref Endpoint_Read_Stream_BE(). * * \ingroup Group_EndpointStreamRW * @@ -915,13 +940,16 @@ * * \return A value from the \ref Endpoint_Stream_RW_ErrorCodes_t enum. */ - uint8_t Endpoint_Read_EStream_BE(void* Buffer, uint16_t Length _CALLBACK_PARAM) ATTR_NON_NULL_PTR_ARG(1); + uint8_t Endpoint_Read_EStream_BE(void* Buffer, uint16_t Length __CALLBACK_PARAM) ATTR_NON_NULL_PTR_ARG(1); /** Writes the given number of bytes to the CONTROL type endpoint from the given buffer in little endian, * sending full packets to the host as needed. The host OUT acknowledgement is not automatically cleared * in both failure and success states; the user is responsible for manually clearing the setup OUT to * finalize the transfer via the \ref Endpoint_ClearOUT() macro. * + * \note This function automatically clears the control transfer's status stage. Do not manually attempt + * to clear the status stage when using this routine in a control transaction. + * * \note This routine should only be used on CONTROL type endpoints. * * \warning Unlike the standard stream read/write commands, the control stream commands cannot be chained @@ -934,10 +962,13 @@ * * \return A value from the \ref Endpoint_ControlStream_RW_ErrorCodes_t enum. */ - uint8_t Endpoint_Write_Control_Stream_LE(void* Buffer, uint16_t Length) ATTR_NON_NULL_PTR_ARG(1); + uint8_t Endpoint_Write_Control_Stream_LE(const void* Buffer, uint16_t Length) ATTR_NON_NULL_PTR_ARG(1); /** EEPROM buffer source version of Endpoint_Write_Control_Stream_LE. * + * \note This function automatically clears the control transfer's status stage. Do not manually attempt + * to clear the status stage when using this routine in a control transaction. + * * \note This routine should only be used on CONTROL type endpoints. * * \warning Unlike the standard stream read/write commands, the control stream commands cannot be chained @@ -950,9 +981,12 @@ * * \return A value from the \ref Endpoint_ControlStream_RW_ErrorCodes_t enum. */ - uint8_t Endpoint_Write_Control_EStream_LE(void* Buffer, uint16_t Length) ATTR_NON_NULL_PTR_ARG(1); + uint8_t Endpoint_Write_Control_EStream_LE(const void* Buffer, uint16_t Length) ATTR_NON_NULL_PTR_ARG(1); - /** FLASH buffer source version of \ref Endpoint_Write_Control_Stream_LE. + /** FLASH buffer source version of \ref Endpoint_Write_Control_Stream_LE(). + * + * \note This function automatically clears the control transfer's status stage. Do not manually attempt + * to clear the status stage when using this routine in a control transaction. * * \note The FLASH data must be located in the first 64KB of FLASH for this function to work correctly. * @@ -968,13 +1002,16 @@ * * \return A value from the \ref Endpoint_ControlStream_RW_ErrorCodes_t enum. */ - uint8_t Endpoint_Write_Control_PStream_LE(void* Buffer, uint16_t Length) ATTR_NON_NULL_PTR_ARG(1); + uint8_t Endpoint_Write_Control_PStream_LE(const void* Buffer, uint16_t Length) ATTR_NON_NULL_PTR_ARG(1); /** Writes the given number of bytes to the CONTROL type endpoint from the given buffer in big endian, * sending full packets to the host as needed. The host OUT acknowledgement is not automatically cleared * in both failure and success states; the user is responsible for manually clearing the setup OUT to * finalize the transfer via the \ref Endpoint_ClearOUT() macro. * + * \note This function automatically clears the control transfer's status stage. Do not manually attempt + * to clear the status stage when using this routine in a control transaction. + * * \note This routine should only be used on CONTROL type endpoints. * * \warning Unlike the standard stream read/write commands, the control stream commands cannot be chained @@ -987,9 +1024,12 @@ * * \return A value from the \ref Endpoint_ControlStream_RW_ErrorCodes_t enum. */ - uint8_t Endpoint_Write_Control_Stream_BE(void* Buffer, uint16_t Length) ATTR_NON_NULL_PTR_ARG(1); + uint8_t Endpoint_Write_Control_Stream_BE(const void* Buffer, uint16_t Length) ATTR_NON_NULL_PTR_ARG(1); - /** EEPROM buffer source version of \ref Endpoint_Write_Control_Stream_BE. + /** EEPROM buffer source version of \ref Endpoint_Write_Control_Stream_BE(). + * + * \note This function automatically clears the control transfer's status stage. Do not manually attempt + * to clear the status stage when using this routine in a control transaction. * * \note This routine should only be used on CONTROL type endpoints. * @@ -1003,9 +1043,12 @@ * * \return A value from the \ref Endpoint_ControlStream_RW_ErrorCodes_t enum. */ - uint8_t Endpoint_Write_Control_EStream_BE(void* Buffer, uint16_t Length) ATTR_NON_NULL_PTR_ARG(1); + uint8_t Endpoint_Write_Control_EStream_BE(const void* Buffer, uint16_t Length) ATTR_NON_NULL_PTR_ARG(1); - /** FLASH buffer source version of \ref Endpoint_Write_Control_Stream_BE. + /** FLASH buffer source version of \ref Endpoint_Write_Control_Stream_BE(). + * + * \note This function automatically clears the control transfer's status stage. Do not manually attempt + * to clear the status stage when using this routine in a control transaction. * * \note The FLASH data must be located in the first 64KB of FLASH for this function to work correctly. * @@ -1021,13 +1064,16 @@ * * \return A value from the \ref Endpoint_ControlStream_RW_ErrorCodes_t enum. */ - uint8_t Endpoint_Write_Control_PStream_BE(void* Buffer, uint16_t Length) ATTR_NON_NULL_PTR_ARG(1); + uint8_t Endpoint_Write_Control_PStream_BE(const void* Buffer, uint16_t Length) ATTR_NON_NULL_PTR_ARG(1); /** Reads the given number of bytes from the CONTROL endpoint from the given buffer in little endian, * discarding fully read packets from the host as needed. The device IN acknowledgement is not * automatically sent after success or failure states; the user is responsible for manually sending the * setup IN to finalize the transfer via the \ref Endpoint_ClearIN() macro. * + * \note This function automatically clears the control transfer's status stage. Do not manually attempt + * to clear the status stage when using this routine in a control transaction. + * * \note This routine should only be used on CONTROL type endpoints. * * \warning Unlike the standard stream read/write commands, the control stream commands cannot be chained @@ -1042,7 +1088,10 @@ */ uint8_t Endpoint_Read_Control_Stream_LE(void* Buffer, uint16_t Length) ATTR_NON_NULL_PTR_ARG(1); - /** EEPROM buffer source version of \ref Endpoint_Read_Control_Stream_LE. + /** EEPROM buffer source version of \ref Endpoint_Read_Control_Stream_LE(). + * + * \note This function automatically clears the control transfer's status stage. Do not manually attempt + * to clear the status stage when using this routine in a control transaction. * * \note This routine should only be used on CONTROL type endpoints. * @@ -1063,6 +1112,9 @@ * automatically sent after success or failure states; the user is responsible for manually sending the * setup IN to finalize the transfer via the \ref Endpoint_ClearIN() macro. * + * \note This function automatically clears the control transfer's status stage. Do not manually attempt + * to clear the status stage when using this routine in a control transaction. + * * \note This routine should only be used on CONTROL type endpoints. * * \warning Unlike the standard stream read/write commands, the control stream commands cannot be chained @@ -1077,7 +1129,10 @@ */ uint8_t Endpoint_Read_Control_Stream_BE(void* Buffer, uint16_t Length) ATTR_NON_NULL_PTR_ARG(1); - /** EEPROM buffer source version of \ref Endpoint_Read_Control_Stream_BE. + /** EEPROM buffer source version of \ref Endpoint_Read_Control_Stream_BE(). + * + * \note This function automatically clears the control transfer's status stage. Do not manually attempt + * to clear the status stage when using this routine in a control transaction. * * \note This routine should only be used on CONTROL type endpoints. *