* 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.
*/
*
* 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.
* \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 <avr/io.h>
- #include <avr/pgmspace.h>
- #include <avr/eeprom.h>
#include <stdbool.h>
#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)
#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: */
*/
};
- /** 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.
*
/* 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
* 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 <b>must</b>
+ * 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,
* 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__)
projects / pub / USBasp.git / blobdiff