X-Git-Url: http://git.linex4red.de/pub/USBasp.git/blobdiff_plain/6a10d6b465be27db090d760dc0fbe722c94e4344..6be24e44046ffc386e2f4072aa5cccb1c462f47f:/LUFA/Drivers/USB/LowLevel/Pipe.h diff --git a/LUFA/Drivers/USB/LowLevel/Pipe.h b/LUFA/Drivers/USB/LowLevel/Pipe.h index a1f28ccc2..f3da9d1ce 100644 --- a/LUFA/Drivers/USB/LowLevel/Pipe.h +++ b/LUFA/Drivers/USB/LowLevel/Pipe.h @@ -27,14 +27,35 @@ arising out of or in connection with the use or performance of this software. */ + +/** \ingroup Group_USB + * @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 + * for various data types. + * + * @{ + */ -/** \file +/** @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 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 for various datatypes. + * Functions, macros, variables, enums and types related to packet management of pipes. */ +/** @defgroup Group_PipeControlReq Pipe Control Request Management + * + * Module for host mode request processing. This module allows for the transmission of standard, class and + * vendor control requests to the default control endpoint of an attached device while in host mode. + * + * \see Chapter 9 of the USB 2.0 specification. + */ + #ifndef __PIPE_H__ #define __PIPE_H__ @@ -46,8 +67,9 @@ #include "../HighLevel/USBTask.h" #if !defined(NO_STREAM_CALLBACKS) || defined(__DOXYGEN__) - #include "StreamCallbacks.h" + #include "../HighLevel/StreamCallbacks.h" #endif + /* Enable C linkage for C++ Compilers: */ #if defined(__cplusplus) extern "C" { @@ -55,322 +77,388 @@ /* Public Interface - May be used in end-application: */ /* Macros: */ - /** Mask for Pipe_GetErrorFlags(), indicating that a CRC error occurred in the pipe on the received data. */ - #define PIPE_ERRORFLAG_CRC16 (1 << 4) + /** Mask for \ref Pipe_GetErrorFlags(), indicating that a CRC error occurred in the pipe on the received data. */ + #define PIPE_ERRORFLAG_CRC16 (1 << 4) - /** Mask for Pipe_GetErrorFlags(), indicating that a hardware timeout error occurred in the pipe. */ - #define PIPE_ERRORFLAG_TIMEOUT (1 << 3) + /** Mask for \ref Pipe_GetErrorFlags(), indicating that a hardware timeout error occurred in the pipe. */ + #define PIPE_ERRORFLAG_TIMEOUT (1 << 3) - /** Mask for Pipe_GetErrorFlags(), indicating that a hardware PID error occurred in the pipe. */ - #define PIPE_ERRORFLAG_PID (1 << 2) + /** Mask for \ref Pipe_GetErrorFlags(), indicating that a hardware PID error occurred in the pipe. */ + #define PIPE_ERRORFLAG_PID (1 << 2) - /** Mask for Pipe_GetErrorFlags(), indicating that a hardware data PID error occurred in the pipe. */ - #define PIPE_ERRORFLAG_DATAPID (1 << 1) + /** Mask for \ref Pipe_GetErrorFlags(), indicating that a hardware data PID error occurred in the pipe. */ + #define PIPE_ERRORFLAG_DATAPID (1 << 1) - /** Mask for Pipe_GetErrorFlags(), indicating that a hardware data toggle error occurred in the pipe. */ - #define PIPE_ERRORFLAG_DATATGL (1 << 0) + /** Mask for \ref Pipe_GetErrorFlags(), indicating that a hardware data toggle error occurred in the pipe. */ + #define PIPE_ERRORFLAG_DATATGL (1 << 0) - /** Token mask for Pipe_ConfigurePipe(). This sets the pipe as a SETUP token (for CONTROL type pipes), + /** Token mask for \ref Pipe_ConfigurePipe(). This sets the pipe as a SETUP token (for CONTROL type pipes), * which will trigger a control request on the attached device when data is written to the pipe. */ - #define PIPE_TOKEN_SETUP (0b00 << PTOKEN0) + #define PIPE_TOKEN_SETUP (0 << PTOKEN0) - /** Token mask for 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 IN token (for non-CONTROL type pipes), * indicating that the pipe data will flow from device to host. */ - #define PIPE_TOKEN_IN (0b01 << PTOKEN0) + #define PIPE_TOKEN_IN (1 << PTOKEN0) - /** Token mask for 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 IN token (for non-CONTROL type pipes), * indicating that the pipe data will flow from host to device. */ - #define PIPE_TOKEN_OUT (0b10 << PTOKEN0) + #define PIPE_TOKEN_OUT (2 << PTOKEN0) - /** Mask for the bank mode selection for the Pipe_ConfigurePipe() macro. This indicates that the pipe + /** Mask for the bank mode selection for the \ref Pipe_ConfigurePipe() macro. This indicates that the pipe * should have one single bank, which requires less USB FIFO memory but results in slower transfers as * only one USB device (the AVR or the attached device) can access the pipe's bank at the one time. */ - #define PIPE_BANK_SINGLE 0 + #define PIPE_BANK_SINGLE (0 << EPBK0) - /** Mask for the bank mode selection for the Pipe_ConfigurePipe() macro. This indicates that the pipe + /** Mask for the bank mode selection for the \ref Pipe_ConfigurePipe() macro. This indicates that the pipe * should have two banks, which requires more USB FIFO memory but results in faster transfers as one * USB device (the AVR or the attached device) can access one bank while the other accesses the second * bank. */ - #define PIPE_BANK_DOUBLE (1 << EPBK0) + #define PIPE_BANK_DOUBLE (1 << EPBK0) /** Pipe address for the default control pipe, which always resides in address 0. This is * defined for convenience to give more readable code when used with the pipe macros. */ - #define PIPE_CONTROLPIPE 0 + #define PIPE_CONTROLPIPE 0 /** Default size of the default control pipe's bank, until altered by the Endpoint0Size value * in the device descriptor of the attached device. */ - #define PIPE_CONTROLPIPE_DEFAULT_SIZE 8 + #define PIPE_CONTROLPIPE_DEFAULT_SIZE 64 /** Pipe number mask, for masking against pipe addresses to retrieve the pipe's numerical address * in the device. */ - #define PIPE_PIPENUM_MASK 0x07 + #define PIPE_PIPENUM_MASK 0x07 /** Total number of pipes (including the default control pipe at address 0) which may be used in * the device. Different USB AVR models support different amounts of pipes, this value reflects * the maximum number of pipes for the currently selected AVR model. */ - #define PIPE_TOTAL_PIPES 7 + #define PIPE_TOTAL_PIPES 7 /** Size in bytes of the largest pipe bank size possible in the device. Not all banks on each AVR * model supports the largest bank size possible on the device; different pipe numbers support * different maximum bank sizes. This value reflects the largest possible bank of any pipe on the * currently selected USB AVR model. */ - #define PIPE_MAX_SIZE 256 + #define PIPE_MAX_SIZE 256 /** 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 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 - - /** Interrupt definition for the pipe IN interrupt (for INTERRUPT type pipes). Should be used with - * the USB_INT_* macros located in USBInterrupt.h. - * - * This interrupt will fire if enabled on an INTERRUPT type pipe if the pipe interrupt period has - * elapsed and the pipe is ready for the next packet from the attached device to be read out from its - * FIFO buffer (if received). - * - * This interrupt must be enabled on *each* pipe which requires it (after the pipe is selected), and - * will fire the common pipe interrupt vector. - * - * \see ENDPOINT_PIPE_vect for more information on the common pipe and endpoint interrupt vector. - */ - #define PIPE_INT_IN UPIENX, (1 << RXINE) , UPINTX, (1 << RXINI) - - /** Interrupt definition for the pipe OUT interrupt (for INTERRUPT type pipes). Should be used with - * the USB_INT_* macros located in USBInterrupt.h. - * - * This interrupt will fire if enabled on an INTERRUPT type endpoint if a the pipe interrupt period - * has elapsed and the pipe is ready for a packet to be written to the pipe's FIFO buffer and sent - * to the attached device (if required). - * - * This interrupt must be enabled on *each* pipe which requires it (after the pipe is selected), and - * will fire the common pipe interrupt vector. - * - * \see ENDPOINT_PIPE_vect for more information on the common pipe and endpoint interrupt vector. */ - #define PIPE_INT_OUT UPIENX, (1 << TXOUTE), UPINTX, (1 << TXOUTI) - - /** Interrupt definition for the pipe SETUP bank ready interrupt (for CONTROL type pipes). Should be - * used with the USB_INT_* macros located in USBInterrupt.h. - * - * This interrupt will fire if enabled on an CONTROL type pipe when the pipe is ready for a new - * control request. - * - * This interrupt must be enabled on *each* pipe which requires it (after the pipe is selected), and - * will fire the common pipe interrupt vector. - * - * \see ENDPOINT_PIPE_vect for more information on the common pipe and endpoint interrupt vector. - */ - #define PIPE_INT_SETUP UPIENX, (1 << TXSTPE) , UPINTX, (1 << TXSTPI) - - /** Interrupt definition for the pipe error interrupt. Should be used with the USB_INT_* macros - * located in USBInterrupt.h. - * - * This interrupt will fire if enabled on a particular pipe if an error occurs on that pipe, such - * as a CRC mismatch error. - * - * This interrupt must be enabled on *each* pipe which requires it (after the pipe is selected), and - * will fire the common pipe interrupt vector. - * - * \see ENDPOINT_PIPE_vect for more information on the common pipe and endpoint interrupt vector. - * - * \see Pipe_GetErrorFlags() for more information on the pipe errors. - */ - #define PIPE_INT_ERROR UPIENX, (1 << PERRE), UPINTX, (1 << PERRI) + #define PIPE_EPSIZE_MASK 0x7FF + + /* Pseudo-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 via \ref Pipe_ConfigurePipe(). + */ + 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); + + /** 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); - /** Interrupt definition for the pipe NAK received interrupt. Should be used with the USB_INT_* macros - * located in USBInterrupt.h. - * - * This interrupt will fire if enabled on a particular pipe if an attached device returns a NAK in - * response to a sent packet. - * - * This interrupt must be enabled on *each* pipe which requires it (after the pipe is selected), and - * will fire the common pipe interrupt vector. - * - * \see ENDPOINT_PIPE_vect for more information on the common pipe and endpoint interrupt vector. - * - * \see Pipe_IsNAKReceived() for more information on pipe NAKs. - */ - #define PIPE_INT_NAK UPIENX, (1 << NAKEDE), UPINTX, (1 << NAKEDI) + /** 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 \ref Pipe_GetErrorFlags() macro for information on retrieving the exact error flag. + * + * \return Boolean true if an error has occurred 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 occurred 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. + * + * \note This function is not valid on CONTROL type pipes. + * + * \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); + + /** Sends the currently selected CONTROL type pipe's contents to the device as a SETUP packet. + * + * \ingroup Group_PipePacketManagement + */ + static inline void Pipe_ClearSETUP(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 + */ + 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 + */ + 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 \ref 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 \ref 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 - /** Interrupt definition for the pipe STALL received interrupt. Should be used with the USB_INT_* macros - * located in USBInterrupt.h. - * - * This interrupt will fire if enabled on a particular pipe if an attached device returns a STALL on the - * currently selected pipe. This will also fire if the pipe is an isochronous pipe and a CRC error occurs. - * - * This interrupt must be enabled on *each* pipe which requires it (after the pipe is selected), and - * will fire the common pipe interrupt vector. - * - * \see ENDPOINT_PIPE_vect for more information on the common pipe and endpoint interrupt vector. - */ - #define PIPE_INT_STALL UPIENX, (1 << RXSTALLE), UPINTX, (1 << RXSTALLI) + #define Pipe_GetCurrentPipe() (UPNUM & PIPE_PIPENUM_MASK) - /** Indicates the number of bytes currently stored in the current pipe's selected bank. */ - #define Pipe_BytesInPipe() UPBCX + #define Pipe_SelectPipe(pipenum) MACROS{ UPNUM = pipenum; }MACROE + + #define Pipe_ResetPipe(pipenum) MACROS{ UPRST = (1 << pipenum); UPRST = 0; }MACROE - /** Resets the desired pipe, including the pipe banks and flags. */ - #define Pipe_ResetPipe(pipenum) MACROS{ UPRST = (1 << pipenum); UPRST = 0; }MACROE + #define Pipe_EnablePipe() MACROS{ UPCONX |= (1 << PEN); }MACROE - /** 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_DisablePipe() MACROS{ UPCONX &= ~(1 << PEN); }MACROE - /** 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_IsEnabled() ((UPCONX & (1 << PEN)) ? true : false) - /** 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_GetPipeToken() (UPCFG0X & PIPE_TOKEN_MASK) - /** 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_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 enabled, false otherwise. */ - #define Pipe_IsEnabled() ((UPCONX & (1 << PEN)) ? true : false) + #define Pipe_SetFiniteINRequests(n) MACROS{ UPCONX &= ~(1 << INMODE); UPINRQX = n; }MACROE - /** 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_IsConfigured() ((UPSTAX & (1 << CFGOK)) ? true : false) - /** 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_SetInterruptPeriod(ms) MACROS{ UPCFG2X = ms; }MACROE - /** Returns true if the currently selected pipe is configured, false otherwise. */ - #define Pipe_IsConfigured() ((UPSTAX & (1 << CFGOK)) ? true : false) + #define Pipe_GetPipeInterrupts() UPINT - /** 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_HasPipeInterrupted(n) ((UPINT & (1 << n)) ? 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_Unfreeze() MACROS{ UPCONX &= ~(1 << PFREEZE); }MACROE - /** Clears the interrupt flag for the specified pipe number. */ - #define Pipe_ClearPipeInterrupt(n) MACROS{ UPINT &= ~(1 << n); }MACROE + #define Pipe_Freeze() MACROS{ UPCONX |= (1 << PFREEZE); }MACROE - /** 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_ClearError() MACROS{ UPINTX &= ~(1 << PERRI); }MACROE - /** Unfreezes the pipe, allowing it to communicate with an attached device. */ - #define Pipe_Unfreeze() MACROS{ UPCONX &= ~(1 << PFREEZE); }MACROE + #define Pipe_IsError() ((UPINTX & (1 << PERRI)) ? true : false) + + #define Pipe_ClearErrorFlags() MACROS{ UPERRX = 0; }MACROE - /** Freezes the pipe, preventing it from communicating with an attached device. */ - #define Pipe_Freeze() MACROS{ UPCONX |= (1 << PFREEZE); }MACROE + #define Pipe_GetErrorFlags() UPERRX - /** Clears the master pipe error flag. */ - #define Pipe_ClearError() MACROS{ UPINTX &= ~(1 << PERRI); }MACROE + #define Pipe_IsReadWriteAllowed() ((UPINTX & (1 << RWAL)) ? true : false) - /** 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 retreiving 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_IsINReceived() ((UPINTX & (1 << RXINI)) ? true : false) - /** Returns a mask of the hardware error flags which have occured 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_IsOUTReady() ((UPINTX & (1 << TXOUTI)) ? true : false) - /** 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 occured 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_IsSETUPSent() ((UPINTX & (1 << TXSTPI)) ? true : false) - /** 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_ClearIN() MACROS{ uint8_t Temp = UPINTX; UPINTX = (Temp & ~(1 << RXINI)); \ + UPINTX = (Temp & ~(1 << FIFOCON)); }MACROE - /** Returns true if no SETUP request is currently being sent to the attached device, false otherwise. */ - #define Pipe_IsSetupSent() ((UPINTX & (1 << TXSTPI)) ? 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_ClearOUT() MACROS{ uint8_t Temp = UPINTX; UPINTX = (Temp & ~(1 << TXOUTI)); \ + UPINTX = (Temp & ~(1 << FIFOCON)); }MACROE + + #define Pipe_ClearSETUP() MACROS{ uint8_t Temp = UPINTX; UPINTX = (Temp & ~(1 << TXSTPI)); \ + UPINTX = (Temp & ~(1 << FIFOCON)); }MACROE - /** Clears the stall condition on the currently selected pipe. */ - #define Pipe_ClearStall() MACROS{ UPINTX &= ~(1 << RXSTALLI); }MACROE + #define Pipe_IsNAKReceived() ((UPINTX & (1 << NAKEDI)) ? 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) - - /** 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_ClearNAKReceived() MACROS{ UPINTX &= ~(1 << NAKEDI); }MACROE - /** Acknowedges 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_IsStalled() ((UPINTX & (1 << RXSTALLI)) ? true : false) - /** 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 Acknowedge) in response to the last sent packet on - * the currently selected pipe. This ocurrs 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 cleard using Pipe_ClearNAKReceived() before the previous (or any other) packet - * can be re-sent. - */ - #define Pipe_IsNAKReceived() ((UPINTX & (1 << NAKEDI)) ? true : false) + #define Pipe_ClearStall() MACROS{ UPINTX &= ~(1 << RXSTALLI); }MACROE + #endif - /** Clears the NAK condition on the currently selected pipe. + /* Enums: */ + /** Enum for the possible error return codes of the Pipe_WaitUntilReady function * - * \see Pipe_IsNAKReceived() for more details. + * \ingroup Group_PipeRW */ - #define Pipe_ClearNAKReceived() MACROS{ UPINTX &= ~(1 << NAKEDI); }MACROE - - /* Enums: */ - /** Enum for the possible error return codes of the Pipe_WaitUntilReady function */ enum Pipe_WaitUntilReady_ErrorCodes_t { PIPE_READYWAIT_NoError = 0, /**< Pipe ready for next packet, no error */ @@ -378,42 +466,60 @@ PIPE_READYWAIT_DeviceDisconnected = 2, /**< Device was disconnected from the host while waiting. */ PIPE_READYWAIT_Timeout = 3, /**< The device failed to accept or send the next packet * within the software timeout period set by the - * USB_STREAM_TIMEOUT_MS macro. + * \ref USB_STREAM_TIMEOUT_MS macro. */ }; - /** 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. */ - PIPE_RWSTREAM_ERROR_PipeStalled = 1, /**< The device stalled the pipe during the transfer. */ - PIPE_RWSTREAM_ERROR_DeviceDisconnected = 2, /**< Device was disconnected from the host during - * the transfer. - */ - PIPE_RWSTREAM_ERROR_Timeout = 3, /**< The device failed to accept or send the next packet - * within the software timeout period set by the - * USB_STREAM_TIMEOUT_MS macro. - */ - PIPE_RWSTREAM_ERROR_CallbackAborted = 4, /**< Indicates that the stream's callback function aborted - * the transfer early. - */ + PIPE_RWSTREAM_NoError = 0, /**< Command completed successfully, no error. */ + PIPE_RWSTREAM_PipeStalled = 1, /**< The device stalled the pipe during the transfer. */ + PIPE_RWSTREAM_DeviceDisconnected = 2, /**< Device was disconnected from the host during + * the transfer. + */ + PIPE_RWSTREAM_Timeout = 3, /**< The device failed to accept or send the next packet + * within the software timeout period set by the + * \ref USB_STREAM_TIMEOUT_MS macro. + */ + PIPE_RWSTREAM_CallbackAborted = 4, /**< Indicates that the stream's callback function aborted + * the transfer early. + */ }; /* Inline Functions: */ - /** Reads one byte from the currently selected pipe's bank, for OUT direction pipes. */ - static inline uint8_t Pipe_Read_Byte(void) ATTR_WARN_UNUSED_RESULT; + /** 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) { uint8_t Dummy; @@ -423,8 +529,12 @@ /** 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; + 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; @@ -437,8 +547,12 @@ /** 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; + 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; @@ -451,7 +565,12 @@ /** 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) { UPDATX = (Word & 0xFF); @@ -460,15 +579,24 @@ /** 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) { UPDATX = (Word >> 8); UPDATX = (Word & 0xFF); } - /** Discards two bytes from the currently selected pipe's bank, for OUT direction pipes. */ - 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; @@ -478,8 +606,12 @@ /** 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; + 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) { union @@ -498,8 +630,12 @@ /** 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; + 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) { union @@ -518,7 +654,12 @@ /** 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) { Pipe_Write_Word_LE(DWord); @@ -527,15 +668,24 @@ /** 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) { Pipe_Write_Word_BE(DWord >> 16); Pipe_Write_Word_BE(DWord); } - /** Discards four bytes from the currently selected pipe's bank, for OUT direction pipes. */ - static inline void Pipe_Ignore_DWord(void) + /** Discards four bytes from the currently selected pipe's bank, for OUT direction pipes. + * + * \ingroup Group_PipeRW + */ + static inline void Pipe_Discard_DWord(void) ATTR_ALWAYS_INLINE; + static inline void Pipe_Discard_DWord(void) { uint8_t Dummy; @@ -559,7 +709,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. @@ -568,9 +719,12 @@ * numbers can handle different maximum packet sizes - refer to the chosen USB AVR's datasheet to * determine the maximum bank size for each pipe. * - * The banking mode may be either PIPE_BANK_SINGLE or PIPE_BANK_DOUBLE. + * 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 Pipe_Unfreeze() macro. + * \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. @@ -583,7 +737,7 @@ /** Spinloops until the currently selected non-control pipe is ready for the next packed of data * to be read or written to it. * - * \note This routine should not be called on CONTROL type pipes. + * \ingroup Group_PipeRW * * \return A value from the Pipe_WaitUntilReady_ErrorCodes_t enum. */ @@ -592,176 +746,139 @@ /** 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 + * \ref 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 ommitted. + * 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_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 sucessive USB packet transfers, NULL if no callback + * \param Callback Name of a callback routine to call between successive USB packet transfers, NULL if no callback * - * \return A value from the Pipe_Stream_RW_ErrorCodes_t enum. + * \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__) - , uint8_t (* const Callback)(void) + , StreamCallbackPtr_t Callback #endif ) 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 - * Pipe_ClearCurrentBank() macro. Between each USB packet, the given stream callback function is + * \ref 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 ommitted. + * 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_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 sucessive USB packet transfers, NULL if no callback + * \param Callback Name of a callback routine to call between successive USB packet transfers, NULL if no callback * - * \return A value from the Pipe_Stream_RW_ErrorCodes_t enum. + * \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__) - , uint8_t (* const Callback)(void) + , StreamCallbackPtr_t Callback #endif ) 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 host via the Pipe_ClearCurrentBank() macro. + * 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 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 ommitted. + * 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_PipeRW * * \param Length Number of bytes to send via the currently selected pipe. - * \param Callback Name of a callback routine to call between sucessive USB packet transfers, NULL if no callback + * \param Callback Name of a callback routine to call between successive USB packet transfers, NULL if no callback * - * \return A value from the Pipe_Stream_RW_ErrorCodes_t enum. + * \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__) - , uint8_t (* const Callback)(void) + , StreamCallbackPtr_t Callback #endif ); /** 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 + * \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 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 ommitted. + * 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_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 sucessive USB packet transfers, NULL if no callback + * \param Callback Name of a callback routine to call between successive USB packet transfers, NULL if no callback * - * \return A value from the Pipe_Stream_RW_ErrorCodes_t enum. + * \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__) - , uint8_t (* const Callback)(void) + , StreamCallbackPtr_t Callback #endif ) 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; * 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 + * \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 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 ommitted. + * 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_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 sucessive USB packet transfers, NULL if no callback + * \param Callback Name of a callback routine to call between successive USB packet transfers, NULL if no callback * - * \return A value from the Pipe_Stream_RW_ErrorCodes_t enum. + * \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__) - , 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 specifier 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 specifier 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 specifier 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 specifier 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 specifier 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 specifier 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) + , StreamCallbackPtr_t Callback #endif + ) ATTR_NON_NULL_PTR_ARG(1); /* Private Interface - For use in library only: */ #if !defined(__DOXYGEN__) /* Macros: */ - #define PIPE_TOKEN_MASK (0x03 << PTOKEN0) + #define PIPE_TOKEN_MASK (0x03 << PTOKEN0) - #define Pipe_AllocateMemory() MACROS{ UPCFG1X |= (1 << ALLOC); }MACROE - #define Pipe_DeallocateMemory() MACROS{ UPCFG1X &= ~(1 << ALLOC); }MACROE + #if !defined(ENDPOINT_CONTROLEP) + #define ENDPOINT_CONTROLEP 0 + #endif + + #define Pipe_AllocateMemory() MACROS{ UPCFG1X |= (1 << ALLOC); }MACROE + #define Pipe_DeallocateMemory() MACROS{ UPCFG1X &= ~(1 << ALLOC); }MACROE /* Function Prototypes: */ void Pipe_ClearPipes(void); /* Inline Functions: */ - static inline uint8_t Pipe_BytesToEPSizeMask(uint16_t Bytes) ATTR_WARN_UNUSED_RESULT ATTR_CONST ATTR_ALWAYSINLINE; + static inline uint8_t Pipe_BytesToEPSizeMask(uint16_t Bytes) ATTR_WARN_UNUSED_RESULT ATTR_CONST ATTR_ALWAYS_INLINE; static inline uint8_t Pipe_BytesToEPSizeMask(uint16_t Bytes) { if (Bytes <= 8) @@ -772,7 +889,7 @@ return (2 << EPSIZE0); else if (Bytes <= 64) return (3 << EPSIZE0); - else if (Bytes <= (8 << 4)) + else if (Bytes <= 128) return (4 << EPSIZE0); else return (5 << EPSIZE0); @@ -784,5 +901,7 @@ #if defined(__cplusplus) } #endif - + #endif + +/** @} */