Fixes to the MIDI device demos (ClassDriver, LowLevel); discard unused read-in events...

[pub/USBasp.git] / LUFA / Drivers / USB / LowLevel / Pipe.h

diff --git a/LUFA/Drivers/USB/LowLevel/Pipe.h b/LUFA/Drivers/USB/LowLevel/Pipe.h
index 7e81cf6..f3da9d1 100644 (file)
--- a/LUFA/Drivers/USB/LowLevel/Pipe.h
+++ b/LUFA/Drivers/USB/LowLevel/Pipe.h
@@ -158,90 +158,6 @@
                         */\r
                        #define PIPE_EPSIZE_MASK                0x7FF\r
 \r
                         */\r
                        #define PIPE_EPSIZE_MASK                0x7FF\r
 \r

-                       /** Interrupt definition for the pipe IN interrupt (for INTERRUPT type pipes). Should be used with\r
-                        *  the USB_INT_* macros located in USBInterrupt.h.\r
-                        *\r
-                        *  This interrupt will fire if enabled on an INTERRUPT type pipe if the pipe interrupt period has\r
-                        *  elapsed and the pipe is ready for the next packet from the attached device to be read out from its\r
-                        *  FIFO buffer (if received).\r
-                        *\r
-                        *  \note This interrupt must be enabled and cleared on *each* pipe which requires it (after the pipe\r
-                        *        is selected), and will fire the common pipe interrupt vector.\r
-                        *\r
-                        *  \see \ref ENDPOINT_PIPE_vect for more information on the common pipe and endpoint interrupt vector.\r
-                        */\r
-                       #define PIPE_INT_IN                     UPIENX, (1 << RXINE) , UPINTX, (1 << RXINI)\r
-\r
-                       /** Interrupt definition for the pipe OUT interrupt (for INTERRUPT type pipes). Should be used with\r
-                        *  the USB_INT_* macros located in USBInterrupt.h.\r
-                        *\r
-                        *  This interrupt will fire if enabled on an INTERRUPT type endpoint if a the pipe interrupt period\r
-                        *  has elapsed and the pipe is ready for a packet to be written to the pipe's FIFO buffer and sent\r
-                        *  to the attached device (if required).\r
-                        *  \r
-                        *  \note This interrupt must be enabled and cleared on *each* pipe which requires it (after the pipe\r
-                        *        is selected), and will fire the common pipe interrupt vector.\r
-                        *\r
-                        *  \see \ref ENDPOINT_PIPE_vect for more information on the common pipe and endpoint interrupt vector.\r
-                        */\r
-                       #define PIPE_INT_OUT                   UPIENX, (1 << TXOUTE), UPINTX, (1 << TXOUTI)\r
-\r
-                       /** Interrupt definition for the pipe SETUP bank ready interrupt (for CONTROL type pipes). Should be\r
-                        *  used with the USB_INT_* macros located in USBInterrupt.h.\r
-                        *\r
-                        *  This interrupt will fire if enabled on an CONTROL type pipe when the pipe is ready for a new\r
-                        *  control request.\r
-                        *\r
-                        *  \note This interrupt must be enabled and cleared on *each* pipe which requires it (after the pipe\r
-                        *        is selected), and will fire the common pipe interrupt vector.\r
-                        *\r
-                        *  \see \ref ENDPOINT_PIPE_vect for more information on the common pipe and endpoint interrupt vector.\r
-                        */\r
-                       #define PIPE_INT_SETUP                 UPIENX, (1 << TXSTPE) , UPINTX, (1 << TXSTPI)\r
-\r
-                       /** Interrupt definition for the pipe error interrupt. Should be used with the USB_INT_* macros\r
-                        *  located in USBInterrupt.h.\r
-                        *\r
-                        *  This interrupt will fire if enabled on a particular pipe if an error occurs on that pipe, such\r
-                        *  as a CRC mismatch error.\r
-                        *\r
-                        *  \note This interrupt must be enabled and cleared on *each* pipe which requires it (after the pipe\r
-                        *        is selected), and will fire the common pipe interrupt vector.\r
-                        *\r
-                        *  \see \ref ENDPOINT_PIPE_vect for more information on the common pipe and endpoint interrupt vector.\r
-                        *\r
-                        *  \see \ref Pipe_GetErrorFlags() for more information on the pipe errors.\r
-                        */\r
-                       #define PIPE_INT_ERROR                 UPIENX, (1 << PERRE), UPINTX, (1 << PERRI)\r
-\r
-                       /** Interrupt definition for the pipe NAK received interrupt. Should be used with the USB_INT_* macros\r
-                        *  located in USBInterrupt.h.\r
-                        *\r
-                        *  This interrupt will fire if enabled on a particular pipe if an attached device returns a NAK in\r
-                        *  response to a sent packet.\r
-                        *\r
-                        *  \note This interrupt must be enabled and cleared on *each* pipe which requires it (after the pipe\r
-                        *        is selected), and will fire the common pipe interrupt vector.\r
-                        *\r
-                        *  \see \ref ENDPOINT_PIPE_vect for more information on the common pipe and endpoint interrupt vector.\r
-                        *\r
-                        *  \see \ref Pipe_IsNAKReceived() for more information on pipe NAKs.\r
-                        */\r
-                       #define PIPE_INT_NAK                   UPIENX, (1 << NAKEDE), UPINTX, (1 << NAKEDI)\r
-\r
-                       /** Interrupt definition for the pipe STALL received interrupt. Should be used with the USB_INT_* macros\r
-                        *  located in USBInterrupt.h.\r
-                        *\r
-                        *  This interrupt will fire if enabled on a particular pipe if an attached device returns a STALL on the\r
-                        *  currently selected pipe. This will also fire if the pipe is an isochronous pipe and a CRC error occurs.\r
-                        *\r
-                        *  \note This interrupt must be enabled and cleared on *each* pipe which requires it (after the pipe\r
-                        *        is selected), and will fire the common pipe interrupt vector.\r
-                        *\r
-                        *  \see \ref ENDPOINT_PIPE_vect for more information on the common pipe and endpoint interrupt vector.\r
-                        */\r
-                       #define PIPE_INT_STALL                 UPIENX, (1 << RXSTALLE), UPINTX, (1 << RXSTALLI)\r
-\r

                /* Pseudo-Function Macros: */\r
                        #if defined(__DOXYGEN__)\r
                                /** Indicates the number of bytes currently stored in the current pipes's selected bank.\r
                /* Pseudo-Function Macros: */\r
                        #if defined(__DOXYGEN__)\r
                                /** Indicates the number of bytes currently stored in the current pipes's selected bank.\r


@@ -337,12 +253,6 @@
                                 */\r
                                static inline uint8_t Pipe_GetPipeInterrupts(void);\r
                                \r
                                 */\r
                                static inline uint8_t Pipe_GetPipeInterrupts(void);\r
                                \r

