LUFA/Drivers/USB/HighLevel/EndpointStream.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 device endpoint 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 endpoints when the library is initialized in USB device 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_EndpointRW
  42  *  @defgroup Group_EndpointStreamRW 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 endpoints.
  46  *
  47  *  @{
  48  */
  49
  50 #ifndef __ENDPOINT_STREAM_H__
  51 #define __ENDPOINT_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 Endpoint_*_Stream_* functions. */
  85                         enum Endpoint_Stream_RW_ErrorCodes_t
  86                         {
  87                                 ENDPOINT_RWSTREAM_NoError            = 0, /**< Command completed successfully, no error. */
  88                                 ENDPOINT_RWSTREAM_EndpointStalled    = 1, /**< The endpoint was stalled during the stream
  89                                                                            *   transfer by the host or device.
  90                                                                            */
  91                                 ENDPOINT_RWSTREAM_DeviceDisconnected = 2, /**< Device was disconnected from the host during
  92                                                                            *   the transfer.
  93                                                                            */
  94                                 ENDPOINT_RWSTREAM_BusSuspended       = 3, /**< The USB bus has been suspended by the host and
  95                                                                            *   no USB endpoint traffic can occur until the bus
  96                                                                            *   has resumed.
  97                                                                            */
  98                                 ENDPOINT_RWSTREAM_Timeout            = 4, /**< The host failed to accept or send the next packet
  99                                                                            *   within the software timeout period set by the
 100                                                                            *   \ref USB_STREAM_TIMEOUT_MS macro.
 101                                                                            */
 102                                 ENDPOINT_RWSTREAM_CallbackAborted    = 5, /**< Indicates that the stream's callback function
 103                                                                        *   aborted the transfer early.
 104                                                                            */
 105                         };
 106
 107                         /** Enum for the possible error return codes of the Endpoint_*_Control_Stream_* functions. */
 108                         enum Endpoint_ControlStream_RW_ErrorCodes_t
 109                         {
 110                                 ENDPOINT_RWCSTREAM_NoError            = 0, /**< Command completed successfully, no error. */
 111                                 ENDPOINT_RWCSTREAM_HostAborted        = 1, /**< The aborted the transfer prematurely. */
 112                                 ENDPOINT_RWCSTREAM_DeviceDisconnected = 2, /**< Device was disconnected from the host during
 113                                                                             *   the transfer.
 114                                                                             */
 115                                 ENDPOINT_RWCSTREAM_BusSuspended       = 3, /**< The USB bus has been suspended by the host and
 116                                                                             *   no USB endpoint traffic can occur until the bus
 117                                                                             *   has resumed.
 118                                                                             */
 119                         };
 120
 121                 /* Function Prototypes: */
 122                         /** Reads and discards the given number of bytes from the endpoint from the given buffer,
 123                          *  discarding fully read packets from the host as needed. The last packet is not automatically
 124                          *  discarded once the remaining bytes has been read; the user is responsible for manually
 125                          *  discarding the last packet from the host via the \ref Endpoint_ClearOUT() macro. Between
 126                          *  each USB packet, the given stream callback function is executed repeatedly until the next
 127                          *  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                          *  \note This routine should not be used on CONTROL type endpoints.
 134                          *
 135                          *  \param[in] Length    Number of bytes to send via the currently selected endpoint.
 136                          *  \param[in] Callback  Name of a callback routine to call between successive USB packet transfers, NULL if no callback.
 137                          *
 138                          *  \return A value from the \ref Endpoint_Stream_RW_ErrorCodes_t enum.
 139                          */
 140                         uint8_t Endpoint_Discard_Stream(uint16_t Length
 141                                                         __CALLBACK_PARAM);
 142
 143                         /** Writes the given number of bytes to the endpoint from the given buffer in little endian,
 144                          *  sending full packets to the host as needed. The last packet filled is not automatically sent;
 145                          *  the user is responsible for manually sending the last written packet to the host via the
 146                          *  \ref Endpoint_ClearIN() macro. Between each USB packet, the given stream callback function
 147                          *  is executed repeatedly until the endpoint is ready to accept the next packet, allowing for early
 148                          *  aborts of stream transfers.
 149                          *
 150                          *      The callback routine should be created according to the information in \ref Group_StreamCallbacks.
 151                          *  If the token NO_STREAM_CALLBACKS is passed via the -D option to the compiler, stream callbacks are
 152                          *  disabled and this function has the Callback parameter omitted.
 153                          *
 154                          *  \note This routine should not be used on CONTROL type endpoints.
 155                          *
 156                          *  \param[in] Buffer    Pointer to the source data buffer to read from.
 157                          *  \param[in] Length    Number of bytes to read for the currently selected endpoint into the buffer.
 158                          *  \param[in] Callback  Name of a callback routine to call between successive USB packet transfers, NULL if no callback.
 159                          *
 160                          *  \return A value from the \ref Endpoint_Stream_RW_ErrorCodes_t enum.
 161                          */
 162                         uint8_t Endpoint_Write_Stream_LE(const void* Buffer,
 163                                                          uint16_t Length
 164                                                          __CALLBACK_PARAM) ATTR_NON_NULL_PTR_ARG(1);
 165
 166                         /** EEPROM buffer source version of \ref Endpoint_Write_Stream_LE().
 167                          *
 168                          *  \param[in] Buffer    Pointer to the source data buffer to read from.
 169                          *  \param[in] Length    Number of bytes to read for the currently selected endpoint into the buffer.
 170                          *  \param[in] Callback  Name of a callback routine to call between successive USB packet transfers, NULL if no callback.
 171                          *
 172                          *  \return A value from the \ref Endpoint_Stream_RW_ErrorCodes_t enum.
 173                          */
 174                         uint8_t Endpoint_Write_EStream_LE(const void* Buffer,
 175                                                           uint16_t Length
 176                                                           __CALLBACK_PARAM) ATTR_NON_NULL_PTR_ARG(1);
 177
 178                         /** FLASH buffer source version of \ref Endpoint_Write_Stream_LE().
 179                          *
 180                          *  \pre The FLASH data must be located in the first 64KB of FLASH for this function to work correctly.
 181                          *
 182                          *  \param[in] Buffer    Pointer to the source data buffer to read from.
 183                          *  \param[in] Length    Number of bytes to read for the currently selected endpoint into the buffer.
 184                          *  \param[in] Callback  Name of a callback routine to call between successive USB packet transfers, NULL if no callback.
 185                          *
 186                          *  \return A value from the \ref Endpoint_Stream_RW_ErrorCodes_t enum.
 187                          */
 188                         uint8_t Endpoint_Write_PStream_LE(const void* Buffer,
 189                                                           uint16_t Length
 190                                                           __CALLBACK_PARAM) ATTR_NON_NULL_PTR_ARG(1);
 191
 192                         /** Writes the given number of bytes to the endpoint from the given buffer in big endian,
 193                          *  sending full packets to the host as needed. The last packet filled is not automatically sent;
 194                          *  the user is responsible for manually sending the last written packet to the host via the
 195                          *  \ref Endpoint_ClearIN() macro. Between each USB packet, the given stream callback function
 196                          *  is executed repeatedly until the endpoint is ready to accept the next packet, allowing for early
 197                          *  aborts of stream transfers.
 198                          *
 199                          *      The callback routine should be created according to the information in \ref Group_StreamCallbacks.
 200                          *  If the token NO_STREAM_CALLBACKS is passed via the -D option to the compiler, stream callbacks are
 201                          *  disabled and this function has the Callback parameter omitted.
 202                          *
 203                          *  \note This routine should not be used on CONTROL type endpoints.
 204                          *
 205                          *  \param[in] Buffer    Pointer to the source data buffer to read from.
 206                          *  \param[in] Length    Number of bytes to read for the currently selected endpoint into the buffer.
 207                          *  \param[in] Callback  Name of a callback routine to call between successive USB packet transfers, NULL if no callback.
 208                          *
 209                          *  \return A value from the \ref Endpoint_Stream_RW_ErrorCodes_t enum.
 210                          */
 211                         uint8_t Endpoint_Write_Stream_BE(const void* Buffer,
 212                                                          uint16_t Length
 213                                                          __CALLBACK_PARAM) ATTR_NON_NULL_PTR_ARG(1);
 214
 215                         /** EEPROM buffer source version of \ref Endpoint_Write_Stream_BE().
 216                          *
 217                          *  \param[in] Buffer    Pointer to the source data buffer to read from.
 218                          *  \param[in] Length    Number of bytes to read for the currently selected endpoint into the buffer.
 219                          *  \param[in] Callback  Name of a callback routine to call between successive USB packet transfers, NULL if no callback.
 220                          *
 221                          *  \return A value from the \ref Endpoint_Stream_RW_ErrorCodes_t enum.
 222                          */
 223                         uint8_t Endpoint_Write_EStream_BE(const void* Buffer,
 224                                                           uint16_t Length
 225                                                           __CALLBACK_PARAM) ATTR_NON_NULL_PTR_ARG(1);
 226
 227                         /** FLASH buffer source version of \ref Endpoint_Write_Stream_BE().
 228                          *
 229                          *  \pre The FLASH data must be located in the first 64KB of FLASH for this function to work correctly.
 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 endpoint into the buffer.
 233                          *  \param[in] Callback  Name of a callback routine to call between successive USB packet transfers, NULL if no callback.
 234                          *
 235                          *  \return A value from the \ref Endpoint_Stream_RW_ErrorCodes_t enum.
 236                          */
 237                         uint8_t Endpoint_Write_PStream_BE(const void* Buffer,
 238                                                           uint16_t Length
 239                                                           __CALLBACK_PARAM) ATTR_NON_NULL_PTR_ARG(1);
 240
 241                         /** Reads the given number of bytes from the endpoint from the given buffer in little endian,
 242                          *  discarding fully read packets from the host as needed. The last packet is not automatically
 243                          *  discarded once the remaining bytes has been read; the user is responsible for manually
 244                          *  discarding the last packet from the host via the \ref Endpoint_ClearOUT() macro. Between
 245                          *  each USB packet, the given stream callback function is executed repeatedly until the endpoint
 246                          *  is ready to accept the next packet, allowing for early aborts of stream transfers.
 247                          *
 248                          *      The callback routine should be created according to the information in \ref Group_StreamCallbacks.
 249                          *  If the token NO_STREAM_CALLBACKS is passed via the -D option to the compiler, stream callbacks are
 250                          *  disabled and this function has the Callback parameter omitted.
 251                          *
 252                          *  \note This routine should not be used on CONTROL type endpoints.
 253                          *
 254                          *  \param[out] Buffer    Pointer to the destination data buffer to write to.
 255                          *  \param[in]  Length    Number of bytes to send via the currently selected endpoint.
 256                          *  \param[in]  Callback  Name of a callback routine to call between successive USB packet transfers, NULL if no callback.
 257                          *
 258                          *  \return A value from the \ref Endpoint_Stream_RW_ErrorCodes_t enum.
 259                          */
 260                         uint8_t Endpoint_Read_Stream_LE(void* Buffer,
 261                                                         uint16_t Length
 262                                                         __CALLBACK_PARAM) ATTR_NON_NULL_PTR_ARG(1);
 263
 264                         /** EEPROM buffer source version of \ref Endpoint_Read_Stream_LE().
 265                          *
 266                          *  \param[out] Buffer    Pointer to the destination data buffer to write to, located in EEPROM memory space.
 267                          *  \param[in]  Length    Number of bytes to send via the currently selected endpoint.
 268                          *  \param[in]  Callback  Name of a callback routine to call between successive USB packet transfers, NULL if no callback.
 269                          *
 270                          *  \return A value from the \ref Endpoint_Stream_RW_ErrorCodes_t enum.
 271                          */
 272                         uint8_t Endpoint_Read_EStream_LE(void* Buffer,
 273                                                          uint16_t Length
 274                                                          __CALLBACK_PARAM) ATTR_NON_NULL_PTR_ARG(1);
 275
 276                         /** Reads the given number of bytes from the endpoint from the given buffer in big endian,
 277                          *  discarding fully read packets from the host as needed. The last packet is not automatically
 278                          *  discarded once the remaining bytes has been read; the user is responsible for manually
 279                          *  discarding the last packet from the host via the \ref Endpoint_ClearOUT() macro. Between
 280                          *  each USB packet, the given stream callback function is executed repeatedly until the endpoint
 281                          *  is ready to accept the next packet, allowing for early aborts of stream transfers.
 282                          *
 283                          *      The callback routine should be created according to the information in \ref Group_StreamCallbacks.
 284                          *  If the token NO_STREAM_CALLBACKS is passed via the -D option to the compiler, stream callbacks are
 285                          *  disabled and this function has the Callback parameter omitted.
 286                          *
 287                          *  \note This routine should not be used on CONTROL type endpoints.
 288                          *
 289                          *  \param[out] Buffer    Pointer to the destination data buffer to write to.
 290                          *  \param[in]  Length    Number of bytes to send via the currently selected endpoint.
 291                          *  \param[in]  Callback  Name of a callback routine to call between successive USB packet transfers, NULL if no callback.
 292                          *
 293                          *  \return A value from the \ref Endpoint_Stream_RW_ErrorCodes_t enum.
 294                          */
 295                         uint8_t Endpoint_Read_Stream_BE(void* Buffer,
 296                                                         uint16_t Length
 297                                                         __CALLBACK_PARAM) ATTR_NON_NULL_PTR_ARG(1);
 298
 299                         /** EEPROM buffer source version of \ref Endpoint_Read_Stream_BE().
 300                          *
 301                          *  \param[out] Buffer    Pointer to the destination data buffer to write to, located in EEPROM memory space.
 302                          *  \param[in]  Length    Number of bytes to send via the currently selected endpoint.
 303                          *  \param[in]  Callback  Name of a callback routine to call between successive USB packet transfers, NULL if no callback.
 304                          *
 305                          *  \return A value from the \ref Endpoint_Stream_RW_ErrorCodes_t enum.
 306                          */
 307                         uint8_t Endpoint_Read_EStream_BE(void* Buffer,
 308                                                          uint16_t Length
 309                                                          __CALLBACK_PARAM) ATTR_NON_NULL_PTR_ARG(1);
 310
 311                         /** Writes the given number of bytes to the CONTROL type endpoint from the given buffer in little endian,
 312                          *  sending full packets to the host as needed. The host OUT acknowledgement is not automatically cleared
 313                          *  in both failure and success states; the user is responsible for manually clearing the setup OUT to
 314                          *  finalize the transfer via the \ref Endpoint_ClearOUT() macro.
 315                          *
 316                          *  \note This function automatically clears the control transfer's status stage. Do not manually attempt
 317                          *        to clear the status stage when using this routine in a control transaction.
 318                          *        \n\n
 319                          *
 320                          *  \note This routine should only be used on CONTROL type endpoints.
 321                          *
 322                          *  \warning Unlike the standard stream read/write commands, the control stream commands cannot be chained
 323                          *           together; i.e. the entire stream data must be read or written at the one time.
 324                          *
 325                          *  \param[in] Buffer  Pointer to the source data buffer to read from.
 326                          *  \param[in] Length  Number of bytes to read for the currently selected endpoint into the buffer.
 327                          *
 328                          *  \return A value from the \ref Endpoint_ControlStream_RW_ErrorCodes_t enum.
 329                          */
 330                         uint8_t Endpoint_Write_Control_Stream_LE(const void* Buffer,
 331                                                                  uint16_t Length) ATTR_NON_NULL_PTR_ARG(1);
 332
 333                         /** EEPROM buffer source version of Endpoint_Write_Control_Stream_LE.
 334                          *
 335                          *  \note This function automatically clears the control transfer's status stage. Do not manually attempt
 336                          *        to clear the status stage when using this routine in a control transaction.
 337                          *        \n\n
 338                          *
 339                          *  \note This routine should only be used on CONTROL type endpoints.
 340                          *
 341                          *  \warning Unlike the standard stream read/write commands, the control stream commands cannot be chained
 342                          *           together; i.e. the entire stream data must be read or written at the one time.
 343                          *
 344                          *  \param[in] Buffer  Pointer to the source data buffer to read from.
 345                          *  \param[in] Length  Number of bytes to read for the currently selected endpoint into the buffer.
 346                          *
 347                          *  \return A value from the \ref Endpoint_ControlStream_RW_ErrorCodes_t enum.
 348                          */
 349                         uint8_t Endpoint_Write_Control_EStream_LE(const void* Buffer,
 350                                                                   uint16_t Length) ATTR_NON_NULL_PTR_ARG(1);
 351
 352                         /** FLASH buffer source version of \ref Endpoint_Write_Control_Stream_LE().
 353                          *
 354                          *  \pre The FLASH data must be located in the first 64KB of FLASH for this function to work correctly.
 355                          *
 356                          *  \note This function automatically clears the control transfer's status stage. Do not manually attempt
 357                          *        to clear the status stage when using this routine in a control transaction.
 358                          *        \n\n
 359                          *
 360                          *  \note This routine should only be used on CONTROL type endpoints.
 361                          *
 362                          *  \warning Unlike the standard stream read/write commands, the control stream commands cannot be chained
 363                          *           together; i.e. the entire stream data must be read or written at the one time.
 364                          *
 365                          *  \param[in] Buffer  Pointer to the source data buffer to read from.
 366                          *  \param[in] Length  Number of bytes to read for the currently selected endpoint into the buffer.
 367                          *
 368                          *  \return A value from the \ref Endpoint_ControlStream_RW_ErrorCodes_t enum.
 369                          */
 370                         uint8_t Endpoint_Write_Control_PStream_LE(const void* Buffer,
 371                                                                   uint16_t Length) ATTR_NON_NULL_PTR_ARG(1);
 372
 373                         /** Writes the given number of bytes to the CONTROL type endpoint from the given buffer in big endian,
 374                          *  sending full packets to the host as needed. The host OUT acknowledgement is not automatically cleared
 375                          *  in both failure and success states; the user is responsible for manually clearing the setup OUT to
 376                          *  finalize the transfer via the \ref Endpoint_ClearOUT() macro.
 377                          *
 378                          *  \note This function automatically clears the control transfer's status stage. Do not manually attempt
 379                          *        to clear the status stage when using this routine in a control transaction.
 380                          *        \n\n
 381                          *
 382                          *  \note This routine should only be used on CONTROL type endpoints.
 383                          *
 384                          *  \warning Unlike the standard stream read/write commands, the control stream commands cannot be chained
 385                          *           together; i.e. the entire stream data must be read or written at the one time.
 386                          *
 387                          *  \param[in] Buffer  Pointer to the source data buffer to read from.
 388                          *  \param[in] Length  Number of bytes to read for the currently selected endpoint into the buffer.
 389                          *
 390                          *  \return A value from the \ref Endpoint_ControlStream_RW_ErrorCodes_t enum.
 391                          */
 392                         uint8_t Endpoint_Write_Control_Stream_BE(const void* Buffer,
 393                                                                  uint16_t Length) ATTR_NON_NULL_PTR_ARG(1);
 394
 395                         /** EEPROM buffer source version of \ref Endpoint_Write_Control_Stream_BE().
 396                          *
 397                          *  \note This function automatically clears the control transfer's status stage. Do not manually attempt
 398                          *        to clear the status stage when using this routine in a control transaction.
 399                          *        \n\n
 400                          *
 401                          *  \note This routine should only be used on CONTROL type endpoints.
 402                          *
 403                          *  \warning Unlike the standard stream read/write commands, the control stream commands cannot be chained
 404                          *           together; i.e. the entire stream data must be read or written at the one time.
 405                          *
 406                          *  \param[in] Buffer  Pointer to the source data buffer to read from.
 407                          *  \param[in] Length  Number of bytes to read for the currently selected endpoint into the buffer.
 408                          *
 409                          *  \return A value from the \ref Endpoint_ControlStream_RW_ErrorCodes_t enum.
 410                          */
 411                         uint8_t Endpoint_Write_Control_EStream_BE(const void* Buffer,
 412                                                                   uint16_t Length) ATTR_NON_NULL_PTR_ARG(1);
 413
 414                         /** FLASH buffer source version of \ref Endpoint_Write_Control_Stream_BE().
 415                          *
 416                          *  \pre The FLASH data must be located in the first 64KB of FLASH for this function to work correctly.
 417                          *
 418                          *  \note This function automatically clears the control transfer's status stage. Do not manually attempt
 419                          *        to clear the status stage when using this routine in a control transaction.
 420                          *        \n\n
 421                          *
 422                          *  \note This routine should only be used on CONTROL type endpoints.
 423                          *
 424                          *  \warning Unlike the standard stream read/write commands, the control stream commands cannot be chained
 425                          *           together; i.e. the entire stream data must be read or written at the one time.
 426                          *
 427                          *  \param[in] Buffer  Pointer to the source data buffer to read from.
 428                          *  \param[in] Length  Number of bytes to read for the currently selected endpoint into the buffer.
 429                          *
 430                          *  \return A value from the \ref Endpoint_ControlStream_RW_ErrorCodes_t enum.
 431                          */
 432                         uint8_t Endpoint_Write_Control_PStream_BE(const void* Buffer,
 433                                                                   uint16_t Length) ATTR_NON_NULL_PTR_ARG(1);
 434
 435                         /** Reads the given number of bytes from the CONTROL endpoint from the given buffer in little endian,
 436                          *  discarding fully read packets from the host as needed. The device IN acknowledgement is not
 437                          *  automatically sent after success or failure states; the user is responsible for manually sending the
 438                          *  setup IN to finalize the transfer via the \ref Endpoint_ClearIN() macro.
 439                          *
 440                          *  \note This function automatically clears the control transfer's status stage. Do not manually attempt
 441                          *        to clear the status stage when using this routine in a control transaction.
 442                          *        \n\n
 443                          *
 444                          *  \note This routine should only be used on CONTROL type endpoints.
 445                          *
 446                          *  \warning Unlike the standard stream read/write commands, the control stream commands cannot be chained
 447                          *           together; i.e. the entire stream data must be read or written at the one time.
 448                          *
 449                          *  \param[out] Buffer  Pointer to the destination data buffer to write to.
 450                          *  \param[in]  Length  Number of bytes to send via the currently selected endpoint.
 451                          *
 452                          *  \return A value from the \ref Endpoint_ControlStream_RW_ErrorCodes_t enum.
 453                          */
 454                         uint8_t Endpoint_Read_Control_Stream_LE(void* Buffer,
 455                                                                 uint16_t Length) ATTR_NON_NULL_PTR_ARG(1);
 456
 457                         /** EEPROM buffer source version of \ref Endpoint_Read_Control_Stream_LE().
 458                          *
 459                          *  \note This function automatically clears the control transfer's status stage. Do not manually attempt
 460                          *        to clear the status stage when using this routine in a control transaction.
 461                          *        \n\n
 462                          *
 463                          *  \note This routine should only be used on CONTROL type endpoints.
 464                          *
 465                          *  \warning Unlike the standard stream read/write commands, the control stream commands cannot be chained
 466                          *           together; i.e. the entire stream data must be read or written at the one time.
 467                          *
 468                          *  \param[out] Buffer  Pointer to the destination data buffer to write to.
 469                          *  \param[in]  Length  Number of bytes to send via the currently selected endpoint.
 470                          *
 471                          *  \return A value from the \ref Endpoint_ControlStream_RW_ErrorCodes_t enum.
 472                          */
 473                         uint8_t Endpoint_Read_Control_EStream_LE(void* Buffer,
 474                                                                  uint16_t Length) ATTR_NON_NULL_PTR_ARG(1);
 475
 476                         /** Reads the given number of bytes from the CONTROL endpoint from the given buffer in big endian,
 477                          *  discarding fully read packets from the host as needed. The device IN acknowledgement is not
 478                          *  automatically sent after success or failure states; the user is responsible for manually sending the
 479                          *  setup IN to finalize the transfer via the \ref Endpoint_ClearIN() macro.
 480                          *
 481                          *  \note This function automatically clears the control transfer's status stage. Do not manually attempt
 482                          *        to clear the status stage when using this routine in a control transaction.
 483                          *        \n\n
 484                          *
 485                          *  \note This routine should only be used on CONTROL type endpoints.
 486                          *
 487                          *  \warning Unlike the standard stream read/write commands, the control stream commands cannot be chained
 488                          *           together; i.e. the entire stream data must be read or written at the one time.
 489                          *
 490                          *  \param[out] Buffer  Pointer to the destination data buffer to write to.
 491                          *  \param[in]  Length  Number of bytes to send via the currently selected endpoint.
 492                          *
 493                          *  \return A value from the \ref Endpoint_ControlStream_RW_ErrorCodes_t enum.
 494                          */
 495                         uint8_t Endpoint_Read_Control_Stream_BE(void* Buffer,
 496                                                                 uint16_t Length) ATTR_NON_NULL_PTR_ARG(1);
 497
 498                         /** EEPROM buffer source version of \ref Endpoint_Read_Control_Stream_BE().
 499                          *
 500                          *  \note This function automatically clears the control transfer's status stage. Do not manually attempt
 501                          *        to clear the status stage when using this routine in a control transaction.
 502                          *        \n\n
 503                          *
 504                          *  \note This routine should only be used on CONTROL type endpoints.
 505                          *
 506                          *  \warning Unlike the standard stream read/write commands, the control stream commands cannot be chained
 507                          *           together; i.e. the entire stream data must be read or written at the one time.
 508                          *
 509                          *  \param[out] Buffer  Pointer to the destination data buffer to write to.
 510                          *  \param[in]  Length  Number of bytes to send via the currently selected endpoint.
 511                          *
 512                          *  \return A value from the \ref Endpoint_ControlStream_RW_ErrorCodes_t enum.
 513                          */
 514                         uint8_t Endpoint_Read_Control_EStream_BE(void* Buffer,
 515                                                                  uint16_t Length) ATTR_NON_NULL_PTR_ARG(1);
 516
 517         /* Disable C linkage for C++ Compilers: */
 518                 #if defined(__cplusplus)
 519                         }
 520                 #endif
 521
 522 #endif
 523
 524 /** @} */
 525