X-Git-Url: http://git.linex4red.de/pub/USBasp.git/blobdiff_plain/73d9fafc0fe42741ad8f609dd4762e2bc14cbd01..e322f14620a1064efc4b3a98cf701efc48da81cc:/LUFA/Drivers/USB/LowLevel/Pipe.h diff --git a/LUFA/Drivers/USB/LowLevel/Pipe.h b/LUFA/Drivers/USB/LowLevel/Pipe.h index 363b9fd93..3e25d4976 100644 --- a/LUFA/Drivers/USB/LowLevel/Pipe.h +++ b/LUFA/Drivers/USB/LowLevel/Pipe.h @@ -1,21 +1,21 @@ /* LUFA Library - Copyright (C) Dean Camera, 2009. + Copyright (C) Dean Camera, 2010. dean [at] fourwalledcubicle [dot] com www.fourwalledcubicle.com */ /* - Copyright 2009 Dean Camera (dean [at] fourwalledcubicle [dot] com) - - Permission to use, copy, modify, and distribute this software - and its documentation for any purpose and without fee is hereby - granted, provided that the above copyright notice appear in all - copies and that both that the copyright notice and this - 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 + Copyright 2010 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 + without fee, provided that the above copyright notice appear in + all copies and that both that the copyright notice and this + 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 software without specific, written prior permission. The author disclaim all warranties with regard to this @@ -32,7 +32,7 @@ * @defgroup Group_PipeManagement Pipe Management * * This module contains functions, macros and enums related to pipe management when in USB Host mode. This - * module contains the pipe management macros, as well as pipe interrupt and data send/recieve functions + * module contains the pipe management macros, as well as pipe interrupt and data send/receive functions * for various data types. * * @{ @@ -91,6 +91,11 @@ extern "C" { #endif + /* Preprocessor Checks: */ + #if !defined(__INCLUDE_FROM_USB_DRIVER) + #error Do not include this file directly. Include LUFA/Drivers/USB.h instead. + #endif + /* Public Interface - May be used in end-application: */ /* Macros: */ /** Mask for \ref Pipe_GetErrorFlags(), indicating that an overflow error occurred in the pipe on the received data. */ @@ -124,7 +129,7 @@ */ #define PIPE_TOKEN_IN (1 << PTOKEN0) - /** Token mask for \ref Pipe_ConfigurePipe(). This sets the pipe as a IN token (for non-CONTROL type pipes), + /** Token mask for \ref Pipe_ConfigurePipe(). This sets the pipe as a OUT token (for non-CONTROL type pipes), * indicating that the pipe data will flow from host to device. */ #define PIPE_TOKEN_OUT (2 << PTOKEN0) @@ -173,12 +178,12 @@ /** Endpoint number mask, for masking against endpoint addresses to retrieve the endpoint's * numerical address in the attached device. */ - #define PIPE_EPNUM_MASK 0x07 + #define PIPE_EPNUM_MASK 0x0F - /** Endpoint bank size mask, for masking against endpoint addresses to retrieve the endpoint's - * bank size in the attached device. + /** Endpoint direction mask, for masking against endpoint addresses to retrieve the endpoint's + * direction for comparing with the ENDPOINT_DESCRIPTOR_DIR_* masks. */ - #define PIPE_EPSIZE_MASK 0x7FF + #define PIPE_EPDIR_MASK 0x80 /* Pseudo-Function Macros: */ #if defined(__DOXYGEN__) @@ -262,6 +267,13 @@ */ static inline bool Pipe_IsConfigured(void); + /** Retrieves the endpoint number of the endpoint within the attached device that the currently selected + * pipe is bound to. + * + * \return Endpoint number the currently selected pipe is bound to + */ + static inline uint8_t Pipe_BoundEndpointNumber(void); + /** Sets the period between interrupts for an INTERRUPT type pipe to a specified number of milliseconds. * * \param[in] Milliseconds Number of milliseconds between each pipe poll @@ -290,6 +302,12 @@ /** Freezes the selected pipe, preventing it from communicating with an attached device. */ static inline void Pipe_Freeze(void); + /** Determines if the currently selected pipe is frozen, and not able to accept data. + * + * \return Boolean true if the currently selected pipe is frozen, false otherwise + */ + static inline bool Pipe_IsFrozen(void); + /** Clears the master pipe error flag. */ static inline void Pipe_ClearError(void); @@ -412,9 +430,9 @@ #define Pipe_GetCurrentPipe() (UPNUM & PIPE_PIPENUM_MASK) - #define Pipe_SelectPipe(pipenum) MACROS{ UPNUM = pipenum; }MACROE + #define Pipe_SelectPipe(pipenum) MACROS{ UPNUM = (pipenum); }MACROE - #define Pipe_ResetPipe(pipenum) MACROS{ UPRST = (1 << pipenum); UPRST = 0; }MACROE + #define Pipe_ResetPipe(pipenum) MACROS{ UPRST = (1 << (pipenum)); UPRST = 0; }MACROE #define Pipe_EnablePipe() MACROS{ UPCONX |= (1 << PEN); }MACROE @@ -424,23 +442,27 @@ #define Pipe_GetPipeToken() (UPCFG0X & PIPE_TOKEN_MASK) - #define Pipe_SetToken(token) MACROS{ UPCFG0X = ((UPCFG0X & ~PIPE_TOKEN_MASK) | token); }MACROE + #define Pipe_SetPipeToken(token) MACROS{ UPCFG0X = ((UPCFG0X & ~PIPE_TOKEN_MASK) | (token)); }MACROE #define Pipe_SetInfiniteINRequests() MACROS{ UPCONX |= (1 << INMODE); }MACROE - #define Pipe_SetFiniteINRequests(n) MACROS{ UPCONX &= ~(1 << INMODE); UPINRQX = n; }MACROE + #define Pipe_SetFiniteINRequests(n) MACROS{ UPCONX &= ~(1 << INMODE); UPINRQX = (n); }MACROE #define Pipe_IsConfigured() ((UPSTAX & (1 << CFGOK)) ? true : false) - #define Pipe_SetInterruptPeriod(ms) MACROS{ UPCFG2X = ms; }MACROE + #define Pipe_BoundEndpointNumber() ((UPCFG0X >> PEPNUM0) & PIPE_EPNUM_MASK) + + #define Pipe_SetInterruptPeriod(ms) MACROS{ UPCFG2X = (ms); }MACROE #define Pipe_GetPipeInterrupts() UPINT - #define Pipe_HasPipeInterrupted(n) ((UPINT & (1 << n)) ? true : false) + #define Pipe_HasPipeInterrupted(n) ((UPINT & (1 << (n))) ? true : false) #define Pipe_Unfreeze() MACROS{ UPCONX &= ~(1 << PFREEZE); }MACROE #define Pipe_Freeze() MACROS{ UPCONX |= (1 << PFREEZE); }MACROE + + #define Pipe_IsFrozen() ((UPCONX & (1 << PFREEZE)) ? true : false) #define Pipe_ClearError() MACROS{ UPINTX &= ~(1 << PERRI); }MACROE @@ -562,12 +584,16 @@ static inline uint16_t Pipe_Read_Word_LE(void) ATTR_WARN_UNUSED_RESULT ATTR_ALWAYS_INLINE; static inline uint16_t Pipe_Read_Word_LE(void) { - uint16_t Data; + union + { + uint16_t Word; + uint8_t Bytes[2]; + } Data; - Data = UPDATX; - Data |= (((uint16_t)UPDATX) << 8); + Data.Bytes[0] = UPDATX; + Data.Bytes[1] = UPDATX; - return Data; + return Data.Word; } /** Reads two bytes from the currently selected pipe's bank in big endian format, for OUT @@ -580,12 +606,16 @@ static inline uint16_t Pipe_Read_Word_BE(void) ATTR_WARN_UNUSED_RESULT ATTR_ALWAYS_INLINE; static inline uint16_t Pipe_Read_Word_BE(void) { - uint16_t Data; + union + { + uint16_t Word; + uint8_t Bytes[2]; + } Data; - Data = (((uint16_t)UPDATX) << 8); - Data |= UPDATX; + Data.Bytes[1] = UPDATX; + Data.Bytes[0] = UPDATX; - return Data; + return Data.Word; } /** Writes two bytes to the currently selected pipe's bank in little endian format, for IN @@ -687,8 +717,10 @@ static inline void Pipe_Write_DWord_LE(const uint32_t DWord) ATTR_ALWAYS_INLINE; static inline void Pipe_Write_DWord_LE(const uint32_t DWord) { - Pipe_Write_Word_LE(DWord); - Pipe_Write_Word_LE(DWord >> 16); + UPDATX = (DWord & 0xFF); + UPDATX = (DWord >> 8); + UPDATX = (DWord >> 16); + UPDATX = (DWord >> 24); } /** Writes four bytes to the currently selected pipe's bank in big endian format, for IN @@ -701,8 +733,10 @@ static inline void Pipe_Write_DWord_BE(const uint32_t DWord) ATTR_ALWAYS_INLINE; static inline void Pipe_Write_DWord_BE(const uint32_t DWord) { - Pipe_Write_Word_BE(DWord >> 16); - Pipe_Write_Word_BE(DWord); + UPDATX = (DWord >> 24); + UPDATX = (DWord >> 16); + UPDATX = (DWord >> 8); + UPDATX = (DWord & 0xFF); } /** Discards four bytes from the currently selected pipe's bank, for OUT direction pipes. @@ -733,9 +767,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 pipe number with the given pipe type, token, target endpoint number in the @@ -769,14 +803,24 @@ bool Pipe_ConfigurePipe(const uint8_t Number, const uint8_t Type, const uint8_t Token, const uint8_t EndpointNumber, const uint16_t Size, const uint8_t Banks); - /** Spinloops until the currently selected non-control pipe is ready for the next packed of data - * to be read or written to it. + /** Spin-loops until the currently selected non-control pipe is ready for the next packed of data to be read + * or written to it, aborting in the case of an error condition (such as a timeout or device disconnect). * * \ingroup Group_PipeRW * * \return A value from the Pipe_WaitUntilReady_ErrorCodes_t enum. */ - uint8_t Pipe_WaitUntilReady(void); + uint8_t Pipe_WaitUntilReady(void); + + /** Determines if a pipe has been bound to the given device endpoint address. If a pipe which is bound to the given + * endpoint is found, it is automatically selected. + * + * \param[in] EndpointAddress Address and direction mask of the endpoint within the attached device to check + * + * \return Boolean true if a pipe bound to the given endpoint address of the specified direction is found, false + * otherwise + */ + bool Pipe_IsEndpointBound(const uint8_t EndpointAddress); /** Reads and discards the given number of bytes from the pipe, discarding fully read packets from the host * as needed. The last packet is not automatically discarded once the remaining bytes has been read; the @@ -798,7 +842,7 @@ * * \return A value from the \ref Pipe_Stream_RW_ErrorCodes_t enum. */ - uint8_t Pipe_Discard_Stream(uint16_t Length _CALLBACK_PARAM); + uint8_t Pipe_Discard_Stream(uint16_t Length __CALLBACK_PARAM); /** Writes the given number of bytes to the pipe from the given buffer in little endian, * sending full packets to the device as needed. The last packet filled is not automatically sent; @@ -821,9 +865,9 @@ * * \return A value from the \ref Pipe_Stream_RW_ErrorCodes_t enum. */ - uint8_t Pipe_Write_Stream_LE(const void* Buffer, uint16_t Length _CALLBACK_PARAM) ATTR_NON_NULL_PTR_ARG(1); + uint8_t Pipe_Write_Stream_LE(const void* Buffer, uint16_t Length __CALLBACK_PARAM) ATTR_NON_NULL_PTR_ARG(1); - /** EEPROM buffer source version of \ref Pipe_Write_Stream_LE. + /** EEPROM buffer source version of \ref Pipe_Write_Stream_LE(). * * \ingroup Group_PipeStreamRW * @@ -833,9 +877,9 @@ * * \return A value from the \ref Pipe_Stream_RW_ErrorCodes_t enum. */ - uint8_t Pipe_Write_EStream_LE(const void* Buffer, uint16_t Length _CALLBACK_PARAM) ATTR_NON_NULL_PTR_ARG(1); + uint8_t Pipe_Write_EStream_LE(const void* Buffer, uint16_t Length __CALLBACK_PARAM) ATTR_NON_NULL_PTR_ARG(1); - /** FLASH buffer source version of \ref Pipe_Write_Stream_LE. + /** FLASH buffer source version of \ref Pipe_Write_Stream_LE(). * * \note The FLASH data must be located in the first 64KB of FLASH for this function to work correctly. * @@ -847,7 +891,7 @@ * * \return A value from the \ref Pipe_Stream_RW_ErrorCodes_t enum. */ - uint8_t Pipe_Write_PStream_LE(const void* Buffer, uint16_t Length _CALLBACK_PARAM) ATTR_NON_NULL_PTR_ARG(1); + uint8_t Pipe_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 pipe from the given buffer in big endian, * sending full packets to the device as needed. The last packet filled is not automatically sent; @@ -870,9 +914,9 @@ * * \return A value from the \ref Pipe_Stream_RW_ErrorCodes_t enum. */ - uint8_t Pipe_Write_Stream_BE(const void* Buffer, uint16_t Length _CALLBACK_PARAM) ATTR_NON_NULL_PTR_ARG(1); + uint8_t Pipe_Write_Stream_BE(const void* Buffer, uint16_t Length __CALLBACK_PARAM) ATTR_NON_NULL_PTR_ARG(1); - /** EEPROM buffer source version of \ref Pipe_Write_Stream_BE. + /** EEPROM buffer source version of \ref Pipe_Write_Stream_BE(). * * \ingroup Group_PipeStreamRW * @@ -882,9 +926,9 @@ * * \return A value from the \ref Pipe_Stream_RW_ErrorCodes_t enum. */ - uint8_t Pipe_Write_EStream_BE(const void* Buffer, uint16_t Length _CALLBACK_PARAM) ATTR_NON_NULL_PTR_ARG(1); + uint8_t Pipe_Write_EStream_BE(const void* Buffer, uint16_t Length __CALLBACK_PARAM) ATTR_NON_NULL_PTR_ARG(1); - /** FLASH buffer source version of \ref Pipe_Write_Stream_BE. + /** FLASH buffer source version of \ref Pipe_Write_Stream_BE(). * * \note The FLASH data must be located in the first 64KB of FLASH for this function to work correctly. * @@ -896,7 +940,7 @@ * * \return A value from the \ref Pipe_Stream_RW_ErrorCodes_t enum. */ - uint8_t Pipe_Write_PStream_BE(const void* Buffer, uint16_t Length _CALLBACK_PARAM) ATTR_NON_NULL_PTR_ARG(1); + uint8_t Pipe_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 pipe into the given buffer in little endian, * sending full packets to the device as needed. The last packet filled is not automatically sent; @@ -913,25 +957,25 @@ * * \ingroup Group_PipeStreamRW * - * \param[out] Buffer Pointer to the source data buffer to write to. + * \param[out] Buffer Pointer to the source data buffer to write to. * \param[in] Length Number of bytes to read for the currently selected pipe to read from. * \param[in] Callback Name of a callback routine to call between successive USB packet transfers, NULL if no callback * * \return A value from the \ref Pipe_Stream_RW_ErrorCodes_t enum. */ - uint8_t Pipe_Read_Stream_LE(void* Buffer, uint16_t Length _CALLBACK_PARAM) ATTR_NON_NULL_PTR_ARG(1); + uint8_t Pipe_Read_Stream_LE(void* Buffer, uint16_t Length __CALLBACK_PARAM) ATTR_NON_NULL_PTR_ARG(1); - /** EEPROM buffer source version of \ref Pipe_Read_Stream_LE. + /** EEPROM buffer source version of \ref Pipe_Read_Stream_LE(). * * \ingroup Group_PipeStreamRW * - * \param[out] Buffer Pointer to the source data buffer to write to. + * \param[out] Buffer Pointer to the source data buffer to write to. * \param[in] Length Number of bytes to read for the currently selected pipe to read from. * \param[in] Callback Name of a callback routine to call between successive USB packet transfers, NULL if no callback * * \return A value from the \ref Pipe_Stream_RW_ErrorCodes_t enum. */ - uint8_t Pipe_Read_EStream_LE(void* Buffer, uint16_t Length _CALLBACK_PARAM) ATTR_NON_NULL_PTR_ARG(1); + uint8_t Pipe_Read_EStream_LE(void* Buffer, uint16_t Length __CALLBACK_PARAM) ATTR_NON_NULL_PTR_ARG(1); /** Reads the given number of bytes from the pipe into the given buffer in big endian, * sending full packets to the device as needed. The last packet filled is not automatically sent; @@ -948,25 +992,25 @@ * * \ingroup Group_PipeStreamRW * - * \param[out] Buffer Pointer to the source data buffer to write to. + * \param[out] Buffer Pointer to the source data buffer to write to. * \param[in] Length Number of bytes to read for the currently selected pipe to read from. * \param[in] Callback Name of a callback routine to call between successive USB packet transfers, NULL if no callback * * \return A value from the \ref Pipe_Stream_RW_ErrorCodes_t enum. */ - uint8_t Pipe_Read_Stream_BE(void* Buffer, uint16_t Length _CALLBACK_PARAM) ATTR_NON_NULL_PTR_ARG(1); + uint8_t Pipe_Read_Stream_BE(void* Buffer, uint16_t Length __CALLBACK_PARAM) ATTR_NON_NULL_PTR_ARG(1); - /** EEPROM buffer source version of \ref Pipe_Read_Stream_BE. + /** EEPROM buffer source version of \ref Pipe_Read_Stream_BE(). * * \ingroup Group_PipeStreamRW * - * \param[out] Buffer Pointer to the source data buffer to write to. + * \param[out] Buffer Pointer to the source data buffer to write to. * \param[in] Length Number of bytes to read for the currently selected pipe to read from. * \param[in] Callback Name of a callback routine to call between successive USB packet transfers, NULL if no callback * * \return A value from the \ref Pipe_Stream_RW_ErrorCodes_t enum. */ - uint8_t Pipe_Read_EStream_BE(void* Buffer, uint16_t Length _CALLBACK_PARAM) ATTR_NON_NULL_PTR_ARG(1); + uint8_t Pipe_Read_EStream_BE(void* Buffer, uint16_t Length __CALLBACK_PARAM) ATTR_NON_NULL_PTR_ARG(1); /* Private Interface - For use in library only: */ #if !defined(__DOXYGEN__) @@ -999,7 +1043,7 @@ return (4 << EPSIZE0); else return (5 << EPSIZE0); - }; + } #endif