LUFA/Drivers/USB/HighLevel/PipeStream.h

   1 /*
   2              LUFA Library
   3      Copyright (C) Dean Camera, 2011.
   4
   5   dean [at] fourwalledcubicle [dot] com
   6            www.lufa-lib.org
   7 */
   8
   9 /*
  10   Copyright 2011  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/pgmspace.h>
  55                 #include <avr/eeprom.h>
  56                 #include <stdbool.h>
  57
  58                 #include "../../../Common/Common.h"
  59                 #include "USBTask.h"
  60
  61         /* Enable C linkage for C++ Compilers: */
  62                 #if defined(__cplusplus)
  63                         extern "C" {
  64                 #endif
  65
  66         /* Preprocessor Checks: */
  67                 #if !defined(__INCLUDE_FROM_USB_DRIVER)
  68                         #error Do not include this file directly. Include LUFA/Drivers/USB/USB.h instead.
  69                 #endif
  70
  71         /* Public Interface - May be used in end-application: */
  72                 /* Enums: */
  73                         /** Enum for the possible error return codes of the Pipe_*_Stream_* functions. */
  74                         enum Pipe_Stream_RW_ErrorCodes_t
  75                         {
  76                                 PIPE_RWSTREAM_NoError            = 0, /**< Command completed successfully, no error. */
  77                                 PIPE_RWSTREAM_PipeStalled        = 1, /**< The device stalled the pipe during the transfer. */
  78                                 PIPE_RWSTREAM_DeviceDisconnected = 2, /**< Device was disconnected from the host during
  79                                                                    *   the transfer.
  80                                                                    */
  81                                 PIPE_RWSTREAM_Timeout            = 3, /**< The device failed to accept or send the next packet
  82                                                                        *   within the software timeout period set by the
  83                                                                        *   \ref USB_STREAM_TIMEOUT_MS macro.
  84                                                                        */
  85                                 PIPE_RWSTREAM_IncompleteTransfer = 4, /**< Indicates that the pipe bank became full/empty before the
  86                                                                        *   complete contents of the stream could be transferred.
  87                                                                        */
  88                         };
  89
  90                 /* Function Prototypes: */
  91
  92                         /** \name Stream functions for null data */
  93                         //@{
  94
  95                         /** Reads and discards the given number of bytes from the pipe, discarding fully read packets from the host
  96                          *  as needed. The last packet is not automatically discarded once the remaining bytes has been read; the
  97                          *  user is responsible for manually discarding the last packet from the device via the \ref Pipe_ClearIN() macro.
  98                          *
  99                          *  If the BytesProcessed parameter is \c NULL, the entire stream transfer is attempted at once, failing or
 100                          *  succeeding as a single unit. If the BytesProcessed parameter points to a valid storage location, the transfer
 101                          *  will instead be performed as a series of chunks. Each time the pipe bank becomes empty while there is still data
 102                          *  to process (and after the current packet has been acknowledged) the BytesProcessed location will be updated with
 103                          *  the total number of bytes processed in the stream, and the function will exit with an error code of
 104                          *  \ref PIPE_RWSTREAM_IncompleteTransfer. This allows for any abort checking to be performed in the user code - to
 105                          *  continue the transfer, call the function again with identical parameters and it will resume until the BytesProcessed
 106                          *  value reaches the total transfer length.
 107                          *
 108                          *  <b>Single Stream Transfer Example:</b>
 109                          *  \code
 110                          *  uint8_t ErrorCode;
 111                          *
 112                          *  if ((ErrorCode = Pipe_Discard_Stream(512, NULL)) != PIPE_RWSTREAM_NoError)
 113                          *  {
 114                          *       // Stream failed to complete - check ErrorCode here
 115                          *  }
 116                          *  \endcode
 117                          *
 118                          *  <b>Partial Stream Transfers Example:</b>
 119                          *  \code
 120                          *  uint8_t  ErrorCode;
 121                          *  uint16_t BytesProcessed;
 122                          *
 123                          *  BytesProcessed = 0;
 124                          *  while ((ErrorCode = Pipe_Discard_Stream(512, &BytesProcessed)) == PIPE_RWSTREAM_IncompleteTransfer)
 125                          *  {
 126                          *      // Stream not yet complete - do other actions here, abort if required
 127                          *  }
 128                          *
 129                          *  if (ErrorCode != PIPE_RWSTREAM_NoError)
 130                          *  {
 131                          *      // Stream failed to complete - check ErrorCode here
 132                          *  }
 133                          *  \endcode
 134                          *
 135                          *  \note The pipe token is set automatically, thus this can be used on bi-directional pipes directly without
 136                          *        having to explicitly change the data direction with a call to \ref Pipe_SetPipeToken().
 137                          *
 138                          *  \param[in] Length          Number of bytes to discard via the currently selected pipe.
 139                          *  \param[in] BytesProcessed  Pointer to a location where the total number of bytes already processed should
 140                          *                             updated, \c NULL if the entire stream should be processed at once.
 141                          *
 142                          *  \return A value from the \ref Pipe_Stream_RW_ErrorCodes_t enum.
 143                          */
 144                         uint8_t Pipe_Discard_Stream(uint16_t Length,
 145                                                     uint16_t* const BytesProcessed);
 146
 147                         /** Writes a given number of zeroed bytes to the pipe, sending full pipe packets from the host to the device
 148                          *  as needed. The last packet is not automatically sent once the remaining bytes has been written; the
 149                          *  user is responsible for manually discarding the last packet from the device via the \ref Pipe_ClearOUT() macro.
 150                          *
 151                          *  If the BytesProcessed parameter is \c NULL, the entire stream transfer is attempted at once, failing or
 152                          *  succeeding as a single unit. If the BytesProcessed parameter points to a valid storage location, the transfer
 153                          *  will instead be performed as a series of chunks. Each time the pipe bank becomes full while there is still data
 154                          *  to process (and after the current packet transmission has been initiated) the BytesProcessed location will be
 155                          *  updated with the total number of bytes processed in the stream, and the function will exit with an error code of
 156                          *  \ref PIPE_RWSTREAM_IncompleteTransfer. This allows for any abort checking to be performed in the user code - to
 157                          *  continue the transfer, call the function again with identical parameters and it will resume until the BytesProcessed
 158                          *  value reaches the total transfer length.
 159                          *
 160                          *  <b>Single Stream Transfer Example:</b>
 161                          *  \code
 162                          *  uint8_t ErrorCode;
 163                          *
 164                          *  if ((ErrorCode = Pipe_Null_Stream(512, NULL)) != PIPE_RWSTREAM_NoError)
 165                          *  {
 166                          *       // Stream failed to complete - check ErrorCode here
 167                          *  }
 168                          *  \endcode
 169                          *
 170                          *  <b>Partial Stream Transfers Example:</b>
 171                          *  \code
 172                          *  uint8_t  ErrorCode;
 173                          *  uint16_t BytesProcessed;
 174                          *
 175                          *  BytesProcessed = 0;
 176                          *  while ((ErrorCode = Pipe_Null_Stream(512, &BytesProcessed)) == PIPE_RWSTREAM_IncompleteTransfer)
 177                          *  {
 178                          *      // Stream not yet complete - do other actions here, abort if required
 179                          *  }
 180                          *
 181                          *  if (ErrorCode != PIPE_RWSTREAM_NoError)
 182                          *  {
 183                          *      // Stream failed to complete - check ErrorCode here
 184                          *  }
 185                          *  \endcode
 186                          *
 187                          *  \note The pipe token is set automatically, thus this can be used on bi-directional pipes directly without
 188                          *        having to explicitly change the data direction with a call to \ref Pipe_SetPipeToken().
 189                          *
 190                          *  \param[in] Length          Number of zero bytes to write via the currently selected pipe.
 191                          *  \param[in] BytesProcessed  Pointer to a location where the total number of bytes already processed should
 192                          *                             updated, \c NULL if the entire stream should be processed at once.
 193                          *
 194                          *  \return A value from the \ref Pipe_Stream_RW_ErrorCodes_t enum.
 195                          */
 196                         uint8_t Pipe_Null_Stream(uint16_t Length,
 197                                                  uint16_t* const BytesProcessed);
 198
 199                         //@}
 200
 201                         /** \name Stream functions for RAM source/destination data */
 202                         //@{
 203
 204                         /** Writes the given number of bytes to the pipe from the given buffer in little endian,
 205                          *  sending full packets to the device as needed. The last packet filled is not automatically sent;
 206                          *  the user is responsible for manually sending the last written packet to the host via the
 207                          *  \ref Pipe_ClearOUT() macro. Between each USB packet, the given stream callback function is
 208                          *  executed repeatedly until the next packet is ready, allowing for early aborts of stream transfers.
 209                          *
 210                          *  If the BytesProcessed parameter is \c NULL, the entire stream transfer is attempted at once,
 211                          *  failing or succeeding as a single unit. If the BytesProcessed parameter points to a valid
 212                          *  storage location, the transfer will instead be performed as a series of chunks. Each time
 213                          *  the pipe bank becomes full while there is still data to process (and after the current
 214                          *  packet transmission has been initiated) the BytesProcessed location will be updated with the
 215                          *  total number of bytes processed in the stream, and the function will exit with an error code of
 216                          *  \ref PIPE_RWSTREAM_IncompleteTransfer. This allows for any abort checking to be performed
 217                          *  in the user code - to continue the transfer, call the function again with identical parameters
 218                          *  and it will resume until the BytesProcessed value reaches the total transfer length.
 219                          *
 220                          *  <b>Single Stream Transfer Example:</b>
 221                          *  \code
 222                          *  uint8_t DataStream[512];
 223                          *  uint8_t ErrorCode;
 224                          *
 225                          *  if ((ErrorCode = Pipe_Write_Stream_LE(DataStream, sizeof(DataStream),
 226                          *                                        NULL)) != PIPE_RWSTREAM_NoError)
 227                          *  {
 228                          *       // Stream failed to complete - check ErrorCode here
 229                          *  }
 230                          *  \endcode
 231                          *
 232                          *  <b>Partial Stream Transfers Example:</b>
 233                          *  \code
 234                          *  uint8_t  DataStream[512];
 235                          *  uint8_t  ErrorCode;
 236                          *  uint16_t BytesProcessed;
 237                          *
 238                          *  BytesProcessed = 0;
 239                          *  while ((ErrorCode = Pipe_Write_Stream_LE(DataStream, sizeof(DataStream),
 240                          *                                           &BytesProcessed)) == PIPE_RWSTREAM_IncompleteTransfer)
 241                          *  {
 242                          *      // Stream not yet complete - do other actions here, abort if required
 243                          *  }
 244                          *
 245                          *  if (ErrorCode != PIPE_RWSTREAM_NoError)
 246                          *  {
 247                          *      // Stream failed to complete - check ErrorCode here
 248                          *  }
 249                          *  \endcode
 250                          *
 251                          *  \note The pipe token is set automatically, thus this can be used on bi-directional pipes directly without
 252                          *        having to explicitly change the data direction with a call to \ref Pipe_SetPipeToken().
 253                          *
 254                          *  \param[in] Buffer          Pointer to the source data buffer to read from.
 255                          *  \param[in] Length          Number of bytes to read for the currently selected pipe into the buffer.
 256                          *  \param[in] BytesProcessed  Pointer to a location where the total number of bytes already processed should
 257                          *                             updated, \c NULL if the entire stream should be written at once.
 258                          *
 259                          *  \return A value from the \ref Pipe_Stream_RW_ErrorCodes_t enum.
 260                          */
 261                         uint8_t Pipe_Write_Stream_LE(const void* const Buffer,
 262                                                      uint16_t Length,
 263                                                      uint16_t* const BytesProcessed) ATTR_NON_NULL_PTR_ARG(1);
 264
 265                         /** Writes the given number of bytes to the pipe from the given buffer in big endian,
 266                          *  sending full packets to the device as needed. The last packet filled is not automatically sent;
 267                          *  the user is responsible for manually sending the last written packet to the host via the
 268                          *  \ref Pipe_ClearOUT() macro. Between each USB packet, the given stream callback function is
 269                          *  executed repeatedly until the next packet is ready, allowing for early aborts of stream transfers.
 270                          *
 271                          *  \note The pipe token is set automatically, thus this can be used on bi-directional pipes directly without
 272                          *        having to explicitly change the data direction with a call to \ref Pipe_SetPipeToken().
 273                          *
 274                          *  \param[in] Buffer          Pointer to the source data buffer to read from.
 275                          *  \param[in] Length          Number of bytes to read for the currently selected pipe into the buffer.
 276                          *  \param[in] BytesProcessed  Pointer to a location where the total number of bytes already processed should
 277                          *                             updated, \c NULL if the entire stream should be written at once.
 278                          *
 279                          *  \return A value from the \ref Pipe_Stream_RW_ErrorCodes_t enum.
 280                          */
 281                         uint8_t Pipe_Write_Stream_BE(const void* const Buffer,
 282                                                      uint16_t Length,
 283                                                      uint16_t* const BytesProcessed) ATTR_NON_NULL_PTR_ARG(1);
 284
 285                         /** Reads the given number of bytes from the pipe into the given buffer in little endian,
 286                          *  sending full packets to the device as needed. The last packet filled is not automatically sent;
 287                          *  the user is responsible for manually sending the last written packet to the host via the
 288                          *  \ref Pipe_ClearIN() macro. Between each USB packet, the given stream callback function is
 289                          *  executed repeatedly until the next packet is ready, allowing for early aborts of stream transfers.
 290                          *
 291                          *  If the BytesProcessed parameter is \c NULL, the entire stream transfer is attempted at once,
 292                          *  failing or succeeding as a single unit. If the BytesProcessed parameter points to a valid
 293                          *  storage location, the transfer will instead be performed as a series of chunks. Each time
 294                          *  the pipe bank becomes empty while there is still data to process (and after the current
 295                          *  packet has been acknowledged) the BytesProcessed location will be updated with the total number
 296                          *  of bytes processed in the stream, and the function will exit with an error code of
 297                          *  \ref PIPE_RWSTREAM_IncompleteTransfer. This allows for any abort checking to be performed
 298                          *  in the user code - to continue the transfer, call the function again with identical parameters
 299                          *  and it will resume until the BytesProcessed value reaches the total transfer length.
 300                          *
 301                          *  <b>Single Stream Transfer Example:</b>
 302                          *  \code
 303                          *  uint8_t DataStream[512];
 304                          *  uint8_t ErrorCode;
 305                          *
 306                          *  if ((ErrorCode = Pipe_Read_Stream_LE(DataStream, sizeof(DataStream),
 307                          *                                       NULL)) != PIPE_RWSTREAM_NoError)
 308                          *  {
 309                          *       // Stream failed to complete - check ErrorCode here
 310                          *  }
 311                          *  \endcode
 312                          *
 313                          *  <b>Partial Stream Transfers Example:</b>
 314                          *  \code
 315                          *  uint8_t  DataStream[512];
 316                          *  uint8_t  ErrorCode;
 317                          *  uint16_t BytesProcessed;
 318                          *
 319                          *  BytesProcessed = 0;
 320                          *  while ((ErrorCode = Pipe_Read_Stream_LE(DataStream, sizeof(DataStream),
 321                          *                                          &BytesProcessed)) == PIPE_RWSTREAM_IncompleteTransfer)
 322                          *  {
 323                          *      // Stream not yet complete - do other actions here, abort if required
 324                          *  }
 325                          *
 326                          *  if (ErrorCode != PIPE_RWSTREAM_NoError)
 327                          *  {
 328                          *      // Stream failed to complete - check ErrorCode here
 329                          *  }
 330                          *  \endcode
 331                          *
 332                          *  \note The pipe token is set automatically, thus this can be used on bi-directional pipes directly without
 333                          *        having to explicitly change the data direction with a call to \ref Pipe_SetPipeToken().
 334                          *
 335                          *  \param[out] Buffer          Pointer to the source data buffer to write to.
 336                          *  \param[in]  Length          Number of bytes to read for the currently selected pipe to read from.
 337                          *  \param[in]  BytesProcessed  Pointer to a location where the total number of bytes already processed should
 338                          *                              updated, \c NULL if the entire stream should be read at once.
 339                          *
 340                          *  \return A value from the \ref Pipe_Stream_RW_ErrorCodes_t enum.
 341                          */
 342                         uint8_t Pipe_Read_Stream_LE(void* const Buffer,
 343                                                     uint16_t Length,
 344                                                     uint16_t* const BytesProcessed) ATTR_NON_NULL_PTR_ARG(1);
 345
 346                         /** Reads the given number of bytes from the pipe into the given buffer in big endian,
 347                          *  sending full packets to the device as needed. The last packet filled is not automatically sent;
 348                          *  the user is responsible for manually sending the last written packet to the host via the
 349                          *  \ref Pipe_ClearIN() macro. Between each USB packet, the given stream callback function is
 350                          *  executed repeatedly until the next packet is ready, allowing for early aborts of stream transfers.
 351                          *
 352                          *  \note The pipe token is set automatically, thus this can be used on bi-directional pipes directly without
 353                          *        having to explicitly change the data direction with a call to \ref Pipe_SetPipeToken().
 354                          *
 355                          *  \param[out] Buffer          Pointer to the source data buffer to write to.
 356                          *  \param[in]  Length          Number of bytes to read for the currently selected pipe to read from.
 357                          *  \param[in]  BytesProcessed  Pointer to a location where the total number of bytes already processed should
 358                          *                              updated, \c NULL if the entire stream should be read at once.
 359                          *
 360                          *  \return A value from the \ref Pipe_Stream_RW_ErrorCodes_t enum.
 361                          */
 362                         uint8_t Pipe_Read_Stream_BE(void* const Buffer,
 363                                                     uint16_t Length,
 364                                                     uint16_t* const BytesProcessed) ATTR_NON_NULL_PTR_ARG(1);
 365                         //@}
 366
 367                         /** \name Stream functions for EEPROM source/destination data */
 368                         //@{
 369
 370                         /** EEPROM buffer source version of \ref Pipe_Write_Stream_LE().
 371                          *
 372                          *  \param[in] Buffer          Pointer to the source data buffer to read from.
 373                          *  \param[in] Length          Number of bytes to read for the currently selected pipe into the buffer.
 374                          *  \param[in] BytesProcessed  Pointer to a location where the total number of bytes already processed should
 375                          *                             updated, \c NULL if the entire stream should be written at once.
 376                          *
 377                          *  \return A value from the \ref Pipe_Stream_RW_ErrorCodes_t enum.
 378                          */
 379                         uint8_t Pipe_Write_EStream_LE(const void* const Buffer,
 380                                                       uint16_t Length,
 381                                                       uint16_t* const BytesProcessed) ATTR_NON_NULL_PTR_ARG(1);
 382
 383                         /** EEPROM buffer source version of \ref Pipe_Write_Stream_BE().
 384                          *
 385                          *  \param[in] Buffer          Pointer to the source data buffer to read from.
 386                          *  \param[in] Length          Number of bytes to read for the currently selected pipe into the buffer.
 387                          *  \param[in] BytesProcessed  Pointer to a location where the total number of bytes already processed should
 388                          *                             updated, \c NULL if the entire stream should be written at once.
 389                          *
 390                          *  \return A value from the \ref Pipe_Stream_RW_ErrorCodes_t enum.
 391                          */
 392                         uint8_t Pipe_Write_EStream_BE(const void* const Buffer,
 393                                                       uint16_t Length,
 394                                                       uint16_t* const BytesProcessed) ATTR_NON_NULL_PTR_ARG(1);
 395
 396                         /** EEPROM buffer source version of \ref Pipe_Read_Stream_LE().
 397                          *
 398                          *  \param[out] Buffer          Pointer to the source data buffer to write to.
 399                          *  \param[in]  Length          Number of bytes to read for the currently selected pipe to read from.
 400                          *  \param[in]  BytesProcessed  Pointer to a location where the total number of bytes already processed should
 401                          *                              updated, \c NULL if the entire stream should be read at once.
 402                          *
 403                          *  \return A value from the \ref Pipe_Stream_RW_ErrorCodes_t enum.
 404                          */
 405                         uint8_t Pipe_Read_EStream_LE(void* const Buffer,
 406                                                      uint16_t Length,
 407                                                      uint16_t* const BytesProcessed) ATTR_NON_NULL_PTR_ARG(1);
 408
 409                         /** EEPROM buffer source version of \ref Pipe_Read_Stream_BE().
 410                          *
 411                          *  \param[out] Buffer          Pointer to the source data buffer to write to.
 412                          *  \param[in]  Length          Number of bytes to read for the currently selected pipe to read from.
 413                          *  \param[in]  BytesProcessed  Pointer to a location where the total number of bytes already processed should
 414                          *                              updated, \c NULL if the entire stream should be read at once.
 415                          *
 416                          *  \return A value from the \ref Pipe_Stream_RW_ErrorCodes_t enum.
 417                          */
 418                         uint8_t Pipe_Read_EStream_BE(void* const Buffer,
 419                                                      uint16_t Length,
 420                                                      uint16_t* const BytesProcessed) ATTR_NON_NULL_PTR_ARG(1);
 421                         //@}
 422
 423                         /** \name Stream functions for PROGMEM source/destination data */
 424                         //@{
 425
 426                         /** FLASH buffer source version of \ref Pipe_Write_Stream_LE().
 427                          *
 428                          *  \pre The FLASH data must be located in the first 64KB of FLASH for this function to work correctly.
 429                          *
 430                          *  \param[in] Buffer          Pointer to the source data buffer to read from.
 431                          *  \param[in] Length          Number of bytes to read for the currently selected pipe into the buffer.
 432                          *  \param[in] BytesProcessed  Pointer to a location where the total number of bytes already processed should
 433                          *                             updated, \c NULL if the entire stream should be written at once.
 434                          *
 435                          *  \return A value from the \ref Pipe_Stream_RW_ErrorCodes_t enum.
 436                          */
 437                         uint8_t Pipe_Write_PStream_LE(const void* const Buffer,
 438                                                       uint16_t Length,
 439                                                       uint16_t* const BytesProcessed) ATTR_NON_NULL_PTR_ARG(1);
 440
 441                         /** FLASH buffer source version of \ref Pipe_Write_Stream_BE().
 442                          *
 443                          *  \pre The FLASH data must be located in the first 64KB of FLASH for this function to work correctly.
 444                          *
 445                          *  \param[in] Buffer          Pointer to the source data buffer to read from.
 446                          *  \param[in] Length          Number of bytes to read for the currently selected pipe into the buffer.
 447                          *  \param[in] BytesProcessed  Pointer to a location where the total number of bytes already processed should
 448                          *                             updated, \c NULL if the entire stream should be written at once.
 449                          *
 450                          *  \return A value from the \ref Pipe_Stream_RW_ErrorCodes_t enum.
 451                          */
 452                         uint8_t Pipe_Write_PStream_BE(const void* const Buffer,
 453                                                       uint16_t Length,
 454                                                       uint16_t* const BytesProcessed) ATTR_NON_NULL_PTR_ARG(1);
 455                         //@}
 456
 457         /* Disable C linkage for C++ Compilers: */
 458                 #if defined(__cplusplus)
 459                         }
 460                 #endif
 461
 462 #endif
 463
 464 /** @} */
 465