ahoneybun/qmk_firmware
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Split out endpoint and pipe stream functions into new EndpointStream.c/.h and PipeStream.c/.h files.

Browse source
This commit is contained in:
Dean Camera 2010-08-22 13:31:27 +00:00
parent 4cc7f5200b
commit e72f424f64
18 changed files with 1320 additions and 1161 deletions
Download patch file Download diff file Expand all files Collapse all files

303
LUFA/Drivers/USB/LowLevel/Pipe.h
View file

@ -38,6 +38,34 @@
* dispatch header located in LUFA/Drivers/USB/USB.h.
*/
/** \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.
*/
/** \ingroup Group_PipeRW
* @defgroup Group_PipePrimitiveRW Read/Write of Primitive Data Types
*
* Functions, macros, variables, enums and types related to data reading and writing of primitive data types
* from and to pipes.
*/
/** \ingroup Group_PipeManagement
* @defgroup Group_PipePacketManagement Pipe Packet Management
*
* Functions, macros, variables, enums and types related to packet management of pipes.
*/
/** \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
*
@ -48,53 +76,15 @@
* @{
*/
/** @defgroup Group_PipeRW Pipe Data Reading and Writing
*
* Functions, macros, variables, enums and types related to data reading and writing from and to pipes.
*/
/** \ingroup Group_PipeRW
* @defgroup Group_PipePrimitiveRW Read/Write of Primitive Data Types
*
* 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
*
* Functions, macros, variables, enums and types related to packet management of pipes.
*/
/** @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.
*/
#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)
@ -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.
*
@ -900,217 +864,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__)