-                               /** Clears the interrupt flag for the specified pipe number.\r
-                                *\r
-                                *  \param PipeNumber  Index of the pipe whose interrupt flag is to be cleared\r
-                                */\r
-                               static inline void Pipe_ClearPipeInterrupt(uint8_t PipeNumber);\r
-                               \r

                                /** Determines if the specified pipe number has interrupted (valid only for INTERRUPT type\r
                                 *  pipes).\r
                                 *\r
                                /** Determines if the specified pipe number has interrupted (valid only for INTERRUPT type\r
                                 *  pipes).\r
                                 *\r


@@ -504,8 +414,6 @@
 \r
                                #define Pipe_GetPipeInterrupts()       UPINT\r
 \r
 \r
                                #define Pipe_GetPipeInterrupts()       UPINT\r
 \r

-                               #define Pipe_ClearPipeInterrupt(n)     MACROS{ UPINT &= ~(1 << n); }MACROE\r
-\r

                                #define Pipe_HasPipeInterrupted(n)     ((UPINT & (1 << n)) ? true : false)\r
 \r
                                #define Pipe_Unfreeze()                MACROS{ UPCONX &= ~(1 << PFREEZE); }MACROE\r
                                #define Pipe_HasPipeInterrupted(n)     ((UPINT & (1 << n)) ? true : false)\r
 \r
                                #define Pipe_Unfreeze()                MACROS{ UPCONX &= ~(1 << PFREEZE); }MACROE\r


@@ -801,7 +709,8 @@
                /* Function Prototypes: */\r
                        /** Configures the specified pipe number with the given pipe type, token, target endpoint number in the\r
                         *  attached device, bank size and banking mode. Pipes should be allocated in ascending order by their\r
                /* Function Prototypes: */\r
                        /** Configures the specified pipe number with the given pipe type, token, target endpoint number in the\r
                         *  attached device, bank size and banking mode. Pipes should be allocated in ascending order by their\r

-                        *  address in the device (i.e. pipe 1 should be configured before pipe 2 and so on).\r
+                        *  address in the device (i.e. pipe 1 should be configured before pipe 2 and so on) to prevent fragmentation\r
+                        *  of the USB FIFO memory.\r

                         *\r
                         *  The pipe type may be one of the EP_TYPE_* macros listed in LowLevel.h, the token may be one of the\r
                         *  PIPE_TOKEN_* masks.\r
                         *\r
                         *  The pipe type may be one of the EP_TYPE_* macros listed in LowLevel.h, the token may be one of the\r
                         *  PIPE_TOKEN_* masks.\r


@@ -814,6 +723,9 @@
                         *\r
                         *  A newly configured pipe is frozen by default, and must be unfrozen before use via the \ref Pipe_Unfreeze() macro.\r
                         *\r
                         *\r
                         *  A newly configured pipe is frozen by default, and must be unfrozen before use via the \ref Pipe_Unfreeze() macro.\r
                         *\r

+                        *  \note The default control pipe does not have to be manually configured, as it is automatically\r
+                        *  configured by the library internally.\r
+                        *\r

                         *  \note This routine will select the specified pipe, and the pipe will remain selected once the\r
                         *        routine completes regardless of if the pipe configuration succeeds.\r
                         *\r
                         *  \note This routine will select the specified pipe, and the pipe will remain selected once the\r
                         *        routine completes regardless of if the pipe configuration succeeds.\r
                         *\r


@@ -837,9 +749,9 @@
                         *  \ref Pipe_ClearOUT() macro. Between each USB packet, the given stream callback function is\r
                         *  executed repeatedly until the next packet is ready, allowing for early aborts of stream transfers.\r
                         *\r
                         *  \ref Pipe_ClearOUT() macro. Between each USB packet, the given stream callback function is\r
                         *  executed repeatedly until the next packet is ready, allowing for early aborts of stream transfers.\r
                         *\r

-                        *      The callback routine should be created using the \ref STREAM_CALLBACK() macro. If the token\r
-                        *  NO_STREAM_CALLBACKS is passed via the -D option to the compiler, stream callbacks are disabled\r
-                        *  and this function has the Callback parameter omitted.\r
+                        *      The callback routine should be created according to the information in \ref Group_StreamCallbacks.\r
+                        *  If the token NO_STREAM_CALLBACKS is passed via the -D option to the compiler, stream callbacks are\r
+                        *  disabled and this function has the Callback parameter omitted.\r

                         *\r
                         *  \ingroup Group_PipeRW\r
                         *\r
                         *\r
                         *  \ingroup Group_PipeRW\r
                         *\r


@@ -851,7 +763,7 @@
                         */\r
                        uint8_t Pipe_Write_Stream_LE(const void* Buffer, uint16_t Length\r
                        #if !defined(NO_STREAM_CALLBACKS) || defined(__DOXYGEN__)\r
                         */\r
                        uint8_t Pipe_Write_Stream_LE(const void* Buffer, uint16_t Length\r
                        #if !defined(NO_STREAM_CALLBACKS) || defined(__DOXYGEN__)\r

-                                                    , uint8_t (* const Callback)(void)\r
+                                                    , StreamCallbackPtr_t Callback\r

                        #endif\r
                                                     ) ATTR_NON_NULL_PTR_ARG(1);                                \r
 \r
                        #endif\r
                                                     ) ATTR_NON_NULL_PTR_ARG(1);                                \r
 \r


