X-Git-Url: http://git.linex4red.de/pub/USBasp.git/blobdiff_plain/508e905d8d39c3968927aa2c1a45350f49452df1..1621158c622e8dbe49deaacf88ea3f5b843b54ac:/LUFA/Drivers/USB/LowLevel/Pipe.h diff --git a/LUFA/Drivers/USB/LowLevel/Pipe.h b/LUFA/Drivers/USB/LowLevel/Pipe.h index 868a93ade..835ca8bd8 100644 --- a/LUFA/Drivers/USB/LowLevel/Pipe.h +++ b/LUFA/Drivers/USB/LowLevel/Pipe.h @@ -38,17 +38,8 @@ * dispatch header located in LUFA/Drivers/USB/USB.h. */ -/** \ingroup Group_USB - * @defgroup Group_PipeManagement Pipe Management - * - * This module contains functions, macros and enums related to pipe management when in USB Host mode. This - * module contains the pipe management macros, as well as pipe interrupt and data send/receive functions - * for various data types. - * - * @{ - */ - -/** @defgroup Group_PipeRW Pipe Data Reading and Writing +/** \ingroup Group_PipeManagement + * @defgroup Group_PipeRW Pipe Data Reading and Writing * * Functions, macros, variables, enums and types related to data reading and writing from and to pipes. */ @@ -58,21 +49,16 @@ * * Functions, macros, variables, enums and types related to data reading and writing of primitive data types * from and to pipes. - */ - -/** \ingroup Group_PipeRW - * @defgroup Group_PipeStreamRW Read/Write of Multi-Byte Streams - * - * Functions, macros, variables, enums and types related to data reading and writing of data streams from - * and to pipes. - */ + */ -/** @defgroup Group_PipePacketManagement Pipe Packet Management +/** \ingroup Group_PipeManagement + * @defgroup Group_PipePacketManagement Pipe Packet Management * * Functions, macros, variables, enums and types related to packet management of pipes. */ -/** @defgroup Group_PipeControlReq Pipe Control Request Management +/** \ingroup Group_PipeManagement + * @defgroup Group_PipeControlReq Pipe Control Request Management * * Module for host mode request processing. This module allows for the transmission of standard, class and * vendor control requests to the default control endpoint of an attached device while in host mode. @@ -80,21 +66,25 @@ * \see Chapter 9 of the USB 2.0 specification. */ +/** \ingroup Group_USB + * @defgroup Group_PipeManagement Pipe Management + * + * This module contains functions, macros and enums related to pipe management when in USB Host mode. This + * module contains the pipe management macros, as well as pipe interrupt and data send/receive functions + * for various data types. + * + * @{ + */ + #ifndef __PIPE_H__ #define __PIPE_H__ /* Includes: */ #include - #include - #include #include #include "../../../Common/Common.h" #include "../HighLevel/USBTask.h" - - #if !defined(NO_STREAM_CALLBACKS) || defined(__DOXYGEN__) - #include "../HighLevel/StreamCallbacks.h" - #endif /* Enable C linkage for C++ Compilers: */ #if defined(__cplusplus) @@ -105,12 +95,6 @@ #if !defined(__INCLUDE_FROM_USB_DRIVER) #error Do not include this file directly. Include LUFA/Drivers/USB/USB.h instead. #endif - - #if !defined(NO_STREAM_CALLBACKS) || defined(__DOXYGEN__) - #define __CALLBACK_PARAM , StreamCallbackPtr_t Callback - #else - #define __CALLBACK_PARAM - #endif /* Public Interface - May be used in end-application: */ /* Macros: */ @@ -217,26 +201,6 @@ */ }; - /** Enum for the possible error return codes of the Pipe_*_Stream_* functions. - * - * \ingroup Group_PipeRW - */ - enum Pipe_Stream_RW_ErrorCodes_t - { - PIPE_RWSTREAM_NoError = 0, /**< Command completed successfully, no error. */ - PIPE_RWSTREAM_PipeStalled = 1, /**< The device stalled the pipe during the transfer. */ - PIPE_RWSTREAM_DeviceDisconnected = 2, /**< Device was disconnected from the host during - * the transfer. - */ - PIPE_RWSTREAM_Timeout = 3, /**< The device failed to accept or send the next packet - * within the software timeout period set by the - * \ref USB_STREAM_TIMEOUT_MS macro. - */ - PIPE_RWSTREAM_CallbackAborted = 4, /**< Indicates that the stream's callback function aborted - * the transfer early. - */ - }; - /* Inline Functions: */ /** Indicates the number of bytes currently stored in the current pipes's selected bank. * @@ -847,18 +811,7 @@ /* Function Prototypes: */ /** Configures the specified pipe number with the given pipe type, token, target endpoint number in the - * attached device, bank size and banking mode. Pipes should be allocated in ascending order by their - * address in the device (i.e. pipe 1 should be configured before pipe 2 and so on) to prevent fragmentation - * of the USB FIFO memory. - * - * The pipe type may be one of the EP_TYPE_* macros listed in LowLevel.h, the token may be one of the - * PIPE_TOKEN_* masks. - * - * The bank size must indicate the maximum packet size that the pipe can handle. Different pipe - * numbers can handle different maximum packet sizes - refer to the chosen USB AVR's datasheet to - * determine the maximum bank size for each pipe. - * - * The banking mode may be either \ref PIPE_BANK_SINGLE or \ref PIPE_BANK_DOUBLE. + * attached device, bank size and banking mode. * * A newly configured pipe is frozen by default, and must be unfrozen before use via the \ref Pipe_Unfreeze() * before being used. Pipes should be kept frozen unless waiting for data from a device while in IN mode, or @@ -866,14 +819,38 @@ * numbers of IN requests without automatic freezing - this can be overridden by a call to * \ref Pipe_SetFiniteINRequests(). * - * \note The default control pipe should not be manually configured by the user application, as it - * is automatically configured by the library internally. + * \param[in] Number Pipe number to configure. This must be more than 0 and less than \ref PIPE_TOTAL_PIPES. + * + * \param[in] Type Type of pipe to configure, a EP_TYPE_* mask. Not all pipe types are available on Low + * Speed USB devices - refer to the USB 2.0 specification. + * + * \param[in] Token Pipe data token, either \ref PIPE_TOKEN_SETUP, \ref PIPE_TOKEN_OUT or \ref PIPE_TOKEN_IN. + * All pipes (except Control type) are unidirectional - data may only be read from or + * written to the pipe bank based on its direction, not both. + * + * \param[in] EndpointNumber Endpoint index within the attached device that the pipe should interface to. + * + * \param[in] Size Size of the pipe's bank, where packets are stored before they are transmitted to + * the USB device, or after they have been received from the USB device (depending on + * the pipe's data direction). The bank size must indicate the maximum packet size that + * the pipe can handle. + * + * \param[in] Banks Number of banks to use for the pipe being configured, a PIPE_BANK_* mask. More banks + * uses more USB DPRAM, but offers better performance. Isochronous type pipes must + * have at least two banks. + * + * \note Certain models of USB AVR's pipes may have different maximum packet sizes based on the pipe's + * index - refer to the chosen USB AVR's datasheet to determine the maximum bank size for each pipe. + * \n\n + * + * \note The default control pipe should not be manually configured by the user application, as it is + * automatically configured by the library internally. * \n\n * - * \note This routine will select the specified pipe, and the pipe will remain selected once the - * routine completes regardless of if the pipe configuration succeeds. + * \note This routine will automatically select the specified pipe upon success. Upon failure, the pipe which + * failed to reconfigure correctly will be selected. * - * \return Boolean true if the configuration is successful, false otherwise. + * \return Boolean true if the configuration succeeded, false otherwise. */ bool Pipe_ConfigurePipe(const uint8_t Number, const uint8_t Type, @@ -900,217 +877,6 @@ * otherwise. */ bool Pipe_IsEndpointBound(const uint8_t EndpointAddress); - - /** Reads and discards the given number of bytes from the pipe, discarding fully read packets from the host - * as needed. The last packet is not automatically discarded once the remaining bytes has been read; the - * user is responsible for manually discarding the last packet from the device via the \ref Pipe_ClearIN() macro. - * Between each USB packet, the given stream callback function is executed repeatedly until the next packet is ready, - * allowing for early aborts of stream transfers. - * - * The callback routine should be created according to the information in \ref Group_StreamCallbacks. - * If the token NO_STREAM_CALLBACKS is passed via the -D option to the compiler, stream callbacks are - * disabled and this function has the Callback parameter omitted. - * - * The pipe token is set automatically, thus this can be used on bi-directional pipes directly without - * having to explicitly change the data direction with a call to \ref Pipe_SetPipeToken(). - * - * \ingroup Group_PipeStreamRW - * - * \param[in] Length Number of bytes to send via the currently selected pipe. - * \param[in] Callback Name of a callback routine to call between successive USB packet transfers, NULL if no callback. - * - * \return A value from the \ref Pipe_Stream_RW_ErrorCodes_t enum. - */ - uint8_t Pipe_Discard_Stream(uint16_t Length - __CALLBACK_PARAM); - - /** Writes the given number of bytes to the pipe from the given buffer in little endian, - * sending full packets to the device as needed. The last packet filled is not automatically sent; - * the user is responsible for manually sending the last written packet to the host via the - * \ref Pipe_ClearOUT() macro. Between each USB packet, the given stream callback function is - * executed repeatedly until the next packet is ready, allowing for early aborts of stream transfers. - * - * The callback routine should be created according to the information in \ref Group_StreamCallbacks. - * If the token NO_STREAM_CALLBACKS is passed via the -D option to the compiler, stream callbacks are - * disabled and this function has the Callback parameter omitted. - * - * The pipe token is set automatically, thus this can be used on bi-directional pipes directly without - * having to explicitly change the data direction with a call to \ref Pipe_SetPipeToken(). - * - * \ingroup Group_PipeStreamRW - * - * \param[in] Buffer Pointer to the source data buffer to read from. - * \param[in] Length Number of bytes to read for the currently selected pipe into the buffer. - * \param[in] Callback Name of a callback routine to call between successive USB packet transfers, NULL if no callback. - * - * \return A value from the \ref Pipe_Stream_RW_ErrorCodes_t enum. - */ - uint8_t Pipe_Write_Stream_LE(const void* Buffer, - uint16_t Length - __CALLBACK_PARAM) ATTR_NON_NULL_PTR_ARG(1); - - /** EEPROM buffer source version of \ref Pipe_Write_Stream_LE(). - * - * \ingroup Group_PipeStreamRW - * - * \param[in] Buffer Pointer to the source data buffer to read from. - * \param[in] Length Number of bytes to read for the currently selected pipe into the buffer. - * \param[in] Callback Name of a callback routine to call between successive USB packet transfers, NULL if no callback. - * - * \return A value from the \ref Pipe_Stream_RW_ErrorCodes_t enum. - */ - uint8_t Pipe_Write_EStream_LE(const void* Buffer, - uint16_t Length - __CALLBACK_PARAM) ATTR_NON_NULL_PTR_ARG(1); - - /** FLASH buffer source version of \ref Pipe_Write_Stream_LE(). - * - * \pre The FLASH data must be located in the first 64KB of FLASH for this function to work correctly. - * - * \ingroup Group_PipeStreamRW - * - * \param[in] Buffer Pointer to the source data buffer to read from. - * \param[in] Length Number of bytes to read for the currently selected pipe into the buffer. - * \param[in] Callback Name of a callback routine to call between successive USB packet transfers, NULL if no callback. - * - * \return A value from the \ref Pipe_Stream_RW_ErrorCodes_t enum. - */ - uint8_t Pipe_Write_PStream_LE(const void* Buffer, - uint16_t Length - __CALLBACK_PARAM) ATTR_NON_NULL_PTR_ARG(1); - - /** Writes the given number of bytes to the pipe from the given buffer in big endian, - * sending full packets to the device as needed. The last packet filled is not automatically sent; - * the user is responsible for manually sending the last written packet to the host via the - * \ref Pipe_ClearOUT() macro. Between each USB packet, the given stream callback function is - * executed repeatedly until the next packet is ready, allowing for early aborts of stream transfers. - * - * The callback routine should be created according to the information in \ref Group_StreamCallbacks. - * If the token NO_STREAM_CALLBACKS is passed via the -D option to the compiler, stream callbacks are - * disabled and this function has the Callback parameter omitted. - * - * The pipe token is set automatically, thus this can be used on bi-directional pipes directly without - * having to explicitly change the data direction with a call to \ref Pipe_SetPipeToken(). - * - * \ingroup Group_PipeStreamRW - * - * \param[in] Buffer Pointer to the source data buffer to read from. - * \param[in] Length Number of bytes to read for the currently selected pipe into the buffer. - * \param[in] Callback Name of a callback routine to call between successive USB packet transfers, NULL if no callback. - * - * \return A value from the \ref Pipe_Stream_RW_ErrorCodes_t enum. - */ - uint8_t Pipe_Write_Stream_BE(const void* Buffer, - uint16_t Length - __CALLBACK_PARAM) ATTR_NON_NULL_PTR_ARG(1); - - /** EEPROM buffer source version of \ref Pipe_Write_Stream_BE(). - * - * \ingroup Group_PipeStreamRW - * - * \param[in] Buffer Pointer to the source data buffer to read from. - * \param[in] Length Number of bytes to read for the currently selected pipe into the buffer. - * \param[in] Callback Name of a callback routine to call between successive USB packet transfers, NULL if no callback. - * - * \return A value from the \ref Pipe_Stream_RW_ErrorCodes_t enum. - */ - uint8_t Pipe_Write_EStream_BE(const void* Buffer, - uint16_t Length - __CALLBACK_PARAM) ATTR_NON_NULL_PTR_ARG(1); - - /** FLASH buffer source version of \ref Pipe_Write_Stream_BE(). - * - * \pre The FLASH data must be located in the first 64KB of FLASH for this function to work correctly. - * - * \ingroup Group_PipeStreamRW - * - * \param[in] Buffer Pointer to the source data buffer to read from. - * \param[in] Length Number of bytes to read for the currently selected pipe into the buffer. - * \param[in] Callback Name of a callback routine to call between successive USB packet transfers, NULL if no callback. - * - * \return A value from the \ref Pipe_Stream_RW_ErrorCodes_t enum. - */ - uint8_t Pipe_Write_PStream_BE(const void* Buffer, - uint16_t Length - __CALLBACK_PARAM) ATTR_NON_NULL_PTR_ARG(1); - - /** Reads the given number of bytes from the pipe into the given buffer in little endian, - * sending full packets to the device as needed. The last packet filled is not automatically sent; - * the user is responsible for manually sending the last written packet to the host via the - * \ref Pipe_ClearIN() macro. Between each USB packet, the given stream callback function is - * executed repeatedly until the next packet is ready, allowing for early aborts of stream transfers. - * - * The callback routine should be created according to the information in \ref Group_StreamCallbacks. - * If the token NO_STREAM_CALLBACKS is passed via the -D option to the compiler, stream callbacks are - * disabled and this function has the Callback parameter omitted. - * - * The pipe token is set automatically, thus this can be used on bi-directional pipes directly without - * having to explicitly change the data direction with a call to \ref Pipe_SetPipeToken(). - * - * \ingroup Group_PipeStreamRW - * - * \param[out] Buffer Pointer to the source data buffer to write to. - * \param[in] Length Number of bytes to read for the currently selected pipe to read from. - * \param[in] Callback Name of a callback routine to call between successive USB packet transfers, NULL if no callback. - * - * \return A value from the \ref Pipe_Stream_RW_ErrorCodes_t enum. - */ - uint8_t Pipe_Read_Stream_LE(void* Buffer, - uint16_t Length - __CALLBACK_PARAM) ATTR_NON_NULL_PTR_ARG(1); - - /** EEPROM buffer source version of \ref Pipe_Read_Stream_LE(). - * - * \ingroup Group_PipeStreamRW - * - * \param[out] Buffer Pointer to the source data buffer to write to. - * \param[in] Length Number of bytes to read for the currently selected pipe to read from. - * \param[in] Callback Name of a callback routine to call between successive USB packet transfers, NULL if no callback. - * - * \return A value from the \ref Pipe_Stream_RW_ErrorCodes_t enum. - */ - uint8_t Pipe_Read_EStream_LE(void* Buffer, - uint16_t Length - __CALLBACK_PARAM) ATTR_NON_NULL_PTR_ARG(1); - - /** Reads the given number of bytes from the pipe into the given buffer in big endian, - * sending full packets to the device as needed. The last packet filled is not automatically sent; - * the user is responsible for manually sending the last written packet to the host via the - * \ref Pipe_ClearIN() macro. Between each USB packet, the given stream callback function is - * executed repeatedly until the next packet is ready, allowing for early aborts of stream transfers. - * - * The callback routine should be created according to the information in \ref Group_StreamCallbacks. - * If the token NO_STREAM_CALLBACKS is passed via the -D option to the compiler, stream callbacks are - * disabled and this function has the Callback parameter omitted. - * - * The pipe token is set automatically, thus this can be used on bi-directional pipes directly without - * having to explicitly change the data direction with a call to \ref Pipe_SetPipeToken(). - * - * \ingroup Group_PipeStreamRW - * - * \param[out] Buffer Pointer to the source data buffer to write to. - * \param[in] Length Number of bytes to read for the currently selected pipe to read from. - * \param[in] Callback Name of a callback routine to call between successive USB packet transfers, NULL if no callback. - * - * \return A value from the \ref Pipe_Stream_RW_ErrorCodes_t enum. - */ - uint8_t Pipe_Read_Stream_BE(void* Buffer, - uint16_t Length - __CALLBACK_PARAM) ATTR_NON_NULL_PTR_ARG(1); - - /** EEPROM buffer source version of \ref Pipe_Read_Stream_BE(). - * - * \ingroup Group_PipeStreamRW - * - * \param[out] Buffer Pointer to the source data buffer to write to. - * \param[in] Length Number of bytes to read for the currently selected pipe to read from. - * \param[in] Callback Name of a callback routine to call between successive USB packet transfers, NULL if no callback. - * - * \return A value from the \ref Pipe_Stream_RW_ErrorCodes_t enum. - */ - uint8_t Pipe_Read_EStream_BE(void* Buffer, - uint16_t Length - __CALLBACK_PARAM) ATTR_NON_NULL_PTR_ARG(1); /* Private Interface - For use in library only: */ #if !defined(__DOXYGEN__)