X-Git-Url: http://git.linex4red.de/pub/USBasp.git/blobdiff_plain/2ee9fc707784e115d744dbc229bdc893f4bb6bc1..e0af6014a746b1ef0707d388a58bcf77b9ea47f1:/LUFA/Drivers/USB/LowLevel/Pipe.h diff --git a/LUFA/Drivers/USB/LowLevel/Pipe.h b/LUFA/Drivers/USB/LowLevel/Pipe.h index befc996a2..cf61eeae0 100644 --- a/LUFA/Drivers/USB/LowLevel/Pipe.h +++ b/LUFA/Drivers/USB/LowLevel/Pipe.h @@ -77,6 +77,12 @@ /* 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. */ + #define PIPE_ERRORFLAG_OVERFLOW (1 << 6) + + /** Mask for \ref Pipe_GetErrorFlags(), indicating that an underflow error occurred in the pipe on the received data. */ + #define PIPE_ERRORFLAG_UNDERFLOW (1 << 5) + /** Mask for \ref Pipe_GetErrorFlags(), indicating that a CRC error occurred in the pipe on the received data. */ #define PIPE_ERRORFLAG_CRC16 (1 << 4) @@ -181,13 +187,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); @@ -213,14 +219,14 @@ * * \return The current pipe token, as a PIPE_TOKEN_* mask */ - static inline uint8_t Pipe_GetCurrentToken(void); + static inline uint8_t Pipe_GetPipeToken(void); /** Sets the token for the currently selected pipe to one of the tokens specified by the PIPE_TOKEN_* * masks. This can be used on CONTROL type pipes, to allow for bidirectional transfer of data during * 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); @@ -230,7 +236,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); @@ -242,7 +248,7 @@ /** 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); @@ -256,7 +262,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 */ @@ -426,7 +432,10 @@ #define Pipe_ClearErrorFlags() MACROS{ UPERRX = 0; }MACROE - #define Pipe_GetErrorFlags() UPERRX + #define Pipe_GetErrorFlags() ((UPERRX & (PIPE_ERRORFLAG_CRC16 | PIPE_ERRORFLAG_TIMEOUT | \ + PIPE_ERRORFLAG_PID | PIPE_ERRORFLAG_DATAPID | \ + PIPE_ERRORFLAG_DATATGL)) | \ + (UPSTAX & PIPE_ERRORFLAG_OVERFLOW | PIPE_ERRORFLAG_UNDERFLOW)) #define Pipe_IsReadWriteAllowed() ((UPINTX & (1 << RWAL)) ? true : false) @@ -507,7 +516,7 @@ * * \ingroup Group_PipeRW * - * \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) @@ -568,7 +577,7 @@ * * \ingroup Group_PipeRW * - * \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) @@ -582,7 +591,7 @@ * * \ingroup Group_PipeRW * - * \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) @@ -657,7 +666,7 @@ * * \ingroup Group_PipeRW * - * \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) @@ -671,7 +680,7 @@ * * \ingroup Group_PipeRW * - * \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) @@ -709,7 +718,8 @@ /* Function Prototypes: */ /** 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). + * address in the device (i.e. pipe 1 should be configured before pipe 2 and so on) to prevent fragmentation + * of the USB FIFO memory. * * The pipe type may be one of the EP_TYPE_* macros listed in LowLevel.h, the token may be one of the * PIPE_TOKEN_* masks. @@ -720,7 +730,14 @@ * * The banking mode may be either \ref PIPE_BANK_SINGLE or \ref PIPE_BANK_DOUBLE. * - * A newly configured pipe is frozen by default, and must be unfrozen before use via the \ref Pipe_Unfreeze() macro. + * A newly configured pipe is frozen by default, and must be unfrozen before use via the \ref Pipe_Unfreeze() + * before being used. Pipes should be kept frozen unless waiting for data from a device while in IN mode, or + * sending data to the device in OUT mode. IN type pipes are also automatically configured to accept infinite + * numbers of IN requests without automatic freezing - this can be overridden by a call to + * \ref Pipe_SetFiniteINRequests(). + * + * \note The default control pipe does not have to be manually configured, as it is automatically + * configured by the library internally. * * \note This routine will select the specified pipe, and the pipe will remain selected once the * routine completes regardless of if the pipe configuration succeeds. @@ -749,11 +766,14 @@ * 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_PipeRW * - * \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. */ @@ -773,11 +793,14 @@ * 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_PipeRW * - * \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. */ @@ -797,10 +820,13 @@ * 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_PipeRW * - * \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 + * \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. */ @@ -820,11 +846,14 @@ * 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_PipeRW * - * \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. */ @@ -844,11 +873,14 @@ * 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_PipeRW * - * \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. */