LUFA/Drivers/USB/Core/UC3/PipeStream_UC3.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 Pipe data stream transmission and reception management for the AVR32 UC3 microcontrollers.
  33  *  \copydetails Group_PipeStreamRW_UC3
  34  *
  35  *  \note This file should not be included directly. It is automatically included as needed by the USB driver
  36  *        dispatch header located in LUFA/Drivers/USB/USB.h.
  37  */
  38
  39 /** \ingroup Group_PipeStreamRW
  40  *  \defgroup Group_PipeStreamRW_UC3 Read/Write of Multi-Byte Streams (UC3)
  41  *  \brief Pipe data stream transmission and reception management for the Atmel AVR32 UC3 architecture.
  42  *
  43  *  Functions, macros, variables, enums and types related to data reading and writing of data streams from
  44  *  and to pipes.
  45  *
  46  *  @{
  47  */
  48
  49 #ifndef __PIPE_STREAM_UC3_H__
  50 #define __PIPE_STREAM_UC3_H__
  51
  52         /* Includes: */
  53                 #include "../../../../Common/Common.h"
  54                 #include "../USBMode.h"
  55
  56         /* Enable C linkage for C++ Compilers: */
  57                 #if defined(__cplusplus)
  58                         extern "C" {
  59                 #endif
  60
  61         /* Preprocessor Checks: */
  62                 #if !defined(__INCLUDE_FROM_USB_DRIVER)
  63                         #error Do not include this file directly. Include LUFA/Drivers/USB/USB.h instead.
  64                 #endif
  65
  66         /* Public Interface - May be used in end-application: */
  67                 /* Function Prototypes: */
  68                         /** \name Stream functions for null data */
  69                         //@{
  70
  71                         /** Reads and discards the given number of bytes from the pipe, discarding fully read packets from the host
  72                          *  as needed. The last packet is not automatically discarded once the remaining bytes has been read; the
  73                          *  user is responsible for manually discarding the last packet from the device via the \ref Pipe_ClearIN() macro.
  74                          *
  75                          *  If the BytesProcessed parameter is \c NULL, the entire stream transfer is attempted at once, failing or
  76                          *  succeeding as a single unit. If the BytesProcessed parameter points to a valid storage location, the transfer
  77                          *  will instead be performed as a series of chunks. Each time the pipe bank becomes empty while there is still data
  78                          *  to process (and after the current packet has been acknowledged) the BytesProcessed location will be updated with
  79                          *  the total number of bytes processed in the stream, and the function will exit with an error code of
  80                          *  \ref PIPE_RWSTREAM_IncompleteTransfer. This allows for any abort checking to be performed in the user code - to
  81                          *  continue the transfer, call the function again with identical parameters and it will resume until the BytesProcessed
  82                          *  value reaches the total transfer length.
  83                          *
  84                          *  <b>Single Stream Transfer Example:</b>
  85                          *  \code
  86                          *  uint8_t ErrorCode;
  87                          *
  88                          *  if ((ErrorCode = Pipe_Discard_Stream(512, NULL)) != PIPE_RWSTREAM_NoError)
  89                          *  {
  90                          *       // Stream failed to complete - check ErrorCode here
  91                          *  }
  92                          *  \endcode
  93                          *
  94                          *  <b>Partial Stream Transfers Example:</b>
  95                          *  \code
  96                          *  uint8_t  ErrorCode;
  97                          *  uint16_t BytesProcessed;
  98                          *
  99                          *  BytesProcessed = 0;
 100                          *  while ((ErrorCode = Pipe_Discard_Stream(512, &BytesProcessed)) == PIPE_RWSTREAM_IncompleteTransfer)
 101                          *  {
 102                          *      // Stream not yet complete - do other actions here, abort if required
 103                          *  }
 104                          *
 105                          *  if (ErrorCode != PIPE_RWSTREAM_NoError)
 106                          *  {
 107                          *      // Stream failed to complete - check ErrorCode here
 108                          *  }
 109                          *  \endcode
 110                          *
 111                          *  \note The pipe token is set automatically, thus this can be used on bi-directional pipes directly without
 112                          *        having to explicitly change the data direction with a call to \ref Pipe_SetPipeToken().
 113                          *
 114                          *  \param[in] Length          Number of bytes to discard via the currently selected pipe.
 115                          *  \param[in] BytesProcessed  Pointer to a location where the total number of bytes already processed should
 116                          *                             updated, \c NULL if the entire stream should be processed at once.
 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                                                     uint16_t* const BytesProcessed);
 122
 123                         /** Writes a given number of zeroed bytes to the pipe, sending full pipe packets from the host to the device
 124                          *  as needed. The last packet is not automatically sent once the remaining bytes has been written; the
 125                          *  user is responsible for manually discarding the last packet from the device via the \ref Pipe_ClearOUT() macro.
 126                          *
 127                          *  If the BytesProcessed parameter is \c NULL, the entire stream transfer is attempted at once, failing or
 128                          *  succeeding as a single unit. If the BytesProcessed parameter points to a valid storage location, the transfer
 129                          *  will instead be performed as a series of chunks. Each time the pipe bank becomes full while there is still data
 130                          *  to process (and after the current packet transmission has been initiated) the BytesProcessed location will be
 131                          *  updated with the total number of bytes processed in the stream, and the function will exit with an error code of
 132                          *  \ref PIPE_RWSTREAM_IncompleteTransfer. This allows for any abort checking to be performed in the user code - to
 133                          *  continue the transfer, call the function again with identical parameters and it will resume until the BytesProcessed
 134                          *  value reaches the total transfer length.
 135                          *
 136                          *  <b>Single Stream Transfer Example:</b>
 137                          *  \code
 138                          *  uint8_t ErrorCode;
 139                          *
 140                          *  if ((ErrorCode = Pipe_Null_Stream(512, NULL)) != PIPE_RWSTREAM_NoError)
 141                          *  {
 142                          *       // Stream failed to complete - check ErrorCode here
 143                          *  }
 144                          *  \endcode
 145                          *
 146                          *  <b>Partial Stream Transfers Example:</b>
 147                          *  \code
 148                          *  uint8_t  ErrorCode;
 149                          *  uint16_t BytesProcessed;
 150                          *
 151                          *  BytesProcessed = 0;
 152                          *  while ((ErrorCode = Pipe_Null_Stream(512, &BytesProcessed)) == PIPE_RWSTREAM_IncompleteTransfer)
 153                          *  {
 154                          *      // Stream not yet complete - do other actions here, abort if required
 155                          *  }
 156                          *
 157                          *  if (ErrorCode != PIPE_RWSTREAM_NoError)
 158                          *  {
 159                          *      // Stream failed to complete - check ErrorCode here
 160                          *  }
 161                          *  \endcode
 162                          *
 163                          *  \note The pipe token is set automatically, thus this can be used on bi-directional pipes directly without
 164                          *        having to explicitly change the data direction with a call to \ref Pipe_SetPipeToken().
 165                          *
 166                          *  \param[in] Length          Number of zero bytes to write via the currently selected pipe.
 167                          *  \param[in] BytesProcessed  Pointer to a location where the total number of bytes already processed should
 168                          *                             updated, \c NULL if the entire stream should be processed at once.
 169                          *
 170                          *  \return A value from the \ref Pipe_Stream_RW_ErrorCodes_t enum.
 171                          */
 172                         uint8_t Pipe_Null_Stream(uint16_t Length,
 173                                                  uint16_t* const BytesProcessed);
 174
 175                         //@}
 176
 177                         /** \name Stream functions for RAM source/destination data */
 178                         //@{
 179
 180                         /** Writes the given number of bytes to the pipe from the given buffer in little endian,
 181                          *  sending full packets to the device as needed. The last packet filled is not automatically sent;
 182                          *  the user is responsible for manually sending the last written packet to the host via the
 183                          *  \ref Pipe_ClearOUT() macro. Between each USB packet, the given stream callback function is
 184                          *  executed repeatedly until the next packet is ready, allowing for early aborts of stream transfers.
 185                          *
 186                          *  If the BytesProcessed parameter is \c NULL, the entire stream transfer is attempted at once,
 187                          *  failing or succeeding as a single unit. If the BytesProcessed parameter points to a valid
 188                          *  storage location, the transfer will instead be performed as a series of chunks. Each time
 189                          *  the pipe bank becomes full while there is still data to process (and after the current
 190                          *  packet transmission has been initiated) the BytesProcessed location will be updated with the
 191                          *  total number of bytes processed in the stream, and the function will exit with an error code of
 192                          *  \ref PIPE_RWSTREAM_IncompleteTransfer. This allows for any abort checking to be performed
 193                          *  in the user code - to continue the transfer, call the function again with identical parameters
 194                          *  and it will resume until the BytesProcessed value reaches the total transfer length.
 195                          *
 196                          *  <b>Single Stream Transfer Example:</b>
 197                          *  \code
 198                          *  uint8_t DataStream[512];
 199                          *  uint8_t ErrorCode;
 200                          *
 201                          *  if ((ErrorCode = Pipe_Write_Stream_LE(DataStream, sizeof(DataStream),
 202                          *                                        NULL)) != PIPE_RWSTREAM_NoError)
 203                          *  {
 204                          *       // Stream failed to complete - check ErrorCode here
 205                          *  }
 206                          *  \endcode
 207                          *
 208                          *  <b>Partial Stream Transfers Example:</b>
 209                          *  \code
 210                          *  uint8_t  DataStream[512];
 211                          *  uint8_t  ErrorCode;
 212                          *  uint16_t BytesProcessed;
 213                          *
 214                          *  BytesProcessed = 0;
 215                          *  while ((ErrorCode = Pipe_Write_Stream_LE(DataStream, sizeof(DataStream),
 216                          *                                           &BytesProcessed)) == PIPE_RWSTREAM_IncompleteTransfer)
 217                          *  {
 218                          *      // Stream not yet complete - do other actions here, abort if required
 219                          *  }
 220                          *
 221                          *  if (ErrorCode != PIPE_RWSTREAM_NoError)
 222                          *  {
 223                          *      // Stream failed to complete - check ErrorCode here
 224                          *  }
 225                          *  \endcode
 226                          *
 227                          *  \note The pipe token is set automatically, thus this can be used on bi-directional pipes directly without
 228                          *        having to explicitly change the data direction with a call to \ref Pipe_SetPipeToken().
 229                          *
 230                          *  \param[in] Buffer          Pointer to the source data buffer to read from.
 231                          *  \param[in] Length          Number of bytes to read for the currently selected pipe into the buffer.
 232                          *  \param[in] BytesProcessed  Pointer to a location where the total number of bytes already processed should
 233                          *                             updated, \c NULL if the entire stream should be written at once.
 234                          *
 235                          *  \return A value from the \ref Pipe_Stream_RW_ErrorCodes_t enum.
 236                          */
 237                         uint8_t Pipe_Write_Stream_LE(const void* const Buffer,
 238                                                      uint16_t Length,
 239                                                      uint16_t* const BytesProcessed) ATTR_NON_NULL_PTR_ARG(1);
 240
 241                         /** Writes the given number of bytes to the pipe from the given buffer in big endian,
 242                          *  sending full packets to the device as needed. The last packet filled is not automatically sent;
 243                          *  the user is responsible for manually sending the last written packet to the host via the
 244                          *  \ref Pipe_ClearOUT() macro. Between each USB packet, the given stream callback function is
 245                          *  executed repeatedly until the next packet is ready, allowing for early aborts of stream transfers.
 246                          *
 247                          *  \note The pipe token is set automatically, thus this can be used on bi-directional pipes directly without
 248                          *        having to explicitly change the data direction with a call to \ref Pipe_SetPipeToken().
 249                          *
 250                          *  \param[in] Buffer          Pointer to the source data buffer to read from.
 251                          *  \param[in] Length          Number of bytes to read for the currently selected pipe into the buffer.
 252                          *  \param[in] BytesProcessed  Pointer to a location where the total number of bytes already processed should
 253                          *                             updated, \c NULL if the entire stream should be written at once.
 254                          *
 255                          *  \return A value from the \ref Pipe_Stream_RW_ErrorCodes_t enum.
 256                          */
 257                         uint8_t Pipe_Write_Stream_BE(const void* const Buffer,
 258                                                      uint16_t Length,
 259                                                      uint16_t* const BytesProcessed) ATTR_NON_NULL_PTR_ARG(1);
 260
 261                         /** Reads the given number of bytes from the pipe into the given buffer in little endian,
 262                          *  sending full packets to the device as needed. The last packet filled is not automatically sent;
 263                          *  the user is responsible for manually sending the last written packet to the host via the
 264                          *  \ref Pipe_ClearIN() macro. Between each USB packet, the given stream callback function is
 265                          *  executed repeatedly until the next packet is ready, allowing for early aborts of stream transfers.
 266                          *
 267                          *  If the BytesProcessed parameter is \c NULL, the entire stream transfer is attempted at once,
 268                          *  failing or succeeding as a single unit. If the BytesProcessed parameter points to a valid
 269                          *  storage location, the transfer will instead be performed as a series of chunks. Each time
 270                          *  the pipe bank becomes empty while there is still data to process (and after the current
 271                          *  packet has been acknowledged) the BytesProcessed location will be updated with the total number
 272                          *  of bytes processed in the stream, and the function will exit with an error code of
 273                          *  \ref PIPE_RWSTREAM_IncompleteTransfer. This allows for any abort checking to be performed
 274                          *  in the user code - to continue the transfer, call the function again with identical parameters
 275                          *  and it will resume until the BytesProcessed value reaches the total transfer length.
 276                          *
 277                          *  <b>Single Stream Transfer Example:</b>
 278                          *  \code
 279                          *  uint8_t DataStream[512];
 280                          *  uint8_t ErrorCode;
 281                          *
 282                          *  if ((ErrorCode = Pipe_Read_Stream_LE(DataStream, sizeof(DataStream),
 283                          *                                       NULL)) != PIPE_RWSTREAM_NoError)
 284                          *  {
 285                          *       // Stream failed to complete - check ErrorCode here
 286                          *  }
 287                          *  \endcode
 288                          *
 289                          *  <b>Partial Stream Transfers Example:</b>
 290                          *  \code
 291                          *  uint8_t  DataStream[512];
 292                          *  uint8_t  ErrorCode;
 293                          *  uint16_t BytesProcessed;
 294                          *
 295                          *  BytesProcessed = 0;
 296                          *  while ((ErrorCode = Pipe_Read_Stream_LE(DataStream, sizeof(DataStream),
 297                          *                                          &BytesProcessed)) == PIPE_RWSTREAM_IncompleteTransfer)
 298                          *  {
 299                          *      // Stream not yet complete - do other actions here, abort if required
 300                          *  }
 301                          *
 302                          *  if (ErrorCode != PIPE_RWSTREAM_NoError)
 303                          *  {
 304                          *      // Stream failed to complete - check ErrorCode here
 305                          *  }
 306                          *  \endcode
 307                          *
 308                          *  \note The pipe token is set automatically, thus this can be used on bi-directional pipes directly without
 309                          *        having to explicitly change the data direction with a call to \ref Pipe_SetPipeToken().
 310                          *
 311                          *  \param[out] Buffer          Pointer to the source data buffer to write to.
 312                          *  \param[in]  Length          Number of bytes to read for the currently selected pipe to read from.
 313                          *  \param[in]  BytesProcessed  Pointer to a location where the total number of bytes already processed should
 314                          *                              updated, \c NULL if the entire stream should be read at once.
 315                          *
 316                          *  \return A value from the \ref Pipe_Stream_RW_ErrorCodes_t enum.
 317                          */
 318                         uint8_t Pipe_Read_Stream_LE(void* const Buffer,
 319                                                     uint16_t Length,
 320                                                     uint16_t* const BytesProcessed) ATTR_NON_NULL_PTR_ARG(1);
 321
 322                         /** Reads the given number of bytes from the pipe into the given buffer in big endian,
 323                          *  sending full packets to the device as needed. The last packet filled is not automatically sent;
 324                          *  the user is responsible for manually sending the last written packet to the host via the
 325                          *  \ref Pipe_ClearIN() macro. Between each USB packet, the given stream callback function is
 326                          *  executed repeatedly until the next packet is ready, allowing for early aborts of stream transfers.
 327                          *
 328                          *  \note The pipe token is set automatically, thus this can be used on bi-directional pipes directly without
 329                          *        having to explicitly change the data direction with a call to \ref Pipe_SetPipeToken().
 330                          *
 331                          *  \param[out] Buffer          Pointer to the source data buffer to write to.
 332                          *  \param[in]  Length          Number of bytes to read for the currently selected pipe to read from.
 333                          *  \param[in]  BytesProcessed  Pointer to a location where the total number of bytes already processed should
 334                          *                              updated, \c NULL if the entire stream should be read at once.
 335                          *
 336                          *  \return A value from the \ref Pipe_Stream_RW_ErrorCodes_t enum.
 337                          */
 338                         uint8_t Pipe_Read_Stream_BE(void* const Buffer,
 339                                                     uint16_t Length,
 340                                                     uint16_t* const BytesProcessed) ATTR_NON_NULL_PTR_ARG(1);
 341                         //@}
 342
 343         /* Disable C linkage for C++ Compilers: */
 344                 #if defined(__cplusplus)
 345                         }
 346                 #endif
 347
 348 #endif
 349
 350 /** @} */
 351