diff options
author | Dean Camera <dean@fourwalledcubicle.com> | 2012-06-21 20:27:00 +0000 |
---|---|---|
committer | Dean Camera <dean@fourwalledcubicle.com> | 2012-06-21 20:27:00 +0000 |
commit | ef06eefc8b0160781cddea86c9005d32fb135c3c (patch) | |
tree | 89d3b991218bfe1ca12b772aaea4d97dd73f4cfa /LUFA/Drivers/USB/Core | |
parent | 393fc71d8e82f4be67fac7f7f33538b92555b4f9 (diff) | |
download | lufa-ef06eefc8b0160781cddea86c9005d32fb135c3c.tar.gz lufa-ef06eefc8b0160781cddea86c9005d32fb135c3c.tar.bz2 lufa-ef06eefc8b0160781cddea86c9005d32fb135c3c.zip |
Add svn:eol-style property on all source files where it was missing. Fix line endings of all makefile, *.c and *.h files.
Diffstat (limited to 'LUFA/Drivers/USB/Core')
-rw-r--r-- | LUFA/Drivers/USB/Core/AVR8/EndpointStream_AVR8.c | 546 | ||||
-rw-r--r-- | LUFA/Drivers/USB/Core/AVR8/EndpointStream_AVR8.h | 1294 | ||||
-rw-r--r-- | LUFA/Drivers/USB/Core/AVR8/PipeStream_AVR8.h | 882 | ||||
-rw-r--r-- | LUFA/Drivers/USB/Core/UC3/EndpointStream_UC3.c | 466 | ||||
-rw-r--r-- | LUFA/Drivers/USB/Core/UC3/EndpointStream_UC3.h | 866 | ||||
-rw-r--r-- | LUFA/Drivers/USB/Core/UC3/PipeStream_UC3.c | 332 | ||||
-rw-r--r-- | LUFA/Drivers/USB/Core/UC3/PipeStream_UC3.h | 702 | ||||
-rw-r--r-- | LUFA/Drivers/USB/Core/XMEGA/EndpointStream_XMEGA.c | 546 | ||||
-rw-r--r-- | LUFA/Drivers/USB/Core/XMEGA/EndpointStream_XMEGA.h | 1294 |
9 files changed, 3464 insertions, 3464 deletions
diff --git a/LUFA/Drivers/USB/Core/AVR8/EndpointStream_AVR8.c b/LUFA/Drivers/USB/Core/AVR8/EndpointStream_AVR8.c index 0117a1d66..a267be1ee 100644 --- a/LUFA/Drivers/USB/Core/AVR8/EndpointStream_AVR8.c +++ b/LUFA/Drivers/USB/Core/AVR8/EndpointStream_AVR8.c @@ -1,275 +1,275 @@ -/*
- LUFA Library
- Copyright (C) Dean Camera, 2012.
-
- dean [at] fourwalledcubicle [dot] com
- www.lufa-lib.org
-*/
-
-/*
- Copyright 2012 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
- software, including all implied warranties of merchantability
- and fitness. In no event shall the author be liable for any
- special, indirect or consequential damages or any damages
- whatsoever resulting from loss of use, data or profits, whether
- in an action of contract, negligence or other tortious action,
- arising out of or in connection with the use or performance of
- this software.
-*/
-
-#include "../../../../Common/Common.h"
-#if (ARCH == ARCH_AVR8)
-
-#define __INCLUDE_FROM_USB_DRIVER
-#include "../USBMode.h"
-
-#if defined(USB_CAN_BE_DEVICE)
-
-#include "EndpointStream_AVR8.h"
-
-#if !defined(CONTROL_ONLY_DEVICE)
-uint8_t Endpoint_Discard_Stream(uint16_t Length,
- uint16_t* const BytesProcessed)
-{
- uint8_t ErrorCode;
- uint16_t BytesInTransfer = 0;
-
- if ((ErrorCode = Endpoint_WaitUntilReady()))
- return ErrorCode;
-
- if (BytesProcessed != NULL)
- Length -= *BytesProcessed;
-
- while (Length)
- {
- if (!(Endpoint_IsReadWriteAllowed()))
- {
- Endpoint_ClearOUT();
-
- if (BytesProcessed != NULL)
- {
- *BytesProcessed += BytesInTransfer;
- return ENDPOINT_RWSTREAM_IncompleteTransfer;
- }
-
- if ((ErrorCode = Endpoint_WaitUntilReady()))
- return ErrorCode;
- }
- else
- {
- Endpoint_Discard_8();
-
- Length--;
- BytesInTransfer++;
- }
- }
-
- return ENDPOINT_RWSTREAM_NoError;
-}
-
-uint8_t Endpoint_Null_Stream(uint16_t Length,
- uint16_t* const BytesProcessed)
-{
- uint8_t ErrorCode;
- uint16_t BytesInTransfer = 0;
-
- if ((ErrorCode = Endpoint_WaitUntilReady()))
- return ErrorCode;
-
- if (BytesProcessed != NULL)
- Length -= *BytesProcessed;
-
- while (Length)
- {
- if (!(Endpoint_IsReadWriteAllowed()))
- {
- Endpoint_ClearIN();
-
- if (BytesProcessed != NULL)
- {
- *BytesProcessed += BytesInTransfer;
- return ENDPOINT_RWSTREAM_IncompleteTransfer;
- }
-
- if ((ErrorCode = Endpoint_WaitUntilReady()))
- return ErrorCode;
- }
- else
- {
- Endpoint_Write_8(0);
-
- Length--;
- BytesInTransfer++;
- }
- }
-
- return ENDPOINT_RWSTREAM_NoError;
-}
-
-/* The following abuses the C preprocessor in order to copy-paste common code with slight alterations,
- * so that the code needs to be written once. It is a crude form of templating to reduce code maintenance. */
-
-#define TEMPLATE_FUNC_NAME Endpoint_Write_Stream_LE
-#define TEMPLATE_BUFFER_TYPE const void*
-#define TEMPLATE_CLEAR_ENDPOINT() Endpoint_ClearIN()
-#define TEMPLATE_BUFFER_OFFSET(Length) 0
-#define TEMPLATE_BUFFER_MOVE(BufferPtr, Amount) BufferPtr += Amount
-#define TEMPLATE_TRANSFER_BYTE(BufferPtr) Endpoint_Write_8(*BufferPtr)
-#include "Template/Template_Endpoint_RW.c"
-
-#define TEMPLATE_FUNC_NAME Endpoint_Write_Stream_BE
-#define TEMPLATE_BUFFER_TYPE const void*
-#define TEMPLATE_CLEAR_ENDPOINT() Endpoint_ClearIN()
-#define TEMPLATE_BUFFER_OFFSET(Length) (Length - 1)
-#define TEMPLATE_BUFFER_MOVE(BufferPtr, Amount) BufferPtr -= Amount
-#define TEMPLATE_TRANSFER_BYTE(BufferPtr) Endpoint_Write_8(*BufferPtr)
-#include "Template/Template_Endpoint_RW.c"
-
-#define TEMPLATE_FUNC_NAME Endpoint_Read_Stream_LE
-#define TEMPLATE_BUFFER_TYPE void*
-#define TEMPLATE_CLEAR_ENDPOINT() Endpoint_ClearOUT()
-#define TEMPLATE_BUFFER_OFFSET(Length) 0
-#define TEMPLATE_BUFFER_MOVE(BufferPtr, Amount) BufferPtr += Amount
-#define TEMPLATE_TRANSFER_BYTE(BufferPtr) *BufferPtr = Endpoint_Read_8()
-#include "Template/Template_Endpoint_RW.c"
-
-#define TEMPLATE_FUNC_NAME Endpoint_Read_Stream_BE
-#define TEMPLATE_BUFFER_TYPE void*
-#define TEMPLATE_CLEAR_ENDPOINT() Endpoint_ClearOUT()
-#define TEMPLATE_BUFFER_OFFSET(Length) (Length - 1)
-#define TEMPLATE_BUFFER_MOVE(BufferPtr, Amount) BufferPtr -= Amount
-#define TEMPLATE_TRANSFER_BYTE(BufferPtr) *BufferPtr = Endpoint_Read_8()
-#include "Template/Template_Endpoint_RW.c"
-
-#if defined(ARCH_HAS_FLASH_ADDRESS_SPACE)
- #define TEMPLATE_FUNC_NAME Endpoint_Write_PStream_LE
- #define TEMPLATE_BUFFER_TYPE const void*
- #define TEMPLATE_CLEAR_ENDPOINT() Endpoint_ClearIN()
- #define TEMPLATE_BUFFER_OFFSET(Length) 0
- #define TEMPLATE_BUFFER_MOVE(BufferPtr, Amount) BufferPtr += Amount
- #define TEMPLATE_TRANSFER_BYTE(BufferPtr) Endpoint_Write_8(pgm_read_byte(BufferPtr))
- #include "Template/Template_Endpoint_RW.c"
-
- #define TEMPLATE_FUNC_NAME Endpoint_Write_PStream_BE
- #define TEMPLATE_BUFFER_TYPE const void*
- #define TEMPLATE_CLEAR_ENDPOINT() Endpoint_ClearIN()
- #define TEMPLATE_BUFFER_OFFSET(Length) (Length - 1)
- #define TEMPLATE_BUFFER_MOVE(BufferPtr, Amount) BufferPtr -= Amount
- #define TEMPLATE_TRANSFER_BYTE(BufferPtr) Endpoint_Write_8(pgm_read_byte(BufferPtr))
- #include "Template/Template_Endpoint_RW.c"
-#endif
-
-#if defined(ARCH_HAS_EEPROM_ADDRESS_SPACE)
- #define TEMPLATE_FUNC_NAME Endpoint_Write_EStream_LE
- #define TEMPLATE_BUFFER_TYPE const void*
- #define TEMPLATE_CLEAR_ENDPOINT() Endpoint_ClearIN()
- #define TEMPLATE_BUFFER_OFFSET(Length) 0
- #define TEMPLATE_BUFFER_MOVE(BufferPtr, Amount) BufferPtr += Amount
- #define TEMPLATE_TRANSFER_BYTE(BufferPtr) Endpoint_Write_8(eeprom_read_byte(BufferPtr))
- #include "Template/Template_Endpoint_RW.c"
-
- #define TEMPLATE_FUNC_NAME Endpoint_Write_EStream_BE
- #define TEMPLATE_BUFFER_TYPE const void*
- #define TEMPLATE_CLEAR_ENDPOINT() Endpoint_ClearIN()
- #define TEMPLATE_BUFFER_OFFSET(Length) (Length - 1)
- #define TEMPLATE_BUFFER_MOVE(BufferPtr, Amount) BufferPtr -= Amount
- #define TEMPLATE_TRANSFER_BYTE(BufferPtr) Endpoint_Write_8(eeprom_read_byte(BufferPtr))
- #include "Template/Template_Endpoint_RW.c"
-
- #define TEMPLATE_FUNC_NAME Endpoint_Read_EStream_LE
- #define TEMPLATE_BUFFER_TYPE void*
- #define TEMPLATE_CLEAR_ENDPOINT() Endpoint_ClearOUT()
- #define TEMPLATE_BUFFER_OFFSET(Length) 0
- #define TEMPLATE_BUFFER_MOVE(BufferPtr, Amount) BufferPtr += Amount
- #define TEMPLATE_TRANSFER_BYTE(BufferPtr) eeprom_update_byte(BufferPtr, Endpoint_Read_8())
- #include "Template/Template_Endpoint_RW.c"
-
- #define TEMPLATE_FUNC_NAME Endpoint_Read_EStream_BE
- #define TEMPLATE_BUFFER_TYPE void*
- #define TEMPLATE_CLEAR_ENDPOINT() Endpoint_ClearOUT()
- #define TEMPLATE_BUFFER_OFFSET(Length) (Length - 1)
- #define TEMPLATE_BUFFER_MOVE(BufferPtr, Amount) BufferPtr -= Amount
- #define TEMPLATE_TRANSFER_BYTE(BufferPtr) eeprom_update_byte(BufferPtr, Endpoint_Read_8())
- #include "Template/Template_Endpoint_RW.c"
-#endif
-
-#endif
-
-#define TEMPLATE_FUNC_NAME Endpoint_Write_Control_Stream_LE
-#define TEMPLATE_BUFFER_OFFSET(Length) 0
-#define TEMPLATE_BUFFER_MOVE(BufferPtr, Amount) BufferPtr += Amount
-#define TEMPLATE_TRANSFER_BYTE(BufferPtr) Endpoint_Write_8(*BufferPtr)
-#include "Template/Template_Endpoint_Control_W.c"
-
-#define TEMPLATE_FUNC_NAME Endpoint_Write_Control_Stream_BE
-#define TEMPLATE_BUFFER_OFFSET(Length) (Length - 1)
-#define TEMPLATE_BUFFER_MOVE(BufferPtr, Amount) BufferPtr -= Amount
-#define TEMPLATE_TRANSFER_BYTE(BufferPtr) Endpoint_Write_8(*BufferPtr)
-#include "Template/Template_Endpoint_Control_W.c"
-
-#define TEMPLATE_FUNC_NAME Endpoint_Read_Control_Stream_LE
-#define TEMPLATE_BUFFER_OFFSET(Length) 0
-#define TEMPLATE_BUFFER_MOVE(BufferPtr, Amount) BufferPtr += Amount
-#define TEMPLATE_TRANSFER_BYTE(BufferPtr) *BufferPtr = Endpoint_Read_8()
-#include "Template/Template_Endpoint_Control_R.c"
-
-#define TEMPLATE_FUNC_NAME Endpoint_Read_Control_Stream_BE
-#define TEMPLATE_BUFFER_OFFSET(Length) (Length - 1)
-#define TEMPLATE_BUFFER_MOVE(BufferPtr, Amount) BufferPtr -= Amount
-#define TEMPLATE_TRANSFER_BYTE(BufferPtr) *BufferPtr = Endpoint_Read_8()
-#include "Template/Template_Endpoint_Control_R.c"
-
-#if defined(ARCH_HAS_FLASH_ADDRESS_SPACE)
- #define TEMPLATE_FUNC_NAME Endpoint_Write_Control_PStream_LE
- #define TEMPLATE_BUFFER_OFFSET(Length) 0
- #define TEMPLATE_BUFFER_MOVE(BufferPtr, Amount) BufferPtr += Amount
- #define TEMPLATE_TRANSFER_BYTE(BufferPtr) Endpoint_Write_8(pgm_read_byte(BufferPtr))
- #include "Template/Template_Endpoint_Control_W.c"
-
- #define TEMPLATE_FUNC_NAME Endpoint_Write_Control_PStream_BE
- #define TEMPLATE_BUFFER_OFFSET(Length) (Length - 1)
- #define TEMPLATE_BUFFER_MOVE(BufferPtr, Amount) BufferPtr -= Amount
- #define TEMPLATE_TRANSFER_BYTE(BufferPtr) Endpoint_Write_8(pgm_read_byte(BufferPtr))
- #include "Template/Template_Endpoint_Control_W.c"
-#endif
-
-#if defined(ARCH_HAS_EEPROM_ADDRESS_SPACE)
- #define TEMPLATE_FUNC_NAME Endpoint_Write_Control_EStream_LE
- #define TEMPLATE_BUFFER_OFFSET(Length) 0
- #define TEMPLATE_BUFFER_MOVE(BufferPtr, Amount) BufferPtr += Amount
- #define TEMPLATE_TRANSFER_BYTE(BufferPtr) Endpoint_Write_8(eeprom_read_byte(BufferPtr))
- #include "Template/Template_Endpoint_Control_W.c"
-
- #define TEMPLATE_FUNC_NAME Endpoint_Write_Control_EStream_BE
- #define TEMPLATE_BUFFER_OFFSET(Length) (Length - 1)
- #define TEMPLATE_BUFFER_MOVE(BufferPtr, Amount) BufferPtr -= Amount
- #define TEMPLATE_TRANSFER_BYTE(BufferPtr) Endpoint_Write_8(eeprom_read_byte(BufferPtr))
- #include "Template/Template_Endpoint_Control_W.c"
-
- #define TEMPLATE_FUNC_NAME Endpoint_Read_Control_EStream_LE
- #define TEMPLATE_BUFFER_OFFSET(Length) 0
- #define TEMPLATE_BUFFER_MOVE(BufferPtr, Amount) BufferPtr += Amount
- #define TEMPLATE_TRANSFER_BYTE(BufferPtr) eeprom_update_byte(BufferPtr, Endpoint_Read_8())
- #include "Template/Template_Endpoint_Control_R.c"
-
- #define TEMPLATE_FUNC_NAME Endpoint_Read_Control_EStream_BE
- #define TEMPLATE_BUFFER_OFFSET(Length) (Length - 1)
- #define TEMPLATE_BUFFER_MOVE(BufferPtr, Amount) BufferPtr -= Amount
- #define TEMPLATE_TRANSFER_BYTE(BufferPtr) eeprom_update_byte(BufferPtr, Endpoint_Read_8())
- #include "Template/Template_Endpoint_Control_R.c"
-#endif
-
+/* + LUFA Library + Copyright (C) Dean Camera, 2012. + + dean [at] fourwalledcubicle [dot] com + www.lufa-lib.org +*/ + +/* + Copyright 2012 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 + software, including all implied warranties of merchantability + and fitness. In no event shall the author be liable for any + special, indirect or consequential damages or any damages + whatsoever resulting from loss of use, data or profits, whether + in an action of contract, negligence or other tortious action, + arising out of or in connection with the use or performance of + this software. +*/ + +#include "../../../../Common/Common.h" +#if (ARCH == ARCH_AVR8) + +#define __INCLUDE_FROM_USB_DRIVER +#include "../USBMode.h" + +#if defined(USB_CAN_BE_DEVICE) + +#include "EndpointStream_AVR8.h" + +#if !defined(CONTROL_ONLY_DEVICE) +uint8_t Endpoint_Discard_Stream(uint16_t Length, + uint16_t* const BytesProcessed) +{ + uint8_t ErrorCode; + uint16_t BytesInTransfer = 0; + + if ((ErrorCode = Endpoint_WaitUntilReady())) + return ErrorCode; + + if (BytesProcessed != NULL) + Length -= *BytesProcessed; + + while (Length) + { + if (!(Endpoint_IsReadWriteAllowed())) + { + Endpoint_ClearOUT(); + + if (BytesProcessed != NULL) + { + *BytesProcessed += BytesInTransfer; + return ENDPOINT_RWSTREAM_IncompleteTransfer; + } + + if ((ErrorCode = Endpoint_WaitUntilReady())) + return ErrorCode; + } + else + { + Endpoint_Discard_8(); + + Length--; + BytesInTransfer++; + } + } + + return ENDPOINT_RWSTREAM_NoError; +} + +uint8_t Endpoint_Null_Stream(uint16_t Length, + uint16_t* const BytesProcessed) +{ + uint8_t ErrorCode; + uint16_t BytesInTransfer = 0; + + if ((ErrorCode = Endpoint_WaitUntilReady())) + return ErrorCode; + + if (BytesProcessed != NULL) + Length -= *BytesProcessed; + + while (Length) + { + if (!(Endpoint_IsReadWriteAllowed())) + { + Endpoint_ClearIN(); + + if (BytesProcessed != NULL) + { + *BytesProcessed += BytesInTransfer; + return ENDPOINT_RWSTREAM_IncompleteTransfer; + } + + if ((ErrorCode = Endpoint_WaitUntilReady())) + return ErrorCode; + } + else + { + Endpoint_Write_8(0); + + Length--; + BytesInTransfer++; + } + } + + return ENDPOINT_RWSTREAM_NoError; +} + +/* The following abuses the C preprocessor in order to copy-paste common code with slight alterations, + * so that the code needs to be written once. It is a crude form of templating to reduce code maintenance. */ + +#define TEMPLATE_FUNC_NAME Endpoint_Write_Stream_LE +#define TEMPLATE_BUFFER_TYPE const void* +#define TEMPLATE_CLEAR_ENDPOINT() Endpoint_ClearIN() +#define TEMPLATE_BUFFER_OFFSET(Length) 0 +#define TEMPLATE_BUFFER_MOVE(BufferPtr, Amount) BufferPtr += Amount +#define TEMPLATE_TRANSFER_BYTE(BufferPtr) Endpoint_Write_8(*BufferPtr) +#include "Template/Template_Endpoint_RW.c" + +#define TEMPLATE_FUNC_NAME Endpoint_Write_Stream_BE +#define TEMPLATE_BUFFER_TYPE const void* +#define TEMPLATE_CLEAR_ENDPOINT() Endpoint_ClearIN() +#define TEMPLATE_BUFFER_OFFSET(Length) (Length - 1) +#define TEMPLATE_BUFFER_MOVE(BufferPtr, Amount) BufferPtr -= Amount +#define TEMPLATE_TRANSFER_BYTE(BufferPtr) Endpoint_Write_8(*BufferPtr) +#include "Template/Template_Endpoint_RW.c" + +#define TEMPLATE_FUNC_NAME Endpoint_Read_Stream_LE +#define TEMPLATE_BUFFER_TYPE void* +#define TEMPLATE_CLEAR_ENDPOINT() Endpoint_ClearOUT() +#define TEMPLATE_BUFFER_OFFSET(Length) 0 +#define TEMPLATE_BUFFER_MOVE(BufferPtr, Amount) BufferPtr += Amount +#define TEMPLATE_TRANSFER_BYTE(BufferPtr) *BufferPtr = Endpoint_Read_8() +#include "Template/Template_Endpoint_RW.c" + +#define TEMPLATE_FUNC_NAME Endpoint_Read_Stream_BE +#define TEMPLATE_BUFFER_TYPE void* +#define TEMPLATE_CLEAR_ENDPOINT() Endpoint_ClearOUT() +#define TEMPLATE_BUFFER_OFFSET(Length) (Length - 1) +#define TEMPLATE_BUFFER_MOVE(BufferPtr, Amount) BufferPtr -= Amount +#define TEMPLATE_TRANSFER_BYTE(BufferPtr) *BufferPtr = Endpoint_Read_8() +#include "Template/Template_Endpoint_RW.c" + +#if defined(ARCH_HAS_FLASH_ADDRESS_SPACE) + #define TEMPLATE_FUNC_NAME Endpoint_Write_PStream_LE + #define TEMPLATE_BUFFER_TYPE const void* + #define TEMPLATE_CLEAR_ENDPOINT() Endpoint_ClearIN() + #define TEMPLATE_BUFFER_OFFSET(Length) 0 + #define TEMPLATE_BUFFER_MOVE(BufferPtr, Amount) BufferPtr += Amount + #define TEMPLATE_TRANSFER_BYTE(BufferPtr) Endpoint_Write_8(pgm_read_byte(BufferPtr)) + #include "Template/Template_Endpoint_RW.c" + + #define TEMPLATE_FUNC_NAME Endpoint_Write_PStream_BE + #define TEMPLATE_BUFFER_TYPE const void* + #define TEMPLATE_CLEAR_ENDPOINT() Endpoint_ClearIN() + #define TEMPLATE_BUFFER_OFFSET(Length) (Length - 1) + #define TEMPLATE_BUFFER_MOVE(BufferPtr, Amount) BufferPtr -= Amount + #define TEMPLATE_TRANSFER_BYTE(BufferPtr) Endpoint_Write_8(pgm_read_byte(BufferPtr)) + #include "Template/Template_Endpoint_RW.c" +#endif + +#if defined(ARCH_HAS_EEPROM_ADDRESS_SPACE) + #define TEMPLATE_FUNC_NAME Endpoint_Write_EStream_LE + #define TEMPLATE_BUFFER_TYPE const void* + #define TEMPLATE_CLEAR_ENDPOINT() Endpoint_ClearIN() + #define TEMPLATE_BUFFER_OFFSET(Length) 0 + #define TEMPLATE_BUFFER_MOVE(BufferPtr, Amount) BufferPtr += Amount + #define TEMPLATE_TRANSFER_BYTE(BufferPtr) Endpoint_Write_8(eeprom_read_byte(BufferPtr)) + #include "Template/Template_Endpoint_RW.c" + + #define TEMPLATE_FUNC_NAME Endpoint_Write_EStream_BE + #define TEMPLATE_BUFFER_TYPE const void* + #define TEMPLATE_CLEAR_ENDPOINT() Endpoint_ClearIN() + #define TEMPLATE_BUFFER_OFFSET(Length) (Length - 1) + #define TEMPLATE_BUFFER_MOVE(BufferPtr, Amount) BufferPtr -= Amount + #define TEMPLATE_TRANSFER_BYTE(BufferPtr) Endpoint_Write_8(eeprom_read_byte(BufferPtr)) + #include "Template/Template_Endpoint_RW.c" + + #define TEMPLATE_FUNC_NAME Endpoint_Read_EStream_LE + #define TEMPLATE_BUFFER_TYPE void* + #define TEMPLATE_CLEAR_ENDPOINT() Endpoint_ClearOUT() + #define TEMPLATE_BUFFER_OFFSET(Length) 0 + #define TEMPLATE_BUFFER_MOVE(BufferPtr, Amount) BufferPtr += Amount + #define TEMPLATE_TRANSFER_BYTE(BufferPtr) eeprom_update_byte(BufferPtr, Endpoint_Read_8()) + #include "Template/Template_Endpoint_RW.c" + + #define TEMPLATE_FUNC_NAME Endpoint_Read_EStream_BE + #define TEMPLATE_BUFFER_TYPE void* + #define TEMPLATE_CLEAR_ENDPOINT() Endpoint_ClearOUT() + #define TEMPLATE_BUFFER_OFFSET(Length) (Length - 1) + #define TEMPLATE_BUFFER_MOVE(BufferPtr, Amount) BufferPtr -= Amount + #define TEMPLATE_TRANSFER_BYTE(BufferPtr) eeprom_update_byte(BufferPtr, Endpoint_Read_8()) + #include "Template/Template_Endpoint_RW.c" #endif -#endif
+#endif + +#define TEMPLATE_FUNC_NAME Endpoint_Write_Control_Stream_LE +#define TEMPLATE_BUFFER_OFFSET(Length) 0 +#define TEMPLATE_BUFFER_MOVE(BufferPtr, Amount) BufferPtr += Amount +#define TEMPLATE_TRANSFER_BYTE(BufferPtr) Endpoint_Write_8(*BufferPtr) +#include "Template/Template_Endpoint_Control_W.c" + +#define TEMPLATE_FUNC_NAME Endpoint_Write_Control_Stream_BE +#define TEMPLATE_BUFFER_OFFSET(Length) (Length - 1) +#define TEMPLATE_BUFFER_MOVE(BufferPtr, Amount) BufferPtr -= Amount +#define TEMPLATE_TRANSFER_BYTE(BufferPtr) Endpoint_Write_8(*BufferPtr) +#include "Template/Template_Endpoint_Control_W.c" + +#define TEMPLATE_FUNC_NAME Endpoint_Read_Control_Stream_LE +#define TEMPLATE_BUFFER_OFFSET(Length) 0 +#define TEMPLATE_BUFFER_MOVE(BufferPtr, Amount) BufferPtr += Amount +#define TEMPLATE_TRANSFER_BYTE(BufferPtr) *BufferPtr = Endpoint_Read_8() +#include "Template/Template_Endpoint_Control_R.c" + +#define TEMPLATE_FUNC_NAME Endpoint_Read_Control_Stream_BE +#define TEMPLATE_BUFFER_OFFSET(Length) (Length - 1) +#define TEMPLATE_BUFFER_MOVE(BufferPtr, Amount) BufferPtr -= Amount +#define TEMPLATE_TRANSFER_BYTE(BufferPtr) *BufferPtr = Endpoint_Read_8() +#include "Template/Template_Endpoint_Control_R.c" + +#if defined(ARCH_HAS_FLASH_ADDRESS_SPACE) + #define TEMPLATE_FUNC_NAME Endpoint_Write_Control_PStream_LE + #define TEMPLATE_BUFFER_OFFSET(Length) 0 + #define TEMPLATE_BUFFER_MOVE(BufferPtr, Amount) BufferPtr += Amount + #define TEMPLATE_TRANSFER_BYTE(BufferPtr) Endpoint_Write_8(pgm_read_byte(BufferPtr)) + #include "Template/Template_Endpoint_Control_W.c" + + #define TEMPLATE_FUNC_NAME Endpoint_Write_Control_PStream_BE + #define TEMPLATE_BUFFER_OFFSET(Length) (Length - 1) + #define TEMPLATE_BUFFER_MOVE(BufferPtr, Amount) BufferPtr -= Amount + #define TEMPLATE_TRANSFER_BYTE(BufferPtr) Endpoint_Write_8(pgm_read_byte(BufferPtr)) + #include "Template/Template_Endpoint_Control_W.c" +#endif + +#if defined(ARCH_HAS_EEPROM_ADDRESS_SPACE) + #define TEMPLATE_FUNC_NAME Endpoint_Write_Control_EStream_LE + #define TEMPLATE_BUFFER_OFFSET(Length) 0 + #define TEMPLATE_BUFFER_MOVE(BufferPtr, Amount) BufferPtr += Amount + #define TEMPLATE_TRANSFER_BYTE(BufferPtr) Endpoint_Write_8(eeprom_read_byte(BufferPtr)) + #include "Template/Template_Endpoint_Control_W.c" + + #define TEMPLATE_FUNC_NAME Endpoint_Write_Control_EStream_BE + #define TEMPLATE_BUFFER_OFFSET(Length) (Length - 1) + #define TEMPLATE_BUFFER_MOVE(BufferPtr, Amount) BufferPtr -= Amount + #define TEMPLATE_TRANSFER_BYTE(BufferPtr) Endpoint_Write_8(eeprom_read_byte(BufferPtr)) + #include "Template/Template_Endpoint_Control_W.c" + + #define TEMPLATE_FUNC_NAME Endpoint_Read_Control_EStream_LE + #define TEMPLATE_BUFFER_OFFSET(Length) 0 + #define TEMPLATE_BUFFER_MOVE(BufferPtr, Amount) BufferPtr += Amount + #define TEMPLATE_TRANSFER_BYTE(BufferPtr) eeprom_update_byte(BufferPtr, Endpoint_Read_8()) + #include "Template/Template_Endpoint_Control_R.c" + + #define TEMPLATE_FUNC_NAME Endpoint_Read_Control_EStream_BE + #define TEMPLATE_BUFFER_OFFSET(Length) (Length - 1) + #define TEMPLATE_BUFFER_MOVE(BufferPtr, Amount) BufferPtr -= Amount + #define TEMPLATE_TRANSFER_BYTE(BufferPtr) eeprom_update_byte(BufferPtr, Endpoint_Read_8()) + #include "Template/Template_Endpoint_Control_R.c" +#endif + +#endif + +#endif diff --git a/LUFA/Drivers/USB/Core/AVR8/EndpointStream_AVR8.h b/LUFA/Drivers/USB/Core/AVR8/EndpointStream_AVR8.h index 072d85932..2d98ef4d6 100644 --- a/LUFA/Drivers/USB/Core/AVR8/EndpointStream_AVR8.h +++ b/LUFA/Drivers/USB/Core/AVR8/EndpointStream_AVR8.h @@ -1,648 +1,648 @@ -/*
- LUFA Library
- Copyright (C) Dean Camera, 2012.
-
- dean [at] fourwalledcubicle [dot] com
- www.lufa-lib.org
-*/
-
-/*
- Copyright 2012 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
- software, including all implied warranties of merchantability
- and fitness. In no event shall the author be liable for any
- special, indirect or consequential damages or any damages
- whatsoever resulting from loss of use, data or profits, whether
- in an action of contract, negligence or other tortious action,
- arising out of or in connection with the use or performance of
- this software.
-*/
-
-/** \file
- * \brief Endpoint data stream transmission and reception management for the AVR8 microcontrollers.
- * \copydetails Group_EndpointStreamRW_AVR8
- *
- * \note This file should not be included directly. It is automatically included as needed by the USB driver
- * dispatch header located in LUFA/Drivers/USB/USB.h.
- */
-
-/** \ingroup Group_EndpointStreamRW
- * \defgroup Group_EndpointStreamRW_AVR8 Read/Write of Multi-Byte Streams (AVR8)
- * \brief Endpoint data stream transmission and reception management for the Atmel AVR8 architecture.
- *
- * Functions, macros, variables, enums and types related to data reading and writing of data streams from
- * and to endpoints.
- *
- * @{
- */
-
-#ifndef __ENDPOINT_STREAM_AVR8_H__
-#define __ENDPOINT_STREAM_AVR8_H__
-
- /* Includes: */
- #include "../../../../Common/Common.h"
- #include "../USBMode.h"
- #include "../USBTask.h"
-
- /* Enable C linkage for C++ Compilers: */
- #if defined(__cplusplus)
- extern "C" {
- #endif
-
- /* Preprocessor Checks: */
- #if !defined(__INCLUDE_FROM_USB_DRIVER)
- #error Do not include this file directly. Include LUFA/Drivers/USB/USB.h instead.
- #endif
-
- /* Public Interface - May be used in end-application: */
- /* Function Prototypes: */
- /** \name Stream functions for null data */
- //@{
-
- /** Reads and discards the given number of bytes from the currently selected endpoint's bank,
- * 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 \ref Endpoint_ClearOUT() macro.
- *
- * If the BytesProcessed parameter is \c NULL, the entire stream transfer is attempted at once,
- * failing or succeeding as a single unit. If the BytesProcessed parameter points to a valid
- * storage location, the transfer will instead be performed as a series of chunks. Each time
- * the endpoint bank becomes empty while there is still data to process (and after the current
- * packet has been acknowledged) the BytesProcessed location will be updated with the total number
- * of bytes processed in the stream, and the function will exit with an error code of
- * \ref ENDPOINT_RWSTREAM_IncompleteTransfer. This allows for any abort checking to be performed
- * in the user code - to continue the transfer, call the function again with identical parameters
- * and it will resume until the BytesProcessed value reaches the total transfer length.
- *
- * <b>Single Stream Transfer Example:</b>
- * \code
- * uint8_t ErrorCode;
- *
- * if ((ErrorCode = Endpoint_Discard_Stream(512, NULL)) != ENDPOINT_RWSTREAM_NoError)
- * {
- * // Stream failed to complete - check ErrorCode here
- * }
- * \endcode
- *
- * <b>Partial Stream Transfers Example:</b>
- * \code
- * uint8_t ErrorCode;
- * uint16_t BytesProcessed;
- *
- * BytesProcessed = 0;
- * while ((ErrorCode = Endpoint_Discard_Stream(512, &BytesProcessed)) == ENDPOINT_RWSTREAM_IncompleteTransfer)
- * {
- * // Stream not yet complete - do other actions here, abort if required
- * }
- *
- * if (ErrorCode != ENDPOINT_RWSTREAM_NoError)
- * {
- * // Stream failed to complete - check ErrorCode here
- * }
- * \endcode
- *
- * \note This routine should not be used on CONTROL type endpoints.
- *
- * \param[in] Length Number of bytes to discard via the currently selected endpoint.
- * \param[in] BytesProcessed Pointer to a location where the total number of bytes processed in the current
- * transaction should be updated, \c NULL if the entire stream should be read at once.
- *
- * \return A value from the \ref Endpoint_Stream_RW_ErrorCodes_t enum.
- */
- uint8_t Endpoint_Discard_Stream(uint16_t Length,
- uint16_t* const BytesProcessed);
-
- /** Writes a given number of zeroed bytes to the currently selected endpoint's bank, sending
- * full packets to the host as needed. The last packet is not automatically sent once the
- * remaining bytes have been written; the user is responsible for manually sending the last
- * packet to the host via the \ref Endpoint_ClearIN() macro.
- *
- * If the BytesProcessed parameter is \c NULL, the entire stream transfer is attempted at once,
- * failing or succeeding as a single unit. If the BytesProcessed parameter points to a valid
- * storage location, the transfer will instead be performed as a series of chunks. Each time
- * the endpoint bank becomes full while there is still data to process (and after the current
- * packet transmission has been initiated) the BytesProcessed location will be updated with the
- * total number of bytes processed in the stream, and the function will exit with an error code of
- * \ref ENDPOINT_RWSTREAM_IncompleteTransfer. This allows for any abort checking to be performed
- * in the user code - to continue the transfer, call the function again with identical parameters
- * and it will resume until the BytesProcessed value reaches the total transfer length.
- *
- * <b>Single Stream Transfer Example:</b>
- * \code
- * uint8_t ErrorCode;
- *
- * if ((ErrorCode = Endpoint_Null_Stream(512, NULL)) != ENDPOINT_RWSTREAM_NoError)
- * {
- * // Stream failed to complete - check ErrorCode here
- * }
- * \endcode
- *
- * <b>Partial Stream Transfers Example:</b>
- * \code
- * uint8_t ErrorCode;
- * uint16_t BytesProcessed;
- *
- * BytesProcessed = 0;
- * while ((ErrorCode = Endpoint_Null_Stream(512, &BytesProcessed)) == ENDPOINT_RWSTREAM_IncompleteTransfer)
- * {
- * // Stream not yet complete - do other actions here, abort if required
- * }
- *
- * if (ErrorCode != ENDPOINT_RWSTREAM_NoError)
- * {
- * // Stream failed to complete - check ErrorCode here
- * }
- * \endcode
- *
- * \note This routine should not be used on CONTROL type endpoints.
- *
- * \param[in] Length Number of zero bytes to send via the currently selected endpoint.
- * \param[in] BytesProcessed Pointer to a location where the total number of bytes processed in the current
- * transaction should be updated, \c NULL if the entire stream should be read at once.
- *
- * \return A value from the \ref Endpoint_Stream_RW_ErrorCodes_t enum.
- */
- uint8_t Endpoint_Null_Stream(uint16_t Length,
- uint16_t* const BytesProcessed);
-
- //@}
-
- /** \name Stream functions for RAM source/destination data */
- //@{
-
- /** Writes the given number of bytes to the endpoint from the given buffer in little endian,
- * sending full packets to the host 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
- * \ref Endpoint_ClearIN() macro.
- *
- * If the BytesProcessed parameter is \c NULL, the entire stream transfer is attempted at once,
- * failing or succeeding as a single unit. If the BytesProcessed parameter points to a valid
- * storage location, the transfer will instead be performed as a series of chunks. Each time
- * the endpoint bank becomes full while there is still data to process (and after the current
- * packet transmission has been initiated) the BytesProcessed location will be updated with the
- * total number of bytes processed in the stream, and the function will exit with an error code of
- * \ref ENDPOINT_RWSTREAM_IncompleteTransfer. This allows for any abort checking to be performed
- * in the user code - to continue the transfer, call the function again with identical parameters
- * and it will resume until the BytesProcessed value reaches the total transfer length.
- *
- * <b>Single Stream Transfer Example:</b>
- * \code
- * uint8_t DataStream[512];
- * uint8_t ErrorCode;
- *
- * if ((ErrorCode = Endpoint_Write_Stream_LE(DataStream, sizeof(DataStream),
- * NULL)) != ENDPOINT_RWSTREAM_NoError)
- * {
- * // Stream failed to complete - check ErrorCode here
- * }
- * \endcode
- *
- * <b>Partial Stream Transfers Example:</b>
- * \code
- * uint8_t DataStream[512];
- * uint8_t ErrorCode;
- * uint16_t BytesProcessed;
- *
- * BytesProcessed = 0;
- * while ((ErrorCode = Endpoint_Write_Stream_LE(DataStream, sizeof(DataStream),
- * &BytesProcessed)) == ENDPOINT_RWSTREAM_IncompleteTransfer)
- * {
- * // Stream not yet complete - do other actions here, abort if required
- * }
- *
- * if (ErrorCode != ENDPOINT_RWSTREAM_NoError)
- * {
- * // Stream failed to complete - check ErrorCode here
- * }
- * \endcode
- *
- * \note This routine should not be used on CONTROL type endpoints.
- *
- * \param[in] Buffer Pointer to the source data buffer to read from.
- * \param[in] Length Number of bytes to read for the currently selected endpoint into the buffer.
- * \param[in] BytesProcessed Pointer to a location where the total number of bytes processed in the current
- * transaction should be updated, \c NULL if the entire stream should be written at once.
- *
- * \return A value from the \ref Endpoint_Stream_RW_ErrorCodes_t enum.
- */
- uint8_t Endpoint_Write_Stream_LE(const void* const Buffer,
- uint16_t Length,
- uint16_t* const BytesProcessed) ATTR_NON_NULL_PTR_ARG(1);
-
- /** Writes the given number of bytes to the endpoint from the given buffer in big endian,
- * sending full packets to the host 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
- * \ref Endpoint_ClearIN() macro.
- *
- * \note This routine should not be used on CONTROL type endpoints.
- *
- * \param[in] Buffer Pointer to the source data buffer to read from.
- * \param[in] Length Number of bytes to read for the currently selected endpoint into the buffer.
- * \param[in] BytesProcessed Pointer to a location where the total number of bytes processed in the current
- * transaction should be updated, \c NULL if the entire stream should be written at once.
- *
- * \return A value from the \ref Endpoint_Stream_RW_ErrorCodes_t enum.
- */
- uint8_t Endpoint_Write_Stream_BE(const void* const Buffer,
- uint16_t Length,
- uint16_t* const BytesProcessed) ATTR_NON_NULL_PTR_ARG(1);
-
- /** Reads the given number of bytes from the endpoint from the given buffer in little endian,
- * 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 \ref Endpoint_ClearOUT() macro.
- *
- * If the BytesProcessed parameter is \c NULL, the entire stream transfer is attempted at once,
- * failing or succeeding as a single unit. If the BytesProcessed parameter points to a valid
- * storage location, the transfer will instead be performed as a series of chunks. Each time
- * the endpoint bank becomes empty while there is still data to process (and after the current
- * packet has been acknowledged) the BytesProcessed location will be updated with the total number
- * of bytes processed in the stream, and the function will exit with an error code of
- * \ref ENDPOINT_RWSTREAM_IncompleteTransfer. This allows for any abort checking to be performed
- * in the user code - to continue the transfer, call the function again with identical parameters
- * and it will resume until the BytesProcessed value reaches the total transfer length.
- *
- * <b>Single Stream Transfer Example:</b>
- * \code
- * uint8_t DataStream[512];
- * uint8_t ErrorCode;
- *
- * if ((ErrorCode = Endpoint_Read_Stream_LE(DataStream, sizeof(DataStream),
- * NULL)) != ENDPOINT_RWSTREAM_NoError)
- * {
- * // Stream failed to complete - check ErrorCode here
- * }
- * \endcode
- *
- * <b>Partial Stream Transfers Example:</b>
- * \code
- * uint8_t DataStream[512];
- * uint8_t ErrorCode;
- * uint16_t BytesProcessed;
- *
- * BytesProcessed = 0;
- * while ((ErrorCode = Endpoint_Read_Stream_LE(DataStream, sizeof(DataStream),
- * &BytesProcessed)) == ENDPOINT_RWSTREAM_IncompleteTransfer)
- * {
- * // Stream not yet complete - do other actions here, abort if required
- * }
- *
- * if (ErrorCode != ENDPOINT_RWSTREAM_NoError)
- * {
- * // Stream failed to complete - check ErrorCode here
- * }
- * \endcode
- *
- * \note This routine should not be used on CONTROL type endpoints.
- *
- * \param[out] Buffer Pointer to the destination data buffer to write to.
- * \param[in] Length Number of bytes to send via the currently selected endpoint.
- * \param[in] BytesProcessed Pointer to a location where the total number of bytes processed in the current
- * transaction should be updated, \c NULL if the entire stream should be read at once.
- *
- * \return A value from the \ref Endpoint_Stream_RW_ErrorCodes_t enum.
- */
- uint8_t Endpoint_Read_Stream_LE(void* const Buffer,
- uint16_t Length,
- uint16_t* const BytesProcessed) ATTR_NON_NULL_PTR_ARG(1);
-
- /** Reads the given number of bytes from the endpoint from the given buffer in big endian,
- * 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 \ref Endpoint_ClearOUT() macro.
- *
- * \note This routine should not be used on CONTROL type endpoints.
- *
- * \param[out] Buffer Pointer to the destination data buffer to write to.
- * \param[in] Length Number of bytes to send via the currently selected endpoint.
- * \param[in] BytesProcessed Pointer to a location where the total number of bytes processed in the current
- * transaction should be updated, \c NULL if the entire stream should be read at once.
- *
- * \return A value from the \ref Endpoint_Stream_RW_ErrorCodes_t enum.
- */
- uint8_t Endpoint_Read_Stream_BE(void* const Buffer,
- uint16_t Length,
- uint16_t* const BytesProcessed) ATTR_NON_NULL_PTR_ARG(1);
-
- /** Writes the given number of bytes to the CONTROL type endpoint from the given buffer in little endian,
- * sending full packets to the host as needed. The host OUT acknowledgement is not automatically cleared
- * in both failure and success states; the user is responsible for manually clearing the setup OUT to
- * finalize the transfer via the \ref Endpoint_ClearOUT() macro.
- *
- * \note This function automatically clears the control transfer's status stage. Do not manually attempt
- * to clear the status stage when using this routine in a control transaction.
- * \n\n
- *
- * \note This routine should only be used on CONTROL type endpoints.
- *
- * \warning Unlike the standard stream read/write commands, the control stream commands cannot be chained
- * together; i.e. the entire stream data must be read or written at the one time.
- *
- * \param[in] Buffer Pointer to the source data buffer to read from.
- * \param[in] Length Number of bytes to read for the currently selected endpoint into the buffer.
- *
- * \return A value from the \ref Endpoint_ControlStream_RW_ErrorCodes_t enum.
- */
- uint8_t Endpoint_Write_Control_Stream_LE(const void* const Buffer,
- uint16_t Length) ATTR_NON_NULL_PTR_ARG(1);
-
- /** Writes the given number of bytes to the CONTROL type endpoint from the given buffer in big endian,
- * sending full packets to the host as needed. The host OUT acknowledgement is not automatically cleared
- * in both failure and success states; the user is responsible for manually clearing the setup OUT to
- * finalize the transfer via the \ref Endpoint_ClearOUT() macro.
- *
- * \note This function automatically clears the control transfer's status stage. Do not manually attempt
- * to clear the status stage when using this routine in a control transaction.
- * \n\n
- *
- * \note This routine should only be used on CONTROL type endpoints.
- *
- * \warning Unlike the standard stream read/write commands, the control stream commands cannot be chained
- * together; i.e. the entire stream data must be read or written at the one time.
- *
- * \param[in] Buffer Pointer to the source data buffer to read from.
- * \param[in] Length Number of bytes to read for the currently selected endpoint into the buffer.
- *
- * \return A value from the \ref Endpoint_ControlStream_RW_ErrorCodes_t enum.
- */
- uint8_t Endpoint_Write_Control_Stream_BE(const void* const Buffer,
- uint16_t Length) ATTR_NON_NULL_PTR_ARG(1);
-
- /** Reads the given number of bytes from the CONTROL endpoint from the given buffer in little endian,
- * discarding fully read packets from the host as needed. The device IN acknowledgement is not
- * automatically sent after success or failure states; the user is responsible for manually sending the
- * setup IN to finalize the transfer via the \ref Endpoint_ClearIN() macro.
- *
- * \note This function automatically clears the control transfer's status stage. Do not manually attempt
- * to clear the status stage when using this routine in a control transaction.
- * \n\n
- *
- * \note This routine should only be used on CONTROL type endpoints.
- *
- * \warning Unlike the standard stream read/write commands, the control stream commands cannot be chained
- * together; i.e. the entire stream data must be read or written at the one time.
- *
- * \param[out] Buffer Pointer to the destination data buffer to write to.
- * \param[in] Length Number of bytes to send via the currently selected endpoint.
- *
- * \return A value from the \ref Endpoint_ControlStream_RW_ErrorCodes_t enum.
- */
- uint8_t Endpoint_Read_Control_Stream_LE(void* const Buffer,
- uint16_t Length) ATTR_NON_NULL_PTR_ARG(1);
-
- /** Reads the given number of bytes from the CONTROL endpoint from the given buffer in big endian,
- * discarding fully read packets from the host as needed. The device IN acknowledgement is not
- * automatically sent after success or failure states; the user is responsible for manually sending the
- * setup IN to finalize the transfer via the \ref Endpoint_ClearIN() macro.
- *
- * \note This function automatically clears the control transfer's status stage. Do not manually attempt
- * to clear the status stage when using this routine in a control transaction.
- * \n\n
- *
- * \note This routine should only be used on CONTROL type endpoints.
- *
- * \warning Unlike the standard stream read/write commands, the control stream commands cannot be chained
- * together; i.e. the entire stream data must be read or written at the one time.
- *
- * \param[out] Buffer Pointer to the destination data buffer to write to.
- * \param[in] Length Number of bytes to send via the currently selected endpoint.
- *
- * \return A value from the \ref Endpoint_ControlStream_RW_ErrorCodes_t enum.
- */
- uint8_t Endpoint_Read_Control_Stream_BE(void* const Buffer,
- uint16_t Length) ATTR_NON_NULL_PTR_ARG(1);
- //@}
-
- /** \name Stream functions for EEPROM source/destination data */
- //@{
-
- /** EEPROM buffer source version of \ref Endpoint_Write_Stream_LE().
- *
- * \param[in] Buffer Pointer to the source data buffer to read from.
- * \param[in] Length Number of bytes to read for the currently selected endpoint into the buffer.
- * \param[in] BytesProcessed Pointer to a location where the total number of bytes processed in the current
- * transaction should be updated, \c NULL if the entire stream should be written at once.
- *
- * \return A value from the \ref Endpoint_Stream_RW_ErrorCodes_t enum.
- */
- uint8_t Endpoint_Write_EStream_LE(const void* const Buffer,
- uint16_t Length,
- uint16_t* const BytesProcessed) ATTR_NON_NULL_PTR_ARG(1);
-
- /** EEPROM buffer source version of \ref Endpoint_Write_Stream_BE().
- *
- * \param[in] Buffer Pointer to the source data buffer to read from.
- * \param[in] Length Number of bytes to read for the currently selected endpoint into the buffer.
- * \param[in] BytesProcessed Pointer to a location where the total number of bytes processed in the current
- * transaction should be updated, \c NULL if the entire stream should be written at once.
- *
- * \return A value from the \ref Endpoint_Stream_RW_ErrorCodes_t enum.
- */
- uint8_t Endpoint_Write_EStream_BE(const void* const Buffer,
- uint16_t Length,
- uint16_t* const BytesProcessed) ATTR_NON_NULL_PTR_ARG(1);
-
- /** EEPROM buffer destination version of \ref Endpoint_Read_Stream_LE().
- *
- * \param[out] Buffer Pointer to the destination data buffer to write to, located in EEPROM memory space.
- * \param[in] Length Number of bytes to send via the currently selected endpoint.
- * \param[in] BytesProcessed Pointer to a location where the total number of bytes processed in the current
- * transaction should be updated, \c NULL if the entire stream should be read at once.
- *
- * \return A value from the \ref Endpoint_Stream_RW_ErrorCodes_t enum.
- */
- uint8_t Endpoint_Read_EStream_LE(void* const Buffer,
- uint16_t Length,
- uint16_t* const BytesProcessed) ATTR_NON_NULL_PTR_ARG(1);
-
- /** EEPROM buffer destination version of \ref Endpoint_Read_Stream_BE().
- *
- * \param[out] Buffer Pointer to the destination data buffer to write to, located in EEPROM memory space.
- * \param[in] Length Number of bytes to send via the currently selected endpoint.
- * \param[in] BytesProcessed Pointer to a location where the total number of bytes processed in the current
- * transaction should be updated, \c NULL if the entire stream should be read at once.
- *
- * \return A value from the \ref Endpoint_Stream_RW_ErrorCodes_t enum.
- */
- uint8_t Endpoint_Read_EStream_BE(void* const Buffer,
- uint16_t Length,
- uint16_t* const BytesProcessed) ATTR_NON_NULL_PTR_ARG(1);
-
- /** EEPROM buffer source version of Endpoint_Write_Control_Stream_LE.
- *
- * \note This function automatically clears the control transfer's status stage. Do not manually attempt
- * to clear the status stage when using this routine in a control transaction.
- * \n\n
- *
- * \note This routine should only be used on CONTROL type endpoints.
- * \n\n
- *
- * \warning Unlike the standard stream read/write commands, the control stream commands cannot be chained
- * together; i.e. the entire stream data must be read or written at the one time.
- *
- * \param[in] Buffer Pointer to the source data buffer to read from.
- * \param[in] Length Number of bytes to read for the currently selected endpoint into the buffer.
- *
- * \return A value from the \ref Endpoint_ControlStream_RW_ErrorCodes_t enum.
- */
- uint8_t Endpoint_Write_Control_EStream_LE(const void* const Buffer,
- uint16_t Length) ATTR_NON_NULL_PTR_ARG(1);
-
- /** EEPROM buffer source version of \ref Endpoint_Write_Control_Stream_BE().
- *
- * \note This function automatically clears the control transfer's status stage. Do not manually attempt
- * to clear the status stage when using this routine in a control transaction.
- * \n\n
- *
- * \note This routine should only be used on CONTROL type endpoints.
- * \n\n
- *
- * \warning Unlike the standard stream read/write commands, the control stream commands cannot be chained
- * together; i.e. the entire stream data must be read or written at the one time.
- *
- * \param[in] Buffer Pointer to the source data buffer to read from.
- * \param[in] Length Number of bytes to read for the currently selected endpoint into the buffer.
- *
- * \return A value from the \ref Endpoint_ControlStream_RW_ErrorCodes_t enum.
- */
- uint8_t Endpoint_Write_Control_EStream_BE(const void* const Buffer,
- uint16_t Length) ATTR_NON_NULL_PTR_ARG(1);
-
- /** EEPROM buffer source version of \ref Endpoint_Read_Control_Stream_LE().
- *
- * \note This function automatically clears the control transfer's status stage. Do not manually attempt
- * to clear the status stage when using this routine in a control transaction.
- * \n\n
- *
- * \note This routine should only be used on CONTROL type endpoints.
- * \n\n
- *
- * \warning Unlike the standard stream read/write commands, the control stream commands cannot be chained
- * together; i.e. the entire stream data must be read or written at the one time.
- *
- * \param[out] Buffer Pointer to the destination data buffer to write to.
- * \param[in] Length Number of bytes to send via the currently selected endpoint.
- *
- * \return A value from the \ref Endpoint_ControlStream_RW_ErrorCodes_t enum.
- */
- uint8_t Endpoint_Read_Control_EStream_LE(void* const Buffer,
- uint16_t Length) ATTR_NON_NULL_PTR_ARG(1);
-
- /** EEPROM buffer source version of \ref Endpoint_Read_Control_Stream_BE().
- *
- * \note This function automatically clears the control transfer's status stage. Do not manually attempt
- * to clear the status stage when using this routine in a control transaction.
- * \n\n
- *
- * \note This routine should only be used on CONTROL type endpoints.
- * \n\n
- *
- * \warning Unlike the standard stream read/write commands, the control stream commands cannot be chained
- * together; i.e. the entire stream data must be read or written at the one time.
- *
- * \param[out] Buffer Pointer to the destination data buffer to write to.
- * \param[in] Length Number of bytes to send via the currently selected endpoint.
- *
- * \return A value from the \ref Endpoint_ControlStream_RW_ErrorCodes_t enum.
- */
- uint8_t Endpoint_Read_Control_EStream_BE(void* const Buffer,
- uint16_t Length) ATTR_NON_NULL_PTR_ARG(1);
- //@}
-
- /** \name Stream functions for PROGMEM source/destination data */
- //@{
-
- /** FLASH buffer source version of \ref Endpoint_Write_Stream_LE().
- *
- * \pre The FLASH data must be located in the first 64KB of FLASH for this function to work correctly.
- *
- * \param[in] Buffer Pointer to the source data buffer to read from.
- * \param[in] Length Number of bytes to read for the currently selected endpoint into the buffer.
- * \param[in] BytesProcessed Pointer to a location where the total number of bytes processed in the current
- * transaction should be updated, \c NULL if the entire stream should be written at once.
- *
- * \return A value from the \ref Endpoint_Stream_RW_ErrorCodes_t enum.
- */
- uint8_t Endpoint_Write_PStream_LE(const void* const Buffer,
- uint16_t Length,
- uint16_t* const BytesProcessed) ATTR_NON_NULL_PTR_ARG(1);
-
- /** FLASH buffer source version of \ref Endpoint_Write_Stream_BE().
- *
- * \pre The FLASH data must be located in the first 64KB of FLASH for this function to work correctly.
- *
- * \param[in] Buffer Pointer to the source data buffer to read from.
- * \param[in] Length Number of bytes to read for the currently selected endpoint into the buffer.
- * \param[in] BytesProcessed Pointer to a location where the total number of bytes processed in the current
- * transaction should be updated, \c NULL if the entire stream should be written at once.
- *
- * \return A value from the \ref Endpoint_Stream_RW_ErrorCodes_t enum.
- */
- uint8_t Endpoint_Write_PStream_BE(const void* const Buffer,
- uint16_t Length,
- uint16_t* const BytesProcessed) ATTR_NON_NULL_PTR_ARG(1);
-
- /** FLASH buffer source version of \ref Endpoint_Write_Control_Stream_LE().
- *
- * \pre The FLASH data must be located in the first 64KB of FLASH for this function to work correctly.
- *
- * \note This function automatically clears the control transfer's status stage. Do not manually attempt
- * to clear the status stage when using this routine in a control transaction.
- * \n\n
- *
- * \note This routine should only be used on CONTROL type endpoints.
- * \n\n
- *
- * \warning Unlike the standard stream read/write commands, the control stream commands cannot be chained
- * together; i.e. the entire stream data must be read or written at the one time.
- *
- * \param[in] Buffer Pointer to the source data buffer to read from.
- * \param[in] Length Number of bytes to read for the currently selected endpoint into the buffer.
- *
- * \return A value from the \ref Endpoint_ControlStream_RW_ErrorCodes_t enum.
- */
- uint8_t Endpoint_Write_Control_PStream_LE(const void* const Buffer,
- uint16_t Length) ATTR_NON_NULL_PTR_ARG(1);
-
- /** FLASH buffer source version of \ref Endpoint_Write_Control_Stream_BE().
- *
- * \pre The FLASH data must be located in the first 64KB of FLASH for this function to work correctly.
- *
- * \note This function automatically clears the control transfer's status stage. Do not manually attempt
- * to clear the status stage when using this routine in a control transaction.
- * \n\n
- *
- * \note This routine should only be used on CONTROL type endpoints.
- * \n\n
- *
- * \warning Unlike the standard stream read/write commands, the control stream commands cannot be chained
- * together; i.e. the entire stream data must be read or written at the one time.
- *
- * \param[in] Buffer Pointer to the source data buffer to read from.
- * \param[in] Length Number of bytes to read for the currently selected endpoint into the buffer.
- *
- * \return A value from the \ref Endpoint_ControlStream_RW_ErrorCodes_t enum.
- */
- uint8_t Endpoint_Write_Control_PStream_BE(const void* const Buffer,
- uint16_t Length) ATTR_NON_NULL_PTR_ARG(1);
- //@}
-
- /* Disable C linkage for C++ Compilers: */
- #if defined(__cplusplus)
- }
- #endif
-
-#endif
-
-/** @} */
+/* + LUFA Library + Copyright (C) Dean Camera, 2012. + + dean [at] fourwalledcubicle [dot] com + www.lufa-lib.org +*/ + +/* + Copyright 2012 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 + software, including all implied warranties of merchantability + and fitness. In no event shall the author be liable for any + special, indirect or consequential damages or any damages + whatsoever resulting from loss of use, data or profits, whether + in an action of contract, negligence or other tortious action, + arising out of or in connection with the use or performance of + this software. +*/ + +/** \file + * \brief Endpoint data stream transmission and reception management for the AVR8 microcontrollers. + * \copydetails Group_EndpointStreamRW_AVR8 + * + * \note This file should not be included directly. It is automatically included as needed by the USB driver + * dispatch header located in LUFA/Drivers/USB/USB.h. + */ + +/** \ingroup Group_EndpointStreamRW + * \defgroup Group_EndpointStreamRW_AVR8 Read/Write of Multi-Byte Streams (AVR8) + * \brief Endpoint data stream transmission and reception management for the Atmel AVR8 architecture. + * + * Functions, macros, variables, enums and types related to data reading and writing of data streams from + * and to endpoints. + * + * @{ + */ + +#ifndef __ENDPOINT_STREAM_AVR8_H__ +#define __ENDPOINT_STREAM_AVR8_H__ + + /* Includes: */ + #include "../../../../Common/Common.h" + #include "../USBMode.h" + #include "../USBTask.h" + + /* Enable C linkage for C++ Compilers: */ + #if defined(__cplusplus) + extern "C" { + #endif + + /* Preprocessor Checks: */ + #if !defined(__INCLUDE_FROM_USB_DRIVER) + #error Do not include this file directly. Include LUFA/Drivers/USB/USB.h instead. + #endif + + /* Public Interface - May be used in end-application: */ + /* Function Prototypes: */ + /** \name Stream functions for null data */ + //@{ + + /** Reads and discards the given number of bytes from the currently selected endpoint's bank, + * 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 \ref Endpoint_ClearOUT() macro. + * + * If the BytesProcessed parameter is \c NULL, the entire stream transfer is attempted at once, + * failing or succeeding as a single unit. If the BytesProcessed parameter points to a valid + * storage location, the transfer will instead be performed as a series of chunks. Each time + * the endpoint bank becomes empty while there is still data to process (and after the current + * packet has been acknowledged) the BytesProcessed location will be updated with the total number + * of bytes processed in the stream, and the function will exit with an error code of + * \ref ENDPOINT_RWSTREAM_IncompleteTransfer. This allows for any abort checking to be performed + * in the user code - to continue the transfer, call the function again with identical parameters + * and it will resume until the BytesProcessed value reaches the total transfer length. + * + * <b>Single Stream Transfer Example:</b> + * \code + * uint8_t ErrorCode; + * + * if ((ErrorCode = Endpoint_Discard_Stream(512, NULL)) != ENDPOINT_RWSTREAM_NoError) + * { + * // Stream failed to complete - check ErrorCode here + * } + * \endcode + * + * <b>Partial Stream Transfers Example:</b> + * \code + * uint8_t ErrorCode; + * uint16_t BytesProcessed; + * + * BytesProcessed = 0; + * while ((ErrorCode = Endpoint_Discard_Stream(512, &BytesProcessed)) == ENDPOINT_RWSTREAM_IncompleteTransfer) + * { + * // Stream not yet complete - do other actions here, abort if required + * } + * + * if (ErrorCode != ENDPOINT_RWSTREAM_NoError) + * { + * // Stream failed to complete - check ErrorCode here + * } + * \endcode + * + * \note This routine should not be used on CONTROL type endpoints. + * + * \param[in] Length Number of bytes to discard via the currently selected endpoint. + * \param[in] BytesProcessed Pointer to a location where the total number of bytes processed in the current + * transaction should be updated, \c NULL if the entire stream should be read at once. + * + * \return A value from the \ref Endpoint_Stream_RW_ErrorCodes_t enum. + */ + uint8_t Endpoint_Discard_Stream(uint16_t Length, + uint16_t* const BytesProcessed); + + /** Writes a given number of zeroed bytes to the currently selected endpoint's bank, sending + * full packets to the host as needed. The last packet is not automatically sent once the + * remaining bytes have been written; the user is responsible for manually sending the last + * packet to the host via the \ref Endpoint_ClearIN() macro. + * + * If the BytesProcessed parameter is \c NULL, the entire stream transfer is attempted at once, + * failing or succeeding as a single unit. If the BytesProcessed parameter points to a valid + * storage location, the transfer will instead be performed as a series of chunks. Each time + * the endpoint bank becomes full while there is still data to process (and after the current + * packet transmission has been initiated) the BytesProcessed location will be updated with the + * total number of bytes processed in the stream, and the function will exit with an error code of + * \ref ENDPOINT_RWSTREAM_IncompleteTransfer. This allows for any abort checking to be performed + * in the user code - to continue the transfer, call the function again with identical parameters + * and it will resume until the BytesProcessed value reaches the total transfer length. + * + * <b>Single Stream Transfer Example:</b> + * \code + * uint8_t ErrorCode; + * + * if ((ErrorCode = Endpoint_Null_Stream(512, NULL)) != ENDPOINT_RWSTREAM_NoError) + * { + * // Stream failed to complete - check ErrorCode here + * } + * \endcode + * + * <b>Partial Stream Transfers Example:</b> + * \code + * uint8_t ErrorCode; + * uint16_t BytesProcessed; + * + * BytesProcessed = 0; + * while ((ErrorCode = Endpoint_Null_Stream(512, &BytesProcessed)) == ENDPOINT_RWSTREAM_IncompleteTransfer) + * { + * // Stream not yet complete - do other actions here, abort if required + * } + * + * if (ErrorCode != ENDPOINT_RWSTREAM_NoError) + * { + * // Stream failed to complete - check ErrorCode here + * } + * \endcode + * + * \note This routine should not be used on CONTROL type endpoints. + * + * \param[in] Length Number of zero bytes to send via the currently selected endpoint. + * \param[in] BytesProcessed Pointer to a location where the total number of bytes processed in the current + * transaction should be updated, \c NULL if the entire stream should be read at once. + * + * \return A value from the \ref Endpoint_Stream_RW_ErrorCodes_t enum. + */ + uint8_t Endpoint_Null_Stream(uint16_t Length, + uint16_t* const BytesProcessed); + + //@} + + /** \name Stream functions for RAM source/destination data */ + //@{ + + /** Writes the given number of bytes to the endpoint from the given buffer in little endian, + * sending full packets to the host 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 + * \ref Endpoint_ClearIN() macro. + * + * If the BytesProcessed parameter is \c NULL, the entire stream transfer is attempted at once, + * failing or succeeding as a single unit. If the BytesProcessed parameter points to a valid + * storage location, the transfer will instead be performed as a series of chunks. Each time + * the endpoint bank becomes full while there is still data to process (and after the current + * packet transmission has been initiated) the BytesProcessed location will be updated with the + * total number of bytes processed in the stream, and the function will exit with an error code of + * \ref ENDPOINT_RWSTREAM_IncompleteTransfer. This allows for any abort checking to be performed + * in the user code - to continue the transfer, call the function again with identical parameters + * and it will resume until the BytesProcessed value reaches the total transfer length. + * + * <b>Single Stream Transfer Example:</b> + * \code + * uint8_t DataStream[512]; + * uint8_t ErrorCode; + * + * if ((ErrorCode = Endpoint_Write_Stream_LE(DataStream, sizeof(DataStream), + * NULL)) != ENDPOINT_RWSTREAM_NoError) + * { + * // Stream failed to complete - check ErrorCode here + * } + * \endcode + * + * <b>Partial Stream Transfers Example:</b> + * \code + * uint8_t DataStream[512]; + * uint8_t ErrorCode; + * uint16_t BytesProcessed; + * + * BytesProcessed = 0; + * while ((ErrorCode = Endpoint_Write_Stream_LE(DataStream, sizeof(DataStream), + * &BytesProcessed)) == ENDPOINT_RWSTREAM_IncompleteTransfer) + * { + * // Stream not yet complete - do other actions here, abort if required + * } + * + * if (ErrorCode != ENDPOINT_RWSTREAM_NoError) + * { + * // Stream failed to complete - check ErrorCode here + * } + * \endcode + * + * \note This routine should not be used on CONTROL type endpoints. + * + * \param[in] Buffer Pointer to the source data buffer to read from. + * \param[in] Length Number of bytes to read for the currently selected endpoint into the buffer. + * \param[in] BytesProcessed Pointer to a location where the total number of bytes processed in the current + * transaction should be updated, \c NULL if the entire stream should be written at once. + * + * \return A value from the \ref Endpoint_Stream_RW_ErrorCodes_t enum. + */ + uint8_t Endpoint_Write_Stream_LE(const void* const Buffer, + uint16_t Length, + uint16_t* const BytesProcessed) ATTR_NON_NULL_PTR_ARG(1); + + /** Writes the given number of bytes to the endpoint from the given buffer in big endian, + * sending full packets to the host 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 + * \ref Endpoint_ClearIN() macro. + * + * \note This routine should not be used on CONTROL type endpoints. + * + * \param[in] Buffer Pointer to the source data buffer to read from. + * \param[in] Length Number of bytes to read for the currently selected endpoint into the buffer. + * \param[in] BytesProcessed Pointer to a location where the total number of bytes processed in the current + * transaction should be updated, \c NULL if the entire stream should be written at once. + * + * \return A value from the \ref Endpoint_Stream_RW_ErrorCodes_t enum. + */ + uint8_t Endpoint_Write_Stream_BE(const void* const Buffer, + uint16_t Length, + uint16_t* const BytesProcessed) ATTR_NON_NULL_PTR_ARG(1); + + /** Reads the given number of bytes from the endpoint from the given buffer in little endian, + * 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 \ref Endpoint_ClearOUT() macro. + * + * If the BytesProcessed parameter is \c NULL, the entire stream transfer is attempted at once, + * failing or succeeding as a single unit. If the BytesProcessed parameter points to a valid + * storage location, the transfer will instead be performed as a series of chunks. Each time + * the endpoint bank becomes empty while there is still data to process (and after the current + * packet has been acknowledged) the BytesProcessed location will be updated with the total number + * of bytes processed in the stream, and the function will exit with an error code of + * \ref ENDPOINT_RWSTREAM_IncompleteTransfer. This allows for any abort checking to be performed + * in the user code - to continue the transfer, call the function again with identical parameters + * and it will resume until the BytesProcessed value reaches the total transfer length. + * + * <b>Single Stream Transfer Example:</b> + * \code + * uint8_t DataStream[512]; + * uint8_t ErrorCode; + * + * if ((ErrorCode = Endpoint_Read_Stream_LE(DataStream, sizeof(DataStream), + * NULL)) != ENDPOINT_RWSTREAM_NoError) + * { + * // Stream failed to complete - check ErrorCode here + * } + * \endcode + * + * <b>Partial Stream Transfers Example:</b> + * \code + * uint8_t DataStream[512]; + * uint8_t ErrorCode; + * uint16_t BytesProcessed; + * + * BytesProcessed = 0; + * while ((ErrorCode = Endpoint_Read_Stream_LE(DataStream, sizeof(DataStream), + * &BytesProcessed)) == ENDPOINT_RWSTREAM_IncompleteTransfer) + * { + * // Stream not yet complete - do other actions here, abort if required + * } + * + * if (ErrorCode != ENDPOINT_RWSTREAM_NoError) + * { + * // Stream failed to complete - check ErrorCode here + * } + * \endcode + * + * \note This routine should not be used on CONTROL type endpoints. + * + * \param[out] Buffer Pointer to the destination data buffer to write to. + * \param[in] Length Number of bytes to send via the currently selected endpoint. + * \param[in] BytesProcessed Pointer to a location where the total number of bytes processed in the current + * transaction should be updated, \c NULL if the entire stream should be read at once. + * + * \return A value from the \ref Endpoint_Stream_RW_ErrorCodes_t enum. + */ + uint8_t Endpoint_Read_Stream_LE(void* const Buffer, + uint16_t Length, + uint16_t* const BytesProcessed) ATTR_NON_NULL_PTR_ARG(1); + + /** Reads the given number of bytes from the endpoint from the given buffer in big endian, + * 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 \ref Endpoint_ClearOUT() macro. + * + * \note This routine should not be used on CONTROL type endpoints. + * + * \param[out] Buffer Pointer to the destination data buffer to write to. + * \param[in] Length Number of bytes to send via the currently selected endpoint. + * \param[in] BytesProcessed Pointer to a location where the total number of bytes processed in the current + * transaction should be updated, \c NULL if the entire stream should be read at once. + * + * \return A value from the \ref Endpoint_Stream_RW_ErrorCodes_t enum. + */ + uint8_t Endpoint_Read_Stream_BE(void* const Buffer, + uint16_t Length, + uint16_t* const BytesProcessed) ATTR_NON_NULL_PTR_ARG(1); + + /** Writes the given number of bytes to the CONTROL type endpoint from the given buffer in little endian, + * sending full packets to the host as needed. The host OUT acknowledgement is not automatically cleared + * in both failure and success states; the user is responsible for manually clearing the setup OUT to + * finalize the transfer via the \ref Endpoint_ClearOUT() macro. + * + * \note This function automatically clears the control transfer's status stage. Do not manually attempt + * to clear the status stage when using this routine in a control transaction. + * \n\n + * + * \note This routine should only be used on CONTROL type endpoints. + * + * \warning Unlike the standard stream read/write commands, the control stream commands cannot be chained + * together; i.e. the entire stream data must be read or written at the one time. + * + * \param[in] Buffer Pointer to the source data buffer to read from. + * \param[in] Length Number of bytes to read for the currently selected endpoint into the buffer. + * + * \return A value from the \ref Endpoint_ControlStream_RW_ErrorCodes_t enum. + */ + uint8_t Endpoint_Write_Control_Stream_LE(const void* const Buffer, + uint16_t Length) ATTR_NON_NULL_PTR_ARG(1); + + /** Writes the given number of bytes to the CONTROL type endpoint from the given buffer in big endian, + * sending full packets to the host as needed. The host OUT acknowledgement is not automatically cleared + * in both failure and success states; the user is responsible for manually clearing the setup OUT to + * finalize the transfer via the \ref Endpoint_ClearOUT() macro. + * + * \note This function automatically clears the control transfer's status stage. Do not manually attempt + * to clear the status stage when using this routine in a control transaction. + * \n\n + * + * \note This routine should only be used on CONTROL type endpoints. + * + * \warning Unlike the standard stream read/write commands, the control stream commands cannot be chained + * together; i.e. the entire stream data must be read or written at the one time. + * + * \param[in] Buffer Pointer to the source data buffer to read from. + * \param[in] Length Number of bytes to read for the currently selected endpoint into the buffer. + * + * \return A value from the \ref Endpoint_ControlStream_RW_ErrorCodes_t enum. + */ + uint8_t Endpoint_Write_Control_Stream_BE(const void* const Buffer, + uint16_t Length) ATTR_NON_NULL_PTR_ARG(1); + + /** Reads the given number of bytes from the CONTROL endpoint from the given buffer in little endian, + * discarding fully read packets from the host as needed. The device IN acknowledgement is not + * automatically sent after success or failure states; the user is responsible for manually sending the + * setup IN to finalize the transfer via the \ref Endpoint_ClearIN() macro. + * + * \note This function automatically clears the control transfer's status stage. Do not manually attempt + * to clear the status stage when using this routine in a control transaction. + * \n\n + * + * \note This routine should only be used on CONTROL type endpoints. + * + * \warning Unlike the standard stream read/write commands, the control stream commands cannot be chained + * together; i.e. the entire stream data must be read or written at the one time. + * + * \param[out] Buffer Pointer to the destination data buffer to write to. + * \param[in] Length Number of bytes to send via the currently selected endpoint. + * + * \return A value from the \ref Endpoint_ControlStream_RW_ErrorCodes_t enum. + */ + uint8_t Endpoint_Read_Control_Stream_LE(void* const Buffer, + uint16_t Length) ATTR_NON_NULL_PTR_ARG(1); + + /** Reads the given number of bytes from the CONTROL endpoint from the given buffer in big endian, + * discarding fully read packets from the host as needed. The device IN acknowledgement is not + * automatically sent after success or failure states; the user is responsible for manually sending the + * setup IN to finalize the transfer via the \ref Endpoint_ClearIN() macro. + * + * \note This function automatically clears the control transfer's status stage. Do not manually attempt + * to clear the status stage when using this routine in a control transaction. + * \n\n + * + * \note This routine should only be used on CONTROL type endpoints. + * + * \warning Unlike the standard stream read/write commands, the control stream commands cannot be chained + * together; i.e. the entire stream data must be read or written at the one time. + * + * \param[out] Buffer Pointer to the destination data buffer to write to. + * \param[in] Length Number of bytes to send via the currently selected endpoint. + * + * \return A value from the \ref Endpoint_ControlStream_RW_ErrorCodes_t enum. + */ + uint8_t Endpoint_Read_Control_Stream_BE(void* const Buffer, + uint16_t Length) ATTR_NON_NULL_PTR_ARG(1); + //@} + + /** \name Stream functions for EEPROM source/destination data */ + //@{ + + /** EEPROM buffer source version of \ref Endpoint_Write_Stream_LE(). + * + * \param[in] Buffer Pointer to the source data buffer to read from. + * \param[in] Length Number of bytes to read for the currently selected endpoint into the buffer. + * \param[in] BytesProcessed Pointer to a location where the total number of bytes processed in the current + * transaction should be updated, \c NULL if the entire stream should be written at once. + * + * \return A value from the \ref Endpoint_Stream_RW_ErrorCodes_t enum. + */ + uint8_t Endpoint_Write_EStream_LE(const void* const Buffer, + uint16_t Length, + uint16_t* const BytesProcessed) ATTR_NON_NULL_PTR_ARG(1); + + /** EEPROM buffer source version of \ref Endpoint_Write_Stream_BE(). + * + * \param[in] Buffer Pointer to the source data buffer to read from. + * \param[in] Length Number of bytes to read for the currently selected endpoint into the buffer. + * \param[in] BytesProcessed Pointer to a location where the total number of bytes processed in the current + * transaction should be updated, \c NULL if the entire stream should be written at once. + * + * \return A value from the \ref Endpoint_Stream_RW_ErrorCodes_t enum. + */ + uint8_t Endpoint_Write_EStream_BE(const void* const Buffer, + uint16_t Length, + uint16_t* const BytesProcessed) ATTR_NON_NULL_PTR_ARG(1); + + /** EEPROM buffer destination version of \ref Endpoint_Read_Stream_LE(). + * + * \param[out] Buffer Pointer to the destination data buffer to write to, located in EEPROM memory space. + * \param[in] Length Number of bytes to send via the currently selected endpoint. + * \param[in] BytesProcessed Pointer to a location where the total number of bytes processed in the current + * transaction should be updated, \c NULL if the entire stream should be read at once. + * + * \return A value from the \ref Endpoint_Stream_RW_ErrorCodes_t enum. + */ + uint8_t Endpoint_Read_EStream_LE(void* const Buffer, + uint16_t Length, + uint16_t* const BytesProcessed) ATTR_NON_NULL_PTR_ARG(1); + + /** EEPROM buffer destination version of \ref Endpoint_Read_Stream_BE(). + * + * \param[out] Buffer Pointer to the destination data buffer to write to, located in EEPROM memory space. + * \param[in] Length Number of bytes to send via the currently selected endpoint. + * \param[in] BytesProcessed Pointer to a location where the total number of bytes processed in the current + * transaction should be updated, \c NULL if the entire stream should be read at once. + * + * \return A value from the \ref Endpoint_Stream_RW_ErrorCodes_t enum. + */ + uint8_t Endpoint_Read_EStream_BE(void* const Buffer, + uint16_t Length, + uint16_t* const BytesProcessed) ATTR_NON_NULL_PTR_ARG(1); + + /** EEPROM buffer source version of Endpoint_Write_Control_Stream_LE. + * + * \note This function automatically clears the control transfer's status stage. Do not manually attempt + * to clear the status stage when using this routine in a control transaction. + * \n\n + * + * \note This routine should only be used on CONTROL type endpoints. + * \n\n + * + * \warning Unlike the standard stream read/write commands, the control stream commands cannot be chained + * together; i.e. the entire stream data must be read or written at the one time. + * + * \param[in] Buffer Pointer to the source data buffer to read from. + * \param[in] Length Number of bytes to read for the currently selected endpoint into the buffer. + * + * \return A value from the \ref Endpoint_ControlStream_RW_ErrorCodes_t enum. + */ + uint8_t Endpoint_Write_Control_EStream_LE(const void* const Buffer, + uint16_t Length) ATTR_NON_NULL_PTR_ARG(1); + + /** EEPROM buffer source version of \ref Endpoint_Write_Control_Stream_BE(). + * + * \note This function automatically clears the control transfer's status stage. Do not manually attempt + * to clear the status stage when using this routine in a control transaction. + * \n\n + * + * \note This routine should only be used on CONTROL type endpoints. + * \n\n + * + * \warning Unlike the standard stream read/write commands, the control stream commands cannot be chained + * together; i.e. the entire stream data must be read or written at the one time. + * + * \param[in] Buffer Pointer to the source data buffer to read from. + * \param[in] Length Number of bytes to read for the currently selected endpoint into the buffer. + * + * \return A value from the \ref Endpoint_ControlStream_RW_ErrorCodes_t enum. + */ + uint8_t Endpoint_Write_Control_EStream_BE(const void* const Buffer, + uint16_t Length) ATTR_NON_NULL_PTR_ARG(1); + + /** EEPROM buffer source version of \ref Endpoint_Read_Control_Stream_LE(). + * + * \note This function automatically clears the control transfer's status stage. Do not manually attempt + * to clear the status stage when using this routine in a control transaction. + * \n\n + * + * \note This routine should only be used on CONTROL type endpoints. + * \n\n + * + * \warning Unlike the standard stream read/write commands, the control stream commands cannot be chained + * together; i.e. the entire stream data must be read or written at the one time. + * + * \param[out] Buffer Pointer to the destination data buffer to write to. + * \param[in] Length Number of bytes to send via the currently selected endpoint. + * + * \return A value from the \ref Endpoint_ControlStream_RW_ErrorCodes_t enum. + */ + uint8_t Endpoint_Read_Control_EStream_LE(void* const Buffer, + uint16_t Length) ATTR_NON_NULL_PTR_ARG(1); + + /** EEPROM buffer source version of \ref Endpoint_Read_Control_Stream_BE(). + * + * \note This function automatically clears the control transfer's status stage. Do not manually attempt + * to clear the status stage when using this routine in a control transaction. + * \n\n + * + * \note This routine should only be used on CONTROL type endpoints. + * \n\n + * + * \warning Unlike the standard stream read/write commands, the control stream commands cannot be chained + * together; i.e. the entire stream data must be read or written at the one time. + * + * \param[out] Buffer Pointer to the destination data buffer to write to. + * \param[in] Length Number of bytes to send via the currently selected endpoint. + * + * \return A value from the \ref Endpoint_ControlStream_RW_ErrorCodes_t enum. + */ + uint8_t Endpoint_Read_Control_EStream_BE(void* const Buffer, + uint16_t Length) ATTR_NON_NULL_PTR_ARG(1); + //@} + + /** \name Stream functions for PROGMEM source/destination data */ + //@{ + + /** FLASH buffer source version of \ref Endpoint_Write_Stream_LE(). + * + * \pre The FLASH data must be located in the first 64KB of FLASH for this function to work correctly. + * + * \param[in] Buffer Pointer to the source data buffer to read from. + * \param[in] Length Number of bytes to read for the currently selected endpoint into the buffer. + * \param[in] BytesProcessed Pointer to a location where the total number of bytes processed in the current + * transaction should be updated, \c NULL if the entire stream should be written at once. + * + * \return A value from the \ref Endpoint_Stream_RW_ErrorCodes_t enum. + */ + uint8_t Endpoint_Write_PStream_LE(const void* const Buffer, + uint16_t Length, + uint16_t* const BytesProcessed) ATTR_NON_NULL_PTR_ARG(1); + + /** FLASH buffer source version of \ref Endpoint_Write_Stream_BE(). + * + * \pre The FLASH data must be located in the first 64KB of FLASH for this function to work correctly. + * + * \param[in] Buffer Pointer to the source data buffer to read from. + * \param[in] Length Number of bytes to read for the currently selected endpoint into the buffer. + * \param[in] BytesProcessed Pointer to a location where the total number of bytes processed in the current + * transaction should be updated, \c NULL if the entire stream should be written at once. + * + * \return A value from the \ref Endpoint_Stream_RW_ErrorCodes_t enum. + */ + uint8_t Endpoint_Write_PStream_BE(const void* const Buffer, + uint16_t Length, + uint16_t* const BytesProcessed) ATTR_NON_NULL_PTR_ARG(1); + + /** FLASH buffer source version of \ref Endpoint_Write_Control_Stream_LE(). + * + * \pre The FLASH data must be located in the first 64KB of FLASH for this function to work correctly. + * + * \note This function automatically clears the control transfer's status stage. Do not manually attempt + * to clear the status stage when using this routine in a control transaction. + * \n\n + * + * \note This routine should only be used on CONTROL type endpoints. + * \n\n + * + * \warning Unlike the standard stream read/write commands, the control stream commands cannot be chained + * together; i.e. the entire stream data must be read or written at the one time. + * + * \param[in] Buffer Pointer to the source data buffer to read from. + * \param[in] Length Number of bytes to read for the currently selected endpoint into the buffer. + * + * \return A value from the \ref Endpoint_ControlStream_RW_ErrorCodes_t enum. + */ + uint8_t Endpoint_Write_Control_PStream_LE(const void* const Buffer, + uint16_t Length) ATTR_NON_NULL_PTR_ARG(1); + + /** FLASH buffer source version of \ref Endpoint_Write_Control_Stream_BE(). + * + * \pre The FLASH data must be located in the first 64KB of FLASH for this function to work correctly. + * + * \note This function automatically clears the control transfer's status stage. Do not manually attempt + * to clear the status stage when using this routine in a control transaction. + * \n\n + * + * \note This routine should only be used on CONTROL type endpoints. + * \n\n + * + * \warning Unlike the standard stream read/write commands, the control stream commands cannot be chained + * together; i.e. the entire stream data must be read or written at the one time. + * + * \param[in] Buffer Pointer to the source data buffer to read from. + * \param[in] Length Number of bytes to read for the currently selected endpoint into the buffer. + * + * \return A value from the \ref Endpoint_ControlStream_RW_ErrorCodes_t enum. + */ + uint8_t Endpoint_Write_Control_PStream_BE(const void* const Buffer, + uint16_t Length) ATTR_NON_NULL_PTR_ARG(1); + //@} + + /* Disable C linkage for C++ Compilers: */ + #if defined(__cplusplus) + } + #endif + +#endif + +/** @} */ diff --git a/LUFA/Drivers/USB/Core/AVR8/PipeStream_AVR8.h b/LUFA/Drivers/USB/Core/AVR8/PipeStream_AVR8.h index 53316f2f9..f69469f28 100644 --- a/LUFA/Drivers/USB/Core/AVR8/PipeStream_AVR8.h +++ b/LUFA/Drivers/USB/Core/AVR8/PipeStream_AVR8.h @@ -1,442 +1,442 @@ -/*
- LUFA Library
- Copyright (C) Dean Camera, 2012.
-
- dean [at] fourwalledcubicle [dot] com
- www.lufa-lib.org
-*/
-
-/*
- Copyright 2012 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
- software, including all implied warranties of merchantability
- and fitness. In no event shall the author be liable for any
- special, indirect or consequential damages or any damages
- whatsoever resulting from loss of use, data or profits, whether
- in an action of contract, negligence or other tortious action,
- arising out of or in connection with the use or performance of
- this software.
-*/
-
-/** \file
- * \brief Pipe data stream transmission and reception management for the AVR8 microcontrollers
- * \copydetails Group_PipeStreamRW_AVR8
- *
- * \note This file should not be included directly. It is automatically included as needed by the USB driver
- * dispatch header located in LUFA/Drivers/USB/USB.h.
- */
-
-/** \ingroup Group_PipeStreamRW
- * \defgroup Group_PipeStreamRW_AVR8 Read/Write of Multi-Byte Streams (AVR8)
- * \brief Pipe data stream transmission and reception management for the Atmel AVR8 architecture.
- *
- * Functions, macros, variables, enums and types related to data reading and writing of data streams from
- * and to pipes.
- *
- * @{
- */
-
-#ifndef __PIPE_STREAM_AVR8_H__
-#define __PIPE_STREAM_AVR8_H__
-
- /* Includes: */
- #include "../../../../Common/Common.h"
- #include "../USBMode.h"
- #include "../USBTask.h"
-
- /* Enable C linkage for C++ Compilers: */
- #if defined(__cplusplus)
- extern "C" {
- #endif
-
- /* Preprocessor Checks: */
- #if !defined(__INCLUDE_FROM_USB_DRIVER)
- #error Do not include this file directly. Include LUFA/Drivers/USB/USB.h instead.
- #endif
-
- /* Public Interface - May be used in end-application: */
- /* Function Prototypes: */
- /** \name Stream functions for null data */
- //@{
-
- /** 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.
- *
- * If the BytesProcessed parameter is \c NULL, the entire stream transfer is attempted at once, failing or
- * succeeding as a single unit. If the BytesProcessed parameter points to a valid storage location, the transfer
- * will instead be performed as a series of chunks. Each time the pipe bank becomes empty while there is still data
- * to process (and after the current packet has been acknowledged) the BytesProcessed location will be updated with
- * the total number of bytes processed in the stream, and the function will exit with an error code of
- * \ref PIPE_RWSTREAM_IncompleteTransfer. This allows for any abort checking to be performed in the user code - to
- * continue the transfer, call the function again with identical parameters and it will resume until the BytesProcessed
- * value reaches the total transfer length.
- *
- * <b>Single Stream Transfer Example:</b>
- * \code
- * uint8_t ErrorCode;
- *
- * if ((ErrorCode = Pipe_Discard_Stream(512, NULL)) != PIPE_RWSTREAM_NoError)
- * {
- * // Stream failed to complete - check ErrorCode here
- * }
- * \endcode
- *
- * <b>Partial Stream Transfers Example:</b>
- * \code
- * uint8_t ErrorCode;
- * uint16_t BytesProcessed;
- *
- * BytesProcessed = 0;
- * while ((ErrorCode = Pipe_Discard_Stream(512, &BytesProcessed)) == PIPE_RWSTREAM_IncompleteTransfer)
- * {
- * // Stream not yet complete - do other actions here, abort if required
- * }
- *
- * if (ErrorCode != PIPE_RWSTREAM_NoError)
- * {
- * // Stream failed to complete - check ErrorCode here
- * }
- * \endcode
- *
- * \note 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().
- *
- * \param[in] Length Number of bytes to discard via the currently selected pipe.
- * \param[in] BytesProcessed Pointer to a location where the total number of bytes already processed should
- * updated, \c NULL if the entire stream should be processed at once.
- *
- * \return A value from the \ref Pipe_Stream_RW_ErrorCodes_t enum.
- */
- uint8_t Pipe_Discard_Stream(uint16_t Length,
- uint16_t* const BytesProcessed);
-
- /** Writes a given number of zeroed bytes to the pipe, sending full pipe packets from the host to the device
- * as needed. The last packet is not automatically sent once the remaining bytes has been written; the
- * user is responsible for manually discarding the last packet from the device via the \ref Pipe_ClearOUT() macro.
- *
- * If the BytesProcessed parameter is \c NULL, the entire stream transfer is attempted at once, failing or
- * succeeding as a single unit. If the BytesProcessed parameter points to a valid storage location, the transfer
- * will instead be performed as a series of chunks. Each time the pipe bank becomes full while there is still data
- * to process (and after the current packet transmission has been initiated) the BytesProcessed location will be
- * updated with the total number of bytes processed in the stream, and the function will exit with an error code of
- * \ref PIPE_RWSTREAM_IncompleteTransfer. This allows for any abort checking to be performed in the user code - to
- * continue the transfer, call the function again with identical parameters and it will resume until the BytesProcessed
- * value reaches the total transfer length.
- *
- * <b>Single Stream Transfer Example:</b>
- * \code
- * uint8_t ErrorCode;
- *
- * if ((ErrorCode = Pipe_Null_Stream(512, NULL)) != PIPE_RWSTREAM_NoError)
- * {
- * // Stream failed to complete - check ErrorCode here
- * }
- * \endcode
- *
- * <b>Partial Stream Transfers Example:</b>
- * \code
- * uint8_t ErrorCode;
- * uint16_t BytesProcessed;
- *
- * BytesProcessed = 0;
- * while ((ErrorCode = Pipe_Null_Stream(512, &BytesProcessed)) == PIPE_RWSTREAM_IncompleteTransfer)
- * {
- * // Stream not yet complete - do other actions here, abort if required
- * }
- *
- * if (ErrorCode != PIPE_RWSTREAM_NoError)
- * {
- * // Stream failed to complete - check ErrorCode here
- * }
- * \endcode
- *
- * \note 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().
- *
- * \param[in] Length Number of zero bytes to write via the currently selected pipe.
- * \param[in] BytesProcessed Pointer to a location where the total number of bytes already processed should
- * updated, \c NULL if the entire stream should be processed at once.
- *
- * \return A value from the \ref Pipe_Stream_RW_ErrorCodes_t enum.
- */
- uint8_t Pipe_Null_Stream(uint16_t Length,
- uint16_t* const BytesProcessed);
-
- //@}
-
- /** \name Stream functions for RAM source/destination data */
- //@{
-
- /** 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
- * \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.
- *
- * If the BytesProcessed parameter is \c NULL, the entire stream transfer is attempted at once,
- * failing or succeeding as a single unit. If the BytesProcessed parameter points to a valid
- * storage location, the transfer will instead be performed as a series of chunks. Each time
- * the pipe bank becomes full while there is still data to process (and after the current
- * packet transmission has been initiated) the BytesProcessed location will be updated with the
- * total number of bytes processed in the stream, and the function will exit with an error code of
- * \ref PIPE_RWSTREAM_IncompleteTransfer. This allows for any abort checking to be performed
- * in the user code - to continue the transfer, call the function again with identical parameters
- * and it will resume until the BytesProcessed value reaches the total transfer length.
- *
- * <b>Single Stream Transfer Example:</b>
- * \code
- * uint8_t DataStream[512];
- * uint8_t ErrorCode;
- *
- * if ((ErrorCode = Pipe_Write_Stream_LE(DataStream, sizeof(DataStream),
- * NULL)) != PIPE_RWSTREAM_NoError)
- * {
- * // Stream failed to complete - check ErrorCode here
- * }
- * \endcode
- *
- * <b>Partial Stream Transfers Example:</b>
- * \code
- * uint8_t DataStream[512];
- * uint8_t ErrorCode;
- * uint16_t BytesProcessed;
- *
- * BytesProcessed = 0;
- * while ((ErrorCode = Pipe_Write_Stream_LE(DataStream, sizeof(DataStream),
- * &BytesProcessed)) == PIPE_RWSTREAM_IncompleteTransfer)
- * {
- * // Stream not yet complete - do other actions here, abort if required
- * }
- *
- * if (ErrorCode != PIPE_RWSTREAM_NoError)
- * {
- * // Stream failed to complete - check ErrorCode here
- * }
- * \endcode
- *
- * \note 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().
- *
- * \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] BytesProcessed Pointer to a location where the total number of bytes already processed should
- * updated, \c NULL if the entire stream should be written at once.
- *
- * \return A value from the \ref Pipe_Stream_RW_ErrorCodes_t enum.
- */
- uint8_t Pipe_Write_Stream_LE(const void* const Buffer,
- uint16_t Length,
- uint16_t* const BytesProcessed) 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
- * \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.
- *
- * \note 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().
- *
- * \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] BytesProcessed Pointer to a location where the total number of bytes already processed should
- * updated, \c NULL if the entire stream should be written at once.
- *
- * \return A value from the \ref Pipe_Stream_RW_ErrorCodes_t enum.
- */
- uint8_t Pipe_Write_Stream_BE(const void* const Buffer,
- uint16_t Length,
- uint16_t* const BytesProcessed) 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
- * \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.
- *
- * If the BytesProcessed parameter is \c NULL, the entire stream transfer is attempted at once,
- * failing or succeeding as a single unit. If the BytesProcessed parameter points to a valid
- * storage location, the transfer will instead be performed as a series of chunks. Each time
- * the pipe bank becomes empty while there is still data to process (and after the current
- * packet has been acknowledged) the BytesProcessed location will be updated with the total number
- * of bytes processed in the stream, and the function will exit with an error code of
- * \ref PIPE_RWSTREAM_IncompleteTransfer. This allows for any abort checking to be performed
- * in the user code - to continue the transfer, call the function again with identical parameters
- * and it will resume until the BytesProcessed value reaches the total transfer length.
- *
- * <b>Single Stream Transfer Example:</b>
- * \code
- * uint8_t DataStream[512];
- * uint8_t ErrorCode;
- *
- * if ((ErrorCode = Pipe_Read_Stream_LE(DataStream, sizeof(DataStream),
- * NULL)) != PIPE_RWSTREAM_NoError)
- * {
- * // Stream failed to complete - check ErrorCode here
- * }
- * \endcode
- *
- * <b>Partial Stream Transfers Example:</b>
- * \code
- * uint8_t DataStream[512];
- * uint8_t ErrorCode;
- * uint16_t BytesProcessed;
- *
- * BytesProcessed = 0;
- * while ((ErrorCode = Pipe_Read_Stream_LE(DataStream, sizeof(DataStream),
- * &BytesProcessed)) == PIPE_RWSTREAM_IncompleteTransfer)
- * {
- * // Stream not yet complete - do other actions here, abort if required
- * }
- *
- * if (ErrorCode != PIPE_RWSTREAM_NoError)
- * {
- * // Stream failed to complete - check ErrorCode here
- * }
- * \endcode
- *
- * \note 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().
- *
- * \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] BytesProcessed Pointer to a location where the total number of bytes already processed should
- * updated, \c NULL if the entire stream should be read at once.
- *
- * \return A value from the \ref Pipe_Stream_RW_ErrorCodes_t enum.
- */
- uint8_t Pipe_Read_Stream_LE(void* const Buffer,
- uint16_t Length,
- uint16_t* const BytesProcessed) 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
- * \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.
- *
- * \note 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().
- *
- * \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] BytesProcessed Pointer to a location where the total number of bytes already processed should
- * updated, \c NULL if the entire stream should be read at once.
- *
- * \return A value from the \ref Pipe_Stream_RW_ErrorCodes_t enum.
- */
- uint8_t Pipe_Read_Stream_BE(void* const Buffer,
- uint16_t Length,
- uint16_t* const BytesProcessed) ATTR_NON_NULL_PTR_ARG(1);
- //@}
-
- /** \name Stream functions for EEPROM source/destination data */
- //@{
-
- /** EEPROM buffer source version of \ref Pipe_Write_Stream_LE().
- *
- * \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] BytesProcessed Pointer to a location where the total number of bytes already processed should
- * updated, \c NULL if the entire stream should be written at once.
- *
- * \return A value from the \ref Pipe_Stream_RW_ErrorCodes_t enum.
- */
- uint8_t Pipe_Write_EStream_LE(const void* const Buffer,
- uint16_t Length,
- uint16_t* const BytesProcessed) ATTR_NON_NULL_PTR_ARG(1);
-
- /** EEPROM buffer source version of \ref Pipe_Write_Stream_BE().
- *
- * \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] BytesProcessed Pointer to a location where the total number of bytes already processed should
- * updated, \c NULL if the entire stream should be written at once.
- *
- * \return A value from the \ref Pipe_Stream_RW_ErrorCodes_t enum.
- */
- uint8_t Pipe_Write_EStream_BE(const void* const Buffer,
- uint16_t Length,
- uint16_t* const BytesProcessed) ATTR_NON_NULL_PTR_ARG(1);
-
- /** EEPROM buffer source version of \ref Pipe_Read_Stream_LE().
- *
- * \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] BytesProcessed Pointer to a location where the total number of bytes already processed should
- * updated, \c NULL if the entire stream should be read at once.
- *
- * \return A value from the \ref Pipe_Stream_RW_ErrorCodes_t enum.
- */
- uint8_t Pipe_Read_EStream_LE(void* const Buffer,
- uint16_t Length,
- uint16_t* const BytesProcessed) ATTR_NON_NULL_PTR_ARG(1);
-
- /** EEPROM buffer source version of \ref Pipe_Read_Stream_BE().
- *
- * \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] BytesProcessed Pointer to a location where the total number of bytes already processed should
- * updated, \c NULL if the entire stream should be read at once.
- *
- * \return A value from the \ref Pipe_Stream_RW_ErrorCodes_t enum.
- */
- uint8_t Pipe_Read_EStream_BE(void* const Buffer,
- uint16_t Length,
- uint16_t* const BytesProcessed) ATTR_NON_NULL_PTR_ARG(1);
- //@}
-
- /** \name Stream functions for PROGMEM source/destination data */
- //@{
-
- /** FLASH buffer source version of \ref Pipe_Write_Stream_LE().
- *
- * \pre The FLASH data must be located in the first 64KB of FLASH for this function to work correctly.
- *
- * \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] BytesProcessed Pointer to a location where the total number of bytes already processed should
- * updated, \c NULL if the entire stream should be written at once.
- *
- * \return A value from the \ref Pipe_Stream_RW_ErrorCodes_t enum.
- */
- uint8_t Pipe_Write_PStream_LE(const void* const Buffer,
- uint16_t Length,
- uint16_t* const BytesProcessed) ATTR_NON_NULL_PTR_ARG(1);
-
- /** FLASH buffer source version of \ref Pipe_Write_Stream_BE().
- *
- * \pre The FLASH data must be located in the first 64KB of FLASH for this function to work correctly.
- *
- * \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] BytesProcessed Pointer to a location where the total number of bytes already processed should
- * updated, \c NULL if the entire stream should be written at once.
- *
- * \return A value from the \ref Pipe_Stream_RW_ErrorCodes_t enum.
- */
- uint8_t Pipe_Write_PStream_BE(const void* const Buffer,
- uint16_t Length,
- uint16_t* const BytesProcessed) ATTR_NON_NULL_PTR_ARG(1);
- //@}
-
- /* Disable C linkage for C++ Compilers: */
- #if defined(__cplusplus)
- }
- #endif
-
-#endif
-
-/** @} */
+/* + LUFA Library + Copyright (C) Dean Camera, 2012. + + dean [at] fourwalledcubicle [dot] com + www.lufa-lib.org +*/ + +/* + Copyright 2012 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 + software, including all implied warranties of merchantability + and fitness. In no event shall the author be liable for any + special, indirect or consequential damages or any damages + whatsoever resulting from loss of use, data or profits, whether + in an action of contract, negligence or other tortious action, + arising out of or in connection with the use or performance of + this software. +*/ + +/** \file + * \brief Pipe data stream transmission and reception management for the AVR8 microcontrollers + * \copydetails Group_PipeStreamRW_AVR8 + * + * \note This file should not be included directly. It is automatically included as needed by the USB driver + * dispatch header located in LUFA/Drivers/USB/USB.h. + */ + +/** \ingroup Group_PipeStreamRW + * \defgroup Group_PipeStreamRW_AVR8 Read/Write of Multi-Byte Streams (AVR8) + * \brief Pipe data stream transmission and reception management for the Atmel AVR8 architecture. + * + * Functions, macros, variables, enums and types related to data reading and writing of data streams from + * and to pipes. + * + * @{ + */ + +#ifndef __PIPE_STREAM_AVR8_H__ +#define __PIPE_STREAM_AVR8_H__ + + /* Includes: */ + #include "../../../../Common/Common.h" + #include "../USBMode.h" + #include "../USBTask.h" + + /* Enable C linkage for C++ Compilers: */ + #if defined(__cplusplus) + extern "C" { + #endif + + /* Preprocessor Checks: */ + #if !defined(__INCLUDE_FROM_USB_DRIVER) + #error Do not include this file directly. Include LUFA/Drivers/USB/USB.h instead. + #endif + + /* Public Interface - May be used in end-application: */ + /* Function Prototypes: */ + /** \name Stream functions for null data */ + //@{ + + /** 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. + * + * If the BytesProcessed parameter is \c NULL, the entire stream transfer is attempted at once, failing or + * succeeding as a single unit. If the BytesProcessed parameter points to a valid storage location, the transfer + * will instead be performed as a series of chunks. Each time the pipe bank becomes empty while there is still data + * to process (and after the current packet has been acknowledged) the BytesProcessed location will be updated with + * the total number of bytes processed in the stream, and the function will exit with an error code of + * \ref PIPE_RWSTREAM_IncompleteTransfer. This allows for any abort checking to be performed in the user code - to + * continue the transfer, call the function again with identical parameters and it will resume until the BytesProcessed + * value reaches the total transfer length. + * + * <b>Single Stream Transfer Example:</b> + * \code + * uint8_t ErrorCode; + * + * if ((ErrorCode = Pipe_Discard_Stream(512, NULL)) != PIPE_RWSTREAM_NoError) + * { + * // Stream failed to complete - check ErrorCode here + * } + * \endcode + * + * <b>Partial Stream Transfers Example:</b> + * \code + * uint8_t ErrorCode; + * uint16_t BytesProcessed; + * + * BytesProcessed = 0; + * while ((ErrorCode = Pipe_Discard_Stream(512, &BytesProcessed)) == PIPE_RWSTREAM_IncompleteTransfer) + * { + * // Stream not yet complete - do other actions here, abort if required + * } + * + * if (ErrorCode != PIPE_RWSTREAM_NoError) + * { + * // Stream failed to complete - check ErrorCode here + * } + * \endcode + * + * \note 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(). + * + * \param[in] Length Number of bytes to discard via the currently selected pipe. + * \param[in] BytesProcessed Pointer to a location where the total number of bytes already processed should + * updated, \c NULL if the entire stream should be processed at once. + * + * \return A value from the \ref Pipe_Stream_RW_ErrorCodes_t enum. + */ + uint8_t Pipe_Discard_Stream(uint16_t Length, + uint16_t* const BytesProcessed); + + /** Writes a given number of zeroed bytes to the pipe, sending full pipe packets from the host to the device + * as needed. The last packet is not automatically sent once the remaining bytes has been written; the + * user is responsible for manually discarding the last packet from the device via the \ref Pipe_ClearOUT() macro. + * + * If the BytesProcessed parameter is \c NULL, the entire stream transfer is attempted at once, failing or + * succeeding as a single unit. If the BytesProcessed parameter points to a valid storage location, the transfer + * will instead be performed as a series of chunks. Each time the pipe bank becomes full while there is still data + * to process (and after the current packet transmission has been initiated) the BytesProcessed location will be + * updated with the total number of bytes processed in the stream, and the function will exit with an error code of + * \ref PIPE_RWSTREAM_IncompleteTransfer. This allows for any abort checking to be performed in the user code - to + * continue the transfer, call the function again with identical parameters and it will resume until the BytesProcessed + * value reaches the total transfer length. + * + * <b>Single Stream Transfer Example:</b> + * \code + * uint8_t ErrorCode; + * + * if ((ErrorCode = Pipe_Null_Stream(512, NULL)) != PIPE_RWSTREAM_NoError) + * { + * // Stream failed to complete - check ErrorCode here + * } + * \endcode + * + * <b>Partial Stream Transfers Example:</b> + * \code + * uint8_t ErrorCode; + * uint16_t BytesProcessed; + * + * BytesProcessed = 0; + * while ((ErrorCode = Pipe_Null_Stream(512, &BytesProcessed)) == PIPE_RWSTREAM_IncompleteTransfer) + * { + * // Stream not yet complete - do other actions here, abort if required + * } + * + * if (ErrorCode != PIPE_RWSTREAM_NoError) + * { + * // Stream failed to complete - check ErrorCode here + * } + * \endcode + * + * \note 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(). + * + * \param[in] Length Number of zero bytes to write via the currently selected pipe. + * \param[in] BytesProcessed Pointer to a location where the total number of bytes already processed should + * updated, \c NULL if the entire stream should be processed at once. + * + * \return A value from the \ref Pipe_Stream_RW_ErrorCodes_t enum. + */ + uint8_t Pipe_Null_Stream(uint16_t Length, + uint16_t* const BytesProcessed); + + //@} + + /** \name Stream functions for RAM source/destination data */ + //@{ + + /** 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 + * \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. + * + * If the BytesProcessed parameter is \c NULL, the entire stream transfer is attempted at once, + * failing or succeeding as a single unit. If the BytesProcessed parameter points to a valid + * storage location, the transfer will instead be performed as a series of chunks. Each time + * the pipe bank becomes full while there is still data to process (and after the current + * packet transmission has been initiated) the BytesProcessed location will be updated with the + * total number of bytes processed in the stream, and the function will exit with an error code of + * \ref PIPE_RWSTREAM_IncompleteTransfer. This allows for any abort checking to be performed + * in the user code - to continue the transfer, call the function again with identical parameters + * and it will resume until the BytesProcessed value reaches the total transfer length. + * + * <b>Single Stream Transfer Example:</b> + * \code + * uint8_t DataStream[512]; + * uint8_t ErrorCode; + * + * if ((ErrorCode = Pipe_Write_Stream_LE(DataStream, sizeof(DataStream), + * NULL)) != PIPE_RWSTREAM_NoError) + * { + * // Stream failed to complete - check ErrorCode here + * } + * \endcode + * + * <b>Partial Stream Transfers Example:</b> + * \code + * uint8_t DataStream[512]; + * uint8_t ErrorCode; + * uint16_t BytesProcessed; + * + * BytesProcessed = 0; + * while ((ErrorCode = Pipe_Write_Stream_LE(DataStream, sizeof(DataStream), + * &BytesProcessed)) == PIPE_RWSTREAM_IncompleteTransfer) + * { + * // Stream not yet complete - do other actions here, abort if required + * } + * + * if (ErrorCode != PIPE_RWSTREAM_NoError) + * { + * // Stream failed to complete - check ErrorCode here + * } + * \endcode + * + * \note 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(). + * + * \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] BytesProcessed Pointer to a location where the total number of bytes already processed should + * updated, \c NULL if the entire stream should be written at once. + * + * \return A value from the \ref Pipe_Stream_RW_ErrorCodes_t enum. + */ + uint8_t Pipe_Write_Stream_LE(const void* const Buffer, + uint16_t Length, + uint16_t* const BytesProcessed) 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 + * \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. + * + * \note 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(). + * + * \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] BytesProcessed Pointer to a location where the total number of bytes already processed should + * updated, \c NULL if the entire stream should be written at once. + * + * \return A value from the \ref Pipe_Stream_RW_ErrorCodes_t enum. + */ + uint8_t Pipe_Write_Stream_BE(const void* const Buffer, + uint16_t Length, + uint16_t* const BytesProcessed) 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 + * \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. + * + * If the BytesProcessed parameter is \c NULL, the entire stream transfer is attempted at once, + * failing or succeeding as a single unit. If the BytesProcessed parameter points to a valid + * storage location, the transfer will instead be performed as a series of chunks. Each time + * the pipe bank becomes empty while there is still data to process (and after the current + * packet has been acknowledged) the BytesProcessed location will be updated with the total number + * of bytes processed in the stream, and the function will exit with an error code of + * \ref PIPE_RWSTREAM_IncompleteTransfer. This allows for any abort checking to be performed + * in the user code - to continue the transfer, call the function again with identical parameters + * and it will resume until the BytesProcessed value reaches the total transfer length. + * + * <b>Single Stream Transfer Example:</b> + * \code + * uint8_t DataStream[512]; + * uint8_t ErrorCode; + * + * if ((ErrorCode = Pipe_Read_Stream_LE(DataStream, sizeof(DataStream), + * NULL)) != PIPE_RWSTREAM_NoError) + * { + * // Stream failed to complete - check ErrorCode here + * } + * \endcode + * + * <b>Partial Stream Transfers Example:</b> + * \code + * uint8_t DataStream[512]; + * uint8_t ErrorCode; + * uint16_t BytesProcessed; + * + * BytesProcessed = 0; + * while ((ErrorCode = Pipe_Read_Stream_LE(DataStream, sizeof(DataStream), + * &BytesProcessed)) == PIPE_RWSTREAM_IncompleteTransfer) + * { + * // Stream not yet complete - do other actions here, abort if required + * } + * + * if (ErrorCode != PIPE_RWSTREAM_NoError) + * { + * // Stream failed to complete - check ErrorCode here + * } + * \endcode + * + * \note 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(). + * + * \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] BytesProcessed Pointer to a location where the total number of bytes already processed should + * updated, \c NULL if the entire stream should be read at once. + * + * \return A value from the \ref Pipe_Stream_RW_ErrorCodes_t enum. + */ + uint8_t Pipe_Read_Stream_LE(void* const Buffer, + uint16_t Length, + uint16_t* const BytesProcessed) 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 + * \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. + * + * \note 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(). + * + * \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] BytesProcessed Pointer to a location where the total number of bytes already processed should + * updated, \c NULL if the entire stream should be read at once. + * + * \return A value from the \ref Pipe_Stream_RW_ErrorCodes_t enum. + */ + uint8_t Pipe_Read_Stream_BE(void* const Buffer, + uint16_t Length, + uint16_t* const BytesProcessed) ATTR_NON_NULL_PTR_ARG(1); + //@} + + /** \name Stream functions for EEPROM source/destination data */ + //@{ + + /** EEPROM buffer source version of \ref Pipe_Write_Stream_LE(). + * + * \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] BytesProcessed Pointer to a location where the total number of bytes already processed should + * updated, \c NULL if the entire stream should be written at once. + * + * \return A value from the \ref Pipe_Stream_RW_ErrorCodes_t enum. + */ + uint8_t Pipe_Write_EStream_LE(const void* const Buffer, + uint16_t Length, + uint16_t* const BytesProcessed) ATTR_NON_NULL_PTR_ARG(1); + + /** EEPROM buffer source version of \ref Pipe_Write_Stream_BE(). + * + * \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] BytesProcessed Pointer to a location where the total number of bytes already processed should + * updated, \c NULL if the entire stream should be written at once. + * + * \return A value from the \ref Pipe_Stream_RW_ErrorCodes_t enum. + */ + uint8_t Pipe_Write_EStream_BE(const void* const Buffer, + uint16_t Length, + uint16_t* const BytesProcessed) ATTR_NON_NULL_PTR_ARG(1); + + /** EEPROM buffer source version of \ref Pipe_Read_Stream_LE(). + * + * \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] BytesProcessed Pointer to a location where the total number of bytes already processed should + * updated, \c NULL if the entire stream should be read at once. + * + * \return A value from the \ref Pipe_Stream_RW_ErrorCodes_t enum. + */ + uint8_t Pipe_Read_EStream_LE(void* const Buffer, + uint16_t Length, + uint16_t* const BytesProcessed) ATTR_NON_NULL_PTR_ARG(1); + + /** EEPROM buffer source version of \ref Pipe_Read_Stream_BE(). + * + * \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] BytesProcessed Pointer to a location where the total number of bytes already processed should + * updated, \c NULL if the entire stream should be read at once. + * + * \return A value from the \ref Pipe_Stream_RW_ErrorCodes_t enum. + */ + uint8_t Pipe_Read_EStream_BE(void* const Buffer, + uint16_t Length, + uint16_t* const BytesProcessed) ATTR_NON_NULL_PTR_ARG(1); + //@} + + /** \name Stream functions for PROGMEM source/destination data */ + //@{ + + /** FLASH buffer source version of \ref Pipe_Write_Stream_LE(). + * + * \pre The FLASH data must be located in the first 64KB of FLASH for this function to work correctly. + * + * \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] BytesProcessed Pointer to a location where the total number of bytes already processed should + * updated, \c NULL if the entire stream should be written at once. + * + * \return A value from the \ref Pipe_Stream_RW_ErrorCodes_t enum. + */ + uint8_t Pipe_Write_PStream_LE(const void* const Buffer, + uint16_t Length, + uint16_t* const BytesProcessed) ATTR_NON_NULL_PTR_ARG(1); + + /** FLASH buffer source version of \ref Pipe_Write_Stream_BE(). + * + * \pre The FLASH data must be located in the first 64KB of FLASH for this function to work correctly. + * + * \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] BytesProcessed Pointer to a location where the total number of bytes already processed should + * updated, \c NULL if the entire stream should be written at once. + * + * \return A value from the \ref Pipe_Stream_RW_ErrorCodes_t enum. + */ + uint8_t Pipe_Write_PStream_BE(const void* const Buffer, + uint16_t Length, + uint16_t* const BytesProcessed) ATTR_NON_NULL_PTR_ARG(1); + //@} + + /* Disable C linkage for C++ Compilers: */ + #if defined(__cplusplus) + } + #endif + +#endif + +/** @} */ diff --git a/LUFA/Drivers/USB/Core/UC3/EndpointStream_UC3.c b/LUFA/Drivers/USB/Core/UC3/EndpointStream_UC3.c index b4e130e74..515461065 100644 --- a/LUFA/Drivers/USB/Core/UC3/EndpointStream_UC3.c +++ b/LUFA/Drivers/USB/Core/UC3/EndpointStream_UC3.c @@ -1,235 +1,235 @@ -/*
- LUFA Library
- Copyright (C) Dean Camera, 2012.
-
- dean [at] fourwalledcubicle [dot] com
- www.lufa-lib.org
-*/
-
-/*
- Copyright 2012 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
- software, including all implied warranties of merchantability
- and fitness. In no event shall the author be liable for any
- special, indirect or consequential damages or any damages
- whatsoever resulting from loss of use, data or profits, whether
- in an action of contract, negligence or other tortious action,
- arising out of or in connection with the use or performance of
- this software.
-*/
-
-#include "../../../../Common/Common.h"
-#if (ARCH == ARCH_UC3)
-
-#define __INCLUDE_FROM_USB_DRIVER
-#include "../USBMode.h"
-
-#if defined(USB_CAN_BE_DEVICE)
-
-#include "EndpointStream_UC3.h"
-
-#if !defined(CONTROL_ONLY_DEVICE)
-uint8_t Endpoint_Discard_Stream(uint16_t Length,
- uint16_t* const BytesProcessed)
-{
- uint8_t ErrorCode;
- uint16_t BytesInTransfer = 0;
-
- if ((ErrorCode = Endpoint_WaitUntilReady()))
- return ErrorCode;
-
- if (BytesProcessed != NULL)
- Length -= *BytesProcessed;
-
- while (Length)
- {
- if (!(Endpoint_IsReadWriteAllowed()))
- {
- Endpoint_ClearOUT();
-
- if (BytesProcessed != NULL)
- {
- *BytesProcessed += BytesInTransfer;
- return ENDPOINT_RWSTREAM_IncompleteTransfer;
- }
-
- if ((ErrorCode = Endpoint_WaitUntilReady()))
- return ErrorCode;
- }
- else
- {
- Endpoint_Discard_8();
-
- Length--;
- BytesInTransfer++;
- }
- }
-
- return ENDPOINT_RWSTREAM_NoError;
-}
-
-uint8_t Endpoint_Null_Stream(uint16_t Length,
- uint16_t* const BytesProcessed)
-{
- uint8_t ErrorCode;
- uint16_t BytesInTransfer = 0;
-
- if ((ErrorCode = Endpoint_WaitUntilReady()))
- return ErrorCode;
-
- if (BytesProcessed != NULL)
- Length -= *BytesProcessed;
-
- while (Length)
- {
- if (!(Endpoint_IsReadWriteAllowed()))
- {
- Endpoint_ClearIN();
-
- if (BytesProcessed != NULL)
- {
- *BytesProcessed += BytesInTransfer;
- return ENDPOINT_RWSTREAM_IncompleteTransfer;
- }
-
- if ((ErrorCode = Endpoint_WaitUntilReady()))
- return ErrorCode;
- }
- else
- {
- Endpoint_Write_8(0);
-
- Length--;
- BytesInTransfer++;
- }
- }
-
- return ENDPOINT_RWSTREAM_NoError;
-}
-
-/* The following abuses the C preprocessor in order to copy-paste common code with slight alterations,
- * so that the code needs to be written once. It is a crude form of templating to reduce code maintenance. */
-
-#define TEMPLATE_FUNC_NAME Endpoint_Write_Stream_LE
-#define TEMPLATE_BUFFER_TYPE const void*
-#define TEMPLATE_CLEAR_ENDPOINT() Endpoint_ClearIN()
-#define TEMPLATE_BUFFER_OFFSET(Length) 0
-#define TEMPLATE_BUFFER_MOVE(BufferPtr, Amount) BufferPtr += Amount
-#define TEMPLATE_TRANSFER_BYTE(BufferPtr) Endpoint_Write_8(*BufferPtr)
-#include "Template/Template_Endpoint_RW.c"
-
-#define TEMPLATE_FUNC_NAME Endpoint_Write_Stream_BE
-#define TEMPLATE_BUFFER_TYPE const void*
-#define TEMPLATE_CLEAR_ENDPOINT() Endpoint_ClearIN()
-#define TEMPLATE_BUFFER_OFFSET(Length) (Length - 1)
-#define TEMPLATE_BUFFER_MOVE(BufferPtr, Amount) BufferPtr -= Amount
-#define TEMPLATE_TRANSFER_BYTE(BufferPtr) Endpoint_Write_8(*BufferPtr)
-#include "Template/Template_Endpoint_RW.c"
-
-#define TEMPLATE_FUNC_NAME Endpoint_Read_Stream_LE
-#define TEMPLATE_BUFFER_TYPE void*
-#define TEMPLATE_CLEAR_ENDPOINT() Endpoint_ClearOUT()
-#define TEMPLATE_BUFFER_OFFSET(Length) 0
-#define TEMPLATE_BUFFER_MOVE(BufferPtr, Amount) BufferPtr += Amount
-#define TEMPLATE_TRANSFER_BYTE(BufferPtr) *BufferPtr = Endpoint_Read_8()
-#include "Template/Template_Endpoint_RW.c"
-
-#define TEMPLATE_FUNC_NAME Endpoint_Read_Stream_BE
-#define TEMPLATE_BUFFER_TYPE void*
-#define TEMPLATE_CLEAR_ENDPOINT() Endpoint_ClearOUT()
-#define TEMPLATE_BUFFER_OFFSET(Length) (Length - 1)
-#define TEMPLATE_BUFFER_MOVE(BufferPtr, Amount) BufferPtr -= Amount
-#define TEMPLATE_TRANSFER_BYTE(BufferPtr) *BufferPtr = Endpoint_Read_8()
-#include "Template/Template_Endpoint_RW.c"
-
-#if defined(ARCH_HAS_FLASH_ADDRESS_SPACE)
- #define TEMPLATE_FUNC_NAME Endpoint_Write_PStream_LE
- #define TEMPLATE_BUFFER_TYPE const void*
- #define TEMPLATE_CLEAR_ENDPOINT() Endpoint_ClearIN()
- #define TEMPLATE_BUFFER_OFFSET(Length) 0
- #define TEMPLATE_BUFFER_MOVE(BufferPtr, Amount) BufferPtr += Amount
- #define TEMPLATE_TRANSFER_BYTE(BufferPtr) Endpoint_Write_8(pgm_read_byte(BufferPtr))
- #include "Template/Template_Endpoint_RW.c"
-
- #define TEMPLATE_FUNC_NAME Endpoint_Write_PStream_BE
- #define TEMPLATE_BUFFER_TYPE const void*
- #define TEMPLATE_CLEAR_ENDPOINT() Endpoint_ClearIN()
- #define TEMPLATE_BUFFER_OFFSET(Length) (Length - 1)
- #define TEMPLATE_BUFFER_MOVE(BufferPtr, Amount) BufferPtr -= Amount
- #define TEMPLATE_TRANSFER_BYTE(BufferPtr) Endpoint_Write_8(pgm_read_byte(BufferPtr))
- #include "Template/Template_Endpoint_RW.c"
-#endif
-
-#if defined(ARCH_HAS_EEPROM_ADDRESS_SPACE)
- #define TEMPLATE_FUNC_NAME Endpoint_Write_EStream_LE
- #define TEMPLATE_BUFFER_TYPE const void*
- #define TEMPLATE_CLEAR_ENDPOINT() Endpoint_ClearIN()
- #define TEMPLATE_BUFFER_OFFSET(Length) 0
- #define TEMPLATE_BUFFER_MOVE(BufferPtr, Amount) BufferPtr += Amount
- #define TEMPLATE_TRANSFER_BYTE(BufferPtr) Endpoint_Write_8(eeprom_read_byte(BufferPtr))
- #include "Template/Template_Endpoint_RW.c"
-
- #define TEMPLATE_FUNC_NAME Endpoint_Write_EStream_BE
- #define TEMPLATE_BUFFER_TYPE const void*
- #define TEMPLATE_CLEAR_ENDPOINT() Endpoint_ClearIN()
- #define TEMPLATE_BUFFER_OFFSET(Length) (Length - 1)
- #define TEMPLATE_BUFFER_MOVE(BufferPtr, Amount) BufferPtr -= Amount
- #define TEMPLATE_TRANSFER_BYTE(BufferPtr) Endpoint_Write_8(eeprom_read_byte(BufferPtr))
- #include "Template/Template_Endpoint_RW.c"
-
- #define TEMPLATE_FUNC_NAME Endpoint_Read_EStream_LE
- #define TEMPLATE_BUFFER_TYPE void*
- #define TEMPLATE_CLEAR_ENDPOINT() Endpoint_ClearOUT()
- #define TEMPLATE_BUFFER_OFFSET(Length) 0
- #define TEMPLATE_BUFFER_MOVE(BufferPtr, Amount) BufferPtr += Amount
- #define TEMPLATE_TRANSFER_BYTE(BufferPtr) eeprom_update_byte(BufferPtr, Endpoint_Read_8())
- #include "Template/Template_Endpoint_RW.c"
-
- #define TEMPLATE_FUNC_NAME Endpoint_Read_EStream_BE
- #define TEMPLATE_BUFFER_TYPE void*
- #define TEMPLATE_CLEAR_ENDPOINT() Endpoint_ClearOUT()
- #define TEMPLATE_BUFFER_OFFSET(Length) (Length - 1)
- #define TEMPLATE_BUFFER_MOVE(BufferPtr, Amount) BufferPtr -= Amount
- #define TEMPLATE_TRANSFER_BYTE(BufferPtr) eeprom_update_byte(BufferPtr, Endpoint_Read_8())
- #include "Template/Template_Endpoint_RW.c"
-#endif
-
-#endif
-
-#define TEMPLATE_FUNC_NAME Endpoint_Write_Control_Stream_LE
-#define TEMPLATE_BUFFER_OFFSET(Length) 0
-#define TEMPLATE_BUFFER_MOVE(BufferPtr, Amount) BufferPtr += Amount
-#define TEMPLATE_TRANSFER_BYTE(BufferPtr) Endpoint_Write_8(*BufferPtr)
-#include "Template/Template_Endpoint_Control_W.c"
-
-#define TEMPLATE_FUNC_NAME Endpoint_Write_Control_Stream_BE
-#define TEMPLATE_BUFFER_OFFSET(Length) (Length - 1)
-#define TEMPLATE_BUFFER_MOVE(BufferPtr, Amount) BufferPtr -= Amount
-#define TEMPLATE_TRANSFER_BYTE(BufferPtr) Endpoint_Write_8(*BufferPtr)
-#include "Template/Template_Endpoint_Control_W.c"
-
-#define TEMPLATE_FUNC_NAME Endpoint_Read_Control_Stream_LE
-#define TEMPLATE_BUFFER_OFFSET(Length) 0
-#define TEMPLATE_BUFFER_MOVE(BufferPtr, Amount) BufferPtr += Amount
-#define TEMPLATE_TRANSFER_BYTE(BufferPtr) *BufferPtr = Endpoint_Read_8()
-#include "Template/Template_Endpoint_Control_R.c"
-
-#define TEMPLATE_FUNC_NAME Endpoint_Read_Control_Stream_BE
-#define TEMPLATE_BUFFER_OFFSET(Length) (Length - 1)
-#define TEMPLATE_BUFFER_MOVE(BufferPtr, Amount) BufferPtr -= Amount
-#define TEMPLATE_TRANSFER_BYTE(BufferPtr) *BufferPtr = Endpoint_Read_8()
-#include "Template/Template_Endpoint_Control_R.c"
-
+/* + LUFA Library + Copyright (C) Dean Camera, 2012. + + dean [at] fourwalledcubicle [dot] com + www.lufa-lib.org +*/ + +/* + Copyright 2012 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 + software, including all implied warranties of merchantability + and fitness. In no event shall the author be liable for any + special, indirect or consequential damages or any damages + whatsoever resulting from loss of use, data or profits, whether + in an action of contract, negligence or other tortious action, + arising out of or in connection with the use or performance of + this software. +*/ + +#include "../../../../Common/Common.h" +#if (ARCH == ARCH_UC3) + +#define __INCLUDE_FROM_USB_DRIVER +#include "../USBMode.h" + +#if defined(USB_CAN_BE_DEVICE) + +#include "EndpointStream_UC3.h" + +#if !defined(CONTROL_ONLY_DEVICE) +uint8_t Endpoint_Discard_Stream(uint16_t Length, + uint16_t* const BytesProcessed) +{ + uint8_t ErrorCode; + uint16_t BytesInTransfer = 0; + + if ((ErrorCode = Endpoint_WaitUntilReady())) + return ErrorCode; + + if (BytesProcessed != NULL) + Length -= *BytesProcessed; + + while (Length) + { + if (!(Endpoint_IsReadWriteAllowed())) + { + Endpoint_ClearOUT(); + + if (BytesProcessed != NULL) + { + *BytesProcessed += BytesInTransfer; + return ENDPOINT_RWSTREAM_IncompleteTransfer; + } + + if ((ErrorCode = Endpoint_WaitUntilReady())) + return ErrorCode; + } + else + { + Endpoint_Discard_8(); + + Length--; + BytesInTransfer++; + } + } + + return ENDPOINT_RWSTREAM_NoError; +} + +uint8_t Endpoint_Null_Stream(uint16_t Length, + uint16_t* const BytesProcessed) +{ + uint8_t ErrorCode; + uint16_t BytesInTransfer = 0; + + if ((ErrorCode = Endpoint_WaitUntilReady())) + return ErrorCode; + + if (BytesProcessed != NULL) + Length -= *BytesProcessed; + + while (Length) + { + if (!(Endpoint_IsReadWriteAllowed())) + { + Endpoint_ClearIN(); + + if (BytesProcessed != NULL) + { + *BytesProcessed += BytesInTransfer; + return ENDPOINT_RWSTREAM_IncompleteTransfer; + } + + if ((ErrorCode = Endpoint_WaitUntilReady())) + return ErrorCode; + } + else + { + Endpoint_Write_8(0); + + Length--; + BytesInTransfer++; + } + } + + return ENDPOINT_RWSTREAM_NoError; +} + +/* The following abuses the C preprocessor in order to copy-paste common code with slight alterations, + * so that the code needs to be written once. It is a crude form of templating to reduce code maintenance. */ + +#define TEMPLATE_FUNC_NAME Endpoint_Write_Stream_LE +#define TEMPLATE_BUFFER_TYPE const void* +#define TEMPLATE_CLEAR_ENDPOINT() Endpoint_ClearIN() +#define TEMPLATE_BUFFER_OFFSET(Length) 0 +#define TEMPLATE_BUFFER_MOVE(BufferPtr, Amount) BufferPtr += Amount +#define TEMPLATE_TRANSFER_BYTE(BufferPtr) Endpoint_Write_8(*BufferPtr) +#include "Template/Template_Endpoint_RW.c" + +#define TEMPLATE_FUNC_NAME Endpoint_Write_Stream_BE +#define TEMPLATE_BUFFER_TYPE const void* +#define TEMPLATE_CLEAR_ENDPOINT() Endpoint_ClearIN() +#define TEMPLATE_BUFFER_OFFSET(Length) (Length - 1) +#define TEMPLATE_BUFFER_MOVE(BufferPtr, Amount) BufferPtr -= Amount +#define TEMPLATE_TRANSFER_BYTE(BufferPtr) Endpoint_Write_8(*BufferPtr) +#include "Template/Template_Endpoint_RW.c" + +#define TEMPLATE_FUNC_NAME Endpoint_Read_Stream_LE +#define TEMPLATE_BUFFER_TYPE void* +#define TEMPLATE_CLEAR_ENDPOINT() Endpoint_ClearOUT() +#define TEMPLATE_BUFFER_OFFSET(Length) 0 +#define TEMPLATE_BUFFER_MOVE(BufferPtr, Amount) BufferPtr += Amount +#define TEMPLATE_TRANSFER_BYTE(BufferPtr) *BufferPtr = Endpoint_Read_8() +#include "Template/Template_Endpoint_RW.c" + +#define TEMPLATE_FUNC_NAME Endpoint_Read_Stream_BE +#define TEMPLATE_BUFFER_TYPE void* +#define TEMPLATE_CLEAR_ENDPOINT() Endpoint_ClearOUT() +#define TEMPLATE_BUFFER_OFFSET(Length) (Length - 1) +#define TEMPLATE_BUFFER_MOVE(BufferPtr, Amount) BufferPtr -= Amount +#define TEMPLATE_TRANSFER_BYTE(BufferPtr) *BufferPtr = Endpoint_Read_8() +#include "Template/Template_Endpoint_RW.c" + +#if defined(ARCH_HAS_FLASH_ADDRESS_SPACE) + #define TEMPLATE_FUNC_NAME Endpoint_Write_PStream_LE + #define TEMPLATE_BUFFER_TYPE const void* + #define TEMPLATE_CLEAR_ENDPOINT() Endpoint_ClearIN() + #define TEMPLATE_BUFFER_OFFSET(Length) 0 + #define TEMPLATE_BUFFER_MOVE(BufferPtr, Amount) BufferPtr += Amount + #define TEMPLATE_TRANSFER_BYTE(BufferPtr) Endpoint_Write_8(pgm_read_byte(BufferPtr)) + #include "Template/Template_Endpoint_RW.c" + + #define TEMPLATE_FUNC_NAME Endpoint_Write_PStream_BE + #define TEMPLATE_BUFFER_TYPE const void* + #define TEMPLATE_CLEAR_ENDPOINT() Endpoint_ClearIN() + #define TEMPLATE_BUFFER_OFFSET(Length) (Length - 1) + #define TEMPLATE_BUFFER_MOVE(BufferPtr, Amount) BufferPtr -= Amount + #define TEMPLATE_TRANSFER_BYTE(BufferPtr) Endpoint_Write_8(pgm_read_byte(BufferPtr)) + #include "Template/Template_Endpoint_RW.c" +#endif + +#if defined(ARCH_HAS_EEPROM_ADDRESS_SPACE) + #define TEMPLATE_FUNC_NAME Endpoint_Write_EStream_LE + #define TEMPLATE_BUFFER_TYPE const void* + #define TEMPLATE_CLEAR_ENDPOINT() Endpoint_ClearIN() + #define TEMPLATE_BUFFER_OFFSET(Length) 0 + #define TEMPLATE_BUFFER_MOVE(BufferPtr, Amount) BufferPtr += Amount + #define TEMPLATE_TRANSFER_BYTE(BufferPtr) Endpoint_Write_8(eeprom_read_byte(BufferPtr)) + #include "Template/Template_Endpoint_RW.c" + + #define TEMPLATE_FUNC_NAME Endpoint_Write_EStream_BE + #define TEMPLATE_BUFFER_TYPE const void* + #define TEMPLATE_CLEAR_ENDPOINT() Endpoint_ClearIN() + #define TEMPLATE_BUFFER_OFFSET(Length) (Length - 1) + #define TEMPLATE_BUFFER_MOVE(BufferPtr, Amount) BufferPtr -= Amount + #define TEMPLATE_TRANSFER_BYTE(BufferPtr) Endpoint_Write_8(eeprom_read_byte(BufferPtr)) + #include "Template/Template_Endpoint_RW.c" + + #define TEMPLATE_FUNC_NAME Endpoint_Read_EStream_LE + #define TEMPLATE_BUFFER_TYPE void* + #define TEMPLATE_CLEAR_ENDPOINT() Endpoint_ClearOUT() + #define TEMPLATE_BUFFER_OFFSET(Length) 0 + #define TEMPLATE_BUFFER_MOVE(BufferPtr, Amount) BufferPtr += Amount + #define TEMPLATE_TRANSFER_BYTE(BufferPtr) eeprom_update_byte(BufferPtr, Endpoint_Read_8()) + #include "Template/Template_Endpoint_RW.c" + + #define TEMPLATE_FUNC_NAME Endpoint_Read_EStream_BE + #define TEMPLATE_BUFFER_TYPE void* + #define TEMPLATE_CLEAR_ENDPOINT() Endpoint_ClearOUT() + #define TEMPLATE_BUFFER_OFFSET(Length) (Length - 1) + #define TEMPLATE_BUFFER_MOVE(BufferPtr, Amount) BufferPtr -= Amount + #define TEMPLATE_TRANSFER_BYTE(BufferPtr) eeprom_update_byte(BufferPtr, Endpoint_Read_8()) + #include "Template/Template_Endpoint_RW.c" #endif -#endif
+#endif + +#define TEMPLATE_FUNC_NAME Endpoint_Write_Control_Stream_LE +#define TEMPLATE_BUFFER_OFFSET(Length) 0 +#define TEMPLATE_BUFFER_MOVE(BufferPtr, Amount) BufferPtr += Amount +#define TEMPLATE_TRANSFER_BYTE(BufferPtr) Endpoint_Write_8(*BufferPtr) +#include "Template/Template_Endpoint_Control_W.c" + +#define TEMPLATE_FUNC_NAME Endpoint_Write_Control_Stream_BE +#define TEMPLATE_BUFFER_OFFSET(Length) (Length - 1) +#define TEMPLATE_BUFFER_MOVE(BufferPtr, Amount) BufferPtr -= Amount +#define TEMPLATE_TRANSFER_BYTE(BufferPtr) Endpoint_Write_8(*BufferPtr) +#include "Template/Template_Endpoint_Control_W.c" + +#define TEMPLATE_FUNC_NAME Endpoint_Read_Control_Stream_LE +#define TEMPLATE_BUFFER_OFFSET(Length) 0 +#define TEMPLATE_BUFFER_MOVE(BufferPtr, Amount) BufferPtr += Amount +#define TEMPLATE_TRANSFER_BYTE(BufferPtr) *BufferPtr = Endpoint_Read_8() +#include "Template/Template_Endpoint_Control_R.c" + +#define TEMPLATE_FUNC_NAME Endpoint_Read_Control_Stream_BE +#define TEMPLATE_BUFFER_OFFSET(Length) (Length - 1) +#define TEMPLATE_BUFFER_MOVE(BufferPtr, Amount) BufferPtr -= Amount +#define TEMPLATE_TRANSFER_BYTE(BufferPtr) *BufferPtr = Endpoint_Read_8() +#include "Template/Template_Endpoint_Control_R.c" + +#endif + +#endif diff --git a/LUFA/Drivers/USB/Core/UC3/EndpointStream_UC3.h b/LUFA/Drivers/USB/Core/UC3/EndpointStream_UC3.h index 40a54ee17..3eccb7f15 100644 --- a/LUFA/Drivers/USB/Core/UC3/EndpointStream_UC3.h +++ b/LUFA/Drivers/USB/Core/UC3/EndpointStream_UC3.h @@ -1,434 +1,434 @@ -/*
- LUFA Library
- Copyright (C) Dean Camera, 2012.
-
- dean [at] fourwalledcubicle [dot] com
- www.lufa-lib.org
-*/
-
-/*
- Copyright 2012 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
- software, including all implied warranties of merchantability
- and fitness. In no event shall the author be liable for any
- special, indirect or consequential damages or any damages
- whatsoever resulting from loss of use, data or profits, whether
- in an action of contract, negligence or other tortious action,
- arising out of or in connection with the use or performance of
- this software.
-*/
-
-/** \file
- * \brief Endpoint data stream transmission and reception management for the AVR32 UC3 microcontrollers.
- * \copydetails Group_EndpointStreamRW_UC3
- *
- * \note This file should not be included directly. It is automatically included as needed by the USB driver
- * dispatch header located in LUFA/Drivers/USB/USB.h.
- */
-
-/** \ingroup Group_EndpointStreamRW
- * \defgroup Group_EndpointStreamRW_UC3 Read/Write of Multi-Byte Streams (UC3)
- * \brief Endpoint data stream transmission and reception management for the Atmel AVR32 UC3 architecture.
- *
- * Functions, macros, variables, enums and types related to data reading and writing of data streams from
- * and to endpoints.
- *
- * @{
- */
-
-#ifndef __ENDPOINT_STREAM_UC3_H__
-#define __ENDPOINT_STREAM_UC3_H__
-
- /* Includes: */
- #include "../../../../Common/Common.h"
- #include "../USBMode.h"
- #include "../USBTask.h"
-
- /* Enable C linkage for C++ Compilers: */
- #if defined(__cplusplus)
- extern "C" {
- #endif
-
- /* Preprocessor Checks: */
- #if !defined(__INCLUDE_FROM_USB_DRIVER)
- #error Do not include this file directly. Include LUFA/Drivers/USB/USB.h instead.
- #endif
-
- /* Public Interface - May be used in end-application: */
- /* Function Prototypes: */
- /** \name Stream functions for null data */
- //@{
-
- /** Reads and discards the given number of bytes from the currently selected endpoint's bank,
- * 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 \ref Endpoint_ClearOUT() macro.
- *
- * If the BytesProcessed parameter is \c NULL, the entire stream transfer is attempted at once,
- * failing or succeeding as a single unit. If the BytesProcessed parameter points to a valid
- * storage location, the transfer will instead be performed as a series of chunks. Each time
- * the endpoint bank becomes empty while there is still data to process (and after the current
- * packet has been acknowledged) the BytesProcessed location will be updated with the total number
- * of bytes processed in the stream, and the function will exit with an error code of
- * \ref ENDPOINT_RWSTREAM_IncompleteTransfer. This allows for any abort checking to be performed
- * in the user code - to continue the transfer, call the function again with identical parameters
- * and it will resume until the BytesProcessed value reaches the total transfer length.
- *
- * <b>Single Stream Transfer Example:</b>
- * \code
- * uint8_t ErrorCode;
- *
- * if ((ErrorCode = Endpoint_Discard_Stream(512, NULL)) != ENDPOINT_RWSTREAM_NoError)
- * {
- * // Stream failed to complete - check ErrorCode here
- * }
- * \endcode
- *
- * <b>Partial Stream Transfers Example:</b>
- * \code
- * uint8_t ErrorCode;
- * uint16_t BytesProcessed;
- *
- * BytesProcessed = 0;
- * while ((ErrorCode = Endpoint_Discard_Stream(512, &BytesProcessed)) == ENDPOINT_RWSTREAM_IncompleteTransfer)
- * {
- * // Stream not yet complete - do other actions here, abort if required
- * }
- *
- * if (ErrorCode != ENDPOINT_RWSTREAM_NoError)
- * {
- * // Stream failed to complete - check ErrorCode here
- * }
- * \endcode
- *
- * \note This routine should not be used on CONTROL type endpoints.
- *
- * \param[in] Length Number of bytes to discard via the currently selected endpoint.
- * \param[in] BytesProcessed Pointer to a location where the total number of bytes processed in the current
- * transaction should be updated, \c NULL if the entire stream should be read at once.
- *
- * \return A value from the \ref Endpoint_Stream_RW_ErrorCodes_t enum.
- */
- uint8_t Endpoint_Discard_Stream(uint16_t Length,
- uint16_t* const BytesProcessed);
-
- /** Writes a given number of zeroed bytes to the currently selected endpoint's bank, sending
- * full packets to the host as needed. The last packet is not automatically sent once the
- * remaining bytes have been written; the user is responsible for manually sending the last
- * packet to the host via the \ref Endpoint_ClearIN() macro.
- *
- * If the BytesProcessed parameter is \c NULL, the entire stream transfer is attempted at once,
- * failing or succeeding as a single unit. If the BytesProcessed parameter points to a valid
- * storage location, the transfer will instead be performed as a series of chunks. Each time
- * the endpoint bank becomes full while there is still data to process (and after the current
- * packet transmission has been initiated) the BytesProcessed location will be updated with the
- * total number of bytes processed in the stream, and the function will exit with an error code of
- * \ref ENDPOINT_RWSTREAM_IncompleteTransfer. This allows for any abort checking to be performed
- * in the user code - to continue the transfer, call the function again with identical parameters
- * and it will resume until the BytesProcessed value reaches the total transfer length.
- *
- * <b>Single Stream Transfer Example:</b>
- * \code
- * uint8_t ErrorCode;
- *
- * if ((ErrorCode = Endpoint_Null_Stream(512, NULL)) != ENDPOINT_RWSTREAM_NoError)
- * {
- * // Stream failed to complete - check ErrorCode here
- * }
- * \endcode
- *
- * <b>Partial Stream Transfers Example:</b>
- * \code
- * uint8_t ErrorCode;
- * uint16_t BytesProcessed;
- *
- * BytesProcessed = 0;
- * while ((ErrorCode = Endpoint_Null_Stream(512, &BytesProcessed)) == ENDPOINT_RWSTREAM_IncompleteTransfer)
- * {
- * // Stream not yet complete - do other actions here, abort if required
- * }
- *
- * if (ErrorCode != ENDPOINT_RWSTREAM_NoError)
- * {
- * // Stream failed to complete - check ErrorCode here
- * }
- * \endcode
- *
- * \note This routine should not be used on CONTROL type endpoints.
- *
- * \param[in] Length Number of zero bytes to send via the currently selected endpoint.
- * \param[in] BytesProcessed Pointer to a location where the total number of bytes processed in the current
- * transaction should be updated, \c NULL if the entire stream should be read at once.
- *
- * \return A value from the \ref Endpoint_Stream_RW_ErrorCodes_t enum.
- */
- uint8_t Endpoint_Null_Stream(uint16_t Length,
- uint16_t* const BytesProcessed);
-
- //@}
-
- /** \name Stream functions for RAM source/destination data */
- //@{
-
- /** Writes the given number of bytes to the endpoint from the given buffer in little endian,
- * sending full packets to the host 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
- * \ref Endpoint_ClearIN() macro.
- *
- * If the BytesProcessed parameter is \c NULL, the entire stream transfer is attempted at once,
- * failing or succeeding as a single unit. If the BytesProcessed parameter points to a valid
- * storage location, the transfer will instead be performed as a series of chunks. Each time
- * the endpoint bank becomes full while there is still data to process (and after the current
- * packet transmission has been initiated) the BytesProcessed location will be updated with the
- * total number of bytes processed in the stream, and the function will exit with an error code of
- * \ref ENDPOINT_RWSTREAM_IncompleteTransfer. This allows for any abort checking to be performed
- * in the user code - to continue the transfer, call the function again with identical parameters
- * and it will resume until the BytesProcessed value reaches the total transfer length.
- *
- * <b>Single Stream Transfer Example:</b>
- * \code
- * uint8_t DataStream[512];
- * uint8_t ErrorCode;
- *
- * if ((ErrorCode = Endpoint_Write_Stream_LE(DataStream, sizeof(DataStream),
- * NULL)) != ENDPOINT_RWSTREAM_NoError)
- * {
- * // Stream failed to complete - check ErrorCode here
- * }
- * \endcode
- *
- * <b>Partial Stream Transfers Example:</b>
- * \code
- * uint8_t DataStream[512];
- * uint8_t ErrorCode;
- * uint16_t BytesProcessed;
- *
- * BytesProcessed = 0;
- * while ((ErrorCode = Endpoint_Write_Stream_LE(DataStream, sizeof(DataStream),
- * &BytesProcessed)) == ENDPOINT_RWSTREAM_IncompleteTransfer)
- * {
- * // Stream not yet complete - do other actions here, abort if required
- * }
- *
- * if (ErrorCode != ENDPOINT_RWSTREAM_NoError)
- * {
- * // Stream failed to complete - check ErrorCode here
- * }
- * \endcode
- *
- * \note This routine should not be used on CONTROL type endpoints.
- *
- * \param[in] Buffer Pointer to the source data buffer to read from.
- * \param[in] Length Number of bytes to read for the currently selected endpoint into the buffer.
- * \param[in] BytesProcessed Pointer to a location where the total number of bytes processed in the current
- * transaction should be updated, \c NULL if the entire stream should be written at once.
- *
- * \return A value from the \ref Endpoint_Stream_RW_ErrorCodes_t enum.
- */
- uint8_t Endpoint_Write_Stream_LE(const void* const Buffer,
- uint16_t Length,
- uint16_t* const BytesProcessed) ATTR_NON_NULL_PTR_ARG(1);
-
- /** Writes the given number of bytes to the endpoint from the given buffer in big endian,
- * sending full packets to the host 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
- * \ref Endpoint_ClearIN() macro.
- *
- * \note This routine should not be used on CONTROL type endpoints.
- *
- * \param[in] Buffer Pointer to the source data buffer to read from.
- * \param[in] Length Number of bytes to read for the currently selected endpoint into the buffer.
- * \param[in] BytesProcessed Pointer to a location where the total number of bytes processed in the current
- * transaction should be updated, \c NULL if the entire stream should be written at once.
- *
- * \return A value from the \ref Endpoint_Stream_RW_ErrorCodes_t enum.
- */
- uint8_t Endpoint_Write_Stream_BE(const void* const Buffer,
- uint16_t Length,
- uint16_t* const BytesProcessed) ATTR_NON_NULL_PTR_ARG(1);
-
- /** Reads the given number of bytes from the endpoint from the given buffer in little endian,
- * 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 \ref Endpoint_ClearOUT() macro.
- *
- * If the BytesProcessed parameter is \c NULL, the entire stream transfer is attempted at once,
- * failing or succeeding as a single unit. If the BytesProcessed parameter points to a valid
- * storage location, the transfer will instead be performed as a series of chunks. Each time
- * the endpoint bank becomes empty while there is still data to process (and after the current
- * packet has been acknowledged) the BytesProcessed location will be updated with the total number
- * of bytes processed in the stream, and the function will exit with an error code of
- * \ref ENDPOINT_RWSTREAM_IncompleteTransfer. This allows for any abort checking to be performed
- * in the user code - to continue the transfer, call the function again with identical parameters
- * and it will resume until the BytesProcessed value reaches the total transfer length.
- *
- * <b>Single Stream Transfer Example:</b>
- * \code
- * uint8_t DataStream[512];
- * uint8_t ErrorCode;
- *
- * if ((ErrorCode = Endpoint_Read_Stream_LE(DataStream, sizeof(DataStream),
- * NULL)) != ENDPOINT_RWSTREAM_NoError)
- * {
- * // Stream failed to complete - check ErrorCode here
- * }
- * \endcode
- *
- * <b>Partial Stream Transfers Example:</b>
- * \code
- * uint8_t DataStream[512];
- * uint8_t ErrorCode;
- * uint16_t BytesProcessed;
- *
- * BytesProcessed = 0;
- * while ((ErrorCode = Endpoint_Read_Stream_LE(DataStream, sizeof(DataStream),
- * &BytesProcessed)) == ENDPOINT_RWSTREAM_IncompleteTransfer)
- * {
- * // Stream not yet complete - do other actions here, abort if required
- * }
- *
- * if (ErrorCode != ENDPOINT_RWSTREAM_NoError)
- * {
- * // Stream failed to complete - check ErrorCode here
- * }
- * \endcode
- *
- * \note This routine should not be used on CONTROL type endpoints.
- *
- * \param[out] Buffer Pointer to the destination data buffer to write to.
- * \param[in] Length Number of bytes to send via the currently selected endpoint.
- * \param[in] BytesProcessed Pointer to a location where the total number of bytes processed in the current
- * transaction should be updated, \c NULL if the entire stream should be read at once.
- *
- * \return A value from the \ref Endpoint_Stream_RW_ErrorCodes_t enum.
- */
- uint8_t Endpoint_Read_Stream_LE(void* const Buffer,
- uint16_t Length,
- uint16_t* const BytesProcessed) ATTR_NON_NULL_PTR_ARG(1);
-
- /** Reads the given number of bytes from the endpoint from the given buffer in big endian,
- * 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 \ref Endpoint_ClearOUT() macro.
- *
- * \note This routine should not be used on CONTROL type endpoints.
- *
- * \param[out] Buffer Pointer to the destination data buffer to write to.
- * \param[in] Length Number of bytes to send via the currently selected endpoint.
- * \param[in] BytesProcessed Pointer to a location where the total number of bytes processed in the current
- * transaction should be updated, \c NULL if the entire stream should be read at once.
- *
- * \return A value from the \ref Endpoint_Stream_RW_ErrorCodes_t enum.
- */
- uint8_t Endpoint_Read_Stream_BE(void* const Buffer,
- uint16_t Length,
- uint16_t* const BytesProcessed) ATTR_NON_NULL_PTR_ARG(1);
-
- /** Writes the given number of bytes to the CONTROL type endpoint from the given buffer in little endian,
- * sending full packets to the host as needed. The host OUT acknowledgement is not automatically cleared
- * in both failure and success states; the user is responsible for manually clearing the setup OUT to
- * finalize the transfer via the \ref Endpoint_ClearOUT() macro.
- *
- * \note This function automatically clears the control transfer's status stage. Do not manually attempt
- * to clear the status stage when using this routine in a control transaction.
- * \n\n
- *
- * \note This routine should only be used on CONTROL type endpoints.
- *
- * \warning Unlike the standard stream read/write commands, the control stream commands cannot be chained
- * together; i.e. the entire stream data must be read or written at the one time.
- *
- * \param[in] Buffer Pointer to the source data buffer to read from.
- * \param[in] Length Number of bytes to read for the currently selected endpoint into the buffer.
- *
- * \return A value from the \ref Endpoint_ControlStream_RW_ErrorCodes_t enum.
- */
- uint8_t Endpoint_Write_Control_Stream_LE(const void* const Buffer,
- uint16_t Length) ATTR_NON_NULL_PTR_ARG(1);
-
- /** Writes the given number of bytes to the CONTROL type endpoint from the given buffer in big endian,
- * sending full packets to the host as needed. The host OUT acknowledgement is not automatically cleared
- * in both failure and success states; the user is responsible for manually clearing the setup OUT to
- * finalize the transfer via the \ref Endpoint_ClearOUT() macro.
- *
- * \note This function automatically clears the control transfer's status stage. Do not manually attempt
- * to clear the status stage when using this routine in a control transaction.
- * \n\n
- *
- * \note This routine should only be used on CONTROL type endpoints.
- *
- * \warning Unlike the standard stream read/write commands, the control stream commands cannot be chained
- * together; i.e. the entire stream data must be read or written at the one time.
- *
- * \param[in] Buffer Pointer to the source data buffer to read from.
- * \param[in] Length Number of bytes to read for the currently selected endpoint into the buffer.
- *
- * \return A value from the \ref Endpoint_ControlStream_RW_ErrorCodes_t enum.
- */
- uint8_t Endpoint_Write_Control_Stream_BE(const void* const Buffer,
- uint16_t Length) ATTR_NON_NULL_PTR_ARG(1);
-
- /** Reads the given number of bytes from the CONTROL endpoint from the given buffer in little endian,
- * discarding fully read packets from the host as needed. The device IN acknowledgement is not
- * automatically sent after success or failure states; the user is responsible for manually sending the
- * setup IN to finalize the transfer via the \ref Endpoint_ClearIN() macro.
- *
- * \note This function automatically clears the control transfer's status stage. Do not manually attempt
- * to clear the status stage when using this routine in a control transaction.
- * \n\n
- *
- * \note This routine should only be used on CONTROL type endpoints.
- *
- * \warning Unlike the standard stream read/write commands, the control stream commands cannot be chained
- * together; i.e. the entire stream data must be read or written at the one time.
- *
- * \param[out] Buffer Pointer to the destination data buffer to write to.
- * \param[in] Length Number of bytes to send via the currently selected endpoint.
- *
- * \return A value from the \ref Endpoint_ControlStream_RW_ErrorCodes_t enum.
- */
- uint8_t Endpoint_Read_Control_Stream_LE(void* const Buffer,
- uint16_t Length) ATTR_NON_NULL_PTR_ARG(1);
-
- /** Reads the given number of bytes from the CONTROL endpoint from the given buffer in big endian,
- * discarding fully read packets from the host as needed. The device IN acknowledgement is not
- * automatically sent after success or failure states; the user is responsible for manually sending the
- * setup IN to finalize the transfer via the \ref Endpoint_ClearIN() macro.
- *
- * \note This function automatically clears the control transfer's status stage. Do not manually attempt
- * to clear the status stage when using this routine in a control transaction.
- * \n\n
- *
- * \note This routine should only be used on CONTROL type endpoints.
- *
- * \warning Unlike the standard stream read/write commands, the control stream commands cannot be chained
- * together; i.e. the entire stream data must be read or written at the one time.
- *
- * \param[out] Buffer Pointer to the destination data buffer to write to.
- * \param[in] Length Number of bytes to send via the currently selected endpoint.
- *
- * \return A value from the \ref Endpoint_ControlStream_RW_ErrorCodes_t enum.
- */
- uint8_t Endpoint_Read_Control_Stream_BE(void* const Buffer,
- uint16_t Length) ATTR_NON_NULL_PTR_ARG(1);
- //@}
-
- /* Disable C linkage for C++ Compilers: */
- #if defined(__cplusplus)
- }
- #endif
-
-#endif
-
-/** @} */
+/* + LUFA Library + Copyright (C) Dean Camera, 2012. + + dean [at] fourwalledcubicle [dot] com + www.lufa-lib.org +*/ + +/* + Copyright 2012 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 + software, including all implied warranties of merchantability + and fitness. In no event shall the author be liable for any + special, indirect or consequential damages or any damages + whatsoever resulting from loss of use, data or profits, whether + in an action of contract, negligence or other tortious action, + arising out of or in connection with the use or performance of + this software. +*/ + +/** \file + * \brief Endpoint data stream transmission and reception management for the AVR32 UC3 microcontrollers. + * \copydetails Group_EndpointStreamRW_UC3 + * + * \note This file should not be included directly. It is automatically included as needed by the USB driver + * dispatch header located in LUFA/Drivers/USB/USB.h. + */ + +/** \ingroup Group_EndpointStreamRW + * \defgroup Group_EndpointStreamRW_UC3 Read/Write of Multi-Byte Streams (UC3) + * \brief Endpoint data stream transmission and reception management for the Atmel AVR32 UC3 architecture. + * + * Functions, macros, variables, enums and types related to data reading and writing of data streams from + * and to endpoints. + * + * @{ + */ + +#ifndef __ENDPOINT_STREAM_UC3_H__ +#define __ENDPOINT_STREAM_UC3_H__ + + /* Includes: */ + #include "../../../../Common/Common.h" + #include "../USBMode.h" + #include "../USBTask.h" + + /* Enable C linkage for C++ Compilers: */ + #if defined(__cplusplus) + extern "C" { + #endif + + /* Preprocessor Checks: */ + #if !defined(__INCLUDE_FROM_USB_DRIVER) + #error Do not include this file directly. Include LUFA/Drivers/USB/USB.h instead. + #endif + + /* Public Interface - May be used in end-application: */ + /* Function Prototypes: */ + /** \name Stream functions for null data */ + //@{ + + /** Reads and discards the given number of bytes from the currently selected endpoint's bank, + * 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 \ref Endpoint_ClearOUT() macro. + * + * If the BytesProcessed parameter is \c NULL, the entire stream transfer is attempted at once, + * failing or succeeding as a single unit. If the BytesProcessed parameter points to a valid + * storage location, the transfer will instead be performed as a series of chunks. Each time + * the endpoint bank becomes empty while there is still data to process (and after the current + * packet has been acknowledged) the BytesProcessed location will be updated with the total number + * of bytes processed in the stream, and the function will exit with an error code of + * \ref ENDPOINT_RWSTREAM_IncompleteTransfer. This allows for any abort checking to be performed + * in the user code - to continue the transfer, call the function again with identical parameters + * and it will resume until the BytesProcessed value reaches the total transfer length. + * + * <b>Single Stream Transfer Example:</b> + * \code + * uint8_t ErrorCode; + * + * if ((ErrorCode = Endpoint_Discard_Stream(512, NULL)) != ENDPOINT_RWSTREAM_NoError) + * { + * // Stream failed to complete - check ErrorCode here + * } + * \endcode + * + * <b>Partial Stream Transfers Example:</b> + * \code + * uint8_t ErrorCode; + * uint16_t BytesProcessed; + * + * BytesProcessed = 0; + * while ((ErrorCode = Endpoint_Discard_Stream(512, &BytesProcessed)) == ENDPOINT_RWSTREAM_IncompleteTransfer) + * { + * // Stream not yet complete - do other actions here, abort if required + * } + * + * if (ErrorCode != ENDPOINT_RWSTREAM_NoError) + * { + * // Stream failed to complete - check ErrorCode here + * } + * \endcode + * + * \note This routine should not be used on CONTROL type endpoints. + * + * \param[in] Length Number of bytes to discard via the currently selected endpoint. + * \param[in] BytesProcessed Pointer to a location where the total number of bytes processed in the current + * transaction should be updated, \c NULL if the entire stream should be read at once. + * + * \return A value from the \ref Endpoint_Stream_RW_ErrorCodes_t enum. + */ + uint8_t Endpoint_Discard_Stream(uint16_t Length, + uint16_t* const BytesProcessed); + + /** Writes a given number of zeroed bytes to the currently selected endpoint's bank, sending + * full packets to the host as needed. The last packet is not automatically sent once the + * remaining bytes have been written; the user is responsible for manually sending the last + * packet to the host via the \ref Endpoint_ClearIN() macro. + * + * If the BytesProcessed parameter is \c NULL, the entire stream transfer is attempted at once, + * failing or succeeding as a single unit. If the BytesProcessed parameter points to a valid + * storage location, the transfer will instead be performed as a series of chunks. Each time + * the endpoint bank becomes full while there is still data to process (and after the current + * packet transmission has been initiated) the BytesProcessed location will be updated with the + * total number of bytes processed in the stream, and the function will exit with an error code of + * \ref ENDPOINT_RWSTREAM_IncompleteTransfer. This allows for any abort checking to be performed + * in the user code - to continue the transfer, call the function again with identical parameters + * and it will resume until the BytesProcessed value reaches the total transfer length. + * + * <b>Single Stream Transfer Example:</b> + * \code + * uint8_t ErrorCode; + * + * if ((ErrorCode = Endpoint_Null_Stream(512, NULL)) != ENDPOINT_RWSTREAM_NoError) + * { + * // Stream failed to complete - check ErrorCode here + * } + * \endcode + * + * <b>Partial Stream Transfers Example:</b> + * \code + * uint8_t ErrorCode; + * uint16_t BytesProcessed; + * + * BytesProcessed = 0; + * while ((ErrorCode = Endpoint_Null_Stream(512, &BytesProcessed)) == ENDPOINT_RWSTREAM_IncompleteTransfer) + * { + * // Stream not yet complete - do other actions here, abort if required + * } + * + * if (ErrorCode != ENDPOINT_RWSTREAM_NoError) + * { + * // Stream failed to complete - check ErrorCode here + * } + * \endcode + * + * \note This routine should not be used on CONTROL type endpoints. + * + * \param[in] Length Number of zero bytes to send via the currently selected endpoint. + * \param[in] BytesProcessed Pointer to a location where the total number of bytes processed in the current + * transaction should be updated, \c NULL if the entire stream should be read at once. + * + * \return A value from the \ref Endpoint_Stream_RW_ErrorCodes_t enum. + */ + uint8_t Endpoint_Null_Stream(uint16_t Length, + uint16_t* const BytesProcessed); + + //@} + + /** \name Stream functions for RAM source/destination data */ + //@{ + + /** Writes the given number of bytes to the endpoint from the given buffer in little endian, + * sending full packets to the host 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 + * \ref Endpoint_ClearIN() macro. + * + * If the BytesProcessed parameter is \c NULL, the entire stream transfer is attempted at once, + * failing or succeeding as a single unit. If the BytesProcessed parameter points to a valid + * storage location, the transfer will instead be performed as a series of chunks. Each time + * the endpoint bank becomes full while there is still data to process (and after the current + * packet transmission has been initiated) the BytesProcessed location will be updated with the + * total number of bytes processed in the stream, and the function will exit with an error code of + * \ref ENDPOINT_RWSTREAM_IncompleteTransfer. This allows for any abort checking to be performed + * in the user code - to continue the transfer, call the function again with identical parameters + * and it will resume until the BytesProcessed value reaches the total transfer length. + * + * <b>Single Stream Transfer Example:</b> + * \code + * uint8_t DataStream[512]; + * uint8_t ErrorCode; + * + * if ((ErrorCode = Endpoint_Write_Stream_LE(DataStream, sizeof(DataStream), + * NULL)) != ENDPOINT_RWSTREAM_NoError) + * { + * // Stream failed to complete - check ErrorCode here + * } + * \endcode + * + * <b>Partial Stream Transfers Example:</b> + * \code + * uint8_t DataStream[512]; + * uint8_t ErrorCode; + * uint16_t BytesProcessed; + * + * BytesProcessed = 0; + * while ((ErrorCode = Endpoint_Write_Stream_LE(DataStream, sizeof(DataStream), + * &BytesProcessed)) == ENDPOINT_RWSTREAM_IncompleteTransfer) + * { + * // Stream not yet complete - do other actions here, abort if required + * } + * + * if (ErrorCode != ENDPOINT_RWSTREAM_NoError) + * { + * // Stream failed to complete - check ErrorCode here + * } + * \endcode + * + * \note This routine should not be used on CONTROL type endpoints. + * + * \param[in] Buffer Pointer to the source data buffer to read from. + * \param[in] Length Number of bytes to read for the currently selected endpoint into the buffer. + * \param[in] BytesProcessed Pointer to a location where the total number of bytes processed in the current + * transaction should be updated, \c NULL if the entire stream should be written at once. + * + * \return A value from the \ref Endpoint_Stream_RW_ErrorCodes_t enum. + */ + uint8_t Endpoint_Write_Stream_LE(const void* const Buffer, + uint16_t Length, + uint16_t* const BytesProcessed) ATTR_NON_NULL_PTR_ARG(1); + + /** Writes the given number of bytes to the endpoint from the given buffer in big endian, + * sending full packets to the host 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 + * \ref Endpoint_ClearIN() macro. + * + * \note This routine should not be used on CONTROL type endpoints. + * + * \param[in] Buffer Pointer to the source data buffer to read from. + * \param[in] Length Number of bytes to read for the currently selected endpoint into the buffer. + * \param[in] BytesProcessed Pointer to a location where the total number of bytes processed in the current + * transaction should be updated, \c NULL if the entire stream should be written at once. + * + * \return A value from the \ref Endpoint_Stream_RW_ErrorCodes_t enum. + */ + uint8_t Endpoint_Write_Stream_BE(const void* const Buffer, + uint16_t Length, + uint16_t* const BytesProcessed) ATTR_NON_NULL_PTR_ARG(1); + + /** Reads the given number of bytes from the endpoint from the given buffer in little endian, + * 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 \ref Endpoint_ClearOUT() macro. + * + * If the BytesProcessed parameter is \c NULL, the entire stream transfer is attempted at once, + * failing or succeeding as a single unit. If the BytesProcessed parameter points to a valid + * storage location, the transfer will instead be performed as a series of chunks. Each time + * the endpoint bank becomes empty while there is still data to process (and after the current + * packet has been acknowledged) the BytesProcessed location will be updated with the total number + * of bytes processed in the stream, and the function will exit with an error code of + * \ref ENDPOINT_RWSTREAM_IncompleteTransfer. This allows for any abort checking to be performed + * in the user code - to continue the transfer, call the function again with identical parameters + * and it will resume until the BytesProcessed value reaches the total transfer length. + * + * <b>Single Stream Transfer Example:</b> + * \code + * uint8_t DataStream[512]; + * uint8_t ErrorCode; + * + * if ((ErrorCode = Endpoint_Read_Stream_LE(DataStream, sizeof(DataStream), + * NULL)) != ENDPOINT_RWSTREAM_NoError) + * { + * // Stream failed to complete - check ErrorCode here + * } + * \endcode + * + * <b>Partial Stream Transfers Example:</b> + * \code + * uint8_t DataStream[512]; + * uint8_t ErrorCode; + * uint16_t BytesProcessed; + * + * BytesProcessed = 0; + * while ((ErrorCode = Endpoint_Read_Stream_LE(DataStream, sizeof(DataStream), + * &BytesProcessed)) == ENDPOINT_RWSTREAM_IncompleteTransfer) + * { + * // Stream not yet complete - do other actions here, abort if required + * } + * + * if (ErrorCode != ENDPOINT_RWSTREAM_NoError) + * { + * // Stream failed to complete - check ErrorCode here + * } + * \endcode + * + * \note This routine should not be used on CONTROL type endpoints. + * + * \param[out] Buffer Pointer to the destination data buffer to write to. + * \param[in] Length Number of bytes to send via the currently selected endpoint. + * \param[in] BytesProcessed Pointer to a location where the total number of bytes processed in the current + * transaction should be updated, \c NULL if the entire stream should be read at once. + * + * \return A value from the \ref Endpoint_Stream_RW_ErrorCodes_t enum. + */ + uint8_t Endpoint_Read_Stream_LE(void* const Buffer, + uint16_t Length, + uint16_t* const BytesProcessed) ATTR_NON_NULL_PTR_ARG(1); + + /** Reads the given number of bytes from the endpoint from the given buffer in big endian, + * 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 \ref Endpoint_ClearOUT() macro. + * + * \note This routine should not be used on CONTROL type endpoints. + * + * \param[out] Buffer Pointer to the destination data buffer to write to. + * \param[in] Length Number of bytes to send via the currently selected endpoint. + * \param[in] BytesProcessed Pointer to a location where the total number of bytes processed in the current + * transaction should be updated, \c NULL if the entire stream should be read at once. + * + * \return A value from the \ref Endpoint_Stream_RW_ErrorCodes_t enum. + */ + uint8_t Endpoint_Read_Stream_BE(void* const Buffer, + uint16_t Length, + uint16_t* const BytesProcessed) ATTR_NON_NULL_PTR_ARG(1); + + /** Writes the given number of bytes to the CONTROL type endpoint from the given buffer in little endian, + * sending full packets to the host as needed. The host OUT acknowledgement is not automatically cleared + * in both failure and success states; the user is responsible for manually clearing the setup OUT to + * finalize the transfer via the \ref Endpoint_ClearOUT() macro. + * + * \note This function automatically clears the control transfer's status stage. Do not manually attempt + * to clear the status stage when using this routine in a control transaction. + * \n\n + * + * \note This routine should only be used on CONTROL type endpoints. + * + * \warning Unlike the standard stream read/write commands, the control stream commands cannot be chained + * together; i.e. the entire stream data must be read or written at the one time. + * + * \param[in] Buffer Pointer to the source data buffer to read from. + * \param[in] Length Number of bytes to read for the currently selected endpoint into the buffer. + * + * \return A value from the \ref Endpoint_ControlStream_RW_ErrorCodes_t enum. + */ + uint8_t Endpoint_Write_Control_Stream_LE(const void* const Buffer, + uint16_t Length) ATTR_NON_NULL_PTR_ARG(1); + + /** Writes the given number of bytes to the CONTROL type endpoint from the given buffer in big endian, + * sending full packets to the host as needed. The host OUT acknowledgement is not automatically cleared + * in both failure and success states; the user is responsible for manually clearing the setup OUT to + * finalize the transfer via the \ref Endpoint_ClearOUT() macro. + * + * \note This function automatically clears the control transfer's status stage. Do not manually attempt + * to clear the status stage when using this routine in a control transaction. + * \n\n + * + * \note This routine should only be used on CONTROL type endpoints. + * + * \warning Unlike the standard stream read/write commands, the control stream commands cannot be chained + * together; i.e. the entire stream data must be read or written at the one time. + * + * \param[in] Buffer Pointer to the source data buffer to read from. + * \param[in] Length Number of bytes to read for the currently selected endpoint into the buffer. + * + * \return A value from the \ref Endpoint_ControlStream_RW_ErrorCodes_t enum. + */ + uint8_t Endpoint_Write_Control_Stream_BE(const void* const Buffer, + uint16_t Length) ATTR_NON_NULL_PTR_ARG(1); + + /** Reads the given number of bytes from the CONTROL endpoint from the given buffer in little endian, + * discarding fully read packets from the host as needed. The device IN acknowledgement is not + * automatically sent after success or failure states; the user is responsible for manually sending the + * setup IN to finalize the transfer via the \ref Endpoint_ClearIN() macro. + * + * \note This function automatically clears the control transfer's status stage. Do not manually attempt + * to clear the status stage when using this routine in a control transaction. + * \n\n + * + * \note This routine should only be used on CONTROL type endpoints. + * + * \warning Unlike the standard stream read/write commands, the control stream commands cannot be chained + * together; i.e. the entire stream data must be read or written at the one time. + * + * \param[out] Buffer Pointer to the destination data buffer to write to. + * \param[in] Length Number of bytes to send via the currently selected endpoint. + * + * \return A value from the \ref Endpoint_ControlStream_RW_ErrorCodes_t enum. + */ + uint8_t Endpoint_Read_Control_Stream_LE(void* const Buffer, + uint16_t Length) ATTR_NON_NULL_PTR_ARG(1); + + /** Reads the given number of bytes from the CONTROL endpoint from the given buffer in big endian, + * discarding fully read packets from the host as needed. The device IN acknowledgement is not + * automatically sent after success or failure states; the user is responsible for manually sending the + * setup IN to finalize the transfer via the \ref Endpoint_ClearIN() macro. + * + * \note This function automatically clears the control transfer's status stage. Do not manually attempt + * to clear the status stage when using this routine in a control transaction. + * \n\n + * + * \note This routine should only be used on CONTROL type endpoints. + * + * \warning Unlike the standard stream read/write commands, the control stream commands cannot be chained + * together; i.e. the entire stream data must be read or written at the one time. + * + * \param[out] Buffer Pointer to the destination data buffer to write to. + * \param[in] Length Number of bytes to send via the currently selected endpoint. + * + * \return A value from the \ref Endpoint_ControlStream_RW_ErrorCodes_t enum. + */ + uint8_t Endpoint_Read_Control_Stream_BE(void* const Buffer, + uint16_t Length) ATTR_NON_NULL_PTR_ARG(1); + //@} + + /* Disable C linkage for C++ Compilers: */ + #if defined(__cplusplus) + } + #endif + +#endif + +/** @} */ diff --git a/LUFA/Drivers/USB/Core/UC3/PipeStream_UC3.c b/LUFA/Drivers/USB/Core/UC3/PipeStream_UC3.c index bb4cbc659..76fbfd8f5 100644 --- a/LUFA/Drivers/USB/Core/UC3/PipeStream_UC3.c +++ b/LUFA/Drivers/USB/Core/UC3/PipeStream_UC3.c @@ -1,166 +1,166 @@ -/*
- LUFA Library
- Copyright (C) Dean Camera, 2012.
-
- dean [at] fourwalledcubicle [dot] com
- www.lufa-lib.org
-*/
-
-/*
- Copyright 2012 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
- software, including all implied warranties of merchantability
- and fitness. In no event shall the author be liable for any
- special, indirect or consequential damages or any damages
- whatsoever resulting from loss of use, data or profits, whether
- in an action of contract, negligence or other tortious action,
- arising out of or in connection with the use or performance of
- this software.
-*/
-
-#include "../../../../Common/Common.h"
-#if (ARCH == ARCH_UC3)
-
-#define __INCLUDE_FROM_USB_DRIVER
-#include "../USBMode.h"
-
-#if defined(USB_CAN_BE_HOST)
-
-#include "PipeStream_UC3.h"
-
-uint8_t Pipe_Discard_Stream(uint16_t Length,
- uint16_t* const BytesProcessed)
-{
- uint8_t ErrorCode;
- uint16_t BytesInTransfer = 0;
-
- Pipe_SetPipeToken(PIPE_TOKEN_IN);
-
- if ((ErrorCode = Pipe_WaitUntilReady()))
- return ErrorCode;
-
- if (BytesProcessed != NULL)
- Length -= *BytesProcessed;
-
- while (Length)
- {
- if (!(Pipe_IsReadWriteAllowed()))
- {
- Pipe_ClearIN();
-
- if (BytesProcessed != NULL)
- {
- *BytesProcessed += BytesInTransfer;
- return PIPE_RWSTREAM_IncompleteTransfer;
- }
-
- if ((ErrorCode = Pipe_WaitUntilReady()))
- return ErrorCode;
- }
- else
- {
- Pipe_Discard_8();
-
- Length--;
- BytesInTransfer++;
- }
- }
-
- return PIPE_RWSTREAM_NoError;
-}
-
-uint8_t Pipe_Null_Stream(uint16_t Length,
- uint16_t* const BytesProcessed)
-{
- uint8_t ErrorCode;
- uint16_t BytesInTransfer = 0;
-
- Pipe_SetPipeToken(PIPE_TOKEN_OUT);
-
- if ((ErrorCode = Pipe_WaitUntilReady()))
- return ErrorCode;
-
- if (BytesProcessed != NULL)
- Length -= *BytesProcessed;
-
- while (Length)
- {
- if (!(Pipe_IsReadWriteAllowed()))
- {
- Pipe_ClearOUT();
-
- if (BytesProcessed != NULL)
- {
- *BytesProcessed += BytesInTransfer;
- return PIPE_RWSTREAM_IncompleteTransfer;
- }
-
- USB_USBTask();
-
- if ((ErrorCode = Pipe_WaitUntilReady()))
- return ErrorCode;
- }
- else
- {
- Pipe_Write_8(0);
-
- Length--;
- BytesInTransfer++;
- }
- }
-
- return PIPE_RWSTREAM_NoError;
-}
-
-/* The following abuses the C preprocessor in order to copy-paste common code with slight alterations,
- * so that the code needs to be written once. It is a crude form of templating to reduce code maintenance. */
-
-#define TEMPLATE_FUNC_NAME Pipe_Write_Stream_LE
-#define TEMPLATE_BUFFER_TYPE const void*
-#define TEMPLATE_TOKEN PIPE_TOKEN_OUT
-#define TEMPLATE_CLEAR_PIPE() Pipe_ClearOUT()
-#define TEMPLATE_BUFFER_OFFSET(Length) 0
-#define TEMPLATE_BUFFER_MOVE(BufferPtr, Amount) DataStream += Amount
-#define TEMPLATE_TRANSFER_BYTE(BufferPtr) Pipe_Write_8(*BufferPtr)
-#include "Template/Template_Pipe_RW.c"
-
-#define TEMPLATE_FUNC_NAME Pipe_Write_Stream_BE
-#define TEMPLATE_BUFFER_TYPE const void*
-#define TEMPLATE_TOKEN PIPE_TOKEN_OUT
-#define TEMPLATE_CLEAR_PIPE() Pipe_ClearOUT()
-#define TEMPLATE_BUFFER_OFFSET(Length) (Length - 1)
-#define TEMPLATE_BUFFER_MOVE(BufferPtr, Amount) DataStream -= Amount
-#define TEMPLATE_TRANSFER_BYTE(BufferPtr) Pipe_Write_8(*BufferPtr)
-#include "Template/Template_Pipe_RW.c"
-
-#define TEMPLATE_FUNC_NAME Pipe_Read_Stream_LE
-#define TEMPLATE_BUFFER_TYPE void*
-#define TEMPLATE_TOKEN PIPE_TOKEN_IN
-#define TEMPLATE_CLEAR_PIPE() Pipe_ClearIN()
-#define TEMPLATE_BUFFER_OFFSET(Length) 0
-#define TEMPLATE_BUFFER_MOVE(BufferPtr, Amount) DataStream += Amount
-#define TEMPLATE_TRANSFER_BYTE(BufferPtr) *BufferPtr = Pipe_Read_8()
-#include "Template/Template_Pipe_RW.c"
-
-#define TEMPLATE_FUNC_NAME Pipe_Read_Stream_BE
-#define TEMPLATE_BUFFER_TYPE void*
-#define TEMPLATE_TOKEN PIPE_TOKEN_IN
-#define TEMPLATE_CLEAR_PIPE() Pipe_ClearIN()
-#define TEMPLATE_BUFFER_OFFSET(Length) (Length - 1)
-#define TEMPLATE_BUFFER_MOVE(BufferPtr, Amount) DataStream -= Amount
-#define TEMPLATE_TRANSFER_BYTE(BufferPtr) *BufferPtr = Pipe_Read_8()
-#include "Template/Template_Pipe_RW.c"
-
-#endif
- -#endif
+/* + LUFA Library + Copyright (C) Dean Camera, 2012. + + dean [at] fourwalledcubicle [dot] com + www.lufa-lib.org +*/ + +/* + Copyright 2012 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 + software, including all implied warranties of merchantability + and fitness. In no event shall the author be liable for any + special, indirect or consequential damages or any damages + whatsoever resulting from loss of use, data or profits, whether + in an action of contract, negligence or other tortious action, + arising out of or in connection with the use or performance of + this software. +*/ + +#include "../../../../Common/Common.h" +#if (ARCH == ARCH_UC3) + +#define __INCLUDE_FROM_USB_DRIVER +#include "../USBMode.h" + +#if defined(USB_CAN_BE_HOST) + +#include "PipeStream_UC3.h" + +uint8_t Pipe_Discard_Stream(uint16_t Length, + uint16_t* const BytesProcessed) +{ + uint8_t ErrorCode; + uint16_t BytesInTransfer = 0; + + Pipe_SetPipeToken(PIPE_TOKEN_IN); + + if ((ErrorCode = Pipe_WaitUntilReady())) + return ErrorCode; + + if (BytesProcessed != NULL) + Length -= *BytesProcessed; + + while (Length) + { + if (!(Pipe_IsReadWriteAllowed())) + { + Pipe_ClearIN(); + + if (BytesProcessed != NULL) + { + *BytesProcessed += BytesInTransfer; + return PIPE_RWSTREAM_IncompleteTransfer; + } + + if ((ErrorCode = Pipe_WaitUntilReady())) + return ErrorCode; + } + else + { + Pipe_Discard_8(); + + Length--; + BytesInTransfer++; + } + } + + return PIPE_RWSTREAM_NoError; +} + +uint8_t Pipe_Null_Stream(uint16_t Length, + uint16_t* const BytesProcessed) +{ + uint8_t ErrorCode; + uint16_t BytesInTransfer = 0; + + Pipe_SetPipeToken(PIPE_TOKEN_OUT); + + if ((ErrorCode = Pipe_WaitUntilReady())) + return ErrorCode; + + if (BytesProcessed != NULL) + Length -= *BytesProcessed; + + while (Length) + { + if (!(Pipe_IsReadWriteAllowed())) + { + Pipe_ClearOUT(); + + if (BytesProcessed != NULL) + { + *BytesProcessed += BytesInTransfer; + return PIPE_RWSTREAM_IncompleteTransfer; + } + + USB_USBTask(); + + if ((ErrorCode = Pipe_WaitUntilReady())) + return ErrorCode; + } + else + { + Pipe_Write_8(0); + + Length--; + BytesInTransfer++; + } + } + + return PIPE_RWSTREAM_NoError; +} + +/* The following abuses the C preprocessor in order to copy-paste common code with slight alterations, + * so that the code needs to be written once. It is a crude form of templating to reduce code maintenance. */ + +#define TEMPLATE_FUNC_NAME Pipe_Write_Stream_LE +#define TEMPLATE_BUFFER_TYPE const void* +#define TEMPLATE_TOKEN PIPE_TOKEN_OUT +#define TEMPLATE_CLEAR_PIPE() Pipe_ClearOUT() +#define TEMPLATE_BUFFER_OFFSET(Length) 0 +#define TEMPLATE_BUFFER_MOVE(BufferPtr, Amount) DataStream += Amount +#define TEMPLATE_TRANSFER_BYTE(BufferPtr) Pipe_Write_8(*BufferPtr) +#include "Template/Template_Pipe_RW.c" + +#define TEMPLATE_FUNC_NAME Pipe_Write_Stream_BE +#define TEMPLATE_BUFFER_TYPE const void* +#define TEMPLATE_TOKEN PIPE_TOKEN_OUT +#define TEMPLATE_CLEAR_PIPE() Pipe_ClearOUT() +#define TEMPLATE_BUFFER_OFFSET(Length) (Length - 1) +#define TEMPLATE_BUFFER_MOVE(BufferPtr, Amount) DataStream -= Amount +#define TEMPLATE_TRANSFER_BYTE(BufferPtr) Pipe_Write_8(*BufferPtr) +#include "Template/Template_Pipe_RW.c" + +#define TEMPLATE_FUNC_NAME Pipe_Read_Stream_LE +#define TEMPLATE_BUFFER_TYPE void* +#define TEMPLATE_TOKEN PIPE_TOKEN_IN +#define TEMPLATE_CLEAR_PIPE() Pipe_ClearIN() +#define TEMPLATE_BUFFER_OFFSET(Length) 0 +#define TEMPLATE_BUFFER_MOVE(BufferPtr, Amount) DataStream += Amount +#define TEMPLATE_TRANSFER_BYTE(BufferPtr) *BufferPtr = Pipe_Read_8() +#include "Template/Template_Pipe_RW.c" + +#define TEMPLATE_FUNC_NAME Pipe_Read_Stream_BE +#define TEMPLATE_BUFFER_TYPE void* +#define TEMPLATE_TOKEN PIPE_TOKEN_IN +#define TEMPLATE_CLEAR_PIPE() Pipe_ClearIN() +#define TEMPLATE_BUFFER_OFFSET(Length) (Length - 1) +#define TEMPLATE_BUFFER_MOVE(BufferPtr, Amount) DataStream -= Amount +#define TEMPLATE_TRANSFER_BYTE(BufferPtr) *BufferPtr = Pipe_Read_8() +#include "Template/Template_Pipe_RW.c" + +#endif + +#endif diff --git a/LUFA/Drivers/USB/Core/UC3/PipeStream_UC3.h b/LUFA/Drivers/USB/Core/UC3/PipeStream_UC3.h index cb8a28c86..72bf83c6c 100644 --- a/LUFA/Drivers/USB/Core/UC3/PipeStream_UC3.h +++ b/LUFA/Drivers/USB/Core/UC3/PipeStream_UC3.h @@ -1,352 +1,352 @@ -/*
- LUFA Library
- Copyright (C) Dean Camera, 2012.
-
- dean [at] fourwalledcubicle [dot] com
- www.lufa-lib.org
-*/
-
-/*
- Copyright 2012 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
- software, including all implied warranties of merchantability
- and fitness. In no event shall the author be liable for any
- special, indirect or consequential damages or any damages
- whatsoever resulting from loss of use, data or profits, whether
- in an action of contract, negligence or other tortious action,
- arising out of or in connection with the use or performance of
- this software.
-*/
-
-/** \file
- * \brief Pipe data stream transmission and reception management for the AVR32 UC3 microcontrollers.
- * \copydetails Group_PipeStreamRW_UC3
- *
- * \note This file should not be included directly. It is automatically included as needed by the USB driver
- * dispatch header located in LUFA/Drivers/USB/USB.h.
- */
-
-/** \ingroup Group_PipeStreamRW
- * \defgroup Group_PipeStreamRW_UC3 Read/Write of Multi-Byte Streams (UC3)
- * \brief Pipe data stream transmission and reception management for the Atmel AVR32 UC3 architecture.
- *
- * Functions, macros, variables, enums and types related to data reading and writing of data streams from
- * and to pipes.
- *
- * @{
- */
-
-#ifndef __PIPE_STREAM_UC3_H__
-#define __PIPE_STREAM_UC3_H__
-
- /* Includes: */
- #include "../../../../Common/Common.h"
- #include "../USBMode.h"
- #include "../USBTask.h"
-
- /* Enable C linkage for C++ Compilers: */
- #if defined(__cplusplus)
- extern "C" {
- #endif
-
- /* Preprocessor Checks: */
- #if !defined(__INCLUDE_FROM_USB_DRIVER)
- #error Do not include this file directly. Include LUFA/Drivers/USB/USB.h instead.
- #endif
-
- /* Public Interface - May be used in end-application: */
- /* Function Prototypes: */
- /** \name Stream functions for null data */
- //@{
-
- /** 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.
- *
- * If the BytesProcessed parameter is \c NULL, the entire stream transfer is attempted at once, failing or
- * succeeding as a single unit. If the BytesProcessed parameter points to a valid storage location, the transfer
- * will instead be performed as a series of chunks. Each time the pipe bank becomes empty while there is still data
- * to process (and after the current packet has been acknowledged) the BytesProcessed location will be updated with
- * the total number of bytes processed in the stream, and the function will exit with an error code of
- * \ref PIPE_RWSTREAM_IncompleteTransfer. This allows for any abort checking to be performed in the user code - to
- * continue the transfer, call the function again with identical parameters and it will resume until the BytesProcessed
- * value reaches the total transfer length.
- *
- * <b>Single Stream Transfer Example:</b>
- * \code
- * uint8_t ErrorCode;
- *
- * if ((ErrorCode = Pipe_Discard_Stream(512, NULL)) != PIPE_RWSTREAM_NoError)
- * {
- * // Stream failed to complete - check ErrorCode here
- * }
- * \endcode
- *
- * <b>Partial Stream Transfers Example:</b>
- * \code
- * uint8_t ErrorCode;
- * uint16_t BytesProcessed;
- *
- * BytesProcessed = 0;
- * while ((ErrorCode = Pipe_Discard_Stream(512, &BytesProcessed)) == PIPE_RWSTREAM_IncompleteTransfer)
- * {
- * // Stream not yet complete - do other actions here, abort if required
- * }
- *
- * if (ErrorCode != PIPE_RWSTREAM_NoError)
- * {
- * // Stream failed to complete - check ErrorCode here
- * }
- * \endcode
- *
- * \note 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().
- *
- * \param[in] Length Number of bytes to discard via the currently selected pipe.
- * \param[in] BytesProcessed Pointer to a location where the total number of bytes already processed should
- * updated, \c NULL if the entire stream should be processed at once.
- *
- * \return A value from the \ref Pipe_Stream_RW_ErrorCodes_t enum.
- */
- uint8_t Pipe_Discard_Stream(uint16_t Length,
- uint16_t* const BytesProcessed);
-
- /** Writes a given number of zeroed bytes to the pipe, sending full pipe packets from the host to the device
- * as needed. The last packet is not automatically sent once the remaining bytes has been written; the
- * user is responsible for manually discarding the last packet from the device via the \ref Pipe_ClearOUT() macro.
- *
- * If the BytesProcessed parameter is \c NULL, the entire stream transfer is attempted at once, failing or
- * succeeding as a single unit. If the BytesProcessed parameter points to a valid storage location, the transfer
- * will instead be performed as a series of chunks. Each time the pipe bank becomes full while there is still data
- * to process (and after the current packet transmission has been initiated) the BytesProcessed location will be
- * updated with the total number of bytes processed in the stream, and the function will exit with an error code of
- * \ref PIPE_RWSTREAM_IncompleteTransfer. This allows for any abort checking to be performed in the user code - to
- * continue the transfer, call the function again with identical parameters and it will resume until the BytesProcessed
- * value reaches the total transfer length.
- *
- * <b>Single Stream Transfer Example:</b>
- * \code
- * uint8_t ErrorCode;
- *
- * if ((ErrorCode = Pipe_Null_Stream(512, NULL)) != PIPE_RWSTREAM_NoError)
- * {
- * // Stream failed to complete - check ErrorCode here
- * }
- * \endcode
- *
- * <b>Partial Stream Transfers Example:</b>
- * \code
- * uint8_t ErrorCode;
- * uint16_t BytesProcessed;
- *
- * BytesProcessed = 0;
- * while ((ErrorCode = Pipe_Null_Stream(512, &BytesProcessed)) == PIPE_RWSTREAM_IncompleteTransfer)
- * {
- * // Stream not yet complete - do other actions here, abort if required
- * }
- *
- * if (ErrorCode != PIPE_RWSTREAM_NoError)
- * {
- * // Stream failed to complete - check ErrorCode here
- * }
- * \endcode
- *
- * \note 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().
- *
- * \param[in] Length Number of zero bytes to write via the currently selected pipe.
- * \param[in] BytesProcessed Pointer to a location where the total number of bytes already processed should
- * updated, \c NULL if the entire stream should be processed at once.
- *
- * \return A value from the \ref Pipe_Stream_RW_ErrorCodes_t enum.
- */
- uint8_t Pipe_Null_Stream(uint16_t Length,
- uint16_t* const BytesProcessed);
-
- //@}
-
- /** \name Stream functions for RAM source/destination data */
- //@{
-
- /** 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
- * \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.
- *
- * If the BytesProcessed parameter is \c NULL, the entire stream transfer is attempted at once,
- * failing or succeeding as a single unit. If the BytesProcessed parameter points to a valid
- * storage location, the transfer will instead be performed as a series of chunks. Each time
- * the pipe bank becomes full while there is still data to process (and after the current
- * packet transmission has been initiated) the BytesProcessed location will be updated with the
- * total number of bytes processed in the stream, and the function will exit with an error code of
- * \ref PIPE_RWSTREAM_IncompleteTransfer. This allows for any abort checking to be performed
- * in the user code - to continue the transfer, call the function again with identical parameters
- * and it will resume until the BytesProcessed value reaches the total transfer length.
- *
- * <b>Single Stream Transfer Example:</b>
- * \code
- * uint8_t DataStream[512];
- * uint8_t ErrorCode;
- *
- * if ((ErrorCode = Pipe_Write_Stream_LE(DataStream, sizeof(DataStream),
- * NULL)) != PIPE_RWSTREAM_NoError)
- * {
- * // Stream failed to complete - check ErrorCode here
- * }
- * \endcode
- *
- * <b>Partial Stream Transfers Example:</b>
- * \code
- * uint8_t DataStream[512];
- * uint8_t ErrorCode;
- * uint16_t BytesProcessed;
- *
- * BytesProcessed = 0;
- * while ((ErrorCode = Pipe_Write_Stream_LE(DataStream, sizeof(DataStream),
- * &BytesProcessed)) == PIPE_RWSTREAM_IncompleteTransfer)
- * {
- * // Stream not yet complete - do other actions here, abort if required
- * }
- *
- * if (ErrorCode != PIPE_RWSTREAM_NoError)
- * {
- * // Stream failed to complete - check ErrorCode here
- * }
- * \endcode
- *
- * \note 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().
- *
- * \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] BytesProcessed Pointer to a location where the total number of bytes already processed should
- * updated, \c NULL if the entire stream should be written at once.
- *
- * \return A value from the \ref Pipe_Stream_RW_ErrorCodes_t enum.
- */
- uint8_t Pipe_Write_Stream_LE(const void* const Buffer,
- uint16_t Length,
- uint16_t* const BytesProcessed) 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
- * \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.
- *
- * \note 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().
- *
- * \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] BytesProcessed Pointer to a location where the total number of bytes already processed should
- * updated, \c NULL if the entire stream should be written at once.
- *
- * \return A value from the \ref Pipe_Stream_RW_ErrorCodes_t enum.
- */
- uint8_t Pipe_Write_Stream_BE(const void* const Buffer,
- uint16_t Length,
- uint16_t* const BytesProcessed) 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
- * \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.
- *
- * If the BytesProcessed parameter is \c NULL, the entire stream transfer is attempted at once,
- * failing or succeeding as a single unit. If the BytesProcessed parameter points to a valid
- * storage location, the transfer will instead be performed as a series of chunks. Each time
- * the pipe bank becomes empty while there is still data to process (and after the current
- * packet has been acknowledged) the BytesProcessed location will be updated with the total number
- * of bytes processed in the stream, and the function will exit with an error code of
- * \ref PIPE_RWSTREAM_IncompleteTransfer. This allows for any abort checking to be performed
- * in the user code - to continue the transfer, call the function again with identical parameters
- * and it will resume until the BytesProcessed value reaches the total transfer length.
- *
- * <b>Single Stream Transfer Example:</b>
- * \code
- * uint8_t DataStream[512];
- * uint8_t ErrorCode;
- *
- * if ((ErrorCode = Pipe_Read_Stream_LE(DataStream, sizeof(DataStream),
- * NULL)) != PIPE_RWSTREAM_NoError)
- * {
- * // Stream failed to complete - check ErrorCode here
- * }
- * \endcode
- *
- * <b>Partial Stream Transfers Example:</b>
- * \code
- * uint8_t DataStream[512];
- * uint8_t ErrorCode;
- * uint16_t BytesProcessed;
- *
- * BytesProcessed = 0;
- * while ((ErrorCode = Pipe_Read_Stream_LE(DataStream, sizeof(DataStream),
- * &BytesProcessed)) == PIPE_RWSTREAM_IncompleteTransfer)
- * {
- * // Stream not yet complete - do other actions here, abort if required
- * }
- *
- * if (ErrorCode != PIPE_RWSTREAM_NoError)
- * {
- * // Stream failed to complete - check ErrorCode here
- * }
- * \endcode
- *
- * \note 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().
- *
- * \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] BytesProcessed Pointer to a location where the total number of bytes already processed should
- * updated, \c NULL if the entire stream should be read at once.
- *
- * \return A value from the \ref Pipe_Stream_RW_ErrorCodes_t enum.
- */
- uint8_t Pipe_Read_Stream_LE(void* const Buffer,
- uint16_t Length,
- uint16_t* const BytesProcessed) 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
- * \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.
- *
- * \note 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().
- *
- * \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] BytesProcessed Pointer to a location where the total number of bytes already processed should
- * updated, \c NULL if the entire stream should be read at once.
- *
- * \return A value from the \ref Pipe_Stream_RW_ErrorCodes_t enum.
- */
- uint8_t Pipe_Read_Stream_BE(void* const Buffer,
- uint16_t Length,
- uint16_t* const BytesProcessed) ATTR_NON_NULL_PTR_ARG(1);
- //@}
-
- /* Disable C linkage for C++ Compilers: */
- #if defined(__cplusplus)
- }
- #endif
-
-#endif
-
-/** @} */
+/* + LUFA Library + Copyright (C) Dean Camera, 2012. + + dean [at] fourwalledcubicle [dot] com + www.lufa-lib.org +*/ + +/* + Copyright 2012 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 + software, including all implied warranties of merchantability + and fitness. In no event shall the author be liable for any + special, indirect or consequential damages or any damages + whatsoever resulting from loss of use, data or profits, whether + in an action of contract, negligence or other tortious action, + arising out of or in connection with the use or performance of + this software. +*/ + +/** \file + * \brief Pipe data stream transmission and reception management for the AVR32 UC3 microcontrollers. + * \copydetails Group_PipeStreamRW_UC3 + * + * \note This file should not be included directly. It is automatically included as needed by the USB driver + * dispatch header located in LUFA/Drivers/USB/USB.h. + */ + +/** \ingroup Group_PipeStreamRW + * \defgroup Group_PipeStreamRW_UC3 Read/Write of Multi-Byte Streams (UC3) + * \brief Pipe data stream transmission and reception management for the Atmel AVR32 UC3 architecture. + * + * Functions, macros, variables, enums and types related to data reading and writing of data streams from + * and to pipes. + * + * @{ + */ + +#ifndef __PIPE_STREAM_UC3_H__ +#define __PIPE_STREAM_UC3_H__ + + /* Includes: */ + #include "../../../../Common/Common.h" + #include "../USBMode.h" + #include "../USBTask.h" + + /* Enable C linkage for C++ Compilers: */ + #if defined(__cplusplus) + extern "C" { + #endif + + /* Preprocessor Checks: */ + #if !defined(__INCLUDE_FROM_USB_DRIVER) + #error Do not include this file directly. Include LUFA/Drivers/USB/USB.h instead. + #endif + + /* Public Interface - May be used in end-application: */ + /* Function Prototypes: */ + /** \name Stream functions for null data */ + //@{ + + /** 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. + * + * If the BytesProcessed parameter is \c NULL, the entire stream transfer is attempted at once, failing or + * succeeding as a single unit. If the BytesProcessed parameter points to a valid storage location, the transfer + * will instead be performed as a series of chunks. Each time the pipe bank becomes empty while there is still data + * to process (and after the current packet has been acknowledged) the BytesProcessed location will be updated with + * the total number of bytes processed in the stream, and the function will exit with an error code of + * \ref PIPE_RWSTREAM_IncompleteTransfer. This allows for any abort checking to be performed in the user code - to + * continue the transfer, call the function again with identical parameters and it will resume until the BytesProcessed + * value reaches the total transfer length. + * + * <b>Single Stream Transfer Example:</b> + * \code + * uint8_t ErrorCode; + * + * if ((ErrorCode = Pipe_Discard_Stream(512, NULL)) != PIPE_RWSTREAM_NoError) + * { + * // Stream failed to complete - check ErrorCode here + * } + * \endcode + * + * <b>Partial Stream Transfers Example:</b> + * \code + * uint8_t ErrorCode; + * uint16_t BytesProcessed; + * + * BytesProcessed = 0; + * while ((ErrorCode = Pipe_Discard_Stream(512, &BytesProcessed)) == PIPE_RWSTREAM_IncompleteTransfer) + * { + * // Stream not yet complete - do other actions here, abort if required + * } + * + * if (ErrorCode != PIPE_RWSTREAM_NoError) + * { + * // Stream failed to complete - check ErrorCode here + * } + * \endcode + * + * \note 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(). + * + * \param[in] Length Number of bytes to discard via the currently selected pipe. + * \param[in] BytesProcessed Pointer to a location where the total number of bytes already processed should + * updated, \c NULL if the entire stream should be processed at once. + * + * \return A value from the \ref Pipe_Stream_RW_ErrorCodes_t enum. + */ + uint8_t Pipe_Discard_Stream(uint16_t Length, + uint16_t* const BytesProcessed); + + /** Writes a given number of zeroed bytes to the pipe, sending full pipe packets from the host to the device + * as needed. The last packet is not automatically sent once the remaining bytes has been written; the + * user is responsible for manually discarding the last packet from the device via the \ref Pipe_ClearOUT() macro. + * + * If the BytesProcessed parameter is \c NULL, the entire stream transfer is attempted at once, failing or + * succeeding as a single unit. If the BytesProcessed parameter points to a valid storage location, the transfer + * will instead be performed as a series of chunks. Each time the pipe bank becomes full while there is still data + * to process (and after the current packet transmission has been initiated) the BytesProcessed location will be + * updated with the total number of bytes processed in the stream, and the function will exit with an error code of + * \ref PIPE_RWSTREAM_IncompleteTransfer. This allows for any abort checking to be performed in the user code - to + * continue the transfer, call the function again with identical parameters and it will resume until the BytesProcessed + * value reaches the total transfer length. + * + * <b>Single Stream Transfer Example:</b> + * \code + * uint8_t ErrorCode; + * + * if ((ErrorCode = Pipe_Null_Stream(512, NULL)) != PIPE_RWSTREAM_NoError) + * { + * // Stream failed to complete - check ErrorCode here + * } + * \endcode + * + * <b>Partial Stream Transfers Example:</b> + * \code + * uint8_t ErrorCode; + * uint16_t BytesProcessed; + * + * BytesProcessed = 0; + * while ((ErrorCode = Pipe_Null_Stream(512, &BytesProcessed)) == PIPE_RWSTREAM_IncompleteTransfer) + * { + * // Stream not yet complete - do other actions here, abort if required + * } + * + * if (ErrorCode != PIPE_RWSTREAM_NoError) + * { + * // Stream failed to complete - check ErrorCode here + * } + * \endcode + * + * \note 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(). + * + * \param[in] Length Number of zero bytes to write via the currently selected pipe. + * \param[in] BytesProcessed Pointer to a location where the total number of bytes already processed should + * updated, \c NULL if the entire stream should be processed at once. + * + * \return A value from the \ref Pipe_Stream_RW_ErrorCodes_t enum. + */ + uint8_t Pipe_Null_Stream(uint16_t Length, + uint16_t* const BytesProcessed); + + //@} + + /** \name Stream functions for RAM source/destination data */ + //@{ + + /** 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 + * \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. + * + * If the BytesProcessed parameter is \c NULL, the entire stream transfer is attempted at once, + * failing or succeeding as a single unit. If the BytesProcessed parameter points to a valid + * storage location, the transfer will instead be performed as a series of chunks. Each time + * the pipe bank becomes full while there is still data to process (and after the current + * packet transmission has been initiated) the BytesProcessed location will be updated with the + * total number of bytes processed in the stream, and the function will exit with an error code of + * \ref PIPE_RWSTREAM_IncompleteTransfer. This allows for any abort checking to be performed + * in the user code - to continue the transfer, call the function again with identical parameters + * and it will resume until the BytesProcessed value reaches the total transfer length. + * + * <b>Single Stream Transfer Example:</b> + * \code + * uint8_t DataStream[512]; + * uint8_t ErrorCode; + * + * if ((ErrorCode = Pipe_Write_Stream_LE(DataStream, sizeof(DataStream), + * NULL)) != PIPE_RWSTREAM_NoError) + * { + * // Stream failed to complete - check ErrorCode here + * } + * \endcode + * + * <b>Partial Stream Transfers Example:</b> + * \code + * uint8_t DataStream[512]; + * uint8_t ErrorCode; + * uint16_t BytesProcessed; + * + * BytesProcessed = 0; + * while ((ErrorCode = Pipe_Write_Stream_LE(DataStream, sizeof(DataStream), + * &BytesProcessed)) == PIPE_RWSTREAM_IncompleteTransfer) + * { + * // Stream not yet complete - do other actions here, abort if required + * } + * + * if (ErrorCode != PIPE_RWSTREAM_NoError) + * { + * // Stream failed to complete - check ErrorCode here + * } + * \endcode + * + * \note 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(). + * + * \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] BytesProcessed Pointer to a location where the total number of bytes already processed should + * updated, \c NULL if the entire stream should be written at once. + * + * \return A value from the \ref Pipe_Stream_RW_ErrorCodes_t enum. + */ + uint8_t Pipe_Write_Stream_LE(const void* const Buffer, + uint16_t Length, + uint16_t* const BytesProcessed) 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 + * \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. + * + * \note 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(). + * + * \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] BytesProcessed Pointer to a location where the total number of bytes already processed should + * updated, \c NULL if the entire stream should be written at once. + * + * \return A value from the \ref Pipe_Stream_RW_ErrorCodes_t enum. + */ + uint8_t Pipe_Write_Stream_BE(const void* const Buffer, + uint16_t Length, + uint16_t* const BytesProcessed) 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 + * \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. + * + * If the BytesProcessed parameter is \c NULL, the entire stream transfer is attempted at once, + * failing or succeeding as a single unit. If the BytesProcessed parameter points to a valid + * storage location, the transfer will instead be performed as a series of chunks. Each time + * the pipe bank becomes empty while there is still data to process (and after the current + * packet has been acknowledged) the BytesProcessed location will be updated with the total number + * of bytes processed in the stream, and the function will exit with an error code of + * \ref PIPE_RWSTREAM_IncompleteTransfer. This allows for any abort checking to be performed + * in the user code - to continue the transfer, call the function again with identical parameters + * and it will resume until the BytesProcessed value reaches the total transfer length. + * + * <b>Single Stream Transfer Example:</b> + * \code + * uint8_t DataStream[512]; + * uint8_t ErrorCode; + * + * if ((ErrorCode = Pipe_Read_Stream_LE(DataStream, sizeof(DataStream), + * NULL)) != PIPE_RWSTREAM_NoError) + * { + * // Stream failed to complete - check ErrorCode here + * } + * \endcode + * + * <b>Partial Stream Transfers Example:</b> + * \code + * uint8_t DataStream[512]; + * uint8_t ErrorCode; + * uint16_t BytesProcessed; + * + * BytesProcessed = 0; + * while ((ErrorCode = Pipe_Read_Stream_LE(DataStream, sizeof(DataStream), + * &BytesProcessed)) == PIPE_RWSTREAM_IncompleteTransfer) + * { + * // Stream not yet complete - do other actions here, abort if required + * } + * + * if (ErrorCode != PIPE_RWSTREAM_NoError) + * { + * // Stream failed to complete - check ErrorCode here + * } + * \endcode + * + * \note 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(). + * + * \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] BytesProcessed Pointer to a location where the total number of bytes already processed should + * updated, \c NULL if the entire stream should be read at once. + * + * \return A value from the \ref Pipe_Stream_RW_ErrorCodes_t enum. + */ + uint8_t Pipe_Read_Stream_LE(void* const Buffer, + uint16_t Length, + uint16_t* const BytesProcessed) 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 + * \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. + * + * \note 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(). + * + * \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] BytesProcessed Pointer to a location where the total number of bytes already processed should + * updated, \c NULL if the entire stream should be read at once. + * + * \return A value from the \ref Pipe_Stream_RW_ErrorCodes_t enum. + */ + uint8_t Pipe_Read_Stream_BE(void* const Buffer, + uint16_t Length, + uint16_t* const BytesProcessed) ATTR_NON_NULL_PTR_ARG(1); + //@} + + /* Disable C linkage for C++ Compilers: */ + #if defined(__cplusplus) + } + #endif + +#endif + +/** @} */ diff --git a/LUFA/Drivers/USB/Core/XMEGA/EndpointStream_XMEGA.c b/LUFA/Drivers/USB/Core/XMEGA/EndpointStream_XMEGA.c index 774a574f3..db804506e 100644 --- a/LUFA/Drivers/USB/Core/XMEGA/EndpointStream_XMEGA.c +++ b/LUFA/Drivers/USB/Core/XMEGA/EndpointStream_XMEGA.c @@ -1,275 +1,275 @@ -/*
- LUFA Library
- Copyright (C) Dean Camera, 2012.
-
- dean [at] fourwalledcubicle [dot] com
- www.lufa-lib.org
-*/
-
-/*
- Copyright 2012 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
- software, including all implied warranties of merchantability
- and fitness. In no event shall the author be liable for any
- special, indirect or consequential damages or any damages
- whatsoever resulting from loss of use, data or profits, whether
- in an action of contract, negligence or other tortious action,
- arising out of or in connection with the use or performance of
- this software.
-*/
-
-#include "../../../../Common/Common.h"
-#if (ARCH == ARCH_XMEGA)
-
-#define __INCLUDE_FROM_USB_DRIVER
-#include "../USBMode.h"
-
-#if defined(USB_CAN_BE_DEVICE)
-
-#include "EndpointStream_XMEGA.h"
-
-#if !defined(CONTROL_ONLY_DEVICE)
-uint8_t Endpoint_Discard_Stream(uint16_t Length,
- uint16_t* const BytesProcessed)
-{
- uint8_t ErrorCode;
- uint16_t BytesInTransfer = 0;
-
- if ((ErrorCode = Endpoint_WaitUntilReady()))
- return ErrorCode;
-
- if (BytesProcessed != NULL)
- Length -= *BytesProcessed;
-
- while (Length)
- {
- if (!(Endpoint_IsReadWriteAllowed()))
- {
- Endpoint_ClearOUT();
-
- if (BytesProcessed != NULL)
- {
- *BytesProcessed += BytesInTransfer;
- return ENDPOINT_RWSTREAM_IncompleteTransfer;
- }
-
- if ((ErrorCode = Endpoint_WaitUntilReady()))
- return ErrorCode;
- }
- else
- {
- Endpoint_Discard_8();
-
- Length--;
- BytesInTransfer++;
- }
- }
-
- return ENDPOINT_RWSTREAM_NoError;
-}
-
-uint8_t Endpoint_Null_Stream(uint16_t Length,
- uint16_t* const BytesProcessed)
-{
- uint8_t ErrorCode;
- uint16_t BytesInTransfer = 0;
-
- if ((ErrorCode = Endpoint_WaitUntilReady()))
- return ErrorCode;
-
- if (BytesProcessed != NULL)
- Length -= *BytesProcessed;
-
- while (Length)
- {
- if (!(Endpoint_IsReadWriteAllowed()))
- {
- Endpoint_ClearIN();
-
- if (BytesProcessed != NULL)
- {
- *BytesProcessed += BytesInTransfer;
- return ENDPOINT_RWSTREAM_IncompleteTransfer;
- }
-
- if ((ErrorCode = Endpoint_WaitUntilReady()))
- return ErrorCode;
- }
- else
- {
- Endpoint_Write_8(0);
-
- Length--;
- BytesInTransfer++;
- }
- }
-
- return ENDPOINT_RWSTREAM_NoError;
-}
-
-/* The following abuses the C preprocessor in order to copy-paste common code with slight alterations,
- * so that the code needs to be written once. It is a crude form of templating to reduce code maintenance. */
-
-#define TEMPLATE_FUNC_NAME Endpoint_Write_Stream_LE
-#define TEMPLATE_BUFFER_TYPE const void*
-#define TEMPLATE_CLEAR_ENDPOINT() Endpoint_ClearIN()
-#define TEMPLATE_BUFFER_OFFSET(Length) 0
-#define TEMPLATE_BUFFER_MOVE(BufferPtr, Amount) BufferPtr += Amount
-#define TEMPLATE_TRANSFER_BYTE(BufferPtr) Endpoint_Write_8(*BufferPtr)
-#include "Template/Template_Endpoint_RW.c"
-
-#define TEMPLATE_FUNC_NAME Endpoint_Write_Stream_BE
-#define TEMPLATE_BUFFER_TYPE const void*
-#define TEMPLATE_CLEAR_ENDPOINT() Endpoint_ClearIN()
-#define TEMPLATE_BUFFER_OFFSET(Length) (Length - 1)
-#define TEMPLATE_BUFFER_MOVE(BufferPtr, Amount) BufferPtr -= Amount
-#define TEMPLATE_TRANSFER_BYTE(BufferPtr) Endpoint_Write_8(*BufferPtr)
-#include "Template/Template_Endpoint_RW.c"
-
-#define TEMPLATE_FUNC_NAME Endpoint_Read_Stream_LE
-#define TEMPLATE_BUFFER_TYPE void*
-#define TEMPLATE_CLEAR_ENDPOINT() Endpoint_ClearOUT()
-#define TEMPLATE_BUFFER_OFFSET(Length) 0
-#define TEMPLATE_BUFFER_MOVE(BufferPtr, Amount) BufferPtr += Amount
-#define TEMPLATE_TRANSFER_BYTE(BufferPtr) *BufferPtr = Endpoint_Read_8()
-#include "Template/Template_Endpoint_RW.c"
-
-#define TEMPLATE_FUNC_NAME Endpoint_Read_Stream_BE
-#define TEMPLATE_BUFFER_TYPE void*
-#define TEMPLATE_CLEAR_ENDPOINT() Endpoint_ClearOUT()
-#define TEMPLATE_BUFFER_OFFSET(Length) (Length - 1)
-#define TEMPLATE_BUFFER_MOVE(BufferPtr, Amount) BufferPtr -= Amount
-#define TEMPLATE_TRANSFER_BYTE(BufferPtr) *BufferPtr = Endpoint_Read_8()
-#include "Template/Template_Endpoint_RW.c"
-
-#if defined(ARCH_HAS_FLASH_ADDRESS_SPACE)
- #define TEMPLATE_FUNC_NAME Endpoint_Write_PStream_LE
- #define TEMPLATE_BUFFER_TYPE const void*
- #define TEMPLATE_CLEAR_ENDPOINT() Endpoint_ClearIN()
- #define TEMPLATE_BUFFER_OFFSET(Length) 0
- #define TEMPLATE_BUFFER_MOVE(BufferPtr, Amount) BufferPtr += Amount
- #define TEMPLATE_TRANSFER_BYTE(BufferPtr) Endpoint_Write_8(pgm_read_byte(BufferPtr))
- #include "Template/Template_Endpoint_RW.c"
-
- #define TEMPLATE_FUNC_NAME Endpoint_Write_PStream_BE
- #define TEMPLATE_BUFFER_TYPE const void*
- #define TEMPLATE_CLEAR_ENDPOINT() Endpoint_ClearIN()
- #define TEMPLATE_BUFFER_OFFSET(Length) (Length - 1)
- #define TEMPLATE_BUFFER_MOVE(BufferPtr, Amount) BufferPtr -= Amount
- #define TEMPLATE_TRANSFER_BYTE(BufferPtr) Endpoint_Write_8(pgm_read_byte(BufferPtr))
- #include "Template/Template_Endpoint_RW.c"
-#endif
-
-#if defined(ARCH_HAS_EEPROM_ADDRESS_SPACE)
- #define TEMPLATE_FUNC_NAME Endpoint_Write_EStream_LE
- #define TEMPLATE_BUFFER_TYPE const void*
- #define TEMPLATE_CLEAR_ENDPOINT() Endpoint_ClearIN()
- #define TEMPLATE_BUFFER_OFFSET(Length) 0
- #define TEMPLATE_BUFFER_MOVE(BufferPtr, Amount) BufferPtr += Amount
- #define TEMPLATE_TRANSFER_BYTE(BufferPtr) Endpoint_Write_8(eeprom_read_byte(BufferPtr))
- #include "Template/Template_Endpoint_RW.c"
-
- #define TEMPLATE_FUNC_NAME Endpoint_Write_EStream_BE
- #define TEMPLATE_BUFFER_TYPE const void*
- #define TEMPLATE_CLEAR_ENDPOINT() Endpoint_ClearIN()
- #define TEMPLATE_BUFFER_OFFSET(Length) (Length - 1)
- #define TEMPLATE_BUFFER_MOVE(BufferPtr, Amount) BufferPtr -= Amount
- #define TEMPLATE_TRANSFER_BYTE(BufferPtr) Endpoint_Write_8(eeprom_read_byte(BufferPtr))
- #include "Template/Template_Endpoint_RW.c"
-
- #define TEMPLATE_FUNC_NAME Endpoint_Read_EStream_LE
- #define TEMPLATE_BUFFER_TYPE void*
- #define TEMPLATE_CLEAR_ENDPOINT() Endpoint_ClearOUT()
- #define TEMPLATE_BUFFER_OFFSET(Length) 0
- #define TEMPLATE_BUFFER_MOVE(BufferPtr, Amount) BufferPtr += Amount
- #define TEMPLATE_TRANSFER_BYTE(BufferPtr) eeprom_update_byte(BufferPtr, Endpoint_Read_8())
- #include "Template/Template_Endpoint_RW.c"
-
- #define TEMPLATE_FUNC_NAME Endpoint_Read_EStream_BE
- #define TEMPLATE_BUFFER_TYPE void*
- #define TEMPLATE_CLEAR_ENDPOINT() Endpoint_ClearOUT()
- #define TEMPLATE_BUFFER_OFFSET(Length) (Length - 1)
- #define TEMPLATE_BUFFER_MOVE(BufferPtr, Amount) BufferPtr -= Amount
- #define TEMPLATE_TRANSFER_BYTE(BufferPtr) eeprom_update_byte(BufferPtr, Endpoint_Read_8())
- #include "Template/Template_Endpoint_RW.c"
-#endif
-
-#endif
-
-#define TEMPLATE_FUNC_NAME Endpoint_Write_Control_Stream_LE
-#define TEMPLATE_BUFFER_OFFSET(Length) 0
-#define TEMPLATE_BUFFER_MOVE(BufferPtr, Amount) BufferPtr += Amount
-#define TEMPLATE_TRANSFER_BYTE(BufferPtr) Endpoint_Write_8(*BufferPtr)
-#include "Template/Template_Endpoint_Control_W.c"
-
-#define TEMPLATE_FUNC_NAME Endpoint_Write_Control_Stream_BE
-#define TEMPLATE_BUFFER_OFFSET(Length) (Length - 1)
-#define TEMPLATE_BUFFER_MOVE(BufferPtr, Amount) BufferPtr -= Amount
-#define TEMPLATE_TRANSFER_BYTE(BufferPtr) Endpoint_Write_8(*BufferPtr)
-#include "Template/Template_Endpoint_Control_W.c"
-
-#define TEMPLATE_FUNC_NAME Endpoint_Read_Control_Stream_LE
-#define TEMPLATE_BUFFER_OFFSET(Length) 0
-#define TEMPLATE_BUFFER_MOVE(BufferPtr, Amount) BufferPtr += Amount
-#define TEMPLATE_TRANSFER_BYTE(BufferPtr) *BufferPtr = Endpoint_Read_8()
-#include "Template/Template_Endpoint_Control_R.c"
-
-#define TEMPLATE_FUNC_NAME Endpoint_Read_Control_Stream_BE
-#define TEMPLATE_BUFFER_OFFSET(Length) (Length - 1)
-#define TEMPLATE_BUFFER_MOVE(BufferPtr, Amount) BufferPtr -= Amount
-#define TEMPLATE_TRANSFER_BYTE(BufferPtr) *BufferPtr = Endpoint_Read_8()
-#include "Template/Template_Endpoint_Control_R.c"
-
-#if defined(ARCH_HAS_FLASH_ADDRESS_SPACE)
- #define TEMPLATE_FUNC_NAME Endpoint_Write_Control_PStream_LE
- #define TEMPLATE_BUFFER_OFFSET(Length) 0
- #define TEMPLATE_BUFFER_MOVE(BufferPtr, Amount) BufferPtr += Amount
- #define TEMPLATE_TRANSFER_BYTE(BufferPtr) Endpoint_Write_8(pgm_read_byte(BufferPtr))
- #include "Template/Template_Endpoint_Control_W.c"
-
- #define TEMPLATE_FUNC_NAME Endpoint_Write_Control_PStream_BE
- #define TEMPLATE_BUFFER_OFFSET(Length) (Length - 1)
- #define TEMPLATE_BUFFER_MOVE(BufferPtr, Amount) BufferPtr -= Amount
- #define TEMPLATE_TRANSFER_BYTE(BufferPtr) Endpoint_Write_8(pgm_read_byte(BufferPtr))
- #include "Template/Template_Endpoint_Control_W.c"
-#endif
-
-#if defined(ARCH_HAS_EEPROM_ADDRESS_SPACE)
- #define TEMPLATE_FUNC_NAME Endpoint_Write_Control_EStream_LE
- #define TEMPLATE_BUFFER_OFFSET(Length) 0
- #define TEMPLATE_BUFFER_MOVE(BufferPtr, Amount) BufferPtr += Amount
- #define TEMPLATE_TRANSFER_BYTE(BufferPtr) Endpoint_Write_8(eeprom_read_byte(BufferPtr))
- #include "Template/Template_Endpoint_Control_W.c"
-
- #define TEMPLATE_FUNC_NAME Endpoint_Write_Control_EStream_BE
- #define TEMPLATE_BUFFER_OFFSET(Length) (Length - 1)
- #define TEMPLATE_BUFFER_MOVE(BufferPtr, Amount) BufferPtr -= Amount
- #define TEMPLATE_TRANSFER_BYTE(BufferPtr) Endpoint_Write_8(eeprom_read_byte(BufferPtr))
- #include "Template/Template_Endpoint_Control_W.c"
-
- #define TEMPLATE_FUNC_NAME Endpoint_Read_Control_EStream_LE
- #define TEMPLATE_BUFFER_OFFSET(Length) 0
- #define TEMPLATE_BUFFER_MOVE(BufferPtr, Amount) BufferPtr += Amount
- #define TEMPLATE_TRANSFER_BYTE(BufferPtr) eeprom_update_byte(BufferPtr, Endpoint_Read_8())
- #include "Template/Template_Endpoint_Control_R.c"
-
- #define TEMPLATE_FUNC_NAME Endpoint_Read_Control_EStream_BE
- #define TEMPLATE_BUFFER_OFFSET(Length) (Length - 1)
- #define TEMPLATE_BUFFER_MOVE(BufferPtr, Amount) BufferPtr -= Amount
- #define TEMPLATE_TRANSFER_BYTE(BufferPtr) eeprom_update_byte(BufferPtr, Endpoint_Read_8())
- #include "Template/Template_Endpoint_Control_R.c"
-#endif
-
+/* + LUFA Library + Copyright (C) Dean Camera, 2012. + + dean [at] fourwalledcubicle [dot] com + www.lufa-lib.org +*/ + +/* + Copyright 2012 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 + software, including all implied warranties of merchantability + and fitness. In no event shall the author be liable for any + special, indirect or consequential damages or any damages + whatsoever resulting from loss of use, data or profits, whether + in an action of contract, negligence or other tortious action, + arising out of or in connection with the use or performance of + this software. +*/ + +#include "../../../../Common/Common.h" +#if (ARCH == ARCH_XMEGA) + +#define __INCLUDE_FROM_USB_DRIVER +#include "../USBMode.h" + +#if defined(USB_CAN_BE_DEVICE) + +#include "EndpointStream_XMEGA.h" + +#if !defined(CONTROL_ONLY_DEVICE) +uint8_t Endpoint_Discard_Stream(uint16_t Length, + uint16_t* const BytesProcessed) +{ + uint8_t ErrorCode; + uint16_t BytesInTransfer = 0; + + if ((ErrorCode = Endpoint_WaitUntilReady())) + return ErrorCode; + + if (BytesProcessed != NULL) + Length -= *BytesProcessed; + + while (Length) + { + if (!(Endpoint_IsReadWriteAllowed())) + { + Endpoint_ClearOUT(); + + if (BytesProcessed != NULL) + { + *BytesProcessed += BytesInTransfer; + return ENDPOINT_RWSTREAM_IncompleteTransfer; + } + + if ((ErrorCode = Endpoint_WaitUntilReady())) + return ErrorCode; + } + else + { + Endpoint_Discard_8(); + + Length--; + BytesInTransfer++; + } + } + + return ENDPOINT_RWSTREAM_NoError; +} + +uint8_t Endpoint_Null_Stream(uint16_t Length, + uint16_t* const BytesProcessed) +{ + uint8_t ErrorCode; + uint16_t BytesInTransfer = 0; + + if ((ErrorCode = Endpoint_WaitUntilReady())) + return ErrorCode; + + if (BytesProcessed != NULL) + Length -= *BytesProcessed; + + while (Length) + { + if (!(Endpoint_IsReadWriteAllowed())) + { + Endpoint_ClearIN(); + + if (BytesProcessed != NULL) + { + *BytesProcessed += BytesInTransfer; + return ENDPOINT_RWSTREAM_IncompleteTransfer; + } + + if ((ErrorCode = Endpoint_WaitUntilReady())) + return ErrorCode; + } + else + { + Endpoint_Write_8(0); + + Length--; + BytesInTransfer++; + } + } + + return ENDPOINT_RWSTREAM_NoError; +} + +/* The following abuses the C preprocessor in order to copy-paste common code with slight alterations, + * so that the code needs to be written once. It is a crude form of templating to reduce code maintenance. */ + +#define TEMPLATE_FUNC_NAME Endpoint_Write_Stream_LE +#define TEMPLATE_BUFFER_TYPE const void* +#define TEMPLATE_CLEAR_ENDPOINT() Endpoint_ClearIN() +#define TEMPLATE_BUFFER_OFFSET(Length) 0 +#define TEMPLATE_BUFFER_MOVE(BufferPtr, Amount) BufferPtr += Amount +#define TEMPLATE_TRANSFER_BYTE(BufferPtr) Endpoint_Write_8(*BufferPtr) +#include "Template/Template_Endpoint_RW.c" + +#define TEMPLATE_FUNC_NAME Endpoint_Write_Stream_BE +#define TEMPLATE_BUFFER_TYPE const void* +#define TEMPLATE_CLEAR_ENDPOINT() Endpoint_ClearIN() +#define TEMPLATE_BUFFER_OFFSET(Length) (Length - 1) +#define TEMPLATE_BUFFER_MOVE(BufferPtr, Amount) BufferPtr -= Amount +#define TEMPLATE_TRANSFER_BYTE(BufferPtr) Endpoint_Write_8(*BufferPtr) +#include "Template/Template_Endpoint_RW.c" + +#define TEMPLATE_FUNC_NAME Endpoint_Read_Stream_LE +#define TEMPLATE_BUFFER_TYPE void* +#define TEMPLATE_CLEAR_ENDPOINT() Endpoint_ClearOUT() +#define TEMPLATE_BUFFER_OFFSET(Length) 0 +#define TEMPLATE_BUFFER_MOVE(BufferPtr, Amount) BufferPtr += Amount +#define TEMPLATE_TRANSFER_BYTE(BufferPtr) *BufferPtr = Endpoint_Read_8() +#include "Template/Template_Endpoint_RW.c" + +#define TEMPLATE_FUNC_NAME Endpoint_Read_Stream_BE +#define TEMPLATE_BUFFER_TYPE void* +#define TEMPLATE_CLEAR_ENDPOINT() Endpoint_ClearOUT() +#define TEMPLATE_BUFFER_OFFSET(Length) (Length - 1) +#define TEMPLATE_BUFFER_MOVE(BufferPtr, Amount) BufferPtr -= Amount +#define TEMPLATE_TRANSFER_BYTE(BufferPtr) *BufferPtr = Endpoint_Read_8() +#include "Template/Template_Endpoint_RW.c" + +#if defined(ARCH_HAS_FLASH_ADDRESS_SPACE) + #define TEMPLATE_FUNC_NAME Endpoint_Write_PStream_LE + #define TEMPLATE_BUFFER_TYPE const void* + #define TEMPLATE_CLEAR_ENDPOINT() Endpoint_ClearIN() + #define TEMPLATE_BUFFER_OFFSET(Length) 0 + #define TEMPLATE_BUFFER_MOVE(BufferPtr, Amount) BufferPtr += Amount + #define TEMPLATE_TRANSFER_BYTE(BufferPtr) Endpoint_Write_8(pgm_read_byte(BufferPtr)) + #include "Template/Template_Endpoint_RW.c" + + #define TEMPLATE_FUNC_NAME Endpoint_Write_PStream_BE + #define TEMPLATE_BUFFER_TYPE const void* + #define TEMPLATE_CLEAR_ENDPOINT() Endpoint_ClearIN() + #define TEMPLATE_BUFFER_OFFSET(Length) (Length - 1) + #define TEMPLATE_BUFFER_MOVE(BufferPtr, Amount) BufferPtr -= Amount + #define TEMPLATE_TRANSFER_BYTE(BufferPtr) Endpoint_Write_8(pgm_read_byte(BufferPtr)) + #include "Template/Template_Endpoint_RW.c" +#endif + +#if defined(ARCH_HAS_EEPROM_ADDRESS_SPACE) + #define TEMPLATE_FUNC_NAME Endpoint_Write_EStream_LE + #define TEMPLATE_BUFFER_TYPE const void* + #define TEMPLATE_CLEAR_ENDPOINT() Endpoint_ClearIN() + #define TEMPLATE_BUFFER_OFFSET(Length) 0 + #define TEMPLATE_BUFFER_MOVE(BufferPtr, Amount) BufferPtr += Amount + #define TEMPLATE_TRANSFER_BYTE(BufferPtr) Endpoint_Write_8(eeprom_read_byte(BufferPtr)) + #include "Template/Template_Endpoint_RW.c" + + #define TEMPLATE_FUNC_NAME Endpoint_Write_EStream_BE + #define TEMPLATE_BUFFER_TYPE const void* + #define TEMPLATE_CLEAR_ENDPOINT() Endpoint_ClearIN() + #define TEMPLATE_BUFFER_OFFSET(Length) (Length - 1) + #define TEMPLATE_BUFFER_MOVE(BufferPtr, Amount) BufferPtr -= Amount + #define TEMPLATE_TRANSFER_BYTE(BufferPtr) Endpoint_Write_8(eeprom_read_byte(BufferPtr)) + #include "Template/Template_Endpoint_RW.c" + + #define TEMPLATE_FUNC_NAME Endpoint_Read_EStream_LE + #define TEMPLATE_BUFFER_TYPE void* + #define TEMPLATE_CLEAR_ENDPOINT() Endpoint_ClearOUT() + #define TEMPLATE_BUFFER_OFFSET(Length) 0 + #define TEMPLATE_BUFFER_MOVE(BufferPtr, Amount) BufferPtr += Amount + #define TEMPLATE_TRANSFER_BYTE(BufferPtr) eeprom_update_byte(BufferPtr, Endpoint_Read_8()) + #include "Template/Template_Endpoint_RW.c" + + #define TEMPLATE_FUNC_NAME Endpoint_Read_EStream_BE + #define TEMPLATE_BUFFER_TYPE void* + #define TEMPLATE_CLEAR_ENDPOINT() Endpoint_ClearOUT() + #define TEMPLATE_BUFFER_OFFSET(Length) (Length - 1) + #define TEMPLATE_BUFFER_MOVE(BufferPtr, Amount) BufferPtr -= Amount + #define TEMPLATE_TRANSFER_BYTE(BufferPtr) eeprom_update_byte(BufferPtr, Endpoint_Read_8()) + #include "Template/Template_Endpoint_RW.c" #endif -#endif
+#endif + +#define TEMPLATE_FUNC_NAME Endpoint_Write_Control_Stream_LE +#define TEMPLATE_BUFFER_OFFSET(Length) 0 +#define TEMPLATE_BUFFER_MOVE(BufferPtr, Amount) BufferPtr += Amount +#define TEMPLATE_TRANSFER_BYTE(BufferPtr) Endpoint_Write_8(*BufferPtr) +#include "Template/Template_Endpoint_Control_W.c" + +#define TEMPLATE_FUNC_NAME Endpoint_Write_Control_Stream_BE +#define TEMPLATE_BUFFER_OFFSET(Length) (Length - 1) +#define TEMPLATE_BUFFER_MOVE(BufferPtr, Amount) BufferPtr -= Amount +#define TEMPLATE_TRANSFER_BYTE(BufferPtr) Endpoint_Write_8(*BufferPtr) +#include "Template/Template_Endpoint_Control_W.c" + +#define TEMPLATE_FUNC_NAME Endpoint_Read_Control_Stream_LE +#define TEMPLATE_BUFFER_OFFSET(Length) 0 +#define TEMPLATE_BUFFER_MOVE(BufferPtr, Amount) BufferPtr += Amount +#define TEMPLATE_TRANSFER_BYTE(BufferPtr) *BufferPtr = Endpoint_Read_8() +#include "Template/Template_Endpoint_Control_R.c" + +#define TEMPLATE_FUNC_NAME Endpoint_Read_Control_Stream_BE +#define TEMPLATE_BUFFER_OFFSET(Length) (Length - 1) +#define TEMPLATE_BUFFER_MOVE(BufferPtr, Amount) BufferPtr -= Amount +#define TEMPLATE_TRANSFER_BYTE(BufferPtr) *BufferPtr = Endpoint_Read_8() +#include "Template/Template_Endpoint_Control_R.c" + +#if defined(ARCH_HAS_FLASH_ADDRESS_SPACE) + #define TEMPLATE_FUNC_NAME Endpoint_Write_Control_PStream_LE + #define TEMPLATE_BUFFER_OFFSET(Length) 0 + #define TEMPLATE_BUFFER_MOVE(BufferPtr, Amount) BufferPtr += Amount + #define TEMPLATE_TRANSFER_BYTE(BufferPtr) Endpoint_Write_8(pgm_read_byte(BufferPtr)) + #include "Template/Template_Endpoint_Control_W.c" + + #define TEMPLATE_FUNC_NAME Endpoint_Write_Control_PStream_BE + #define TEMPLATE_BUFFER_OFFSET(Length) (Length - 1) + #define TEMPLATE_BUFFER_MOVE(BufferPtr, Amount) BufferPtr -= Amount + #define TEMPLATE_TRANSFER_BYTE(BufferPtr) Endpoint_Write_8(pgm_read_byte(BufferPtr)) + #include "Template/Template_Endpoint_Control_W.c" +#endif + +#if defined(ARCH_HAS_EEPROM_ADDRESS_SPACE) + #define TEMPLATE_FUNC_NAME Endpoint_Write_Control_EStream_LE + #define TEMPLATE_BUFFER_OFFSET(Length) 0 + #define TEMPLATE_BUFFER_MOVE(BufferPtr, Amount) BufferPtr += Amount + #define TEMPLATE_TRANSFER_BYTE(BufferPtr) Endpoint_Write_8(eeprom_read_byte(BufferPtr)) + #include "Template/Template_Endpoint_Control_W.c" + + #define TEMPLATE_FUNC_NAME Endpoint_Write_Control_EStream_BE + #define TEMPLATE_BUFFER_OFFSET(Length) (Length - 1) + #define TEMPLATE_BUFFER_MOVE(BufferPtr, Amount) BufferPtr -= Amount + #define TEMPLATE_TRANSFER_BYTE(BufferPtr) Endpoint_Write_8(eeprom_read_byte(BufferPtr)) + #include "Template/Template_Endpoint_Control_W.c" + + #define TEMPLATE_FUNC_NAME Endpoint_Read_Control_EStream_LE + #define TEMPLATE_BUFFER_OFFSET(Length) 0 + #define TEMPLATE_BUFFER_MOVE(BufferPtr, Amount) BufferPtr += Amount + #define TEMPLATE_TRANSFER_BYTE(BufferPtr) eeprom_update_byte(BufferPtr, Endpoint_Read_8()) + #include "Template/Template_Endpoint_Control_R.c" + + #define TEMPLATE_FUNC_NAME Endpoint_Read_Control_EStream_BE + #define TEMPLATE_BUFFER_OFFSET(Length) (Length - 1) + #define TEMPLATE_BUFFER_MOVE(BufferPtr, Amount) BufferPtr -= Amount + #define TEMPLATE_TRANSFER_BYTE(BufferPtr) eeprom_update_byte(BufferPtr, Endpoint_Read_8()) + #include "Template/Template_Endpoint_Control_R.c" +#endif + +#endif + +#endif diff --git a/LUFA/Drivers/USB/Core/XMEGA/EndpointStream_XMEGA.h b/LUFA/Drivers/USB/Core/XMEGA/EndpointStream_XMEGA.h index 3269d2b1d..436752880 100644 --- a/LUFA/Drivers/USB/Core/XMEGA/EndpointStream_XMEGA.h +++ b/LUFA/Drivers/USB/Core/XMEGA/EndpointStream_XMEGA.h @@ -1,648 +1,648 @@ -/*
- LUFA Library
- Copyright (C) Dean Camera, 2012.
-
- dean [at] fourwalledcubicle [dot] com
- www.lufa-lib.org
-*/
-
-/*
- Copyright 2012 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
- software, including all implied warranties of merchantability
- and fitness. In no event shall the author be liable for any
- special, indirect or consequential damages or any damages
- whatsoever resulting from loss of use, data or profits, whether
- in an action of contract, negligence or other tortious action,
- arising out of or in connection with the use or performance of
- this software.
-*/
-
-/** \file
- * \brief Endpoint data stream transmission and reception management for the AVR XMEGA microcontrollers.
- * \copydetails Group_EndpointStreamRW_XMEGA
- *
- * \note This file should not be included directly. It is automatically included as needed by the USB driver
- * dispatch header located in LUFA/Drivers/USB/USB.h.
- */
-
-/** \ingroup Group_EndpointStreamRW
- * \defgroup Group_EndpointStreamRW_XMEGA Read/Write of Multi-Byte Streams (XMEGA)
- * \brief Endpoint data stream transmission and reception management for the Atmel AVR XMEGA architecture.
- *
- * Functions, macros, variables, enums and types related to data reading and writing of data streams from
- * and to endpoints.
- *
- * @{
- */
-
-#ifndef __ENDPOINT_STREAM_XMEGA_H__
-#define __ENDPOINT_STREAM_XMEGA_H__
-
- /* Includes: */
- #include "../../../../Common/Common.h"
- #include "../USBMode.h"
- #include "../USBTask.h"
-
- /* Enable C linkage for C++ Compilers: */
- #if defined(__cplusplus)
- extern "C" {
- #endif
-
- /* Preprocessor Checks: */
- #if !defined(__INCLUDE_FROM_USB_DRIVER)
- #error Do not include this file directly. Include LUFA/Drivers/USB/USB.h instead.
- #endif
-
- /* Public Interface - May be used in end-application: */
- /* Function Prototypes: */
- /** \name Stream functions for null data */
- //@{
-
- /** Reads and discards the given number of bytes from the currently selected endpoint's bank,
- * 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 \ref Endpoint_ClearOUT() macro.
- *
- * If the BytesProcessed parameter is \c NULL, the entire stream transfer is attempted at once,
- * failing or succeeding as a single unit. If the BytesProcessed parameter points to a valid
- * storage location, the transfer will instead be performed as a series of chunks. Each time
- * the endpoint bank becomes empty while there is still data to process (and after the current
- * packet has been acknowledged) the BytesProcessed location will be updated with the total number
- * of bytes processed in the stream, and the function will exit with an error code of
- * \ref ENDPOINT_RWSTREAM_IncompleteTransfer. This allows for any abort checking to be performed
- * in the user code - to continue the transfer, call the function again with identical parameters
- * and it will resume until the BytesProcessed value reaches the total transfer length.
- *
- * <b>Single Stream Transfer Example:</b>
- * \code
- * uint8_t ErrorCode;
- *
- * if ((ErrorCode = Endpoint_Discard_Stream(512, NULL)) != ENDPOINT_RWSTREAM_NoError)
- * {
- * // Stream failed to complete - check ErrorCode here
- * }
- * \endcode
- *
- * <b>Partial Stream Transfers Example:</b>
- * \code
- * uint8_t ErrorCode;
- * uint16_t BytesProcessed;
- *
- * BytesProcessed = 0;
- * while ((ErrorCode = Endpoint_Discard_Stream(512, &BytesProcessed)) == ENDPOINT_RWSTREAM_IncompleteTransfer)
- * {
- * // Stream not yet complete - do other actions here, abort if required
- * }
- *
- * if (ErrorCode != ENDPOINT_RWSTREAM_NoError)
- * {
- * // Stream failed to complete - check ErrorCode here
- * }
- * \endcode
- *
- * \note This routine should not be used on CONTROL type endpoints.
- *
- * \param[in] Length Number of bytes to discard via the currently selected endpoint.
- * \param[in] BytesProcessed Pointer to a location where the total number of bytes processed in the current
- * transaction should be updated, \c NULL if the entire stream should be read at once.
- *
- * \return A value from the \ref Endpoint_Stream_RW_ErrorCodes_t enum.
- */
- uint8_t Endpoint_Discard_Stream(uint16_t Length,
- uint16_t* const BytesProcessed);
-
- /** Writes a given number of zeroed bytes to the currently selected endpoint's bank, sending
- * full packets to the host as needed. The last packet is not automatically sent once the
- * remaining bytes have been written; the user is responsible for manually sending the last
- * packet to the host via the \ref Endpoint_ClearIN() macro.
- *
- * If the BytesProcessed parameter is \c NULL, the entire stream transfer is attempted at once,
- * failing or succeeding as a single unit. If the BytesProcessed parameter points to a valid
- * storage location, the transfer will instead be performed as a series of chunks. Each time
- * the endpoint bank becomes full while there is still data to process (and after the current
- * packet transmission has been initiated) the BytesProcessed location will be updated with the
- * total number of bytes processed in the stream, and the function will exit with an error code of
- * \ref ENDPOINT_RWSTREAM_IncompleteTransfer. This allows for any abort checking to be performed
- * in the user code - to continue the transfer, call the function again with identical parameters
- * and it will resume until the BytesProcessed value reaches the total transfer length.
- *
- * <b>Single Stream Transfer Example:</b>
- * \code
- * uint8_t ErrorCode;
- *
- * if ((ErrorCode = Endpoint_Null_Stream(512, NULL)) != ENDPOINT_RWSTREAM_NoError)
- * {
- * // Stream failed to complete - check ErrorCode here
- * }
- * \endcode
- *
- * <b>Partial Stream Transfers Example:</b>
- * \code
- * uint8_t ErrorCode;
- * uint16_t BytesProcessed;
- *
- * BytesProcessed = 0;
- * while ((ErrorCode = Endpoint_Null_Stream(512, &BytesProcessed)) == ENDPOINT_RWSTREAM_IncompleteTransfer)
- * {
- * // Stream not yet complete - do other actions here, abort if required
- * }
- *
- * if (ErrorCode != ENDPOINT_RWSTREAM_NoError)
- * {
- * // Stream failed to complete - check ErrorCode here
- * }
- * \endcode
- *
- * \note This routine should not be used on CONTROL type endpoints.
- *
- * \param[in] Length Number of zero bytes to send via the currently selected endpoint.
- * \param[in] BytesProcessed Pointer to a location where the total number of bytes processed in the current
- * transaction should be updated, \c NULL if the entire stream should be read at once.
- *
- * \return A value from the \ref Endpoint_Stream_RW_ErrorCodes_t enum.
- */
- uint8_t Endpoint_Null_Stream(uint16_t Length,
- uint16_t* const BytesProcessed);
-
- //@}
-
- /** \name Stream functions for RAM source/destination data */
- //@{
-
- /** Writes the given number of bytes to the endpoint from the given buffer in little endian,
- * sending full packets to the host 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
- * \ref Endpoint_ClearIN() macro.
- *
- * If the BytesProcessed parameter is \c NULL, the entire stream transfer is attempted at once,
- * failing or succeeding as a single unit. If the BytesProcessed parameter points to a valid
- * storage location, the transfer will instead be performed as a series of chunks. Each time
- * the endpoint bank becomes full while there is still data to process (and after the current
- * packet transmission has been initiated) the BytesProcessed location will be updated with the
- * total number of bytes processed in the stream, and the function will exit with an error code of
- * \ref ENDPOINT_RWSTREAM_IncompleteTransfer. This allows for any abort checking to be performed
- * in the user code - to continue the transfer, call the function again with identical parameters
- * and it will resume until the BytesProcessed value reaches the total transfer length.
- *
- * <b>Single Stream Transfer Example:</b>
- * \code
- * uint8_t DataStream[512];
- * uint8_t ErrorCode;
- *
- * if ((ErrorCode = Endpoint_Write_Stream_LE(DataStream, sizeof(DataStream),
- * NULL)) != ENDPOINT_RWSTREAM_NoError)
- * {
- * // Stream failed to complete - check ErrorCode here
- * }
- * \endcode
- *
- * <b>Partial Stream Transfers Example:</b>
- * \code
- * uint8_t DataStream[512];
- * uint8_t ErrorCode;
- * uint16_t BytesProcessed;
- *
- * BytesProcessed = 0;
- * while ((ErrorCode = Endpoint_Write_Stream_LE(DataStream, sizeof(DataStream),
- * &BytesProcessed)) == ENDPOINT_RWSTREAM_IncompleteTransfer)
- * {
- * // Stream not yet complete - do other actions here, abort if required
- * }
- *
- * if (ErrorCode != ENDPOINT_RWSTREAM_NoError)
- * {
- * // Stream failed to complete - check ErrorCode here
- * }
- * \endcode
- *
- * \note This routine should not be used on CONTROL type endpoints.
- *
- * \param[in] Buffer Pointer to the source data buffer to read from.
- * \param[in] Length Number of bytes to read for the currently selected endpoint into the buffer.
- * \param[in] BytesProcessed Pointer to a location where the total number of bytes processed in the current
- * transaction should be updated, \c NULL if the entire stream should be written at once.
- *
- * \return A value from the \ref Endpoint_Stream_RW_ErrorCodes_t enum.
- */
- uint8_t Endpoint_Write_Stream_LE(const void* const Buffer,
- uint16_t Length,
- uint16_t* const BytesProcessed) ATTR_NON_NULL_PTR_ARG(1);
-
- /** Writes the given number of bytes to the endpoint from the given buffer in big endian,
- * sending full packets to the host 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
- * \ref Endpoint_ClearIN() macro.
- *
- * \note This routine should not be used on CONTROL type endpoints.
- *
- * \param[in] Buffer Pointer to the source data buffer to read from.
- * \param[in] Length Number of bytes to read for the currently selected endpoint into the buffer.
- * \param[in] BytesProcessed Pointer to a location where the total number of bytes processed in the current
- * transaction should be updated, \c NULL if the entire stream should be written at once.
- *
- * \return A value from the \ref Endpoint_Stream_RW_ErrorCodes_t enum.
- */
- uint8_t Endpoint_Write_Stream_BE(const void* const Buffer,
- uint16_t Length,
- uint16_t* const BytesProcessed) ATTR_NON_NULL_PTR_ARG(1);
-
- /** Reads the given number of bytes from the endpoint from the given buffer in little endian,
- * 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 \ref Endpoint_ClearOUT() macro.
- *
- * If the BytesProcessed parameter is \c NULL, the entire stream transfer is attempted at once,
- * failing or succeeding as a single unit. If the BytesProcessed parameter points to a valid
- * storage location, the transfer will instead be performed as a series of chunks. Each time
- * the endpoint bank becomes empty while there is still data to process (and after the current
- * packet has been acknowledged) the BytesProcessed location will be updated with the total number
- * of bytes processed in the stream, and the function will exit with an error code of
- * \ref ENDPOINT_RWSTREAM_IncompleteTransfer. This allows for any abort checking to be performed
- * in the user code - to continue the transfer, call the function again with identical parameters
- * and it will resume until the BytesProcessed value reaches the total transfer length.
- *
- * <b>Single Stream Transfer Example:</b>
- * \code
- * uint8_t DataStream[512];
- * uint8_t ErrorCode;
- *
- * if ((ErrorCode = Endpoint_Read_Stream_LE(DataStream, sizeof(DataStream),
- * NULL)) != ENDPOINT_RWSTREAM_NoError)
- * {
- * // Stream failed to complete - check ErrorCode here
- * }
- * \endcode
- *
- * <b>Partial Stream Transfers Example:</b>
- * \code
- * uint8_t DataStream[512];
- * uint8_t ErrorCode;
- * uint16_t BytesProcessed;
- *
- * BytesProcessed = 0;
- * while ((ErrorCode = Endpoint_Read_Stream_LE(DataStream, sizeof(DataStream),
- * &BytesProcessed)) == ENDPOINT_RWSTREAM_IncompleteTransfer)
- * {
- * // Stream not yet complete - do other actions here, abort if required
- * }
- *
- * if (ErrorCode != ENDPOINT_RWSTREAM_NoError)
- * {
- * // Stream failed to complete - check ErrorCode here
- * }
- * \endcode
- *
- * \note This routine should not be used on CONTROL type endpoints.
- *
- * \param[out] Buffer Pointer to the destination data buffer to write to.
- * \param[in] Length Number of bytes to send via the currently selected endpoint.
- * \param[in] BytesProcessed Pointer to a location where the total number of bytes processed in the current
- * transaction should be updated, \c NULL if the entire stream should be read at once.
- *
- * \return A value from the \ref Endpoint_Stream_RW_ErrorCodes_t enum.
- */
- uint8_t Endpoint_Read_Stream_LE(void* const Buffer,
- uint16_t Length,
- uint16_t* const BytesProcessed) ATTR_NON_NULL_PTR_ARG(1);
-
- /** Reads the given number of bytes from the endpoint from the given buffer in big endian,
- * 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 \ref Endpoint_ClearOUT() macro.
- *
- * \note This routine should not be used on CONTROL type endpoints.
- *
- * \param[out] Buffer Pointer to the destination data buffer to write to.
- * \param[in] Length Number of bytes to send via the currently selected endpoint.
- * \param[in] BytesProcessed Pointer to a location where the total number of bytes processed in the current
- * transaction should be updated, \c NULL if the entire stream should be read at once.
- *
- * \return A value from the \ref Endpoint_Stream_RW_ErrorCodes_t enum.
- */
- uint8_t Endpoint_Read_Stream_BE(void* const Buffer,
- uint16_t Length,
- uint16_t* const BytesProcessed) ATTR_NON_NULL_PTR_ARG(1);
-
- /** Writes the given number of bytes to the CONTROL type endpoint from the given buffer in little endian,
- * sending full packets to the host as needed. The host OUT acknowledgement is not automatically cleared
- * in both failure and success states; the user is responsible for manually clearing the setup OUT to
- * finalize the transfer via the \ref Endpoint_ClearOUT() macro.
- *
- * \note This function automatically clears the control transfer's status stage. Do not manually attempt
- * to clear the status stage when using this routine in a control transaction.
- * \n\n
- *
- * \note This routine should only be used on CONTROL type endpoints.
- *
- * \warning Unlike the standard stream read/write commands, the control stream commands cannot be chained
- * together; i.e. the entire stream data must be read or written at the one time.
- *
- * \param[in] Buffer Pointer to the source data buffer to read from.
- * \param[in] Length Number of bytes to read for the currently selected endpoint into the buffer.
- *
- * \return A value from the \ref Endpoint_ControlStream_RW_ErrorCodes_t enum.
- */
- uint8_t Endpoint_Write_Control_Stream_LE(const void* const Buffer,
- uint16_t Length) ATTR_NON_NULL_PTR_ARG(1);
-
- /** Writes the given number of bytes to the CONTROL type endpoint from the given buffer in big endian,
- * sending full packets to the host as needed. The host OUT acknowledgement is not automatically cleared
- * in both failure and success states; the user is responsible for manually clearing the setup OUT to
- * finalize the transfer via the \ref Endpoint_ClearOUT() macro.
- *
- * \note This function automatically clears the control transfer's status stage. Do not manually attempt
- * to clear the status stage when using this routine in a control transaction.
- * \n\n
- *
- * \note This routine should only be used on CONTROL type endpoints.
- *
- * \warning Unlike the standard stream read/write commands, the control stream commands cannot be chained
- * together; i.e. the entire stream data must be read or written at the one time.
- *
- * \param[in] Buffer Pointer to the source data buffer to read from.
- * \param[in] Length Number of bytes to read for the currently selected endpoint into the buffer.
- *
- * \return A value from the \ref Endpoint_ControlStream_RW_ErrorCodes_t enum.
- */
- uint8_t Endpoint_Write_Control_Stream_BE(const void* const Buffer,
- uint16_t Length) ATTR_NON_NULL_PTR_ARG(1);
-
- /** Reads the given number of bytes from the CONTROL endpoint from the given buffer in little endian,
- * discarding fully read packets from the host as needed. The device IN acknowledgement is not
- * automatically sent after success or failure states; the user is responsible for manually sending the
- * setup IN to finalize the transfer via the \ref Endpoint_ClearIN() macro.
- *
- * \note This function automatically clears the control transfer's status stage. Do not manually attempt
- * to clear the status stage when using this routine in a control transaction.
- * \n\n
- *
- * \note This routine should only be used on CONTROL type endpoints.
- *
- * \warning Unlike the standard stream read/write commands, the control stream commands cannot be chained
- * together; i.e. the entire stream data must be read or written at the one time.
- *
- * \param[out] Buffer Pointer to the destination data buffer to write to.
- * \param[in] Length Number of bytes to send via the currently selected endpoint.
- *
- * \return A value from the \ref Endpoint_ControlStream_RW_ErrorCodes_t enum.
- */
- uint8_t Endpoint_Read_Control_Stream_LE(void* const Buffer,
- uint16_t Length) ATTR_NON_NULL_PTR_ARG(1);
-
- /** Reads the given number of bytes from the CONTROL endpoint from the given buffer in big endian,
- * discarding fully read packets from the host as needed. The device IN acknowledgement is not
- * automatically sent after success or failure states; the user is responsible for manually sending the
- * setup IN to finalize the transfer via the \ref Endpoint_ClearIN() macro.
- *
- * \note This function automatically clears the control transfer's status stage. Do not manually attempt
- * to clear the status stage when using this routine in a control transaction.
- * \n\n
- *
- * \note This routine should only be used on CONTROL type endpoints.
- *
- * \warning Unlike the standard stream read/write commands, the control stream commands cannot be chained
- * together; i.e. the entire stream data must be read or written at the one time.
- *
- * \param[out] Buffer Pointer to the destination data buffer to write to.
- * \param[in] Length Number of bytes to send via the currently selected endpoint.
- *
- * \return A value from the \ref Endpoint_ControlStream_RW_ErrorCodes_t enum.
- */
- uint8_t Endpoint_Read_Control_Stream_BE(void* const Buffer,
- uint16_t Length) ATTR_NON_NULL_PTR_ARG(1);
- //@}
-
- /** \name Stream functions for EEPROM source/destination data */
- //@{
-
- /** EEPROM buffer source version of \ref Endpoint_Write_Stream_LE().
- *
- * \param[in] Buffer Pointer to the source data buffer to read from.
- * \param[in] Length Number of bytes to read for the currently selected endpoint into the buffer.
- * \param[in] BytesProcessed Pointer to a location where the total number of bytes processed in the current
- * transaction should be updated, \c NULL if the entire stream should be written at once.
- *
- * \return A value from the \ref Endpoint_Stream_RW_ErrorCodes_t enum.
- */
- uint8_t Endpoint_Write_EStream_LE(const void* const Buffer,
- uint16_t Length,
- uint16_t* const BytesProcessed) ATTR_NON_NULL_PTR_ARG(1);
-
- /** EEPROM buffer source version of \ref Endpoint_Write_Stream_BE().
- *
- * \param[in] Buffer Pointer to the source data buffer to read from.
- * \param[in] Length Number of bytes to read for the currently selected endpoint into the buffer.
- * \param[in] BytesProcessed Pointer to a location where the total number of bytes processed in the current
- * transaction should be updated, \c NULL if the entire stream should be written at once.
- *
- * \return A value from the \ref Endpoint_Stream_RW_ErrorCodes_t enum.
- */
- uint8_t Endpoint_Write_EStream_BE(const void* const Buffer,
- uint16_t Length,
- uint16_t* const BytesProcessed) ATTR_NON_NULL_PTR_ARG(1);
-
- /** EEPROM buffer destination version of \ref Endpoint_Read_Stream_LE().
- *
- * \param[out] Buffer Pointer to the destination data buffer to write to, located in EEPROM memory space.
- * \param[in] Length Number of bytes to send via the currently selected endpoint.
- * \param[in] BytesProcessed Pointer to a location where the total number of bytes processed in the current
- * transaction should be updated, \c NULL if the entire stream should be read at once.
- *
- * \return A value from the \ref Endpoint_Stream_RW_ErrorCodes_t enum.
- */
- uint8_t Endpoint_Read_EStream_LE(void* const Buffer,
- uint16_t Length,
- uint16_t* const BytesProcessed) ATTR_NON_NULL_PTR_ARG(1);
-
- /** EEPROM buffer destination version of \ref Endpoint_Read_Stream_BE().
- *
- * \param[out] Buffer Pointer to the destination data buffer to write to, located in EEPROM memory space.
- * \param[in] Length Number of bytes to send via the currently selected endpoint.
- * \param[in] BytesProcessed Pointer to a location where the total number of bytes processed in the current
- * transaction should be updated, \c NULL if the entire stream should be read at once.
- *
- * \return A value from the \ref Endpoint_Stream_RW_ErrorCodes_t enum.
- */
- uint8_t Endpoint_Read_EStream_BE(void* const Buffer,
- uint16_t Length,
- uint16_t* const BytesProcessed) ATTR_NON_NULL_PTR_ARG(1);
-
- /** EEPROM buffer source version of Endpoint_Write_Control_Stream_LE.
- *
- * \note This function automatically clears the control transfer's status stage. Do not manually attempt
- * to clear the status stage when using this routine in a control transaction.
- * \n\n
- *
- * \note This routine should only be used on CONTROL type endpoints.
- * \n\n
- *
- * \warning Unlike the standard stream read/write commands, the control stream commands cannot be chained
- * together; i.e. the entire stream data must be read or written at the one time.
- *
- * \param[in] Buffer Pointer to the source data buffer to read from.
- * \param[in] Length Number of bytes to read for the currently selected endpoint into the buffer.
- *
- * \return A value from the \ref Endpoint_ControlStream_RW_ErrorCodes_t enum.
- */
- uint8_t Endpoint_Write_Control_EStream_LE(const void* const Buffer,
- uint16_t Length) ATTR_NON_NULL_PTR_ARG(1);
-
- /** EEPROM buffer source version of \ref Endpoint_Write_Control_Stream_BE().
- *
- * \note This function automatically clears the control transfer's status stage. Do not manually attempt
- * to clear the status stage when using this routine in a control transaction.
- * \n\n
- *
- * \note This routine should only be used on CONTROL type endpoints.
- * \n\n
- *
- * \warning Unlike the standard stream read/write commands, the control stream commands cannot be chained
- * together; i.e. the entire stream data must be read or written at the one time.
- *
- * \param[in] Buffer Pointer to the source data buffer to read from.
- * \param[in] Length Number of bytes to read for the currently selected endpoint into the buffer.
- *
- * \return A value from the \ref Endpoint_ControlStream_RW_ErrorCodes_t enum.
- */
- uint8_t Endpoint_Write_Control_EStream_BE(const void* const Buffer,
- uint16_t Length) ATTR_NON_NULL_PTR_ARG(1);
-
- /** EEPROM buffer source version of \ref Endpoint_Read_Control_Stream_LE().
- *
- * \note This function automatically clears the control transfer's status stage. Do not manually attempt
- * to clear the status stage when using this routine in a control transaction.
- * \n\n
- *
- * \note This routine should only be used on CONTROL type endpoints.
- * \n\n
- *
- * \warning Unlike the standard stream read/write commands, the control stream commands cannot be chained
- * together; i.e. the entire stream data must be read or written at the one time.
- *
- * \param[out] Buffer Pointer to the destination data buffer to write to.
- * \param[in] Length Number of bytes to send via the currently selected endpoint.
- *
- * \return A value from the \ref Endpoint_ControlStream_RW_ErrorCodes_t enum.
- */
- uint8_t Endpoint_Read_Control_EStream_LE(void* const Buffer,
- uint16_t Length) ATTR_NON_NULL_PTR_ARG(1);
-
- /** EEPROM buffer source version of \ref Endpoint_Read_Control_Stream_BE().
- *
- * \note This function automatically clears the control transfer's status stage. Do not manually attempt
- * to clear the status stage when using this routine in a control transaction.
- * \n\n
- *
- * \note This routine should only be used on CONTROL type endpoints.
- * \n\n
- *
- * \warning Unlike the standard stream read/write commands, the control stream commands cannot be chained
- * together; i.e. the entire stream data must be read or written at the one time.
- *
- * \param[out] Buffer Pointer to the destination data buffer to write to.
- * \param[in] Length Number of bytes to send via the currently selected endpoint.
- *
- * \return A value from the \ref Endpoint_ControlStream_RW_ErrorCodes_t enum.
- */
- uint8_t Endpoint_Read_Control_EStream_BE(void* const Buffer,
- uint16_t Length) ATTR_NON_NULL_PTR_ARG(1);
- //@}
-
- /** \name Stream functions for PROGMEM source/destination data */
- //@{
-
- /** FLASH buffer source version of \ref Endpoint_Write_Stream_LE().
- *
- * \pre The FLASH data must be located in the first 64KB of FLASH for this function to work correctly.
- *
- * \param[in] Buffer Pointer to the source data buffer to read from.
- * \param[in] Length Number of bytes to read for the currently selected endpoint into the buffer.
- * \param[in] BytesProcessed Pointer to a location where the total number of bytes processed in the current
- * transaction should be updated, \c NULL if the entire stream should be written at once.
- *
- * \return A value from the \ref Endpoint_Stream_RW_ErrorCodes_t enum.
- */
- uint8_t Endpoint_Write_PStream_LE(const void* const Buffer,
- uint16_t Length,
- uint16_t* const BytesProcessed) ATTR_NON_NULL_PTR_ARG(1);
-
- /** FLASH buffer source version of \ref Endpoint_Write_Stream_BE().
- *
- * \pre The FLASH data must be located in the first 64KB of FLASH for this function to work correctly.
- *
- * \param[in] Buffer Pointer to the source data buffer to read from.
- * \param[in] Length Number of bytes to read for the currently selected endpoint into the buffer.
- * \param[in] BytesProcessed Pointer to a location where the total number of bytes processed in the current
- * transaction should be updated, \c NULL if the entire stream should be written at once.
- *
- * \return A value from the \ref Endpoint_Stream_RW_ErrorCodes_t enum.
- */
- uint8_t Endpoint_Write_PStream_BE(const void* const Buffer,
- uint16_t Length,
- uint16_t* const BytesProcessed) ATTR_NON_NULL_PTR_ARG(1);
-
- /** FLASH buffer source version of \ref Endpoint_Write_Control_Stream_LE().
- *
- * \pre The FLASH data must be located in the first 64KB of FLASH for this function to work correctly.
- *
- * \note This function automatically clears the control transfer's status stage. Do not manually attempt
- * to clear the status stage when using this routine in a control transaction.
- * \n\n
- *
- * \note This routine should only be used on CONTROL type endpoints.
- * \n\n
- *
- * \warning Unlike the standard stream read/write commands, the control stream commands cannot be chained
- * together; i.e. the entire stream data must be read or written at the one time.
- *
- * \param[in] Buffer Pointer to the source data buffer to read from.
- * \param[in] Length Number of bytes to read for the currently selected endpoint into the buffer.
- *
- * \return A value from the \ref Endpoint_ControlStream_RW_ErrorCodes_t enum.
- */
- uint8_t Endpoint_Write_Control_PStream_LE(const void* const Buffer,
- uint16_t Length) ATTR_NON_NULL_PTR_ARG(1);
-
- /** FLASH buffer source version of \ref Endpoint_Write_Control_Stream_BE().
- *
- * \pre The FLASH data must be located in the first 64KB of FLASH for this function to work correctly.
- *
- * \note This function automatically clears the control transfer's status stage. Do not manually attempt
- * to clear the status stage when using this routine in a control transaction.
- * \n\n
- *
- * \note This routine should only be used on CONTROL type endpoints.
- * \n\n
- *
- * \warning Unlike the standard stream read/write commands, the control stream commands cannot be chained
- * together; i.e. the entire stream data must be read or written at the one time.
- *
- * \param[in] Buffer Pointer to the source data buffer to read from.
- * \param[in] Length Number of bytes to read for the currently selected endpoint into the buffer.
- *
- * \return A value from the \ref Endpoint_ControlStream_RW_ErrorCodes_t enum.
- */
- uint8_t Endpoint_Write_Control_PStream_BE(const void* const Buffer,
- uint16_t Length) ATTR_NON_NULL_PTR_ARG(1);
- //@}
-
- /* Disable C linkage for C++ Compilers: */
- #if defined(__cplusplus)
- }
- #endif
-
-#endif
-
-/** @} */
+/* + LUFA Library + Copyright (C) Dean Camera, 2012. + + dean [at] fourwalledcubicle [dot] com + www.lufa-lib.org +*/ + +/* + Copyright 2012 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 + software, including all implied warranties of merchantability + and fitness. In no event shall the author be liable for any + special, indirect or consequential damages or any damages + whatsoever resulting from loss of use, data or profits, whether + in an action of contract, negligence or other tortious action, + arising out of or in connection with the use or performance of + this software. +*/ + +/** \file + * \brief Endpoint data stream transmission and reception management for the AVR XMEGA microcontrollers. + * \copydetails Group_EndpointStreamRW_XMEGA + * + * \note This file should not be included directly. It is automatically included as needed by the USB driver + * dispatch header located in LUFA/Drivers/USB/USB.h. + */ + +/** \ingroup Group_EndpointStreamRW + * \defgroup Group_EndpointStreamRW_XMEGA Read/Write of Multi-Byte Streams (XMEGA) + * \brief Endpoint data stream transmission and reception management for the Atmel AVR XMEGA architecture. + * + * Functions, macros, variables, enums and types related to data reading and writing of data streams from + * and to endpoints. + * + * @{ + */ + +#ifndef __ENDPOINT_STREAM_XMEGA_H__ +#define __ENDPOINT_STREAM_XMEGA_H__ + + /* Includes: */ + #include "../../../../Common/Common.h" + #include "../USBMode.h" + #include "../USBTask.h" + + /* Enable C linkage for C++ Compilers: */ + #if defined(__cplusplus) + extern "C" { + #endif + + /* Preprocessor Checks: */ + #if !defined(__INCLUDE_FROM_USB_DRIVER) + #error Do not include this file directly. Include LUFA/Drivers/USB/USB.h instead. + #endif + + /* Public Interface - May be used in end-application: */ + /* Function Prototypes: */ + /** \name Stream functions for null data */ + //@{ + + /** Reads and discards the given number of bytes from the currently selected endpoint's bank, + * 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 \ref Endpoint_ClearOUT() macro. + * + * If the BytesProcessed parameter is \c NULL, the entire stream transfer is attempted at once, + * failing or succeeding as a single unit. If the BytesProcessed parameter points to a valid + * storage location, the transfer will instead be performed as a series of chunks. Each time + * the endpoint bank becomes empty while there is still data to process (and after the current + * packet has been acknowledged) the BytesProcessed location will be updated with the total number + * of bytes processed in the stream, and the function will exit with an error code of + * \ref ENDPOINT_RWSTREAM_IncompleteTransfer. This allows for any abort checking to be performed + * in the user code - to continue the transfer, call the function again with identical parameters + * and it will resume until the BytesProcessed value reaches the total transfer length. + * + * <b>Single Stream Transfer Example:</b> + * \code + * uint8_t ErrorCode; + * + * if ((ErrorCode = Endpoint_Discard_Stream(512, NULL)) != ENDPOINT_RWSTREAM_NoError) + * { + * // Stream failed to complete - check ErrorCode here + * } + * \endcode + * + * <b>Partial Stream Transfers Example:</b> + * \code + * uint8_t ErrorCode; + * uint16_t BytesProcessed; + * + * BytesProcessed = 0; + * while ((ErrorCode = Endpoint_Discard_Stream(512, &BytesProcessed)) == ENDPOINT_RWSTREAM_IncompleteTransfer) + * { + * // Stream not yet complete - do other actions here, abort if required + * } + * + * if (ErrorCode != ENDPOINT_RWSTREAM_NoError) + * { + * // Stream failed to complete - check ErrorCode here + * } + * \endcode + * + * \note This routine should not be used on CONTROL type endpoints. + * + * \param[in] Length Number of bytes to discard via the currently selected endpoint. + * \param[in] BytesProcessed Pointer to a location where the total number of bytes processed in the current + * transaction should be updated, \c NULL if the entire stream should be read at once. + * + * \return A value from the \ref Endpoint_Stream_RW_ErrorCodes_t enum. + */ + uint8_t Endpoint_Discard_Stream(uint16_t Length, + uint16_t* const BytesProcessed); + + /** Writes a given number of zeroed bytes to the currently selected endpoint's bank, sending + * full packets to the host as needed. The last packet is not automatically sent once the + * remaining bytes have been written; the user is responsible for manually sending the last + * packet to the host via the \ref Endpoint_ClearIN() macro. + * + * If the BytesProcessed parameter is \c NULL, the entire stream transfer is attempted at once, + * failing or succeeding as a single unit. If the BytesProcessed parameter points to a valid + * storage location, the transfer will instead be performed as a series of chunks. Each time + * the endpoint bank becomes full while there is still data to process (and after the current + * packet transmission has been initiated) the BytesProcessed location will be updated with the + * total number of bytes processed in the stream, and the function will exit with an error code of + * \ref ENDPOINT_RWSTREAM_IncompleteTransfer. This allows for any abort checking to be performed + * in the user code - to continue the transfer, call the function again with identical parameters + * and it will resume until the BytesProcessed value reaches the total transfer length. + * + * <b>Single Stream Transfer Example:</b> + * \code + * uint8_t ErrorCode; + * + * if ((ErrorCode = Endpoint_Null_Stream(512, NULL)) != ENDPOINT_RWSTREAM_NoError) + * { + * // Stream failed to complete - check ErrorCode here + * } + * \endcode + * + * <b>Partial Stream Transfers Example:</b> + * \code + * uint8_t ErrorCode; + * uint16_t BytesProcessed; + * + * BytesProcessed = 0; + * while ((ErrorCode = Endpoint_Null_Stream(512, &BytesProcessed)) == ENDPOINT_RWSTREAM_IncompleteTransfer) + * { + * // Stream not yet complete - do other actions here, abort if required + * } + * + * if (ErrorCode != ENDPOINT_RWSTREAM_NoError) + * { + * // Stream failed to complete - check ErrorCode here + * } + * \endcode + * + * \note This routine should not be used on CONTROL type endpoints. + * + * \param[in] Length Number of zero bytes to send via the currently selected endpoint. + * \param[in] BytesProcessed Pointer to a location where the total number of bytes processed in the current + * transaction should be updated, \c NULL if the entire stream should be read at once. + * + * \return A value from the \ref Endpoint_Stream_RW_ErrorCodes_t enum. + */ + uint8_t Endpoint_Null_Stream(uint16_t Length, + uint16_t* const BytesProcessed); + + //@} + + /** \name Stream functions for RAM source/destination data */ + //@{ + + /** Writes the given number of bytes to the endpoint from the given buffer in little endian, + * sending full packets to the host 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 + * \ref Endpoint_ClearIN() macro. + * + * If the BytesProcessed parameter is \c NULL, the entire stream transfer is attempted at once, + * failing or succeeding as a single unit. If the BytesProcessed parameter points to a valid + * storage location, the transfer will instead be performed as a series of chunks. Each time + * the endpoint bank becomes full while there is still data to process (and after the current + * packet transmission has been initiated) the BytesProcessed location will be updated with the + * total number of bytes processed in the stream, and the function will exit with an error code of + * \ref ENDPOINT_RWSTREAM_IncompleteTransfer. This allows for any abort checking to be performed + * in the user code - to continue the transfer, call the function again with identical parameters + * and it will resume until the BytesProcessed value reaches the total transfer length. + * + * <b>Single Stream Transfer Example:</b> + * \code + * uint8_t DataStream[512]; + * uint8_t ErrorCode; + * + * if ((ErrorCode = Endpoint_Write_Stream_LE(DataStream, sizeof(DataStream), + * NULL)) != ENDPOINT_RWSTREAM_NoError) + * { + * // Stream failed to complete - check ErrorCode here + * } + * \endcode + * + * <b>Partial Stream Transfers Example:</b> + * \code + * uint8_t DataStream[512]; + * uint8_t ErrorCode; + * uint16_t BytesProcessed; + * + * BytesProcessed = 0; + * while ((ErrorCode = Endpoint_Write_Stream_LE(DataStream, sizeof(DataStream), + * &BytesProcessed)) == ENDPOINT_RWSTREAM_IncompleteTransfer) + * { + * // Stream not yet complete - do other actions here, abort if required + * } + * + * if (ErrorCode != ENDPOINT_RWSTREAM_NoError) + * { + * // Stream failed to complete - check ErrorCode here + * } + * \endcode + * + * \note This routine should not be used on CONTROL type endpoints. + * + * \param[in] Buffer Pointer to the source data buffer to read from. + * \param[in] Length Number of bytes to read for the currently selected endpoint into the buffer. + * \param[in] BytesProcessed Pointer to a location where the total number of bytes processed in the current + * transaction should be updated, \c NULL if the entire stream should be written at once. + * + * \return A value from the \ref Endpoint_Stream_RW_ErrorCodes_t enum. + */ + uint8_t Endpoint_Write_Stream_LE(const void* const Buffer, + uint16_t Length, + uint16_t* const BytesProcessed) ATTR_NON_NULL_PTR_ARG(1); + + /** Writes the given number of bytes to the endpoint from the given buffer in big endian, + * sending full packets to the host 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 + * \ref Endpoint_ClearIN() macro. + * + * \note This routine should not be used on CONTROL type endpoints. + * + * \param[in] Buffer Pointer to the source data buffer to read from. + * \param[in] Length Number of bytes to read for the currently selected endpoint into the buffer. + * \param[in] BytesProcessed Pointer to a location where the total number of bytes processed in the current + * transaction should be updated, \c NULL if the entire stream should be written at once. + * + * \return A value from the \ref Endpoint_Stream_RW_ErrorCodes_t enum. + */ + uint8_t Endpoint_Write_Stream_BE(const void* const Buffer, + uint16_t Length, + uint16_t* const BytesProcessed) ATTR_NON_NULL_PTR_ARG(1); + + /** Reads the given number of bytes from the endpoint from the given buffer in little endian, + * 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 \ref Endpoint_ClearOUT() macro. + * + * If the BytesProcessed parameter is \c NULL, the entire stream transfer is attempted at once, + * failing or succeeding as a single unit. If the BytesProcessed parameter points to a valid + * storage location, the transfer will instead be performed as a series of chunks. Each time + * the endpoint bank becomes empty while there is still data to process (and after the current + * packet has been acknowledged) the BytesProcessed location will be updated with the total number + * of bytes processed in the stream, and the function will exit with an error code of + * \ref ENDPOINT_RWSTREAM_IncompleteTransfer. This allows for any abort checking to be performed + * in the user code - to continue the transfer, call the function again with identical parameters + * and it will resume until the BytesProcessed value reaches the total transfer length. + * + * <b>Single Stream Transfer Example:</b> + * \code + * uint8_t DataStream[512]; + * uint8_t ErrorCode; + * + * if ((ErrorCode = Endpoint_Read_Stream_LE(DataStream, sizeof(DataStream), + * NULL)) != ENDPOINT_RWSTREAM_NoError) + * { + * // Stream failed to complete - check ErrorCode here + * } + * \endcode + * + * <b>Partial Stream Transfers Example:</b> + * \code + * uint8_t DataStream[512]; + * uint8_t ErrorCode; + * uint16_t BytesProcessed; + * + * BytesProcessed = 0; + * while ((ErrorCode = Endpoint_Read_Stream_LE(DataStream, sizeof(DataStream), + * &BytesProcessed)) == ENDPOINT_RWSTREAM_IncompleteTransfer) + * { + * // Stream not yet complete - do other actions here, abort if required + * } + * + * if (ErrorCode != ENDPOINT_RWSTREAM_NoError) + * { + * // Stream failed to complete - check ErrorCode here + * } + * \endcode + * + * \note This routine should not be used on CONTROL type endpoints. + * + * \param[out] Buffer Pointer to the destination data buffer to write to. + * \param[in] Length Number of bytes to send via the currently selected endpoint. + * \param[in] BytesProcessed Pointer to a location where the total number of bytes processed in the current + * transaction should be updated, \c NULL if the entire stream should be read at once. + * + * \return A value from the \ref Endpoint_Stream_RW_ErrorCodes_t enum. + */ + uint8_t Endpoint_Read_Stream_LE(void* const Buffer, + uint16_t Length, + uint16_t* const BytesProcessed) ATTR_NON_NULL_PTR_ARG(1); + + /** Reads the given number of bytes from the endpoint from the given buffer in big endian, + * 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 \ref Endpoint_ClearOUT() macro. + * + * \note This routine should not be used on CONTROL type endpoints. + * + * \param[out] Buffer Pointer to the destination data buffer to write to. + * \param[in] Length Number of bytes to send via the currently selected endpoint. + * \param[in] BytesProcessed Pointer to a location where the total number of bytes processed in the current + * transaction should be updated, \c NULL if the entire stream should be read at once. + * + * \return A value from the \ref Endpoint_Stream_RW_ErrorCodes_t enum. + */ + uint8_t Endpoint_Read_Stream_BE(void* const Buffer, + uint16_t Length, + uint16_t* const BytesProcessed) ATTR_NON_NULL_PTR_ARG(1); + + /** Writes the given number of bytes to the CONTROL type endpoint from the given buffer in little endian, + * sending full packets to the host as needed. The host OUT acknowledgement is not automatically cleared + * in both failure and success states; the user is responsible for manually clearing the setup OUT to + * finalize the transfer via the \ref Endpoint_ClearOUT() macro. + * + * \note This function automatically clears the control transfer's status stage. Do not manually attempt + * to clear the status stage when using this routine in a control transaction. + * \n\n + * + * \note This routine should only be used on CONTROL type endpoints. + * + * \warning Unlike the standard stream read/write commands, the control stream commands cannot be chained + * together; i.e. the entire stream data must be read or written at the one time. + * + * \param[in] Buffer Pointer to the source data buffer to read from. + * \param[in] Length Number of bytes to read for the currently selected endpoint into the buffer. + * + * \return A value from the \ref Endpoint_ControlStream_RW_ErrorCodes_t enum. + */ + uint8_t Endpoint_Write_Control_Stream_LE(const void* const Buffer, + uint16_t Length) ATTR_NON_NULL_PTR_ARG(1); + + /** Writes the given number of bytes to the CONTROL type endpoint from the given buffer in big endian, + * sending full packets to the host as needed. The host OUT acknowledgement is not automatically cleared + * in both failure and success states; the user is responsible for manually clearing the setup OUT to + * finalize the transfer via the \ref Endpoint_ClearOUT() macro. + * + * \note This function automatically clears the control transfer's status stage. Do not manually attempt + * to clear the status stage when using this routine in a control transaction. + * \n\n + * + * \note This routine should only be used on CONTROL type endpoints. + * + * \warning Unlike the standard stream read/write commands, the control stream commands cannot be chained + * together; i.e. the entire stream data must be read or written at the one time. + * + * \param[in] Buffer Pointer to the source data buffer to read from. + * \param[in] Length Number of bytes to read for the currently selected endpoint into the buffer. + * + * \return A value from the \ref Endpoint_ControlStream_RW_ErrorCodes_t enum. + */ + uint8_t Endpoint_Write_Control_Stream_BE(const void* const Buffer, + uint16_t Length) ATTR_NON_NULL_PTR_ARG(1); + + /** Reads the given number of bytes from the CONTROL endpoint from the given buffer in little endian, + * discarding fully read packets from the host as needed. The device IN acknowledgement is not + * automatically sent after success or failure states; the user is responsible for manually sending the + * setup IN to finalize the transfer via the \ref Endpoint_ClearIN() macro. + * + * \note This function automatically clears the control transfer's status stage. Do not manually attempt + * to clear the status stage when using this routine in a control transaction. + * \n\n + * + * \note This routine should only be used on CONTROL type endpoints. + * + * \warning Unlike the standard stream read/write commands, the control stream commands cannot be chained + * together; i.e. the entire stream data must be read or written at the one time. + * + * \param[out] Buffer Pointer to the destination data buffer to write to. + * \param[in] Length Number of bytes to send via the currently selected endpoint. + * + * \return A value from the \ref Endpoint_ControlStream_RW_ErrorCodes_t enum. + */ + uint8_t Endpoint_Read_Control_Stream_LE(void* const Buffer, + uint16_t Length) ATTR_NON_NULL_PTR_ARG(1); + + /** Reads the given number of bytes from the CONTROL endpoint from the given buffer in big endian, + * discarding fully read packets from the host as needed. The device IN acknowledgement is not + * automatically sent after success or failure states; the user is responsible for manually sending the + * setup IN to finalize the transfer via the \ref Endpoint_ClearIN() macro. + * + * \note This function automatically clears the control transfer's status stage. Do not manually attempt + * to clear the status stage when using this routine in a control transaction. + * \n\n + * + * \note This routine should only be used on CONTROL type endpoints. + * + * \warning Unlike the standard stream read/write commands, the control stream commands cannot be chained + * together; i.e. the entire stream data must be read or written at the one time. + * + * \param[out] Buffer Pointer to the destination data buffer to write to. + * \param[in] Length Number of bytes to send via the currently selected endpoint. + * + * \return A value from the \ref Endpoint_ControlStream_RW_ErrorCodes_t enum. + */ + uint8_t Endpoint_Read_Control_Stream_BE(void* const Buffer, + uint16_t Length) ATTR_NON_NULL_PTR_ARG(1); + //@} + + /** \name Stream functions for EEPROM source/destination data */ + //@{ + + /** EEPROM buffer source version of \ref Endpoint_Write_Stream_LE(). + * + * \param[in] Buffer Pointer to the source data buffer to read from. + * \param[in] Length Number of bytes to read for the currently selected endpoint into the buffer. + * \param[in] BytesProcessed Pointer to a location where the total number of bytes processed in the current + * transaction should be updated, \c NULL if the entire stream should be written at once. + * + * \return A value from the \ref Endpoint_Stream_RW_ErrorCodes_t enum. + */ + uint8_t Endpoint_Write_EStream_LE(const void* const Buffer, + uint16_t Length, + uint16_t* const BytesProcessed) ATTR_NON_NULL_PTR_ARG(1); + + /** EEPROM buffer source version of \ref Endpoint_Write_Stream_BE(). + * + * \param[in] Buffer Pointer to the source data buffer to read from. + * \param[in] Length Number of bytes to read for the currently selected endpoint into the buffer. + * \param[in] BytesProcessed Pointer to a location where the total number of bytes processed in the current + * transaction should be updated, \c NULL if the entire stream should be written at once. + * + * \return A value from the \ref Endpoint_Stream_RW_ErrorCodes_t enum. + */ + uint8_t Endpoint_Write_EStream_BE(const void* const Buffer, + uint16_t Length, + uint16_t* const BytesProcessed) ATTR_NON_NULL_PTR_ARG(1); + + /** EEPROM buffer destination version of \ref Endpoint_Read_Stream_LE(). + * + * \param[out] Buffer Pointer to the destination data buffer to write to, located in EEPROM memory space. + * \param[in] Length Number of bytes to send via the currently selected endpoint. + * \param[in] BytesProcessed Pointer to a location where the total number of bytes processed in the current + * transaction should be updated, \c NULL if the entire stream should be read at once. + * + * \return A value from the \ref Endpoint_Stream_RW_ErrorCodes_t enum. + */ + uint8_t Endpoint_Read_EStream_LE(void* const Buffer, + uint16_t Length, + uint16_t* const BytesProcessed) ATTR_NON_NULL_PTR_ARG(1); + + /** EEPROM buffer destination version of \ref Endpoint_Read_Stream_BE(). + * + * \param[out] Buffer Pointer to the destination data buffer to write to, located in EEPROM memory space. + * \param[in] Length Number of bytes to send via the currently selected endpoint. + * \param[in] BytesProcessed Pointer to a location where the total number of bytes processed in the current + * transaction should be updated, \c NULL if the entire stream should be read at once. + * + * \return A value from the \ref Endpoint_Stream_RW_ErrorCodes_t enum. + */ + uint8_t Endpoint_Read_EStream_BE(void* const Buffer, + uint16_t Length, + uint16_t* const BytesProcessed) ATTR_NON_NULL_PTR_ARG(1); + + /** EEPROM buffer source version of Endpoint_Write_Control_Stream_LE. + * + * \note This function automatically clears the control transfer's status stage. Do not manually attempt + * to clear the status stage when using this routine in a control transaction. + * \n\n + * + * \note This routine should only be used on CONTROL type endpoints. + * \n\n + * + * \warning Unlike the standard stream read/write commands, the control stream commands cannot be chained + * together; i.e. the entire stream data must be read or written at the one time. + * + * \param[in] Buffer Pointer to the source data buffer to read from. + * \param[in] Length Number of bytes to read for the currently selected endpoint into the buffer. + * + * \return A value from the \ref Endpoint_ControlStream_RW_ErrorCodes_t enum. + */ + uint8_t Endpoint_Write_Control_EStream_LE(const void* const Buffer, + uint16_t Length) ATTR_NON_NULL_PTR_ARG(1); + + /** EEPROM buffer source version of \ref Endpoint_Write_Control_Stream_BE(). + * + * \note This function automatically clears the control transfer's status stage. Do not manually attempt + * to clear the status stage when using this routine in a control transaction. + * \n\n + * + * \note This routine should only be used on CONTROL type endpoints. + * \n\n + * + * \warning Unlike the standard stream read/write commands, the control stream commands cannot be chained + * together; i.e. the entire stream data must be read or written at the one time. + * + * \param[in] Buffer Pointer to the source data buffer to read from. + * \param[in] Length Number of bytes to read for the currently selected endpoint into the buffer. + * + * \return A value from the \ref Endpoint_ControlStream_RW_ErrorCodes_t enum. + */ + uint8_t Endpoint_Write_Control_EStream_BE(const void* const Buffer, + uint16_t Length) ATTR_NON_NULL_PTR_ARG(1); + + /** EEPROM buffer source version of \ref Endpoint_Read_Control_Stream_LE(). + * + * \note This function automatically clears the control transfer's status stage. Do not manually attempt + * to clear the status stage when using this routine in a control transaction. + * \n\n + * + * \note This routine should only be used on CONTROL type endpoints. + * \n\n + * + * \warning Unlike the standard stream read/write commands, the control stream commands cannot be chained + * together; i.e. the entire stream data must be read or written at the one time. + * + * \param[out] Buffer Pointer to the destination data buffer to write to. + * \param[in] Length Number of bytes to send via the currently selected endpoint. + * + * \return A value from the \ref Endpoint_ControlStream_RW_ErrorCodes_t enum. + */ + uint8_t Endpoint_Read_Control_EStream_LE(void* const Buffer, + uint16_t Length) ATTR_NON_NULL_PTR_ARG(1); + + /** EEPROM buffer source version of \ref Endpoint_Read_Control_Stream_BE(). + * + * \note This function automatically clears the control transfer's status stage. Do not manually attempt + * to clear the status stage when using this routine in a control transaction. + * \n\n + * + * \note This routine should only be used on CONTROL type endpoints. + * \n\n + * + * \warning Unlike the standard stream read/write commands, the control stream commands cannot be chained + * together; i.e. the entire stream data must be read or written at the one time. + * + * \param[out] Buffer Pointer to the destination data buffer to write to. + * \param[in] Length Number of bytes to send via the currently selected endpoint. + * + * \return A value from the \ref Endpoint_ControlStream_RW_ErrorCodes_t enum. + */ + uint8_t Endpoint_Read_Control_EStream_BE(void* const Buffer, + uint16_t Length) ATTR_NON_NULL_PTR_ARG(1); + //@} + + /** \name Stream functions for PROGMEM source/destination data */ + //@{ + + /** FLASH buffer source version of \ref Endpoint_Write_Stream_LE(). + * + * \pre The FLASH data must be located in the first 64KB of FLASH for this function to work correctly. + * + * \param[in] Buffer Pointer to the source data buffer to read from. + * \param[in] Length Number of bytes to read for the currently selected endpoint into the buffer. + * \param[in] BytesProcessed Pointer to a location where the total number of bytes processed in the current + * transaction should be updated, \c NULL if the entire stream should be written at once. + * + * \return A value from the \ref Endpoint_Stream_RW_ErrorCodes_t enum. + */ + uint8_t Endpoint_Write_PStream_LE(const void* const Buffer, + uint16_t Length, + uint16_t* const BytesProcessed) ATTR_NON_NULL_PTR_ARG(1); + + /** FLASH buffer source version of \ref Endpoint_Write_Stream_BE(). + * + * \pre The FLASH data must be located in the first 64KB of FLASH for this function to work correctly. + * + * \param[in] Buffer Pointer to the source data buffer to read from. + * \param[in] Length Number of bytes to read for the currently selected endpoint into the buffer. + * \param[in] BytesProcessed Pointer to a location where the total number of bytes processed in the current + * transaction should be updated, \c NULL if the entire stream should be written at once. + * + * \return A value from the \ref Endpoint_Stream_RW_ErrorCodes_t enum. + */ + uint8_t Endpoint_Write_PStream_BE(const void* const Buffer, + uint16_t Length, + uint16_t* const BytesProcessed) ATTR_NON_NULL_PTR_ARG(1); + + /** FLASH buffer source version of \ref Endpoint_Write_Control_Stream_LE(). + * + * \pre The FLASH data must be located in the first 64KB of FLASH for this function to work correctly. + * + * \note This function automatically clears the control transfer's status stage. Do not manually attempt + * to clear the status stage when using this routine in a control transaction. + * \n\n + * + * \note This routine should only be used on CONTROL type endpoints. + * \n\n + * + * \warning Unlike the standard stream read/write commands, the control stream commands cannot be chained + * together; i.e. the entire stream data must be read or written at the one time. + * + * \param[in] Buffer Pointer to the source data buffer to read from. + * \param[in] Length Number of bytes to read for the currently selected endpoint into the buffer. + * + * \return A value from the \ref Endpoint_ControlStream_RW_ErrorCodes_t enum. + */ + uint8_t Endpoint_Write_Control_PStream_LE(const void* const Buffer, + uint16_t Length) ATTR_NON_NULL_PTR_ARG(1); + + /** FLASH buffer source version of \ref Endpoint_Write_Control_Stream_BE(). + * + * \pre The FLASH data must be located in the first 64KB of FLASH for this function to work correctly. + * + * \note This function automatically clears the control transfer's status stage. Do not manually attempt + * to clear the status stage when using this routine in a control transaction. + * \n\n + * + * \note This routine should only be used on CONTROL type endpoints. + * \n\n + * + * \warning Unlike the standard stream read/write commands, the control stream commands cannot be chained + * together; i.e. the entire stream data must be read or written at the one time. + * + * \param[in] Buffer Pointer to the source data buffer to read from. + * \param[in] Length Number of bytes to read for the currently selected endpoint into the buffer. + * + * \return A value from the \ref Endpoint_ControlStream_RW_ErrorCodes_t enum. + */ + uint8_t Endpoint_Write_Control_PStream_BE(const void* const Buffer, + uint16_t Length) ATTR_NON_NULL_PTR_ARG(1); + //@} + + /* Disable C linkage for C++ Compilers: */ + #if defined(__cplusplus) + } + #endif + +#endif + +/** @} */ |