@@ -861,9 +773,9 @@
                         *  \ref Pipe_ClearOUT() macro. Between each USB packet, the given stream callback function is\r
                         *  executed repeatedly until the next packet is ready, allowing for early aborts of stream transfers.\r
                         *\r
                         *  \ref Pipe_ClearOUT() macro. Between each USB packet, the given stream callback function is\r
                         *  executed repeatedly until the next packet is ready, allowing for early aborts of stream transfers.\r
                         *\r

-                        *      The callback routine should be created using the \ref STREAM_CALLBACK() macro. If the token\r
-                        *  NO_STREAM_CALLBACKS is passed via the -D option to the compiler, stream callbacks are disabled\r
-                        *  and this function has the Callback parameter omitted.\r
+                        *      The callback routine should be created according to the information in \ref Group_StreamCallbacks.\r
+                        *  If the token NO_STREAM_CALLBACKS is passed via the -D option to the compiler, stream callbacks are\r
+                        *  disabled and this function has the Callback parameter omitted.\r

                         *\r
                         *  \ingroup Group_PipeRW\r
                         *\r
                         *\r
                         *  \ingroup Group_PipeRW\r
                         *\r


@@ -875,7 +787,7 @@
                         */\r
                        uint8_t Pipe_Write_Stream_BE(const void* Buffer, uint16_t Length\r
                        #if !defined(NO_STREAM_CALLBACKS) || defined(__DOXYGEN__)\r
                         */\r
                        uint8_t Pipe_Write_Stream_BE(const void* Buffer, uint16_t Length\r
                        #if !defined(NO_STREAM_CALLBACKS) || defined(__DOXYGEN__)\r

-                                                    , uint8_t (* const Callback)(void)\r
+                                                    , StreamCallbackPtr_t Callback\r

                        #endif\r
                                                     ) ATTR_NON_NULL_PTR_ARG(1);\r
 \r
                        #endif\r
                                                     ) ATTR_NON_NULL_PTR_ARG(1);\r
 \r


