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