X-Git-Url: http://git.linex4red.de/pub/lufa.git/blobdiff_plain/ef06bfd1c0ef5272c32808e23d0fd60d2d1bca9c..8f6b4ddf764c3a54e42d00a7502c82c5c3e71b1c:/LUFA/Drivers/USB/LowLevel/Pipe.h diff --git a/LUFA/Drivers/USB/LowLevel/Pipe.h b/LUFA/Drivers/USB/LowLevel/Pipe.h index 46a10e493..253ce2a93 100644 --- a/LUFA/Drivers/USB/LowLevel/Pipe.h +++ b/LUFA/Drivers/USB/LowLevel/Pipe.h @@ -35,6 +35,29 @@ * send/recieve functions for various data types. */ +/** \ingroup Group_USB + * @defgroup Group_PipeManagement Pipe Management + * + * Functions, macros, variables, enums and types related to the setup and management of pipes while in USB Device mode. + * + * @{ + */ + +/** @defgroup Group_PipeRW Pipe Data Reading and Writing + * + * Functions, macros, variables, enums and types related to data reading and writing from and to pipes. + */ + +/** @defgroup Group_PipePacketManagement Pipe Packet Management + * + * Functions, macros, variables, enums and types related to packet management of pipes. + */ + +/** @defgroup Group_PipeControlReq Pipe Control Request Management + * + * Functions, macros, variables, enums and types related to control request management of pipes. + */ + #ifndef __PIPE_H__ #define __PIPE_H__ @@ -221,158 +244,339 @@ */ #define PIPE_INT_STALL UPIENX, (1 << RXSTALLE), UPINTX, (1 << RXSTALLI) - /** Indicates the number of bytes currently stored in the current pipe's selected bank. */ - #define Pipe_BytesInPipe() UPBCX + /* Psuedo-Function Macros: */ + #if defined(__DOXYGEN__) + /** Indicates the number of bytes currently stored in the current pipes's selected bank. + * + * \note The return width of this function may differ, depending on the maximum pipe bank size + * of the selected AVR model. + * + * \ingroup Group_PipeRW + * + * \return Total number of bytes in the currently selected Pipe's FIFO buffer + */ + static inline uint16_t Pipe_BytesInPipe(void); + + /** Returns the pipe address of the currently selected pipe. This is typically used to save the + * currently selected pipe number so that it can be restored after another pipe has been manipulated. + * + * \return Index of the currently selected pipe + */ + static inline uint8_t Pipe_GetCurrentPipe(void); + + /** 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 + */ + 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 + */ + static inline void Pipe_ResetPipe(uint8_t PipeNumber); + + /** Enables the currently selected pipe so that data can be sent and received through it to and from + * an attached device. + * + * \note Pipes must first be configured properly rather than just being enabled via the + * Pipe_ConfigurePipe() macro, which calls Pipe_EnablePipe() automatically. + */ + static inline void Pipe_EnablePipe(void); + + /** Disables the currently selected pipe so that data cannot be sent and received through it to and + * from an attached device. + */ + static inline void Pipe_DisablePipe(void); + + /** Determines if the currently selected pipe is enabled, but not necessarily configured. + * + * \return Boolean True if the currently selected pipe is enabled, false otherwise + */ + static inline bool Pipe_IsEnabled(void); + + /** Gets the current pipe token, indicating the pipe's data direction and type. + * + * \return The current pipe token, as a PIPE_TOKEN_* mask + */ + static inline uint8_t Pipe_GetCurrentToken(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 + */ + static inline void Pipe_SetPipeToken(uint8_t Token); + + /** Configures the currently selected pipe to allow for an unlimited number of IN requests. */ + static inline void Pipe_SetInfiniteINRequests(void); + + /** 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 + */ + static inline void Pipe_SetFiniteINRequests(uint8_t TotalINRequests); + + /** Determines if the currently selected pipe is configured. + * + * \return Boolean true if the selected pipe is configured, false otherwise + */ + static inline bool Pipe_IsConfigured(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 + */ + static inline void Pipe_SetInterruptPeriod(uint8_t Milliseconds); + + /** Returns a mask indicating which pipe's interrupt periods have elapsed, indicating that the pipe should + * be serviced. + * + * \return Mask whose bits indicate which pipes have interrupted + */ + static inline uint8_t Pipe_GetPipeInterrupts(void); + + /** Clears the interrupt flag for the specified pipe number. + * + * \param PipeNumber Index of the pipe whose interrupt flag is to be cleared + */ + static inline void Pipe_ClearPipeInterrupt(uint8_t PipeNumber); + + /** 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 + * + * \return Boolean true if the specified pipe has interrupted, false otherwise + */ + static inline bool Pipe_HasPipeInterrupted(uint8_t PipeNumber); + + /** Unfreezes the selected pipe, allowing it to communicate with an attached device. */ + static inline void Pipe_Unfreeze(void); + + /** Freezes the selected pipe, preventing it from communicating with an attached device. */ + static inline void Pipe_Freeze(void); - /** Resets the desired pipe, including the pipe banks and flags. */ - #define Pipe_ResetPipe(pipenum) MACROS{ UPRST = (1 << pipenum); UPRST = 0; }MACROE + /** Clears the master pipe error flag. */ + static inline void Pipe_ClearError(void); + + /** Determines if the master pipe error flag is set for the currently selected pipe, indicating that + * some sort of hardware error has occurred on the pipe. + * + * \see Pipe_GetErrorFlags() macro for information on retrieving the exact error flag. + * + * \return Boolean true if an error has ocurred on the selected pipe, false otherwise + */ + static inline bool Pipe_IsError(void); + + /** Clears all the currently selected pipe's hardware error flags, but does not clear the master error + * flag for the pipe. + */ + static inline void Pipe_ClearErrorFlags(void); + + /** Gets a mask of the hardware error flags which have occurred on the currently selected pipe. This + * value can then be masked against the PIPE_ERRORFLAG_* masks to determine what error has occurred. + * + * \return Mask comprising of PIPE_ERRORFLAG_* bits indicating what error has ocurred on the selected pipe + */ + static inline uint8_t Pipe_GetErrorFlags(void); + + /** Determines if the currently selected pipe may be read from (if data is waiting in the pipe + * bank and the pipe is an IN direction, or if the bank is not yet full if the pipe is an OUT + * direction). This function will return false if an error has occurred in the pipe, or if the pipe + * is an IN direction and no packet (or an empty packet) has been received, or if the pipe is an OUT + * direction and the pipe bank is full. + * + * \ingroup Group_PipePacketManagement + * + * \return Boolean true if the currently selected pipe may be read from or written to, depending on its direction + */ + static inline bool Pipe_IsReadWriteAllowed(void); + + /** Determines if an IN request has been received on the currently selected pipe. + * + * \ingroup Group_PipePacketManagement + * + * \return Boolean true if the current pipe has received an IN packet, false otherwise. + */ + static inline bool Pipe_IsINReceived(void); + + /** Determines if the currently selected pipe is ready to send an OUT request. + * + * \ingroup Group_PipePacketManagement + * + * \return Boolean true if the current pipe is ready for an OUT packet, false otherwise. + */ + static inline bool Pipe_IsOUTReady(void); + + /** Determines if no SETUP request is currently being sent to the attached device on the selected + * CONTROL type pipe. + * + * \ingroup Group_PipePacketManagement + * + * \return Boolean true if the current pipe is ready for a SETUP packet, false otherwise. + */ + static inline bool Pipe_IsSETUPSent(void); + + /** Acknowledges the reception of a setup IN request from the attached device on the currently selected + * CONTROL type pipe, freeing the bank ready for the next packet. + * + * \ingroup Group_PipePacketManagement + * + * \note For non CONTROL type pipes, use Pipe_ClearIN() instead. + */ + static inline void Pipe_ClearControlIN(void); + + /** Sends the currently selected pipe's contents to the device as an OUT packet on the selected pipe, freeing + * the bank ready for the next packet. + * + * \ingroup Group_PipePacketManagement + * + * \note For non CONTROL type pipes, use Pipe_ClearOUT() instead. + */ + static inline void Pipe_ClearControlOUT(void); + + /** Sends the currently selected CONTROL type pipe's contents to the device as a SETUP packet. + * + * \ingroup Group_PipePacketManagement + * + * \note This is not applicable for non CONTROL type pipes. + */ + static inline void Pipe_ClearControlSETUP(void); + + /** Acknowledges the reception of a setup IN request from the attached device on the currently selected + * pipe, freeing the bank ready for the next packet. + * + * \ingroup Group_PipePacketManagement + * + * \note For CONTROL type pipes, use Pipe_ClearControlIN() instead. + */ + static inline void Pipe_ClearIN(void); + + /** Sends the currently selected pipe's contents to the device as an OUT packet on the selected pipe, freeing + * the bank ready for the next packet. + * + * \ingroup Group_PipePacketManagement + * + * \note For CONTROL type pipes, use Pipe_ClearControlOUT() instead. + */ + static inline void Pipe_ClearOUT(void); + + /** Determines if the device sent a NAK (Negative Acknowledge) in response to the last sent packet on + * the currently selected pipe. This occurs when the host sends a packet to the device, but the device + * is not currently ready to handle the packet (i.e. its endpoint banks are full). Once a NAK has been + * received, it must be cleared using Pipe_ClearNAKReceived() before the previous (or any other) packet + * can be re-sent. + * + * \ingroup Group_PipePacketManagement + * + * \return Boolean true if an NAK has been received on the current pipe, false otherwise + */ + static inline bool Pipe_IsNAKReceived(void); + + /** Clears the NAK condition on the currently selected pipe. + * + * \ingroup Group_PipePacketManagement + * + * \see Pipe_IsNAKReceived() for more details. + */ + static inline void Pipe_ClearNAKReceived(void); + + /** Determines if the currently selected pipe has had the STALL condition set by the attached device. + * + * \ingroup Group_PipePacketManagement + * + * \return Boolean true if the current pipe has been stalled by the attached device, false otherwise + */ + static inline bool Pipe_IsStalled(void); + + /** Clears the STALL condition detection flag on the currently selected pipe, but does not clear the + * STALL condition itself (this must be done via a ClearFeature control request to the device). + * + * \ingroup Group_PipePacketManagement + */ + static inline void Pipe_ClearStall(void); + #else + #define Pipe_BytesInPipe() UPBCX - /** 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. - */ - #define Pipe_SelectPipe(pipenum) MACROS{ UPNUM = pipenum; }MACROE + #define Pipe_GetCurrentPipe() (UPNUM & PIPE_PIPENUM_MASK) - /** Returns the pipe address of the currently selected pipe. This is typically used to save the - * currently selected pipe number so that it can be restored after another pipe has been manipulated. - */ - #define Pipe_GetCurrentPipe() (UPNUM & PIPE_PIPENUM_MASK) + #define Pipe_SelectPipe(pipenum) MACROS{ UPNUM = pipenum; }MACROE + + #define Pipe_ResetPipe(pipenum) MACROS{ UPRST = (1 << pipenum); UPRST = 0; }MACROE - /** Enables the currently selected pipe so that data can be sent and received through it to and from - * an attached device. - * - * \note Pipes must first be configured properly rather than just being enabled via the - * Pipe_ConfigurePipe() macro, which calls Pipe_EnablePipe() automatically. - */ - #define Pipe_EnablePipe() MACROS{ UPCONX |= (1 << PEN); }MACROE + #define Pipe_EnablePipe() MACROS{ UPCONX |= (1 << PEN); }MACROE - /** Disables the currently selected pipe so that data cannot be sent and received through it to and - * from an attached device. - */ - #define Pipe_DisablePipe() MACROS{ UPCONX &= ~(1 << PEN); }MACROE + #define Pipe_DisablePipe() MACROS{ UPCONX &= ~(1 << PEN); }MACROE - /** Returns true if the currently selected pipe is enabled, false otherwise. */ - #define Pipe_IsEnabled() ((UPCONX & (1 << PEN)) ? true : false) + #define Pipe_IsEnabled() ((UPCONX & (1 << PEN)) ? true : false) - /** Sets the token for the currently selected endpoint to one of the tokens specified by the PIPE_TOKEN_* - * masks. This should only be used on CONTROL type endpoints, to allow for bidirectional transfer of - * data during control requests. - */ - #define Pipe_SetToken(token) MACROS{ UPCFG0X = ((UPCFG0X & ~PIPE_TOKEN_MASK) | token); }MACROE - - /** Configures the currently selected pipe to allow for an unlimited number of IN requests. */ - #define Pipe_SetInfiniteINRequests() MACROS{ UPCONX |= (1 << INMODE); }MACROE + #define Pipe_GetPipeToken() (UPCFG0X & PIPE_TOKEN_MASK) - /** 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. - */ - #define Pipe_SetFiniteINRequests(n) MACROS{ UPCONX &= ~(1 << INMODE); UPINRQX = n; }MACROE + #define Pipe_SetToken(token) MACROS{ UPCFG0X = ((UPCFG0X & ~PIPE_TOKEN_MASK) | token); }MACROE + + #define Pipe_SetInfiniteINRequests() MACROS{ UPCONX |= (1 << INMODE); }MACROE - /** Returns true if the currently selected pipe is configured, false otherwise. */ - #define Pipe_IsConfigured() ((UPSTAX & (1 << CFGOK)) ? true : false) + #define Pipe_SetFiniteINRequests(n) MACROS{ UPCONX &= ~(1 << INMODE); UPINRQX = n; }MACROE - /** Sets the period between interrupts for an INTERRUPT type pipe to a specified number of milliseconds. */ - #define Pipe_SetInterruptPeriod(ms) MACROS{ UPCFG2X = ms; }MACROE + #define Pipe_IsConfigured() ((UPSTAX & (1 << CFGOK)) ? true : false) - /** Returns a mask indicating which pipe's interrupt periods have elapsed, indicating that the pipe should - * be serviced. - */ - #define Pipe_GetPipeInterrupts() UPINT + #define Pipe_SetInterruptPeriod(ms) MACROS{ UPCFG2X = ms; }MACROE - /** Clears the interrupt flag for the specified pipe number. */ - #define Pipe_ClearPipeInterrupt(n) MACROS{ UPINT &= ~(1 << n); }MACROE + #define Pipe_GetPipeInterrupts() UPINT - /** Returns true if the specified pipe's interrupt period has elapsed, false otherwise. */ - #define Pipe_HasPipeInterrupted(n) ((UPINT & (1 << n)) ? true : false) - - /** Clears the pipe bank, and switches to the alternate bank if the currently selected pipe is - * dual-banked. When cleared, this either frees the bank up for the next packet from the host - * (if the endpoint is of the OUT direction) or sends the packet contents to the host (if the - * pipe is of the IN direction). - */ - #define Pipe_ClearCurrentBank() MACROS{ UPINTX &= ~(1 << FIFOCON); }MACROE + #define Pipe_ClearPipeInterrupt(n) MACROS{ UPINT &= ~(1 << n); }MACROE - /** Unfreezes the pipe, allowing it to communicate with an attached device. */ - #define Pipe_Unfreeze() MACROS{ UPCONX &= ~(1 << PFREEZE); }MACROE + #define Pipe_HasPipeInterrupted(n) ((UPINT & (1 << n)) ? true : false) - /** Freezes the pipe, preventing it from communicating with an attached device. */ - #define Pipe_Freeze() MACROS{ UPCONX |= (1 << PFREEZE); }MACROE + #define Pipe_Unfreeze() MACROS{ UPCONX &= ~(1 << PFREEZE); }MACROE - /** Clears the master pipe error flag. */ - #define Pipe_ClearError() MACROS{ UPINTX &= ~(1 << PERRI); }MACROE + #define Pipe_Freeze() MACROS{ UPCONX |= (1 << PFREEZE); }MACROE - /** Returns true if the master pipe error flag is set for the currently selected pipe, indicating that - * some sort of hardware error has occurred on the pipe. - * - * \see Pipe_GetErrorFlags() macro for information on retrieving the exact error flag. - */ - #define Pipe_IsError() ((UPINTX & (1 << PERRI)) ? true : false) - - /** Clears all the currently selected pipe's hardware error flags, but does not clear the master error - * flag for the pipe. */ - #define Pipe_ClearErrorFlags() MACROS{ UPERRX = 0; }MACROE + #define Pipe_ClearError() MACROS{ UPINTX &= ~(1 << PERRI); }MACROE - /** Returns a mask of the hardware error flags which have occurred on the currently selected pipe. This - * value can then be masked against the PIPE_ERRORFLAG_* masks to determine what error has occurred. - */ - #define Pipe_GetErrorFlags() UPERRX + #define Pipe_IsError() ((UPINTX & (1 << PERRI)) ? true : false) + + #define Pipe_ClearErrorFlags() MACROS{ UPERRX = 0; }MACROE - /** Returns true if the currently selected pipe may be read from (if data is waiting in the pipe - * bank and the pipe is an IN direction, or if the bank is not yet full if the pipe is an OUT - * direction). This function will return false if an error has occurred in the pipe, or if the pipe - * is an IN direction and no packet has been received, or if the pipe is an OUT direction and the - * pipe bank is full. - */ - #define Pipe_ReadWriteAllowed() ((UPINTX & (1 << RWAL)) ? true : false) + #define Pipe_GetErrorFlags() UPERRX - /** Clears the flag indicating that a SETUP request has been sent to the attached device from the - * currently selected CONTROL type pipe. - */ - #define Pipe_ClearSetupSent() MACROS{ UPINTX &= ~(1 << TXSTPI); }MACROE + #define Pipe_IsReadWriteAllowed() ((UPINTX & (1 << RWAL)) ? true : false) - /** Returns true if no SETUP request is currently being sent to the attached device, false otherwise. */ - #define Pipe_IsSetupSent() ((UPINTX & (1 << TXSTPI)) ? true : false) + #define Pipe_IsINReceived() ((UPINTX & (1 << RXINI)) ? true : false) - /** Returns true if the currently selected pipe has been stalled by the attached device, false otherwise. */ - #define Pipe_IsStalled() ((UPINTX & (1 << RXSTALLI)) ? true : false) + #define Pipe_IsOUTReady() ((UPINTX & (1 << TXOUTI)) ? true : false) - /** Clears the stall condition on the currently selected pipe. */ - #define Pipe_ClearStall() MACROS{ UPINTX &= ~(1 << RXSTALLI); }MACROE + #define Pipe_IsSETUPSent() ((UPINTX & (1 << TXSTPI)) ? true : false) - /** Returns true if an IN request has been received on the currently selected CONTROL type pipe, false - * otherwise. - */ - #define Pipe_IsSetupINReceived() ((UPINTX & (1 << RXINI)) ? true : false) + #define Pipe_ClearIN() MACROS{ UPINTX &= ~(1 << RXINI); UPINTX &= ~(1 << FIFOCON); }MACROE - /** Returns true if the currently selected CONTROL type pipe is ready to send an OUT request, false - * otherwise. - */ - #define Pipe_IsSetupOUTReady() ((UPINTX & (1 << TXOUTI)) ? true : false) + #define Pipe_ClearControlIN() MACROS{ UPINTX &= ~(1 << RXINI); UPINTX &= ~(1 << FIFOCON); }MACROE - /** Acknowledges the reception of a setup IN request from the attached device on the currently selected - * CONTROL type endpoint, allowing for the transmission of a setup OUT packet, or the reception of - * another setup IN packet. - */ - #define Pipe_ClearSetupIN() MACROS{ UPINTX &= ~(1 << RXINI); UPINTX &= ~(1 << FIFOCON); }MACROE + #define Pipe_ClearOUT() MACROS{ UPINTX &= ~(1 << TXOUTI); UPINTX &= ~(1 << FIFOCON); }MACROE + + #define Pipe_ClearControlOUT() MACROS{ UPINTX &= ~(1 << TXOUTI); UPINTX &= ~(1 << FIFOCON); }MACROE - /** Sends the currently selected CONTROL type pipe's contents to the device as a setup OUT packet. */ - #define Pipe_ClearSetupOUT() MACROS{ UPINTX &= ~(1 << TXOUTI); UPINTX &= ~(1 << FIFOCON); }MACROE - - /** Returns true if the device sent a NAK (Negative Acknowledge) in response to the last sent packet on - * the currently selected pipe. This occurs when the host sends a packet to the device, but the device - * is not currently ready to handle the packet (i.e. its endpoint banks are full). Once a NAK has been - * received, it must be cleared using Pipe_ClearNAKReceived() before the previous (or any other) packet - * can be re-sent. - */ - #define Pipe_IsNAKReceived() ((UPINTX & (1 << NAKEDI)) ? true : false) + #define Pipe_ClearControlSETUP() MACROS{ UPINTX &= ~(1 << TXSTPI); UPINTX &= ~(1 << FIFOCON); }MACROE - /** Clears the NAK condition on the currently selected pipe. - * - * \see Pipe_IsNAKReceived() for more details. - */ - #define Pipe_ClearNAKReceived() MACROS{ UPINTX &= ~(1 << NAKEDI); }MACROE + #define Pipe_IsNAKReceived() ((UPINTX & (1 << NAKEDI)) ? true : false) + + #define Pipe_ClearNAKReceived() MACROS{ UPINTX &= ~(1 << NAKEDI); }MACROE + + #define Pipe_IsStalled() ((UPINTX & (1 << RXSTALLI)) ? true : false) + + #define Pipe_ClearStall() MACROS{ UPINTX &= ~(1 << RXSTALLI); }MACROE + #endif /* Enums: */ - /** Enum for the possible error return codes of the Pipe_WaitUntilReady function */ + /** Enum for the possible error return codes of the Pipe_WaitUntilReady function + * + * \ingroup Group_PipeRW + */ enum Pipe_WaitUntilReady_ErrorCodes_t { PIPE_READYWAIT_NoError = 0, /**< Pipe ready for next packet, no error */ @@ -384,7 +588,10 @@ */ }; - /** Enum for the possible error return codes of the Pipe_*_Stream_* functions. */ + /** Enum for the possible error return codes of the Pipe_*_Stream_* functions. + * + * \ingroup Group_PipeRW + */ enum Pipe_Stream_RW_ErrorCodes_t { PIPE_RWSTREAM_ERROR_NoError = 0, /**< Command completed successfully, no error. */ @@ -402,21 +609,34 @@ }; /* Inline Functions: */ - /** Reads one byte from the currently selected pipe's bank, for OUT direction pipes. */ + /** Reads one byte from the currently selected pipe's bank, for OUT direction pipes. + * + * \ingroup Group_PipeRW + * + * \return Next byte in the currently selected pipe's FIFO buffer + */ static inline uint8_t Pipe_Read_Byte(void) ATTR_WARN_UNUSED_RESULT ATTR_ALWAYS_INLINE; static inline uint8_t Pipe_Read_Byte(void) { return UPDATX; } - /** Writes one byte from the currently selected pipe's bank, for IN direction pipes. */ + /** Writes one byte from the currently selected pipe's bank, for IN direction pipes. + * + * \ingroup Group_PipeRW + * + * \param 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) { UPDATX = Byte; } - /** Discards one byte from the currently selected pipe's bank, for OUT direction pipes. */ + /** Discards one byte from the currently selected pipe's bank, for OUT direction pipes. + * + * \ingroup Group_PipeRW + */ static inline void Pipe_Discard_Byte(void) ATTR_ALWAYS_INLINE; static inline void Pipe_Discard_Byte(void) { @@ -427,6 +647,10 @@ /** Reads two bytes from the currently selected pipe's bank in little endian format, for OUT * direction pipes. + * + * \ingroup Group_PipeRW + * + * \return Next word in the currently selected pipe's FIFO buffer */ 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) @@ -441,6 +665,10 @@ /** Reads two bytes from the currently selected pipe's bank in big endian format, for OUT * direction pipes. + * + * \ingroup Group_PipeRW + * + * \return Next word in the currently selected pipe's FIFO buffer */ 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) @@ -455,6 +683,10 @@ /** Writes two bytes to the currently selected pipe's bank in little endian format, for IN * direction pipes. + * + * \ingroup Group_PipeRW + * + * \param 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) @@ -465,6 +697,10 @@ /** Writes two bytes to the currently selected pipe's bank in big endian format, for IN * direction pipes. + * + * \ingroup Group_PipeRW + * + * \param 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) @@ -473,9 +709,12 @@ UPDATX = (Word & 0xFF); } - /** Discards two bytes from the currently selected pipe's bank, for OUT direction pipes. */ - static inline void Pipe_Ignore_Word(void) ATTR_ALWAYS_INLINE; - static inline void Pipe_Ignore_Word(void) + /** Discards two bytes from the currently selected pipe's bank, for OUT direction pipes. + * + * \ingroup Group_PipeRW + */ + static inline void Pipe_Discard_Word(void) ATTR_ALWAYS_INLINE; + static inline void Pipe_Discard_Word(void) { uint8_t Dummy; @@ -485,6 +724,10 @@ /** Reads four bytes from the currently selected pipe's bank in little endian format, for OUT * direction pipes. + * + * \ingroup Group_PipeRW + * + * \return Next double word in the currently selected pipe's FIFO buffer */ static inline uint32_t Pipe_Read_DWord_LE(void) ATTR_WARN_UNUSED_RESULT ATTR_ALWAYS_INLINE; static inline uint32_t Pipe_Read_DWord_LE(void) @@ -505,6 +748,10 @@ /** Reads four bytes from the currently selected pipe's bank in big endian format, for OUT * direction pipes. + * + * \ingroup Group_PipeRW + * + * \return Next double word in the currently selected pipe's FIFO buffer */ static inline uint32_t Pipe_Read_DWord_BE(void) ATTR_WARN_UNUSED_RESULT ATTR_ALWAYS_INLINE; static inline uint32_t Pipe_Read_DWord_BE(void) @@ -525,6 +772,10 @@ /** Writes four bytes to the currently selected pipe's bank in little endian format, for IN * direction pipes. + * + * \ingroup Group_PipeRW + * + * \param 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) @@ -535,6 +786,10 @@ /** Writes four bytes to the currently selected pipe's bank in big endian format, for IN * direction pipes. + * + * \ingroup Group_PipeRW + * + * \param 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) @@ -543,7 +798,10 @@ Pipe_Write_Word_BE(DWord); } - /** Discards four bytes from the currently selected pipe's bank, for OUT direction pipes. */ + /** Discards four bytes from the currently selected pipe's bank, for OUT direction pipes. + * + * \ingroup Group_PipeRW + */ static inline void Pipe_Ignore_DWord(void) ATTR_ALWAYS_INLINE; static inline void Pipe_Ignore_DWord(void) { @@ -595,6 +853,8 @@ * * \note This routine should not be called on CONTROL type pipes. * + * \ingroup Group_PipeRW + * * \return A value from the Pipe_WaitUntilReady_ErrorCodes_t enum. */ uint8_t Pipe_WaitUntilReady(void); @@ -602,13 +862,15 @@ /** 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 - * Pipe_ClearCurrentBank() macro. Between each USB packet, the given stream callback function is + * Pipe_ClearOUT() 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 using the STREAM_CALLBACK() macro. 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_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 @@ -624,13 +886,15 @@ /** 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 - * Pipe_ClearCurrentBank() macro. Between each USB packet, the given stream callback function is + * Pipe_ClearOUT() 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 using the STREAM_CALLBACK() macro. 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_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 @@ -645,7 +909,7 @@ /** 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 host via the Pipe_ClearCurrentBank() macro. + * user is responsible for manually discarding the last packet from the device via the 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. * @@ -653,6 +917,8 @@ * 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_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 * @@ -667,13 +933,15 @@ /** 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; * the user is responsible for manually sending the last written packet to the host via the - * Pipe_ClearCurrentBank() macro. Between each USB packet, the given stream callback function is + * 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 using the STREAM_CALLBACK() macro. 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_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 @@ -689,13 +957,15 @@ /** 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; * the user is responsible for manually sending the last written packet to the host via the - * Pipe_ClearCurrentBank() macro. Between each USB packet, the given stream callback function is + * 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 using the STREAM_CALLBACK() macro. 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_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 @@ -706,58 +976,7 @@ #if !defined(NO_STREAM_CALLBACKS) || defined(__DOXYGEN__) , uint8_t (* const Callback)(void) #endif - ) ATTR_NON_NULL_PTR_ARG(1); - - /* Function Aliases: */ - /** Alias for Pipe_Discard_Byte(). - */ - #define Pipe_Ignore_Byte() Pipe_Discard_Byte() - - /** Alias for Pipe_Discard_Word(). - */ - #define Pipe_Ignore_Word() Pipe_Discard_Word() - - /** Alias for Pipe_Discard_DWord(). - */ - #define Pipe_Ignore_DWord() Pipe_Discard_DWord() - - /** Alias for Pipe_Read_Word_LE(). By default USB transfers use little endian format, thus - * the command with no endianness specified indicates little endian mode. - */ - #define Pipe_Read_Word() Pipe_Read_Word_LE() - - /** Alias for Pipe_Write_Word_LE(). By default USB transfers use little endian format, thus - * the command with no endianness specified indicates little endian mode. - */ - #define Pipe_Write_Word(Word) Pipe_Write_Word_LE(Word) - - /** Alias for Pipe_Read_DWord_LE(). By default USB transfers use little endian format, thus - * the command with no endianness specified indicates little endian mode. - */ - #define Pipe_Read_DWord() Pipe_Read_DWord_LE() - - /** Alias for Pipe_Write_DWord_LE(). By default USB transfers use little endian format, thus - * the command with no endianness specified indicates little endian mode. - */ - #define Pipe_Write_DWord(DWord) Pipe_Write_DWord_LE(DWord) - - /** Alias for Pipe_Read_Stream_LE(). By default USB transfers use little endian format, thus - * the command with no endianness specified indicates little endian mode. - */ - #if !defined(NO_STREAM_CALLBACKS) - #define Pipe_Read_Stream(Buffer, Length, Callback) Pipe_Read_Stream_LE(Buffer, Length, Callback) - #else - #define Pipe_Read_Stream(Buffer, Length) Pipe_Read_Stream_LE(Buffer, Length) - #endif - - /** Alias for Pipe_Write_Stream_LE(). By default USB transfers use little endian format, thus - * the command with no endianness specified indicates little endian mode. - */ - #if !defined(NO_STREAM_CALLBACKS) - #define Pipe_Write_Stream(Buffer, Length, Callback) Pipe_Read_Stream_LE(Buffer, Length, Callback) - #else - #define Pipe_Write_Stream(Buffer, Length) Pipe_Read_Stream_LE(Buffer, Length) - #endif + ) ATTR_NON_NULL_PTR_ARG(1); /* Private Interface - For use in library only: */ #if !defined(__DOXYGEN__) @@ -794,5 +1013,7 @@ #if defined(__cplusplus) } #endif - + #endif + +/** @} */