X-Git-Url: http://git.linex4red.de/pub/USBasp.git/blobdiff_plain/a3a04aa6719a891a1350179d5ac451c3e18c3bf2..abc7dce10c03bcbc9659e1a9643cec30c465867d:/LUFA/Drivers/USB/LowLevel/Pipe.h diff --git a/LUFA/Drivers/USB/LowLevel/Pipe.h b/LUFA/Drivers/USB/LowLevel/Pipe.h index 30e0fde90..b6fad5146 100644 --- a/LUFA/Drivers/USB/LowLevel/Pipe.h +++ b/LUFA/Drivers/USB/LowLevel/Pipe.h @@ -43,6 +43,20 @@ * Functions, macros, variables, enums and types related to data reading and writing from and to pipes. */ +/** \ingroup Group_PipeRW + * @defgroup Group_PipePrimitiveRW Read/Write of Primitive Data Types + * + * Functions, macros, variables, enums and types related to data reading and writing of primitive data types + * from and to pipes. + */ + +/** \ingroup Group_PipeRW + * @defgroup Group_PipeStreamRW Read/Write of Multi-Byte Streams + * + * Functions, macros, variables, enums and types related to data reading and writing of data streams from + * and to pipes. + */ + /** @defgroup Group_PipePacketManagement Pipe Packet Management * * Functions, macros, variables, enums and types related to packet management of pipes. @@ -61,6 +75,8 @@ /* Includes: */ #include + #include + #include #include #include "../../../Common/Common.h" @@ -157,12 +173,7 @@ /** Endpoint number mask, for masking against endpoint addresses to retrieve the endpoint's * numerical address in the attached device. */ - #define PIPE_EPNUM_MASK 0x07 - - /** Endpoint bank size mask, for masking against endpoint addresses to retrieve the endpoint's - * bank size in the attached device. - */ - #define PIPE_EPSIZE_MASK 0x7FF + #define PIPE_EPNUM_MASK 0x0F /* Pseudo-Function Macros: */ #if defined(__DOXYGEN__) @@ -187,13 +198,13 @@ /** Selects the given pipe number. Any pipe operations which do not require the pipe number to be * indicated will operate on the currently selected pipe. * - * \param PipeNumber Index of the pipe to select + * \param[in] PipeNumber Index of the pipe to select */ static inline void Pipe_SelectPipe(uint8_t PipeNumber); /** Resets the desired pipe, including the pipe banks and flags. * - * \param PipeNumber Index of the pipe to reset + * \param[in] PipeNumber Index of the pipe to reset */ static inline void Pipe_ResetPipe(uint8_t PipeNumber); @@ -226,7 +237,7 @@ * control requests, or on regular pipes to allow for half-duplex bidirectional data transfer to devices * which have two endpoints of opposite direction sharing the same endpoint address within the device. * - * \param Token New pipe token to set the selected pipe to, as a PIPE_TOKEN_* mask + * \param[in] Token New pipe token to set the selected pipe to, as a PIPE_TOKEN_* mask */ static inline void Pipe_SetPipeToken(uint8_t Token); @@ -236,7 +247,7 @@ /** Configures the currently selected pipe to only allow the specified number of IN requests to be * accepted by the pipe before it is automatically frozen. * - * \param TotalINRequests Total number of IN requests that the pipe may receive before freezing + * \param[in] TotalINRequests Total number of IN requests that the pipe may receive before freezing */ static inline void Pipe_SetFiniteINRequests(uint8_t TotalINRequests); @@ -246,9 +257,16 @@ */ 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 Milliseconds Number of milliseconds between each pipe poll + * \param[in] Milliseconds Number of milliseconds between each pipe poll */ static inline void Pipe_SetInterruptPeriod(uint8_t Milliseconds); @@ -262,7 +280,7 @@ /** Determines if the specified pipe number has interrupted (valid only for INTERRUPT type * pipes). * - * \param PipeNumber Index of the pipe whose interrupt flag should be tested + * \param[in] PipeNumber Index of the pipe whose interrupt flag should be tested * * \return Boolean true if the specified pipe has interrupted, false otherwise */ @@ -416,6 +434,8 @@ #define Pipe_IsConfigured() ((UPSTAX & (1 << CFGOK)) ? true : false) + #define Pipe_BoundEndpointNumber() ((UPCFG0X >> PEPNUM0) & PIPE_EPNUM_MASK) + #define Pipe_SetInterruptPeriod(ms) MACROS{ UPCFG2X = ms; }MACROE #define Pipe_GetPipeInterrupts() UPINT @@ -502,7 +522,7 @@ /* Inline Functions: */ /** Reads one byte from the currently selected pipe's bank, for OUT direction pipes. * - * \ingroup Group_PipeRW + * \ingroup Group_PipePrimitiveRW * * \return Next byte in the currently selected pipe's FIFO buffer */ @@ -514,9 +534,9 @@ /** Writes one byte from the currently selected pipe's bank, for IN direction pipes. * - * \ingroup Group_PipeRW + * \ingroup Group_PipePrimitiveRW * - * \param Byte Next byte to write into the the currently selected pipe's FIFO buffer + * \param[in] Byte Next byte to write into the the currently selected pipe's FIFO buffer */ static inline void Pipe_Write_Byte(const uint8_t Byte) ATTR_ALWAYS_INLINE; static inline void Pipe_Write_Byte(const uint8_t Byte) @@ -526,7 +546,7 @@ /** Discards one byte from the currently selected pipe's bank, for OUT direction pipes. * - * \ingroup Group_PipeRW + * \ingroup Group_PipePrimitiveRW */ static inline void Pipe_Discard_Byte(void) ATTR_ALWAYS_INLINE; static inline void Pipe_Discard_Byte(void) @@ -539,7 +559,7 @@ /** Reads two bytes from the currently selected pipe's bank in little endian format, for OUT * direction pipes. * - * \ingroup Group_PipeRW + * \ingroup Group_PipePrimitiveRW * * \return Next word in the currently selected pipe's FIFO buffer */ @@ -557,7 +577,7 @@ /** Reads two bytes from the currently selected pipe's bank in big endian format, for OUT * direction pipes. * - * \ingroup Group_PipeRW + * \ingroup Group_PipePrimitiveRW * * \return Next word in the currently selected pipe's FIFO buffer */ @@ -575,9 +595,9 @@ /** Writes two bytes to the currently selected pipe's bank in little endian format, for IN * direction pipes. * - * \ingroup Group_PipeRW + * \ingroup Group_PipePrimitiveRW * - * \param Word Next word to write to the currently selected pipe's FIFO buffer + * \param[in] Word Next word to write to the currently selected pipe's FIFO buffer */ static inline void Pipe_Write_Word_LE(const uint16_t Word) ATTR_ALWAYS_INLINE; static inline void Pipe_Write_Word_LE(const uint16_t Word) @@ -589,9 +609,9 @@ /** Writes two bytes to the currently selected pipe's bank in big endian format, for IN * direction pipes. * - * \ingroup Group_PipeRW + * \ingroup Group_PipePrimitiveRW * - * \param Word Next word to write to the currently selected pipe's FIFO buffer + * \param[in] Word Next word to write to the currently selected pipe's FIFO buffer */ static inline void Pipe_Write_Word_BE(const uint16_t Word) ATTR_ALWAYS_INLINE; static inline void Pipe_Write_Word_BE(const uint16_t Word) @@ -602,7 +622,7 @@ /** Discards two bytes from the currently selected pipe's bank, for OUT direction pipes. * - * \ingroup Group_PipeRW + * \ingroup Group_PipePrimitiveRW */ static inline void Pipe_Discard_Word(void) ATTR_ALWAYS_INLINE; static inline void Pipe_Discard_Word(void) @@ -616,7 +636,7 @@ /** Reads four bytes from the currently selected pipe's bank in little endian format, for OUT * direction pipes. * - * \ingroup Group_PipeRW + * \ingroup Group_PipePrimitiveRW * * \return Next double word in the currently selected pipe's FIFO buffer */ @@ -640,7 +660,7 @@ /** Reads four bytes from the currently selected pipe's bank in big endian format, for OUT * direction pipes. * - * \ingroup Group_PipeRW + * \ingroup Group_PipePrimitiveRW * * \return Next double word in the currently selected pipe's FIFO buffer */ @@ -664,9 +684,9 @@ /** Writes four bytes to the currently selected pipe's bank in little endian format, for IN * direction pipes. * - * \ingroup Group_PipeRW + * \ingroup Group_PipePrimitiveRW * - * \param DWord Next double word to write to the currently selected pipe's FIFO buffer + * \param[in] DWord Next double word to write to the currently selected pipe's FIFO buffer */ 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) @@ -678,9 +698,9 @@ /** Writes four bytes to the currently selected pipe's bank in big endian format, for IN * direction pipes. * - * \ingroup Group_PipeRW + * \ingroup Group_PipePrimitiveRW * - * \param DWord Next double word to write to the currently selected pipe's FIFO buffer + * \param[in] DWord Next double word to write to the currently selected pipe's FIFO buffer */ 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) @@ -691,7 +711,7 @@ /** Discards four bytes from the currently selected pipe's bank, for OUT direction pipes. * - * \ingroup Group_PipeRW + * \ingroup Group_PipePrimitiveRW */ static inline void Pipe_Discard_DWord(void) ATTR_ALWAYS_INLINE; static inline void Pipe_Discard_DWord(void) @@ -716,6 +736,12 @@ extern uint8_t USB_ControlPipeSize; /* Function Prototypes: */ + #if !defined(NO_STREAM_CALLBACKS) || defined(__DOXYGEN__) + #define _CALLBACK_PARAM , StreamCallbackPtr_t Callback + #else + #define _CALLBACK_PARAM + #endif + /** Configures the specified pipe number with the given pipe type, token, target endpoint number in the * attached device, bank size and banking mode. Pipes should be allocated in ascending order by their * address in the device (i.e. pipe 1 should be configured before pipe 2 and so on) to prevent fragmentation @@ -747,15 +773,46 @@ 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. + /** Spinloops 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 EndpointAddress Address of the endpoint within the attached device to check + * + * \return Boolean true if a pipe bound to the given endpoint address is found, false otherwise + */ + bool Pipe_IsEndpointBound(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 + * user is responsible for manually discarding the last packet from the device via the \ref Pipe_ClearIN() macro. + * Between each USB packet, the given stream callback function is executed repeatedly until the next packet is ready, + * allowing for early aborts of stream transfers. + * + * The callback routine should be created according to the information in \ref Group_StreamCallbacks. + * If the token NO_STREAM_CALLBACKS is passed via the -D option to the compiler, stream callbacks are + * disabled and this function has the Callback parameter omitted. + * + * The pipe token is set automatically, thus this can be used on bi-directional pipes directly without + * having to explicitly change the data direction with a call to \ref Pipe_SetPipeToken(). + * + * \ingroup Group_PipeStreamRW + * + * \param[in] Length Number of bytes to send via the currently selected pipe. + * \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_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; * the user is responsible for manually sending the last written packet to the host via the @@ -769,20 +826,42 @@ * The pipe token is set automatically, thus this can be used on bi-directional pipes directly without * having to explicitly change the data direction with a call to \ref Pipe_SetPipeToken(). * - * \ingroup Group_PipeRW + * \ingroup Group_PipeStreamRW * - * \param Buffer Pointer to the source data buffer to read from. - * \param Length Number of bytes to read for the currently selected pipe into the buffer. - * \param Callback Name of a callback routine to call between successive USB packet transfers, NULL if no callback + * \param[in] Buffer Pointer to the source data buffer to read from. + * \param[in] Length Number of bytes to read for the currently selected pipe into the buffer. + * \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_Write_Stream_LE(const void* Buffer, uint16_t Length - #if !defined(NO_STREAM_CALLBACKS) || defined(__DOXYGEN__) - , StreamCallbackPtr_t Callback - #endif - ) ATTR_NON_NULL_PTR_ARG(1); + uint8_t Pipe_Write_Stream_LE(void* Buffer, uint16_t Length _CALLBACK_PARAM) ATTR_NON_NULL_PTR_ARG(1); + /** EEPROM buffer source version of \ref Pipe_Write_Stream_LE. + * + * \ingroup Group_PipeStreamRW + * + * \param[in] Buffer Pointer to the source data buffer to read from. + * \param[in] Length Number of bytes to read for the currently selected pipe into the buffer. + * \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_Write_EStream_LE(void* Buffer, uint16_t Length _CALLBACK_PARAM) ATTR_NON_NULL_PTR_ARG(1); + + /** 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. + * + * \ingroup Group_PipeStreamRW + * + * \param[in] Buffer Pointer to the source data buffer to read from. + * \param[in] Length Number of bytes to read for the currently selected pipe into the buffer. + * \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_Write_PStream_LE(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; * the user is responsible for manually sending the last written packet to the host via the @@ -796,45 +875,41 @@ * The pipe token is set automatically, thus this can be used on bi-directional pipes directly without * having to explicitly change the data direction with a call to \ref Pipe_SetPipeToken(). * - * \ingroup Group_PipeRW + * \ingroup Group_PipeStreamRW * - * \param Buffer Pointer to the source data buffer to read from. - * \param Length Number of bytes to read for the currently selected pipe into the buffer. - * \param Callback Name of a callback routine to call between successive USB packet transfers, NULL if no callback + * \param[in] Buffer Pointer to the source data buffer to read from. + * \param[in] Length Number of bytes to read for the currently selected pipe into the buffer. + * \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_Write_Stream_BE(const void* Buffer, uint16_t Length - #if !defined(NO_STREAM_CALLBACKS) || defined(__DOXYGEN__) - , StreamCallbackPtr_t Callback - #endif - ) ATTR_NON_NULL_PTR_ARG(1); + uint8_t Pipe_Write_Stream_BE(void* Buffer, uint16_t Length _CALLBACK_PARAM) ATTR_NON_NULL_PTR_ARG(1); - /** 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 - * user is responsible for manually discarding the last packet from the device via the \ref Pipe_ClearIN() macro. - * Between each USB packet, the given stream callback function is executed repeatedly until the next packet is ready, - * allowing for early aborts of stream transfers. + /** EEPROM buffer source version of \ref Pipe_Write_Stream_BE. * - * The callback routine should be created according to the information in \ref Group_StreamCallbacks. - * If the token NO_STREAM_CALLBACKS is passed via the -D option to the compiler, stream callbacks are - * disabled and this function has the Callback parameter omitted. + * \ingroup Group_PipeStreamRW * - * The pipe token is set automatically, thus this can be used on bi-directional pipes directly without - * having to explicitly change the data direction with a call to \ref Pipe_SetPipeToken(). + * \param[in] Buffer Pointer to the source data buffer to read from. + * \param[in] Length Number of bytes to read for the currently selected pipe into the buffer. + * \param[in] Callback Name of a callback routine to call between successive USB packet transfers, NULL if no callback * - * \ingroup Group_PipeRW + * \return A value from the \ref Pipe_Stream_RW_ErrorCodes_t enum. + */ + uint8_t Pipe_Write_EStream_BE(void* Buffer, uint16_t Length _CALLBACK_PARAM) ATTR_NON_NULL_PTR_ARG(1); + + /** FLASH buffer source version of \ref Pipe_Write_Stream_BE. * - * \param Length Number of bytes to send via the currently selected pipe. - * \param Callback Name of a callback routine to call between successive USB packet transfers, NULL if no callback + * \note The FLASH data must be located in the first 64KB of FLASH for this function to work correctly. + * + * \ingroup Group_PipeStreamRW + * + * \param[in] Buffer Pointer to the source data buffer to read from. + * \param[in] Length Number of bytes to read for the currently selected pipe into the buffer. + * \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_Discard_Stream(uint16_t Length - #if !defined(NO_STREAM_CALLBACKS) || defined(__DOXYGEN__) - , StreamCallbackPtr_t Callback - #endif - ); + uint8_t Pipe_Write_PStream_BE(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; @@ -849,19 +924,27 @@ * The pipe token is set automatically, thus this can be used on bi-directional pipes directly without * having to explicitly change the data direction with a call to \ref Pipe_SetPipeToken(). * - * \ingroup Group_PipeRW + * \ingroup Group_PipeStreamRW * - * \param Buffer Pointer to the source data buffer to write to. - * \param Length Number of bytes to read for the currently selected pipe to read from. - * \param Callback Name of a callback routine to call between successive USB packet transfers, NULL if no callback + * \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 - #if !defined(NO_STREAM_CALLBACKS) || defined(__DOXYGEN__) - , StreamCallbackPtr_t Callback - #endif - ) 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. + * + * \ingroup Group_PipeStreamRW + * + * \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); /** 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; @@ -876,20 +959,28 @@ * The pipe token is set automatically, thus this can be used on bi-directional pipes directly without * having to explicitly change the data direction with a call to \ref Pipe_SetPipeToken(). * - * \ingroup Group_PipeRW + * \ingroup Group_PipeStreamRW * - * \param Buffer Pointer to the source data buffer to write to. - * \param Length Number of bytes to read for the currently selected pipe to read from. - * \param Callback Name of a callback routine to call between successive USB packet transfers, NULL if no callback + * \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 - #if !defined(NO_STREAM_CALLBACKS) || defined(__DOXYGEN__) - , StreamCallbackPtr_t Callback - #endif - ) 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. + * + * \ingroup Group_PipeStreamRW + * + * \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); + /* Private Interface - For use in library only: */ #if !defined(__DOXYGEN__) /* Macros: */