LUFA/Drivers/USB/HighLevel/PipeStream.h

   1 /*
   2              LUFA Library
   3      Copyright (C) Dean Camera, 2010.
   4
   5   dean [at] fourwalledcubicle [dot] com
   6            www.lufa-lib.org
   7 */
   8
   9 /*
  10   Copyright 2010  Dean Camera (dean [at] fourwalledcubicle [dot] com)
  11
  12   Permission to use, copy, modify, distribute, and sell this
  13   software and its documentation for any purpose is hereby granted
  14   without fee, provided that the above copyright notice appear in
  15   all copies and that both that the copyright notice and this
  16   permission notice and warranty disclaimer appear in supporting
  17   documentation, and that the name of the author not be used in
  18   advertising or publicity pertaining to distribution of the
  19   software without specific, written prior permission.
  20
  21   The author disclaim all warranties with regard to this
  22   software, including all implied warranties of merchantability
  23   and fitness.  In no event shall the author be liable for any
  24   special, indirect or consequential damages or any damages
  25   whatsoever resulting from loss of use, data or profits, whether
  26   in an action of contract, negligence or other tortious action,
  27   arising out of or in connection with the use or performance of
  28   this software.
  29 */
  30
  31 /** \file
  32  *  \brief USB host pipe stream function definitions.
  33  *
  34  *  This file contains structures, function prototypes and macros related to the sending and receiving of
  35  *  arbitrary data streams through the device's data pipes when the library is initialized in USB host mode.
  36  *
  37  *  \note This file should not be included directly. It is automatically included as needed by the USB driver
  38  *        dispatch header located in LUFA/Drivers/USB/USB.h.
  39  */
  40
  41 /** \ingroup Group_PipeRW
  42  *  @defgroup Group_PipeStreamRW Read/Write of Multi-Byte Streams
  43  *
  44  *  Functions, macros, variables, enums and types related to data reading and writing of data streams from
  45  *  and to pipes.
  46  *
  47  *  @{
  48  */
  49
  50 #ifndef __PIPE_STREAM_H__
  51 #define __PIPE_STREAM_H__
  52
  53         /* Includes: */
  54                 #include <avr/io.h>
  55                 #include <avr/pgmspace.h>
  56                 #include <avr/eeprom.h>
  57                 #include <stdbool.h>
  58
  59                 #include "../../../Common/Common.h"
  60                 #include "USBTask.h"
  61
  62                 #if !defined(NO_STREAM_CALLBACKS) || defined(__DOXYGEN__)
  63                         #include "StreamCallbacks.h"
  64                 #endif
  65
  66         /* Enable C linkage for C++ Compilers: */
  67                 #if defined(__cplusplus)
  68                         extern "C" {
  69                 #endif
  70
  71         /* Preprocessor Checks: */
  72                 #if !defined(__INCLUDE_FROM_USB_DRIVER)
  73                         #error Do not include this file directly. Include LUFA/Drivers/USB/USB.h instead.
  74                 #endif
  75
  76                 #if !defined(NO_STREAM_CALLBACKS) || defined(__DOXYGEN__)
  77                         #define __CALLBACK_PARAM     , StreamCallbackPtr_t Callback
  78                 #else
  79                         #define __CALLBACK_PARAM
  80                 #endif
  81
  82         /* Public Interface - May be used in end-application: */
  83                 /* Enums: */
  84                         /** Enum for the possible error return codes of the Pipe_*_Stream_* functions. */
  85                         enum Pipe_Stream_RW_ErrorCodes_t
  86                         {
  87                                 PIPE_RWSTREAM_NoError            = 0, /**< Command completed successfully, no error. */
  88                                 PIPE_RWSTREAM_PipeStalled        = 1, /**< The device stalled the pipe during the transfer. */
  89                                 PIPE_RWSTREAM_DeviceDisconnected = 2, /**< Device was disconnected from the host during
  90                                                                    *   the transfer.
  91                                                                    */
  92                                 PIPE_RWSTREAM_Timeout            = 3, /**< The device failed to accept or send the next packet
  93                                                                        *   within the software timeout period set by the
  94                                                                        *   \ref USB_STREAM_TIMEOUT_MS macro.
  95                                                                        */
  96                                 PIPE_RWSTREAM_CallbackAborted    = 4, /**< Indicates that the stream's callback function aborted
  97                                                                    *   the transfer early.
  98                                                                        */
  99                         };
 100
 101                 /* Function Prototypes: */
 102                         /** Reads and discards the given number of bytes from the pipe, discarding fully read packets from the host
 103                          *  as needed. The last packet is not automatically discarded once the remaining bytes has been read; the
 104                          *  user is responsible for manually discarding the last packet from the device via the \ref Pipe_ClearIN() macro.
 105                          *  Between each USB packet, the given stream callback function is executed repeatedly until the next packet is ready,
 106                          *  allowing for early aborts of stream transfers.
 107                          *
 108                          *      The callback routine should be created according to the information in \ref Group_StreamCallbacks.
 109                          *  If the token NO_STREAM_CALLBACKS is passed via the -D option to the compiler, stream callbacks are
 110                          *  disabled and this function has the Callback parameter omitted.
 111                          *
 112                          *  The pipe token is set automatically, thus this can be used on bi-directional pipes directly without
 113                          *  having to explicitly change the data direction with a call to \ref Pipe_SetPipeToken().
 114                          *
 115                          *  \param[in] Length    Number of bytes to send via the currently selected pipe.
 116                          *  \param[in] Callback  Name of a callback routine to call between successive USB packet transfers, NULL if no callback.
 117                          *
 118                          *  \return A value from the \ref Pipe_Stream_RW_ErrorCodes_t enum.
 119                          */
 120                         uint8_t Pipe_Discard_Stream(uint16_t Length
 121                                                     __CALLBACK_PARAM);
 122
 123                         /** Writes the given number of bytes to the pipe from the given buffer in little endian,
 124                          *  sending full packets to the device as needed. The last packet filled is not automatically sent;
 125                          *  the user is responsible for manually sending the last written packet to the host via the
 126                          *  \ref Pipe_ClearOUT() macro. Between each USB packet, the given stream callback function is
 127                          *  executed repeatedly until the next packet is ready, allowing for early aborts of stream transfers.
 128                          *
 129                          *      The callback routine should be created according to the information in \ref Group_StreamCallbacks.
 130                          *  If the token NO_STREAM_CALLBACKS is passed via the -D option to the compiler, stream callbacks are
 131                          *  disabled and this function has the Callback parameter omitted.
 132                          *
 133                          *  The pipe token is set automatically, thus this can be used on bi-directional pipes directly without
 134                          *  having to explicitly change the data direction with a call to \ref Pipe_SetPipeToken().
 135                          *
 136                          *  \param[in] Buffer    Pointer to the source data buffer to read from.
 137                          *  \param[in] Length    Number of bytes to read for the currently selected pipe into the buffer.
 138                          *  \param[in] Callback  Name of a callback routine to call between successive USB packet transfers, NULL if no callback.
 139                          *
 140                          *  \return A value from the \ref Pipe_Stream_RW_ErrorCodes_t enum.
 141                          */
 142                         uint8_t Pipe_Write_Stream_LE(const void* Buffer,
 143                                                      uint16_t Length
 144                                                      __CALLBACK_PARAM) ATTR_NON_NULL_PTR_ARG(1);
 145
 146                         /** EEPROM buffer source version of \ref Pipe_Write_Stream_LE().
 147                          *
 148                          *  \param[in] Buffer    Pointer to the source data buffer to read from.
 149                          *  \param[in] Length    Number of bytes to read for the currently selected pipe into the buffer.
 150                          *  \param[in] Callback  Name of a callback routine to call between successive USB packet transfers, NULL if no callback.
 151                          *
 152                          *  \return A value from the \ref Pipe_Stream_RW_ErrorCodes_t enum.
 153                          */
 154                         uint8_t Pipe_Write_EStream_LE(const void* Buffer,
 155                                                       uint16_t Length
 156                                                       __CALLBACK_PARAM) ATTR_NON_NULL_PTR_ARG(1);
 157
 158                         /** FLASH buffer source version of \ref Pipe_Write_Stream_LE().
 159                          *
 160                          *  \pre The FLASH data must be located in the first 64KB of FLASH for this function to work correctly.
 161                          *
 162                          *  \param[in] Buffer    Pointer to the source data buffer to read from.
 163                          *  \param[in] Length    Number of bytes to read for the currently selected pipe into the buffer.
 164                          *  \param[in] Callback  Name of a callback routine to call between successive USB packet transfers, NULL if no callback.
 165                          *
 166                          *  \return A value from the \ref Pipe_Stream_RW_ErrorCodes_t enum.
 167                          */
 168                         uint8_t Pipe_Write_PStream_LE(const void* Buffer,
 169                                                       uint16_t Length
 170                                                       __CALLBACK_PARAM) ATTR_NON_NULL_PTR_ARG(1);
 171
 172                         /** Writes the given number of bytes to the pipe from the given buffer in big endian,
 173                          *  sending full packets to the device as needed. The last packet filled is not automatically sent;
 174                          *  the user is responsible for manually sending the last written packet to the host via the
 175                          *  \ref Pipe_ClearOUT() macro. Between each USB packet, the given stream callback function is
 176                          *  executed repeatedly until the next packet is ready, allowing for early aborts of stream transfers.
 177                          *
 178                          *      The callback routine should be created according to the information in \ref Group_StreamCallbacks.
 179                          *  If the token NO_STREAM_CALLBACKS is passed via the -D option to the compiler, stream callbacks are
 180                          *  disabled and this function has the Callback parameter omitted.
 181                          *
 182                          *  The pipe token is set automatically, thus this can be used on bi-directional pipes directly without
 183                          *  having to explicitly change the data direction with a call to \ref Pipe_SetPipeToken().
 184                          *
 185                          *  \param[in] Buffer    Pointer to the source data buffer to read from.
 186                          *  \param[in] Length    Number of bytes to read for the currently selected pipe into the buffer.
 187                          *  \param[in] Callback  Name of a callback routine to call between successive USB packet transfers, NULL if no callback.
 188                          *
 189                          *  \return A value from the \ref Pipe_Stream_RW_ErrorCodes_t enum.
 190                          */
 191                         uint8_t Pipe_Write_Stream_BE(const void* Buffer,
 192                                                      uint16_t Length
 193                                                      __CALLBACK_PARAM) ATTR_NON_NULL_PTR_ARG(1);
 194
 195                         /** EEPROM buffer source version of \ref Pipe_Write_Stream_BE().
 196                          *
 197                          *  \param[in] Buffer    Pointer to the source data buffer to read from.
 198                          *  \param[in] Length    Number of bytes to read for the currently selected pipe into the buffer.
 199                          *  \param[in] Callback  Name of a callback routine to call between successive USB packet transfers, NULL if no callback.
 200                          *
 201                          *  \return A value from the \ref Pipe_Stream_RW_ErrorCodes_t enum.
 202                          */
 203                         uint8_t Pipe_Write_EStream_BE(const void* Buffer,
 204                                                       uint16_t Length
 205                                                       __CALLBACK_PARAM) ATTR_NON_NULL_PTR_ARG(1);
 206
 207                         /** FLASH buffer source version of \ref Pipe_Write_Stream_BE().
 208                          *
 209                          *  \pre The FLASH data must be located in the first 64KB of FLASH for this function to work correctly.
 210                          *
 211                          *  \param[in] Buffer    Pointer to the source data buffer to read from.
 212                          *  \param[in] Length    Number of bytes to read for the currently selected pipe into the buffer.
 213                          *  \param[in] Callback  Name of a callback routine to call between successive USB packet transfers, NULL if no callback.
 214                          *
 215                          *  \return A value from the \ref Pipe_Stream_RW_ErrorCodes_t enum.
 216                          */
 217                         uint8_t Pipe_Write_PStream_BE(const void* Buffer,
 218                                                       uint16_t Length
 219                                                       __CALLBACK_PARAM) ATTR_NON_NULL_PTR_ARG(1);
 220
 221                         /** Reads the given number of bytes from the pipe into the given buffer in little endian,
 222                          *  sending full packets to the device as needed. The last packet filled is not automatically sent;
 223                          *  the user is responsible for manually sending the last written packet to the host via the
 224                          *  \ref Pipe_ClearIN() macro. Between each USB packet, the given stream callback function is
 225                          *  executed repeatedly until the next packet is ready, allowing for early aborts of stream transfers.
 226                          *
 227                          *      The callback routine should be created according to the information in \ref Group_StreamCallbacks.
 228                          *  If the token NO_STREAM_CALLBACKS is passed via the -D option to the compiler, stream callbacks are
 229                          *  disabled and this function has the Callback parameter omitted.
 230                          *
 231                          *  The pipe token is set automatically, thus this can be used on bi-directional pipes directly without
 232                          *  having to explicitly change the data direction with a call to \ref Pipe_SetPipeToken().
 233                          *
 234                          *  \param[out] Buffer    Pointer to the source data buffer to write to.
 235                          *  \param[in]  Length    Number of bytes to read for the currently selected pipe to read from.
 236                          *  \param[in]  Callback  Name of a callback routine to call between successive USB packet transfers, NULL if no callback.
 237                          *
 238                          *  \return A value from the \ref Pipe_Stream_RW_ErrorCodes_t enum.
 239                          */
 240                         uint8_t Pipe_Read_Stream_LE(void* Buffer,
 241                                                     uint16_t Length
 242                                                     __CALLBACK_PARAM) ATTR_NON_NULL_PTR_ARG(1);
 243
 244                         /** EEPROM buffer source version of \ref Pipe_Read_Stream_LE().
 245                          *
 246                          *  \param[out] Buffer    Pointer to the source data buffer to write to.
 247                          *  \param[in]  Length    Number of bytes to read for the currently selected pipe to read from.
 248                          *  \param[in]  Callback  Name of a callback routine to call between successive USB packet transfers, NULL if no callback.
 249                          *
 250                          *  \return A value from the \ref Pipe_Stream_RW_ErrorCodes_t enum.
 251                          */
 252                         uint8_t Pipe_Read_EStream_LE(void* Buffer,
 253                                                      uint16_t Length
 254                                                      __CALLBACK_PARAM) ATTR_NON_NULL_PTR_ARG(1);
 255
 256                         /** Reads the given number of bytes from the pipe into the given buffer in big endian,
 257                          *  sending full packets to the device as needed. The last packet filled is not automatically sent;
 258                          *  the user is responsible for manually sending the last written packet to the host via the
 259                          *  \ref Pipe_ClearIN() macro. Between each USB packet, the given stream callback function is
 260                          *  executed repeatedly until the next packet is ready, allowing for early aborts of stream transfers.
 261                          *
 262                          *      The callback routine should be created according to the information in \ref Group_StreamCallbacks.
 263                          *  If the token NO_STREAM_CALLBACKS is passed via the -D option to the compiler, stream callbacks are
 264                          *  disabled and this function has the Callback parameter omitted.
 265                          *
 266                          *  The pipe token is set automatically, thus this can be used on bi-directional pipes directly without
 267                          *  having to explicitly change the data direction with a call to \ref Pipe_SetPipeToken().
 268                          *
 269                          *  \param[out] Buffer    Pointer to the source data buffer to write to.
 270                          *  \param[in]  Length    Number of bytes to read for the currently selected pipe to read from.
 271                          *  \param[in]  Callback  Name of a callback routine to call between successive USB packet transfers, NULL if no callback.
 272                          *
 273                          *  \return A value from the \ref Pipe_Stream_RW_ErrorCodes_t enum.
 274                          */
 275                         uint8_t Pipe_Read_Stream_BE(void* Buffer,
 276                                                     uint16_t Length
 277                                                     __CALLBACK_PARAM) ATTR_NON_NULL_PTR_ARG(1);
 278
 279                         /** EEPROM buffer source version of \ref Pipe_Read_Stream_BE().
 280                          *
 281                          *  \param[out] Buffer    Pointer to the source data buffer to write to.
 282                          *  \param[in]  Length    Number of bytes to read for the currently selected pipe to read from.
 283                          *  \param[in]  Callback  Name of a callback routine to call between successive USB packet transfers, NULL if no callback.
 284                          *
 285                          *  \return A value from the \ref Pipe_Stream_RW_ErrorCodes_t enum.
 286                          */
 287                         uint8_t Pipe_Read_EStream_BE(void* Buffer,
 288                                                      uint16_t Length
 289                                                      __CALLBACK_PARAM) ATTR_NON_NULL_PTR_ARG(1);
 290
 291         /* Disable C linkage for C++ Compilers: */
 292                 #if defined(__cplusplus)
 293                         }
 294                 #endif
 295
 296 #endif
 297
 298 /** @} */
 299