LUFA/Drivers/USB/Core/AVR8/PipeStream_AVR8.h

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