diff options
Diffstat (limited to 'LUFA/Drivers/USB/Core/PipeStream.h')
| -rw-r--r-- | LUFA/Drivers/USB/Core/PipeStream.h | 396 |
1 files changed, 7 insertions, 389 deletions
diff --git a/LUFA/Drivers/USB/Core/PipeStream.h b/LUFA/Drivers/USB/Core/PipeStream.h index c914fc149..91f465257 100644 --- a/LUFA/Drivers/USB/Core/PipeStream.h +++ b/LUFA/Drivers/USB/Core/PipeStream.h @@ -51,8 +51,7 @@ /* Includes: */
#include "../../../Common/Common.h"
- #include "USBMode.h"
- #include "USBTask.h"
+ #include "USBMode.h"
/* Enable C linkage for C++ Compilers: */
#if defined(__cplusplus)
@@ -83,395 +82,14 @@ */
};
- /* 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 */
- //@{
-
- #if defined(ARCH_HAS_EEPROM_ADDRESS_SPACE) || defined(__DOXYGEN__)
- /** EEPROM buffer source version of \ref Pipe_Write_Stream_LE().
- *
- * \note This function is not available on all architectures.
- *
- * \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().
- *
- * \note This function is not available on all architectures.
- *
- * \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().
- *
- * \note This function is not available on all architectures.
- *
- * \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().
- *
- * \note This function is not available on all architectures.
- *
- * \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);
- #endif
- //@}
-
- /** \name Stream functions for PROGMEM source/destination data */
- //@{
-
- #if defined(ARCH_HAS_FLASH_ADDRESS_SPACE) || defined(__DOXYGEN__)
- /** 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.
- *
- * \note This function is not available on all architectures.
- *
- * \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.
- *
- * \note This function is not available on all architectures.
- *
- * \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);
- #endif
- //@}
-
- /* Disable C linkage for C++ Compilers: */
- #if defined(__cplusplus)
- }
+ /* Architecture Includes: */
+ #if (ARCH == ARCH_AVR8)
+ #include "AVR8/PipeStream_AVR8.h"
+ #elif (ARCH == ARCH_UC3)
+ #include "UC3/PipeStream_UC3.h"
#endif
#endif
/** @} */
- +
|