@@ -885,9 +797,9 @@
                         *  Between each USB packet, the given stream callback function is executed repeatedly until the next packet is ready,\r
                         *  allowing for early aborts of stream transfers.\r
                         *\r
                         *  Between each USB packet, the given stream callback function is executed repeatedly until the next packet is ready,\r
                         *  allowing for early aborts of stream transfers.\r
                         *\r

-                        *      The callback routine should be created using the \ref STREAM_CALLBACK() macro. If the token\r
-                        *  NO_STREAM_CALLBACKS is passed via the -D option to the compiler, stream callbacks are disabled\r
-                        *  and this function has the Callback parameter omitted.\r
+                        *      The callback routine should be created according to the information in \ref Group_StreamCallbacks.\r
+                        *  If the token NO_STREAM_CALLBACKS is passed via the -D option to the compiler, stream callbacks are\r
+                        *  disabled and this function has the Callback parameter omitted.\r

                         *\r
                         *  \ingroup Group_PipeRW\r
                         *\r
                         *\r
                         *  \ingroup Group_PipeRW\r
                         *\r


@@ -898,7 +810,7 @@
                         */\r
                        uint8_t Pipe_Discard_Stream(uint16_t Length\r
                        #if !defined(NO_STREAM_CALLBACKS) || defined(__DOXYGEN__)\r
                         */\r
                        uint8_t Pipe_Discard_Stream(uint16_t Length\r
                        #if !defined(NO_STREAM_CALLBACKS) || defined(__DOXYGEN__)\r

-                                                   , uint8_t (* const Callback)(void)\r
+                                                   , StreamCallbackPtr_t Callback\r

                        #endif\r
                                                    );\r
 \r
                        #endif\r
                                                    );\r
 \r


