X-Git-Url: http://git.linex4red.de/pub/USBasp.git/blobdiff_plain/1c16ae399a9f924c15d9dec54cacb1320ff0a92f..e322f14620a1064efc4b3a98cf701efc48da81cc:/LUFA/Drivers/USB/LowLevel/Pipe.h diff --git a/LUFA/Drivers/USB/LowLevel/Pipe.h b/LUFA/Drivers/USB/LowLevel/Pipe.h index 9d8dded04..3e25d4976 100644 --- a/LUFA/Drivers/USB/LowLevel/Pipe.h +++ b/LUFA/Drivers/USB/LowLevel/Pipe.h @@ -1,21 +1,21 @@ /* LUFA Library - Copyright (C) Dean Camera, 2009. + Copyright (C) Dean Camera, 2010. dean [at] fourwalledcubicle [dot] com www.fourwalledcubicle.com */ /* - Copyright 2009 Dean Camera (dean [at] fourwalledcubicle [dot] com) - - Permission to use, copy, modify, and distribute this software - and its documentation for any purpose and without fee is hereby - granted, provided that the above copyright notice appear in all - copies and that both that the copyright notice and this - permission notice and warranty disclaimer appear in supporting - documentation, and that the name of the author not be used in - advertising or publicity pertaining to distribution of the + Copyright 2010 Dean Camera (dean [at] fourwalledcubicle [dot] com) + + Permission to use, copy, modify, distribute, and sell this + software and its documentation for any purpose is hereby granted + without fee, provided that the above copyright notice appear in + all copies and that both that the copyright notice and this + permission notice and warranty disclaimer appear in supporting + documentation, and that the name of the author not be used in + advertising or publicity pertaining to distribution of the software without specific, written prior permission. The author disclaim all warranties with regard to this @@ -27,18 +27,13 @@ arising out of or in connection with the use or performance of this software. */ - -/** \file - * - * 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. - */ /** \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. + * 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/receive functions + * for various data types. * * @{ */ @@ -48,6 +43,20 @@ * Functions, macros, variables, enums and types related to data reading and writing from and to pipes. */ +/** \ingroup Group_PipeRW + * @defgroup Group_PipePrimitiveRW Read/Write of Primitive Data Types + * + * Functions, macros, variables, enums and types related to data reading and writing of primitive data types + * from and to pipes. + */ + +/** \ingroup Group_PipeRW + * @defgroup Group_PipeStreamRW Read/Write of Multi-Byte Streams + * + * Functions, macros, variables, enums and types related to data reading and writing of data streams from + * and to pipes. + */ + /** @defgroup Group_PipePacketManagement Pipe Packet Management * * Functions, macros, variables, enums and types related to packet management of pipes. @@ -55,14 +64,19 @@ /** @defgroup Group_PipeControlReq Pipe Control Request Management * - * Functions, macros, variables, enums and types related to control request management of pipes. - */ + * 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__ /* Includes: */ #include + #include + #include #include #include "../../../Common/Common.h" @@ -77,45 +91,56 @@ extern "C" { #endif + /* Preprocessor Checks: */ + #if !defined(__INCLUDE_FROM_USB_DRIVER) + #error Do not include this file directly. Include LUFA/Drivers/USB.h instead. + #endif + /* Public Interface - May be used in end-application: */ /* Macros: */ - /** Mask for Pipe_GetErrorFlags(), indicating that a CRC error occurred in the pipe on the received data. */ + /** 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) - /** Mask for Pipe_GetErrorFlags(), indicating that a hardware timeout error occurred in the pipe. */ + /** 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. */ + /** 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. */ + /** 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. */ + /** 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 (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 (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 OUT token (for non-CONTROL type pipes), * indicating that the pipe data will flow from host to device. */ #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 << 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. @@ -130,7 +155,7 @@ /** 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. @@ -153,98 +178,14 @@ /** Endpoint number mask, for masking against endpoint addresses to retrieve the endpoint's * numerical address in the attached device. */ - #define PIPE_EPNUM_MASK 0x07 - - /** Endpoint bank size mask, for masking against endpoint addresses to retrieve the endpoint's - * bank size in the attached device. - */ - #define PIPE_EPSIZE_MASK 0x7FF + #define PIPE_EPNUM_MASK 0x0F - /** 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). - * - * \note This interrupt must be enabled and cleared 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. + /** Endpoint direction mask, for masking against endpoint addresses to retrieve the endpoint's + * direction for comparing with the ENDPOINT_DESCRIPTOR_DIR_* masks. */ - #define PIPE_INT_IN UPIENX, (1 << RXINE) , UPINTX, (1 << RXINI) + #define PIPE_EPDIR_MASK 0x80 - /** 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). - * - * \note This interrupt must be enabled and cleared 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. - * - * \note This interrupt must be enabled and cleared 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. - * - * \note This interrupt must be enabled and cleared 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) - - /** 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. - * - * \note This interrupt must be enabled and cleared 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) - - /** 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. - * - * \note This interrupt must be enabled and cleared 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) - - /* Psuedo-Function Macros: */ + /* Pseudo-Function Macros: */ #if defined(__DOXYGEN__) /** Indicates the number of bytes currently stored in the current pipes's selected bank. * @@ -267,21 +208,20 @@ /** 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); /** 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. + * \note Pipes must first be configured properly via \ref Pipe_ConfigurePipe(). */ static inline void Pipe_EnablePipe(void); @@ -300,14 +240,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); @@ -317,7 +257,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); @@ -327,9 +267,16 @@ */ static inline bool Pipe_IsConfigured(void); + /** Retrieves the endpoint number of the endpoint within the attached device that the currently selected + * pipe is bound to. + * + * \return Endpoint number the currently selected pipe is bound to + */ + static inline uint8_t Pipe_BoundEndpointNumber(void); + /** Sets the period between interrupts for an INTERRUPT type pipe to a specified number of milliseconds. * - * \param Milliseconds Number of milliseconds between each pipe poll + * \param[in] Milliseconds Number of milliseconds between each pipe poll */ static inline void Pipe_SetInterruptPeriod(uint8_t Milliseconds); @@ -340,16 +287,10 @@ */ 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 + * \param[in] PipeNumber Index of the pipe whose interrupt flag should be tested * * \return Boolean true if the specified pipe has interrupted, false otherwise */ @@ -361,15 +302,21 @@ /** Freezes the selected pipe, preventing it from communicating with an attached device. */ static inline void Pipe_Freeze(void); + /** Determines if the currently selected pipe is frozen, and not able to accept data. + * + * \return Boolean true if the currently selected pipe is frozen, false otherwise + */ + static inline bool Pipe_IsFrozen(void); + /** Clears the master pipe error flag. */ static inline void Pipe_ClearError(void); /** 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. + * \see \ref 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 + * \return Boolean true if an error has occurred on the selected pipe, false otherwise */ static inline bool Pipe_IsError(void); @@ -381,7 +328,7 @@ /** 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 + * \return Mask comprising of PIPE_ERRORFLAG_* bits indicating what error has occurred on the selected pipe */ static inline uint8_t Pipe_GetErrorFlags(void); @@ -391,6 +338,8 @@ * 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 @@ -422,38 +371,16 @@ */ 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. + * \ingroup Group_PipePacketManagement */ - static inline void Pipe_ClearControlSETUP(void); + 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 - * - * \note For CONTROL type pipes, use Pipe_ClearControlIN() instead. */ static inline void Pipe_ClearIN(void); @@ -461,15 +388,13 @@ * 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 + * received, it must be cleared using \ref Pipe_ClearNAKReceived() before the previous (or any other) packet * can be re-sent. * * \ingroup Group_PipePacketManagement @@ -482,7 +407,7 @@ * * \ingroup Group_PipePacketManagement * - * \see Pipe_IsNAKReceived() for more details. + * \see \ref Pipe_IsNAKReceived() for more details. */ static inline void Pipe_ClearNAKReceived(void); @@ -505,9 +430,9 @@ #define Pipe_GetCurrentPipe() (UPNUM & PIPE_PIPENUM_MASK) - #define Pipe_SelectPipe(pipenum) MACROS{ UPNUM = pipenum; }MACROE + #define Pipe_SelectPipe(pipenum) MACROS{ UPNUM = (pipenum); }MACROE - #define Pipe_ResetPipe(pipenum) MACROS{ UPRST = (1 << pipenum); UPRST = 0; }MACROE + #define Pipe_ResetPipe(pipenum) MACROS{ UPRST = (1 << (pipenum)); UPRST = 0; }MACROE #define Pipe_EnablePipe() MACROS{ UPCONX |= (1 << PEN); }MACROE @@ -517,25 +442,27 @@ #define Pipe_GetPipeToken() (UPCFG0X & PIPE_TOKEN_MASK) - #define Pipe_SetToken(token) MACROS{ UPCFG0X = ((UPCFG0X & ~PIPE_TOKEN_MASK) | token); }MACROE + #define Pipe_SetPipeToken(token) MACROS{ UPCFG0X = ((UPCFG0X & ~PIPE_TOKEN_MASK) | (token)); }MACROE #define Pipe_SetInfiniteINRequests() MACROS{ UPCONX |= (1 << INMODE); }MACROE - #define Pipe_SetFiniteINRequests(n) MACROS{ UPCONX &= ~(1 << INMODE); UPINRQX = n; }MACROE + #define Pipe_SetFiniteINRequests(n) MACROS{ UPCONX &= ~(1 << INMODE); UPINRQX = (n); }MACROE #define Pipe_IsConfigured() ((UPSTAX & (1 << CFGOK)) ? true : false) - #define Pipe_SetInterruptPeriod(ms) MACROS{ UPCFG2X = ms; }MACROE + #define Pipe_BoundEndpointNumber() ((UPCFG0X >> PEPNUM0) & PIPE_EPNUM_MASK) + + #define Pipe_SetInterruptPeriod(ms) MACROS{ UPCFG2X = (ms); }MACROE #define Pipe_GetPipeInterrupts() UPINT - #define Pipe_ClearPipeInterrupt(n) MACROS{ UPINT &= ~(1 << n); }MACROE - - #define Pipe_HasPipeInterrupted(n) ((UPINT & (1 << n)) ? true : false) + #define Pipe_HasPipeInterrupted(n) ((UPINT & (1 << (n))) ? true : false) #define Pipe_Unfreeze() MACROS{ UPCONX &= ~(1 << PFREEZE); }MACROE #define Pipe_Freeze() MACROS{ UPCONX |= (1 << PFREEZE); }MACROE + + #define Pipe_IsFrozen() ((UPCONX & (1 << PFREEZE)) ? true : false) #define Pipe_ClearError() MACROS{ UPINTX &= ~(1 << PERRI); }MACROE @@ -543,7 +470,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) @@ -556,16 +486,10 @@ #define Pipe_ClearIN() MACROS{ uint8_t Temp = UPINTX; UPINTX = (Temp & ~(1 << RXINI)); \ UPINTX = (Temp & ~(1 << FIFOCON)); }MACROE - #define Pipe_ClearControlIN() MACROS{ uint8_t Temp = UPINTX; UPINTX = (Temp & ~(1 << RXINI)); \ - UPINTX = (Temp & ~(1 << FIFOCON)); }MACROE - #define Pipe_ClearOUT() MACROS{ uint8_t Temp = UPINTX; UPINTX = (Temp & ~(1 << TXOUTI)); \ UPINTX = (Temp & ~(1 << FIFOCON)); }MACROE - #define Pipe_ClearControlOUT() MACROS{ uint8_t Temp = UPINTX; UPINTX = (Temp & ~(1 << TXOUTI)); \ - UPINTX = (Temp & ~(1 << FIFOCON)); }MACROE - - #define Pipe_ClearControlSETUP() MACROS{ uint8_t Temp = UPINTX; UPINTX = (Temp & ~(1 << TXSTPI)); \ + #define Pipe_ClearSETUP() MACROS{ uint8_t Temp = UPINTX; UPINTX = (Temp & ~(1 << TXSTPI)); \ UPINTX = (Temp & ~(1 << FIFOCON)); }MACROE #define Pipe_IsNAKReceived() ((UPINTX & (1 << NAKEDI)) ? true : false) @@ -589,7 +513,7 @@ 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. */ }; @@ -599,24 +523,24 @@ */ 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. * - * \ingroup Group_PipeRW + * \ingroup Group_PipePrimitiveRW * * \return Next byte in the currently selected pipe's FIFO buffer */ @@ -628,9 +552,9 @@ /** Writes one byte from the currently selected pipe's bank, for IN direction pipes. * - * \ingroup Group_PipeRW + * \ingroup Group_PipePrimitiveRW * - * \param Byte Next byte to write into the the currently selected pipe's FIFO buffer + * \param[in] Byte Next byte to write into the the currently selected pipe's FIFO buffer */ static inline void Pipe_Write_Byte(const uint8_t Byte) ATTR_ALWAYS_INLINE; static inline void Pipe_Write_Byte(const uint8_t Byte) @@ -640,7 +564,7 @@ /** Discards one byte from the currently selected pipe's bank, for OUT direction pipes. * - * \ingroup Group_PipeRW + * \ingroup Group_PipePrimitiveRW */ static inline void Pipe_Discard_Byte(void) ATTR_ALWAYS_INLINE; static inline void Pipe_Discard_Byte(void) @@ -653,45 +577,53 @@ /** Reads two bytes from the currently selected pipe's bank in little endian format, for OUT * direction pipes. * - * \ingroup Group_PipeRW + * \ingroup Group_PipePrimitiveRW * * \return Next word in the currently selected pipe's FIFO buffer */ static inline uint16_t Pipe_Read_Word_LE(void) ATTR_WARN_UNUSED_RESULT ATTR_ALWAYS_INLINE; static inline uint16_t Pipe_Read_Word_LE(void) { - uint16_t Data; + union + { + uint16_t Word; + uint8_t Bytes[2]; + } Data; - Data = UPDATX; - Data |= (((uint16_t)UPDATX) << 8); + Data.Bytes[0] = UPDATX; + Data.Bytes[1] = UPDATX; - return Data; + return Data.Word; } /** Reads two bytes from the currently selected pipe's bank in big endian format, for OUT * direction pipes. * - * \ingroup Group_PipeRW + * \ingroup Group_PipePrimitiveRW * * \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) { - uint16_t Data; + union + { + uint16_t Word; + uint8_t Bytes[2]; + } Data; - Data = (((uint16_t)UPDATX) << 8); - Data |= UPDATX; + Data.Bytes[1] = UPDATX; + Data.Bytes[0] = UPDATX; - return Data; + return Data.Word; } /** Writes two bytes to the currently selected pipe's bank in little endian format, for IN * direction pipes. * - * \ingroup Group_PipeRW + * \ingroup Group_PipePrimitiveRW * - * \param Word Next word to write to the currently selected pipe's FIFO buffer + * \param[in] Word Next word to write to the currently selected pipe's FIFO buffer */ static inline void Pipe_Write_Word_LE(const uint16_t Word) ATTR_ALWAYS_INLINE; static inline void Pipe_Write_Word_LE(const uint16_t Word) @@ -703,9 +635,9 @@ /** Writes two bytes to the currently selected pipe's bank in big endian format, for IN * direction pipes. * - * \ingroup Group_PipeRW + * \ingroup Group_PipePrimitiveRW * - * \param Word Next word to write to the currently selected pipe's FIFO buffer + * \param[in] Word Next word to write to the currently selected pipe's FIFO buffer */ static inline void Pipe_Write_Word_BE(const uint16_t Word) ATTR_ALWAYS_INLINE; static inline void Pipe_Write_Word_BE(const uint16_t Word) @@ -716,7 +648,7 @@ /** Discards two bytes from the currently selected pipe's bank, for OUT direction pipes. * - * \ingroup Group_PipeRW + * \ingroup Group_PipePrimitiveRW */ static inline void Pipe_Discard_Word(void) ATTR_ALWAYS_INLINE; static inline void Pipe_Discard_Word(void) @@ -730,7 +662,7 @@ /** Reads four bytes from the currently selected pipe's bank in little endian format, for OUT * direction pipes. * - * \ingroup Group_PipeRW + * \ingroup Group_PipePrimitiveRW * * \return Next double word in the currently selected pipe's FIFO buffer */ @@ -754,7 +686,7 @@ /** Reads four bytes from the currently selected pipe's bank in big endian format, for OUT * direction pipes. * - * \ingroup Group_PipeRW + * \ingroup Group_PipePrimitiveRW * * \return Next double word in the currently selected pipe's FIFO buffer */ @@ -778,37 +710,41 @@ /** Writes four bytes to the currently selected pipe's bank in little endian format, for IN * direction pipes. * - * \ingroup Group_PipeRW + * \ingroup Group_PipePrimitiveRW * - * \param DWord Next double word to write to the currently selected pipe's FIFO buffer + * \param[in] DWord Next double word to write to the currently selected pipe's FIFO buffer */ static inline void Pipe_Write_DWord_LE(const uint32_t DWord) ATTR_ALWAYS_INLINE; static inline void Pipe_Write_DWord_LE(const uint32_t DWord) { - Pipe_Write_Word_LE(DWord); - Pipe_Write_Word_LE(DWord >> 16); + UPDATX = (DWord & 0xFF); + UPDATX = (DWord >> 8); + UPDATX = (DWord >> 16); + UPDATX = (DWord >> 24); } /** Writes four bytes to the currently selected pipe's bank in big endian format, for IN * direction pipes. * - * \ingroup Group_PipeRW + * \ingroup Group_PipePrimitiveRW * - * \param DWord Next double word to write to the currently selected pipe's FIFO buffer + * \param[in] DWord Next double word to write to the currently selected pipe's FIFO buffer */ static inline void Pipe_Write_DWord_BE(const uint32_t DWord) ATTR_ALWAYS_INLINE; static inline void Pipe_Write_DWord_BE(const uint32_t DWord) { - Pipe_Write_Word_BE(DWord >> 16); - Pipe_Write_Word_BE(DWord); + UPDATX = (DWord >> 24); + UPDATX = (DWord >> 16); + UPDATX = (DWord >> 8); + UPDATX = (DWord & 0xFF); } /** Discards four bytes from the currently selected pipe's bank, for OUT direction pipes. * - * \ingroup Group_PipeRW + * \ingroup Group_PipePrimitiveRW */ - static inline void Pipe_Ignore_DWord(void) ATTR_ALWAYS_INLINE; - static inline void Pipe_Ignore_DWord(void) + static inline void Pipe_Discard_DWord(void) ATTR_ALWAYS_INLINE; + static inline void Pipe_Discard_DWord(void) { uint8_t Dummy; @@ -830,9 +766,16 @@ extern uint8_t USB_ControlPipeSize; /* Function Prototypes: */ + #if !defined(NO_STREAM_CALLBACKS) || defined(__DOXYGEN__) + #define __CALLBACK_PARAM , StreamCallbackPtr_t Callback + #else + #define __CALLBACK_PARAM + #endif + /** Configures the specified pipe number with the given pipe type, token, target endpoint number in the * attached device, bank size and banking mode. Pipes should be allocated in ascending order by their - * address in the device (i.e. pipe 1 should be configured before pipe 2 and so on). + * 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. @@ -841,9 +784,16 @@ * 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() + * 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(). * - * 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. @@ -853,141 +803,224 @@ bool Pipe_ConfigurePipe(const uint8_t Number, const uint8_t Type, const uint8_t Token, const uint8_t EndpointNumber, const uint16_t Size, const uint8_t Banks); - /** Spinloops until the currently selected non-control pipe is ready for the next packed of data - * to be read or written to it. - * - * \note This routine should not be called on CONTROL type pipes. + /** Spin-loops until the currently selected non-control pipe is ready for the next packed of data to be read + * or written to it, aborting in the case of an error condition (such as a timeout or device disconnect). * * \ingroup Group_PipeRW * * \return A value from the Pipe_WaitUntilReady_ErrorCodes_t enum. */ - uint8_t Pipe_WaitUntilReady(void); + uint8_t Pipe_WaitUntilReady(void); + + /** Determines if a pipe has been bound to the given device endpoint address. If a pipe which is bound to the given + * endpoint is found, it is automatically selected. + * + * \param[in] EndpointAddress Address and direction mask of the endpoint within the attached device to check + * + * \return Boolean true if a pipe bound to the given endpoint address of the specified direction is found, false + * otherwise + */ + bool Pipe_IsEndpointBound(const uint8_t EndpointAddress); + /** Reads and discards the given number of bytes from the pipe, discarding fully read packets from the host + * as needed. The last packet is not automatically discarded once the remaining bytes has been read; the + * user is responsible for manually discarding the last packet from the device via the \ref Pipe_ClearIN() macro. + * Between each USB packet, the given stream callback function is executed repeatedly until the next packet is ready, + * allowing for early aborts of stream transfers. + * + * The callback routine should be created according to the information in \ref Group_StreamCallbacks. + * If the token NO_STREAM_CALLBACKS is passed via the -D option to the compiler, stream callbacks are + * disabled and this function has the Callback parameter omitted. + * + * The pipe token is set automatically, thus this can be used on bi-directional pipes directly without + * having to explicitly change the data direction with a call to \ref Pipe_SetPipeToken(). + * + * \ingroup Group_PipeStreamRW + * + * \param[in] Length Number of bytes to send via the currently selected pipe. + * \param[in] Callback Name of a callback routine to call between successive USB packet transfers, NULL if no callback + * + * \return A value from the \ref Pipe_Stream_RW_ErrorCodes_t enum. + */ + uint8_t Pipe_Discard_Stream(uint16_t Length __CALLBACK_PARAM); + /** Writes the given number of bytes to the pipe from the given buffer in little endian, * sending full packets to the device as needed. The last packet filled is not automatically sent; * the user is responsible for manually sending the last written packet to the host via the - * Pipe_ClearOUT() 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 omitted. + * 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 + * The pipe token is set automatically, thus this can be used on bi-directional pipes directly without + * having to explicitly change the data direction with a call to \ref Pipe_SetPipeToken(). + * + * \ingroup Group_PipeStreamRW * - * \param 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 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) - #endif - ) ATTR_NON_NULL_PTR_ARG(1); + uint8_t Pipe_Write_Stream_LE(const void* Buffer, uint16_t Length __CALLBACK_PARAM) ATTR_NON_NULL_PTR_ARG(1); + /** EEPROM buffer source version of \ref Pipe_Write_Stream_LE(). + * + * \ingroup Group_PipeStreamRW + * + * \param[in] Buffer Pointer to the source data buffer to read from. + * \param[in] Length Number of bytes to read for the currently selected pipe into the buffer. + * \param[in] Callback Name of a callback routine to call between successive USB packet transfers, NULL if no callback + * + * \return A value from the \ref Pipe_Stream_RW_ErrorCodes_t enum. + */ + uint8_t Pipe_Write_EStream_LE(const void* Buffer, uint16_t Length __CALLBACK_PARAM) ATTR_NON_NULL_PTR_ARG(1); + + /** FLASH buffer source version of \ref Pipe_Write_Stream_LE(). + * + * \note The FLASH data must be located in the first 64KB of FLASH for this function to work correctly. + * + * \ingroup Group_PipeStreamRW + * + * \param[in] Buffer Pointer to the source data buffer to read from. + * \param[in] Length Number of bytes to read for the currently selected pipe into the buffer. + * \param[in] Callback Name of a callback routine to call between successive USB packet transfers, NULL if no callback + * + * \return A value from the \ref Pipe_Stream_RW_ErrorCodes_t enum. + */ + uint8_t Pipe_Write_PStream_LE(const void* Buffer, uint16_t Length __CALLBACK_PARAM) ATTR_NON_NULL_PTR_ARG(1); + /** Writes the given number of bytes to the pipe from the given buffer in big endian, * sending full packets to the device as needed. The last packet filled is not automatically sent; * the user is responsible for manually sending the last written packet to the host via the - * Pipe_ClearOUT() 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 omitted. + * 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 + * The pipe token is set automatically, thus this can be used on bi-directional pipes directly without + * having to explicitly change the data direction with a call to \ref Pipe_SetPipeToken(). + * + * \ingroup Group_PipeStreamRW * - * \param 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 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) - #endif - ) ATTR_NON_NULL_PTR_ARG(1); + uint8_t Pipe_Write_Stream_BE(const void* Buffer, uint16_t Length __CALLBACK_PARAM) ATTR_NON_NULL_PTR_ARG(1); - /** Reads and discards the given number of bytes from the pipe, discarding fully read packets from the host - * as needed. The last packet is not automatically discarded once the remaining bytes has been read; the - * user is responsible for manually discarding the last packet from the device via the Pipe_ClearIN() macro. - * Between each USB packet, the given stream callback function is executed repeatedly until the next packet is ready, - * allowing for early aborts of stream transfers. + /** EEPROM buffer source version of \ref Pipe_Write_Stream_BE(). * - * The callback routine should be created 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_PipeStreamRW * - * \ingroup Group_PipeRW + * \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 * - * \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 + * \return A value from the \ref Pipe_Stream_RW_ErrorCodes_t enum. + */ + uint8_t Pipe_Write_EStream_BE(const void* Buffer, uint16_t Length __CALLBACK_PARAM) ATTR_NON_NULL_PTR_ARG(1); + + /** FLASH buffer source version of \ref Pipe_Write_Stream_BE(). * - * \return A value from the Pipe_Stream_RW_ErrorCodes_t enum. + * \note The FLASH data must be located in the first 64KB of FLASH for this function to work correctly. + * + * \ingroup Group_PipeStreamRW + * + * \param[in] Buffer Pointer to the source data buffer to read from. + * \param[in] Length Number of bytes to read for the currently selected pipe into the buffer. + * \param[in] Callback Name of a callback routine to call between successive USB packet transfers, NULL if no callback + * + * \return A value from the \ref Pipe_Stream_RW_ErrorCodes_t enum. */ - uint8_t Pipe_Discard_Stream(uint16_t Length - #if !defined(NO_STREAM_CALLBACKS) || defined(__DOXYGEN__) - , uint8_t (* const Callback)(void) - #endif - ); + uint8_t Pipe_Write_PStream_BE(const void* Buffer, uint16_t Length __CALLBACK_PARAM) ATTR_NON_NULL_PTR_ARG(1); /** Reads the given number of bytes from the pipe into the given buffer in little endian, * sending full packets to the device as needed. The last packet filled is not automatically sent; * the user is responsible for manually sending the last written packet to the host via the - * Pipe_ClearIN() 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 omitted. + * 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 + * The pipe token is set automatically, thus this can be used on bi-directional pipes directly without + * having to explicitly change the data direction with a call to \ref Pipe_SetPipeToken(). + * + * \ingroup Group_PipeStreamRW * - * \param 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 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) - #endif - ) ATTR_NON_NULL_PTR_ARG(1); + uint8_t Pipe_Read_Stream_LE(void* Buffer, uint16_t Length __CALLBACK_PARAM) ATTR_NON_NULL_PTR_ARG(1); + + /** EEPROM buffer source version of \ref Pipe_Read_Stream_LE(). + * + * \ingroup Group_PipeStreamRW + * + * \param[out] Buffer Pointer to the source data buffer to write to. + * \param[in] Length Number of bytes to read for the currently selected pipe to read from. + * \param[in] Callback Name of a callback routine to call between successive USB packet transfers, NULL if no callback + * + * \return A value from the \ref Pipe_Stream_RW_ErrorCodes_t enum. + */ + uint8_t Pipe_Read_EStream_LE(void* Buffer, uint16_t Length __CALLBACK_PARAM) ATTR_NON_NULL_PTR_ARG(1); /** Reads the given number of bytes from the pipe into the given buffer in big endian, * sending full packets to the device as needed. The last packet filled is not automatically sent; * the user is responsible for manually sending the last written packet to the host via the - * Pipe_ClearIN() 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 omitted. + * 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 + * The pipe token is set automatically, thus this can be used on bi-directional pipes directly without + * having to explicitly change the data direction with a call to \ref Pipe_SetPipeToken(). + * + * \ingroup Group_PipeStreamRW * - * \param 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 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); + uint8_t Pipe_Read_Stream_BE(void* Buffer, uint16_t Length __CALLBACK_PARAM) ATTR_NON_NULL_PTR_ARG(1); + /** EEPROM buffer source version of \ref Pipe_Read_Stream_BE(). + * + * \ingroup Group_PipeStreamRW + * + * \param[out] Buffer Pointer to the source data buffer to write to. + * \param[in] Length Number of bytes to read for the currently selected pipe to read from. + * \param[in] Callback Name of a callback routine to call between successive USB packet transfers, NULL if no callback + * + * \return A value from the \ref Pipe_Stream_RW_ErrorCodes_t enum. + */ + uint8_t Pipe_Read_EStream_BE(void* Buffer, uint16_t Length __CALLBACK_PARAM) ATTR_NON_NULL_PTR_ARG(1); + /* Private Interface - For use in library only: */ #if !defined(__DOXYGEN__) /* Macros: */ #define PIPE_TOKEN_MASK (0x03 << PTOKEN0) + #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 @@ -1010,7 +1043,7 @@ return (4 << EPSIZE0); else return (5 << EPSIZE0); - }; + } #endif