@@ -908,9 +820,9 @@
                         *  \ref Pipe_ClearIN() macro. Between each USB packet, the given stream callback function is\r
                         *  executed repeatedly until the next packet is ready, allowing for early aborts of stream transfers.\r
                         *\r
                         *  \ref Pipe_ClearIN() macro. Between each USB packet, the given stream callback function is\r
                         *  executed repeatedly until the next packet is ready, allowing for early aborts of stream transfers.\r
                         *\r

-                        *      The callback routine should be created using the \ref STREAM_CALLBACK() macro. If the token\r
-                        *  NO_STREAM_CALLBACKS is passed via the -D option to the compiler, stream callbacks are disabled\r
-                        *  and this function has the Callback parameter omitted.\r
+                        *      The callback routine should be created according to the information in \ref Group_StreamCallbacks.\r
+                        *  If the token NO_STREAM_CALLBACKS is passed via the -D option to the compiler, stream callbacks are\r
+                        *  disabled and this function has the Callback parameter omitted.\r

                         *\r
                         *  \ingroup Group_PipeRW\r
                         *\r
                         *\r
                         *  \ingroup Group_PipeRW\r
                         *\r


@@ -922,7 +834,7 @@
                         */\r
                        uint8_t Pipe_Read_Stream_LE(void* Buffer, uint16_t Length\r
                        #if !defined(NO_STREAM_CALLBACKS) || defined(__DOXYGEN__)\r
                         */\r
                        uint8_t Pipe_Read_Stream_LE(void* Buffer, uint16_t Length\r
                        #if !defined(NO_STREAM_CALLBACKS) || defined(__DOXYGEN__)\r

-                                                   , uint8_t (* const Callback)(void)\r
+                                                   , StreamCallbackPtr_t Callback\r

                        #endif\r
                                                    ) ATTR_NON_NULL_PTR_ARG(1);\r
 \r
                        #endif\r
                                                    ) ATTR_NON_NULL_PTR_ARG(1);\r
 \r


@@ -932,9 +844,9 @@
                         *  \ref Pipe_ClearIN() macro. Between each USB packet, the given stream callback function is\r
                         *  executed repeatedly until the next packet is ready, allowing for early aborts of stream transfers.\r
                         *\r
                         *  \ref Pipe_ClearIN() macro. Between each USB packet, the given stream callback function is\r
                         *  executed repeatedly until the next packet is ready, allowing for early aborts of stream transfers.\r
                         *\r

-                        *      The callback routine should be created using the \ref STREAM_CALLBACK() macro. If the token\r
-                        *  NO_STREAM_CALLBACKS is passed via the -D option to the compiler, stream callbacks are disabled\r
-                        *  and this function has the Callback parameter omitted.\r
+                        *      The callback routine should be created according to the information in \ref Group_StreamCallbacks.\r
+                        *  If the token NO_STREAM_CALLBACKS is passed via the -D option to the compiler, stream callbacks are\r
+                        *  disabled and this function has the Callback parameter omitted.\r

                         *\r
                         *  \ingroup Group_PipeRW\r
                         *\r
                         *\r
                         *  \ingroup Group_PipeRW\r
                         *\r


@@ -946,7 +858,7 @@
                         */\r
                        uint8_t Pipe_Read_Stream_BE(void* Buffer, uint16_t Length\r
                        #if !defined(NO_STREAM_CALLBACKS) || defined(__DOXYGEN__)\r
                         */\r
                        uint8_t Pipe_Read_Stream_BE(void* Buffer, uint16_t Length\r
                        #if !defined(NO_STREAM_CALLBACKS) || defined(__DOXYGEN__)\r

-                                                   , uint8_t (* const Callback)(void)\r
+                                                   , StreamCallbackPtr_t Callback\r

                        #endif\r
                                                    ) ATTR_NON_NULL_PTR_ARG(1);\r
                        \r
                        #endif\r
                                                    ) ATTR_NON_NULL_PTR_ARG(1);\r
                        \r