projects / pub / lufa.git / blob
? search:
summary | shortlog | log | commit | commitdiff | tree
blame | history | raw | HEAD
Add missing SVN eol-style property to files where it was missing.
[pub/lufa.git] / LUFA / Drivers / USB / Core / EndpointStream.h
1 /*
2 LUFA Library
3 Copyright (C) Dean Camera, 2011.
4
5 dean [at] fourwalledcubicle [dot] com
6 www.lufa-lib.org
7 */
8
9 /*
10 Copyright 2011 Dean Camera (dean [at] fourwalledcubicle [dot] com)
11
12 Permission to use, copy, modify, distribute, and sell this
13 software and its documentation for any purpose is hereby granted
14 without fee, provided that the above copyright notice appear in
15 all copies and that both that the copyright notice and this
16 permission notice and warranty disclaimer appear in supporting
17 documentation, and that the name of the author not be used in
18 advertising or publicity pertaining to distribution of the
19 software without specific, written prior permission.
20
21 The author disclaim all warranties with regard to this
22 software, including all implied warranties of merchantability
23 and fitness. In no event shall the author be liable for any
24 special, indirect or consequential damages or any damages
25 whatsoever resulting from loss of use, data or profits, whether
26 in an action of contract, negligence or other tortious action,
27 arising out of or in connection with the use or performance of
28 this software.
29 */
30
31 /** \file
32 * \brief Endpoint data stream transmission and reception management.
33 * \copydetails Group_EndpointStreamRW
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_EndpointRW
40 * \defgroup Group_EndpointStreamRW Read/Write of Multi-Byte Streams
41 * \brief Endpoint data stream transmission and reception management.
42 *
43 * Functions, macros, variables, enums and types related to data reading and writing of data streams from
44 * and to endpoints.
45 *
46 * @{
47 */
48
49 #ifndef __ENDPOINT_STREAM_H__
50 #define __ENDPOINT_STREAM_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 /* Enums: */
69 /** Enum for the possible error return codes of the \c Endpoint_*_Stream_* functions. */
70 enum Endpoint_Stream_RW_ErrorCodes_t
71 {
72 ENDPOINT_RWSTREAM_NoError = 0, /**< Command completed successfully, no error. */
73 ENDPOINT_RWSTREAM_EndpointStalled = 1, /**< The endpoint was stalled during the stream
74 * transfer by the host or device.
75 */
76 ENDPOINT_RWSTREAM_DeviceDisconnected = 2, /**< Device was disconnected from the host during
77 * the transfer.
78 */
79 ENDPOINT_RWSTREAM_BusSuspended = 3, /**< The USB bus has been suspended by the host and
80 * no USB endpoint traffic can occur until the bus
81 * has resumed.
82 */
83 ENDPOINT_RWSTREAM_Timeout = 4, /**< The host failed to accept or send the next packet
84 * within the software timeout period set by the
85 * \ref USB_STREAM_TIMEOUT_MS macro.
86 */
87 ENDPOINT_RWSTREAM_IncompleteTransfer = 5, /**< Indicates that the endpoint bank became full or empty before
88 * the complete contents of the current stream could be
89 * transferred. The endpoint stream function should be called
90 * again to process the next chunk of data in the transfer.
91 */
92 };
93
94 /** Enum for the possible error return codes of the \c Endpoint_*_Control_Stream_* functions. */
95 enum Endpoint_ControlStream_RW_ErrorCodes_t
96 {
97 ENDPOINT_RWCSTREAM_NoError = 0, /**< Command completed successfully, no error. */
98 ENDPOINT_RWCSTREAM_HostAborted = 1, /**< The aborted the transfer prematurely. */
99 ENDPOINT_RWCSTREAM_DeviceDisconnected = 2, /**< Device was disconnected from the host during
100 * the transfer.
101 */
102 ENDPOINT_RWCSTREAM_BusSuspended = 3, /**< The USB bus has been suspended by the host and
103 * no USB endpoint traffic can occur until the bus
104 * has resumed.
105 */
106 };
107
108 /* Function Prototypes: */
109
110 /** \name Stream functions for null data */
111 //@{
112
113 /** Reads and discards the given number of bytes from the currently selected endpoint's bank,
114 * discarding fully read packets from the host as needed. The last packet is not automatically
115 * discarded once the remaining bytes has been read; the user is responsible for manually
116 * discarding the last packet from the host via the \ref Endpoint_ClearOUT() macro.
117 *
118 * If the BytesProcessed parameter is \c NULL, the entire stream transfer is attempted at once,
119 * failing or succeeding as a single unit. If the BytesProcessed parameter points to a valid
120 * storage location, the transfer will instead be performed as a series of chunks. Each time
121 * the endpoint bank becomes empty while there is still data to process (and after the current
122 * packet has been acknowledged) the BytesProcessed location will be updated with the total number
123 * of bytes processed in the stream, and the function will exit with an error code of
124 * \ref ENDPOINT_RWSTREAM_IncompleteTransfer. This allows for any abort checking to be performed
125 * in the user code - to continue the transfer, call the function again with identical parameters
126 * and it will resume until the BytesProcessed value reaches the total transfer length.
127 *
128 * <b>Single Stream Transfer Example:</b>
129 * \code
130 * uint8_t ErrorCode;
131 *
132 * if ((ErrorCode = Endpoint_Discard_Stream(512, NULL)) != ENDPOINT_RWSTREAM_NoError)
133 * {
134 * // Stream failed to complete - check ErrorCode here
135 * }
136 * \endcode
137 *
138 * <b>Partial Stream Transfers Example:</b>
139 * \code
140 * uint8_t ErrorCode;
141 * uint16_t BytesProcessed;
142 *
143 * BytesProcessed = 0;
144 * while ((ErrorCode = Endpoint_Discard_Stream(512, &BytesProcessed)) == ENDPOINT_RWSTREAM_IncompleteTransfer)
145 * {
146 * // Stream not yet complete - do other actions here, abort if required
147 * }
148 *
149 * if (ErrorCode != ENDPOINT_RWSTREAM_NoError)
150 * {
151 * // Stream failed to complete - check ErrorCode here
152 * }
153 * \endcode
154 *
155 * \note This routine should not be used on CONTROL type endpoints.
156 *
157 * \param[in] Length Number of bytes to discard via the currently selected endpoint.
158 * \param[in] BytesProcessed Pointer to a location where the total number of bytes processed in the current
159 * transaction should be updated, \c NULL if the entire stream should be read at once.
160 *
161 * \return A value from the \ref Endpoint_Stream_RW_ErrorCodes_t enum.
162 */
163 uint8_t Endpoint_Discard_Stream(uint16_t Length,
164 uint16_t* const BytesProcessed);
165
166 /** Writes a given number of zeroed bytes to the currently selected endpoint's bank, sending
167 * full packets to the host as needed. The last packet is not automatically sent once the
168 * remaining bytes have been written; the user is responsible for manually sending the last
169 * packet to the host via the \ref Endpoint_ClearIN() macro.
170 *
171 * If the BytesProcessed parameter is \c NULL, the entire stream transfer is attempted at once,
172 * failing or succeeding as a single unit. If the BytesProcessed parameter points to a valid
173 * storage location, the transfer will instead be performed as a series of chunks. Each time
174 * the endpoint bank becomes full while there is still data to process (and after the current
175 * packet transmission has been initiated) the BytesProcessed location will be updated with the
176 * total number of bytes processed in the stream, and the function will exit with an error code of
177 * \ref ENDPOINT_RWSTREAM_IncompleteTransfer. This allows for any abort checking to be performed
178 * in the user code - to continue the transfer, call the function again with identical parameters
179 * and it will resume until the BytesProcessed value reaches the total transfer length.
180 *
181 * <b>Single Stream Transfer Example:</b>
182 * \code
183 * uint8_t ErrorCode;
184 *
185 * if ((ErrorCode = Endpoint_Null_Stream(512, NULL)) != ENDPOINT_RWSTREAM_NoError)
186 * {
187 * // Stream failed to complete - check ErrorCode here
188 * }
189 * \endcode
190 *
191 * <b>Partial Stream Transfers Example:</b>
192 * \code
193 * uint8_t ErrorCode;
194 * uint16_t BytesProcessed;
195 *
196 * BytesProcessed = 0;
197 * while ((ErrorCode = Endpoint_Null_Stream(512, &BytesProcessed)) == ENDPOINT_RWSTREAM_IncompleteTransfer)
198 * {
199 * // Stream not yet complete - do other actions here, abort if required
200 * }
201 *
202 * if (ErrorCode != ENDPOINT_RWSTREAM_NoError)
203 * {
204 * // Stream failed to complete - check ErrorCode here
205 * }
206 * \endcode
207 *
208 * \note This routine should not be used on CONTROL type endpoints.
209 *
210 * \param[in] Length Number of zero bytes to send via the currently selected endpoint.
211 * \param[in] BytesProcessed Pointer to a location where the total number of bytes processed in the current
212 * transaction should be updated, \c NULL if the entire stream should be read at once.
213 *
214 * \return A value from the \ref Endpoint_Stream_RW_ErrorCodes_t enum.
215 */
216 uint8_t Endpoint_Null_Stream(uint16_t Length,
217 uint16_t* const BytesProcessed);
218
219 //@}
220
221 /** \name Stream functions for RAM source/destination data */
222 //@{
223
224 /** Writes the given number of bytes to the endpoint from the given buffer in little endian,
225 * sending full packets to the host as needed. The last packet filled is not automatically sent;
226 * the user is responsible for manually sending the last written packet to the host via the
227 * \ref Endpoint_ClearIN() macro.
228 *
229 * If the BytesProcessed parameter is \c NULL, the entire stream transfer is attempted at once,
230 * failing or succeeding as a single unit. If the BytesProcessed parameter points to a valid
231 * storage location, the transfer will instead be performed as a series of chunks. Each time
232 * the endpoint bank becomes full while there is still data to process (and after the current
233 * packet transmission has been initiated) the BytesProcessed location will be updated with the
234 * total number of bytes processed in the stream, and the function will exit with an error code of
235 * \ref ENDPOINT_RWSTREAM_IncompleteTransfer. This allows for any abort checking to be performed
236 * in the user code - to continue the transfer, call the function again with identical parameters
237 * and it will resume until the BytesProcessed value reaches the total transfer length.
238 *
239 * <b>Single Stream Transfer Example:</b>
240 * \code
241 * uint8_t DataStream[512];
242 * uint8_t ErrorCode;
243 *
244 * if ((ErrorCode = Endpoint_Write_Stream_LE(DataStream, sizeof(DataStream),
245 * NULL)) != ENDPOINT_RWSTREAM_NoError)
246 * {
247 * // Stream failed to complete - check ErrorCode here
248 * }
249 * \endcode
250 *
251 * <b>Partial Stream Transfers Example:</b>
252 * \code
253 * uint8_t DataStream[512];
254 * uint8_t ErrorCode;
255 * uint16_t BytesProcessed;
256 *
257 * BytesProcessed = 0;
258 * while ((ErrorCode = Endpoint_Write_Stream_LE(DataStream, sizeof(DataStream),
259 * &BytesProcessed)) == ENDPOINT_RWSTREAM_IncompleteTransfer)
260 * {
261 * // Stream not yet complete - do other actions here, abort if required
262 * }
263 *
264 * if (ErrorCode != ENDPOINT_RWSTREAM_NoError)
265 * {
266 * // Stream failed to complete - check ErrorCode here
267 * }
268 * \endcode
269 *
270 * \note This routine should not be used on CONTROL type endpoints.
271 *
272 * \param[in] Buffer Pointer to the source data buffer to read from.
273 * \param[in] Length Number of bytes to read for the currently selected endpoint into the buffer.
274 * \param[in] BytesProcessed Pointer to a location where the total number of bytes processed in the current
275 * transaction should be updated, \c NULL if the entire stream should be written at once.
276 *
277 * \return A value from the \ref Endpoint_Stream_RW_ErrorCodes_t enum.
278 */
279 uint8_t Endpoint_Write_Stream_LE(const void* const Buffer,
280 uint16_t Length,
281 uint16_t* const BytesProcessed) ATTR_NON_NULL_PTR_ARG(1);
282
283 /** Writes the given number of bytes to the endpoint from the given buffer in big endian,
284 * sending full packets to the host as needed. The last packet filled is not automatically sent;
285 * the user is responsible for manually sending the last written packet to the host via the
286 * \ref Endpoint_ClearIN() macro.
287 *
288 * \note This routine should not be used on CONTROL type endpoints.
289 *
290 * \param[in] Buffer Pointer to the source data buffer to read from.
291 * \param[in] Length Number of bytes to read for the currently selected endpoint into the buffer.
292 * \param[in] BytesProcessed Pointer to a location where the total number of bytes processed in the current
293 * transaction should be updated, \c NULL if the entire stream should be written at once.
294 *
295 * \return A value from the \ref Endpoint_Stream_RW_ErrorCodes_t enum.
296 */
297 uint8_t Endpoint_Write_Stream_BE(const void* const Buffer,
298 uint16_t Length,
299 uint16_t* const BytesProcessed) ATTR_NON_NULL_PTR_ARG(1);
300
301 /** Reads the given number of bytes from the endpoint from the given buffer in little endian,
302 * discarding fully read packets from the host as needed. The last packet is not automatically
303 * discarded once the remaining bytes has been read; the user is responsible for manually
304 * discarding the last packet from the host via the \ref Endpoint_ClearOUT() macro.
305 *
306 * If the BytesProcessed parameter is \c NULL, the entire stream transfer is attempted at once,
307 * failing or succeeding as a single unit. If the BytesProcessed parameter points to a valid
308 * storage location, the transfer will instead be performed as a series of chunks. Each time
309 * the endpoint bank becomes empty while there is still data to process (and after the current
310 * packet has been acknowledged) the BytesProcessed location will be updated with the total number
311 * of bytes processed in the stream, and the function will exit with an error code of
312 * \ref ENDPOINT_RWSTREAM_IncompleteTransfer. This allows for any abort checking to be performed
313 * in the user code - to continue the transfer, call the function again with identical parameters
314 * and it will resume until the BytesProcessed value reaches the total transfer length.
315 *
316 * <b>Single Stream Transfer Example:</b>
317 * \code
318 * uint8_t DataStream[512];
319 * uint8_t ErrorCode;
320 *
321 * if ((ErrorCode = Endpoint_Read_Stream_LE(DataStream, sizeof(DataStream),
322 * NULL)) != ENDPOINT_RWSTREAM_NoError)
323 * {
324 * // Stream failed to complete - check ErrorCode here
325 * }
326 * \endcode
327 *
328 * <b>Partial Stream Transfers Example:</b>
329 * \code
330 * uint8_t DataStream[512];
331 * uint8_t ErrorCode;
332 * uint16_t BytesProcessed;
333 *
334 * BytesProcessed = 0;
335 * while ((ErrorCode = Endpoint_Read_Stream_LE(DataStream, sizeof(DataStream),
336 * &BytesProcessed)) == ENDPOINT_RWSTREAM_IncompleteTransfer)
337 * {
338 * // Stream not yet complete - do other actions here, abort if required
339 * }
340 *
341 * if (ErrorCode != ENDPOINT_RWSTREAM_NoError)
342 * {
343 * // Stream failed to complete - check ErrorCode here
344 * }
345 * \endcode
346 *
347 * \note This routine should not be used on CONTROL type endpoints.
348 *
349 * \param[out] Buffer Pointer to the destination data buffer to write to.
350 * \param[in] Length Number of bytes to send via the currently selected endpoint.
351 * \param[in] BytesProcessed Pointer to a location where the total number of bytes processed in the current
352 * transaction should be updated, \c NULL if the entire stream should be read at once.
353 *
354 * \return A value from the \ref Endpoint_Stream_RW_ErrorCodes_t enum.
355 */
356 uint8_t Endpoint_Read_Stream_LE(void* const Buffer,
357 uint16_t Length,
358 uint16_t* const BytesProcessed) ATTR_NON_NULL_PTR_ARG(1);
359
360 /** Reads the given number of bytes from the endpoint from the given buffer in big endian,
361 * discarding fully read packets from the host as needed. The last packet is not automatically
362 * discarded once the remaining bytes has been read; the user is responsible for manually
363 * discarding the last packet from the host via the \ref Endpoint_ClearOUT() macro.
364 *
365 * \note This routine should not be used on CONTROL type endpoints.
366 *
367 * \param[out] Buffer Pointer to the destination data buffer to write to.
368 * \param[in] Length Number of bytes to send via the currently selected endpoint.
369 * \param[in] BytesProcessed Pointer to a location where the total number of bytes processed in the current
370 * transaction should be updated, \c NULL if the entire stream should be read at once.
371 *
372 * \return A value from the \ref Endpoint_Stream_RW_ErrorCodes_t enum.
373 */
374 uint8_t Endpoint_Read_Stream_BE(void* const Buffer,
375 uint16_t Length,
376 uint16_t* const BytesProcessed) ATTR_NON_NULL_PTR_ARG(1);
377
378 /** Writes the given number of bytes to the CONTROL type endpoint from the given buffer in little endian,
379 * sending full packets to the host as needed. The host OUT acknowledgement is not automatically cleared
380 * in both failure and success states; the user is responsible for manually clearing the setup OUT to
381 * finalize the transfer via the \ref Endpoint_ClearOUT() macro.
382 *
383 * \note This function automatically clears the control transfer's status stage. Do not manually attempt
384 * to clear the status stage when using this routine in a control transaction.
385 * \n\n
386 *
387 * \note This routine should only be used on CONTROL type endpoints.
388 *
389 * \warning Unlike the standard stream read/write commands, the control stream commands cannot be chained
390 * together; i.e. the entire stream data must be read or written at the one time.
391 *
392 * \param[in] Buffer Pointer to the source data buffer to read from.
393 * \param[in] Length Number of bytes to read for the currently selected endpoint into the buffer.
394 *
395 * \return A value from the \ref Endpoint_ControlStream_RW_ErrorCodes_t enum.
396 */
397 uint8_t Endpoint_Write_Control_Stream_LE(const void* const Buffer,
398 uint16_t Length) ATTR_NON_NULL_PTR_ARG(1);
399
400 /** Writes the given number of bytes to the CONTROL type endpoint from the given buffer in big endian,
401 * sending full packets to the host as needed. The host OUT acknowledgement is not automatically cleared
402 * in both failure and success states; the user is responsible for manually clearing the setup OUT to
403 * finalize the transfer via the \ref Endpoint_ClearOUT() macro.
404 *
405 * \note This function automatically clears the control transfer's status stage. Do not manually attempt
406 * to clear the status stage when using this routine in a control transaction.
407 * \n\n
408 *
409 * \note This routine should only be used on CONTROL type endpoints.
410 *
411 * \warning Unlike the standard stream read/write commands, the control stream commands cannot be chained
412 * together; i.e. the entire stream data must be read or written at the one time.
413 *
414 * \param[in] Buffer Pointer to the source data buffer to read from.
415 * \param[in] Length Number of bytes to read for the currently selected endpoint into the buffer.
416 *
417 * \return A value from the \ref Endpoint_ControlStream_RW_ErrorCodes_t enum.
418 */
419 uint8_t Endpoint_Write_Control_Stream_BE(const void* const Buffer,
420 uint16_t Length) ATTR_NON_NULL_PTR_ARG(1);
421
422 /** Reads the given number of bytes from the CONTROL endpoint from the given buffer in little endian,
423 * discarding fully read packets from the host as needed. The device IN acknowledgement is not
424 * automatically sent after success or failure states; the user is responsible for manually sending the
425 * setup IN to finalize the transfer via the \ref Endpoint_ClearIN() macro.
426 *
427 * \note This function automatically clears the control transfer's status stage. Do not manually attempt
428 * to clear the status stage when using this routine in a control transaction.
429 * \n\n
430 *
431 * \note This routine should only be used on CONTROL type endpoints.
432 *
433 * \warning Unlike the standard stream read/write commands, the control stream commands cannot be chained
434 * together; i.e. the entire stream data must be read or written at the one time.
435 *
436 * \param[out] Buffer Pointer to the destination data buffer to write to.
437 * \param[in] Length Number of bytes to send via the currently selected endpoint.
438 *
439 * \return A value from the \ref Endpoint_ControlStream_RW_ErrorCodes_t enum.
440 */
441 uint8_t Endpoint_Read_Control_Stream_LE(void* const Buffer,
442 uint16_t Length) ATTR_NON_NULL_PTR_ARG(1);
443
444 /** Reads the given number of bytes from the CONTROL endpoint from the given buffer in big endian,
445 * discarding fully read packets from the host as needed. The device IN acknowledgement is not
446 * automatically sent after success or failure states; the user is responsible for manually sending the
447 * setup IN to finalize the transfer via the \ref Endpoint_ClearIN() macro.
448 *
449 * \note This function automatically clears the control transfer's status stage. Do not manually attempt
450 * to clear the status stage when using this routine in a control transaction.
451 * \n\n
452 *
453 * \note This routine should only be used on CONTROL type endpoints.
454 *
455 * \warning Unlike the standard stream read/write commands, the control stream commands cannot be chained
456 * together; i.e. the entire stream data must be read or written at the one time.
457 *
458 * \param[out] Buffer Pointer to the destination data buffer to write to.
459 * \param[in] Length Number of bytes to send via the currently selected endpoint.
460 *
461 * \return A value from the \ref Endpoint_ControlStream_RW_ErrorCodes_t enum.
462 */
463 uint8_t Endpoint_Read_Control_Stream_BE(void* const Buffer,
464 uint16_t Length) ATTR_NON_NULL_PTR_ARG(1);
465 //@}
466
467 /** \name Stream functions for EEPROM source/destination data */
468 //@{
469
470 #if defined(ARCH_HAS_EEPROM_ADDRESS_SPACE) || defined(__DOXYGEN__)
471 /** EEPROM buffer source version of \ref Endpoint_Write_Stream_LE().
472 *
473 * \note This function is not available on all architectures.
474 *
475 * \param[in] Buffer Pointer to the source data buffer to read from.
476 * \param[in] Length Number of bytes to read for the currently selected endpoint into the buffer.
477 * \param[in] BytesProcessed Pointer to a location where the total number of bytes processed in the current
478 * transaction should be updated, \c NULL if the entire stream should be written at once.
479 *
480 * \return A value from the \ref Endpoint_Stream_RW_ErrorCodes_t enum.
481 */
482 uint8_t Endpoint_Write_EStream_LE(const void* const Buffer,
483 uint16_t Length,
484 uint16_t* const BytesProcessed) ATTR_NON_NULL_PTR_ARG(1);
485
486 /** EEPROM buffer source version of \ref Endpoint_Write_Stream_BE().
487 *
488 * \note This function is not available on all architectures.
489 *
490 * \param[in] Buffer Pointer to the source data buffer to read from.
491 * \param[in] Length Number of bytes to read for the currently selected endpoint into the buffer.
492 * \param[in] BytesProcessed Pointer to a location where the total number of bytes processed in the current
493 * transaction should be updated, \c NULL if the entire stream should be written at once.
494 *
495 * \return A value from the \ref Endpoint_Stream_RW_ErrorCodes_t enum.
496 */
497 uint8_t Endpoint_Write_EStream_BE(const void* const Buffer,
498 uint16_t Length,
499 uint16_t* const BytesProcessed) ATTR_NON_NULL_PTR_ARG(1);
500
501 /** EEPROM buffer source version of \ref Endpoint_Read_Stream_LE().
502 *
503 * \note This function is not available on all architectures.
504 *
505 * \param[out] Buffer Pointer to the destination data buffer to write to, located in EEPROM memory space.
506 * \param[in] Length Number of bytes to send via the currently selected endpoint.
507 * \param[in] BytesProcessed Pointer to a location where the total number of bytes processed in the current
508 * transaction should be updated, \c NULL if the entire stream should be read at once.
509 *
510 * \return A value from the \ref Endpoint_Stream_RW_ErrorCodes_t enum.
511 */
512 uint8_t Endpoint_Read_EStream_LE(void* const Buffer,
513 uint16_t Length,
514 uint16_t* const BytesProcessed) ATTR_NON_NULL_PTR_ARG(1);
515
516 /** EEPROM buffer source version of \ref Endpoint_Read_Stream_BE().
517 *
518 * \note This function is not available on all architectures.
519 *
520 * \param[out] Buffer Pointer to the destination data buffer to write to, located in EEPROM memory space.
521 * \param[in] Length Number of bytes to send via the currently selected endpoint.
522 * \param[in] BytesProcessed Pointer to a location where the total number of bytes processed in the current
523 * transaction should be updated, \c NULL if the entire stream should be read at once.
524 *
525 * \return A value from the \ref Endpoint_Stream_RW_ErrorCodes_t enum.
526 */
527 uint8_t Endpoint_Read_EStream_BE(void* const Buffer,
528 uint16_t Length,
529 uint16_t* const BytesProcessed) ATTR_NON_NULL_PTR_ARG(1);
530
531 /** EEPROM buffer source version of Endpoint_Write_Control_Stream_LE.
532 *
533 * \note This function automatically clears the control transfer's status stage. Do not manually attempt
534 * to clear the status stage when using this routine in a control transaction.
535 * \n\n
536 *
537 * \note This routine should only be used on CONTROL type endpoints.
538 * \n\n
539 *
540 * \note This function is not available on all architectures.
541 *
542 * \warning Unlike the standard stream read/write commands, the control stream commands cannot be chained
543 * together; i.e. the entire stream data must be read or written at the one time.
544 *
545 * \param[in] Buffer Pointer to the source data buffer to read from.
546 * \param[in] Length Number of bytes to read for the currently selected endpoint into the buffer.
547 *
548 * \return A value from the \ref Endpoint_ControlStream_RW_ErrorCodes_t enum.
549 */
550 uint8_t Endpoint_Write_Control_EStream_LE(const void* const Buffer,
551 uint16_t Length) ATTR_NON_NULL_PTR_ARG(1);
552
553 /** EEPROM buffer source version of \ref Endpoint_Write_Control_Stream_BE().
554 *
555 * \note This function automatically clears the control transfer's status stage. Do not manually attempt
556 * to clear the status stage when using this routine in a control transaction.
557 * \n\n
558 *
559 * \note This routine should only be used on CONTROL type endpoints.
560 * \n\n
561 *
562 * \note This function is not available on all architectures.
563 *
564 * \warning Unlike the standard stream read/write commands, the control stream commands cannot be chained
565 * together; i.e. the entire stream data must be read or written at the one time.
566 *
567 * \param[in] Buffer Pointer to the source data buffer to read from.
568 * \param[in] Length Number of bytes to read for the currently selected endpoint into the buffer.
569 *
570 * \return A value from the \ref Endpoint_ControlStream_RW_ErrorCodes_t enum.
571 */
572 uint8_t Endpoint_Write_Control_EStream_BE(const void* const Buffer,
573 uint16_t Length) ATTR_NON_NULL_PTR_ARG(1);
574
575 /** EEPROM buffer source version of \ref Endpoint_Read_Control_Stream_LE().
576 *
577 * \note This function automatically clears the control transfer's status stage. Do not manually attempt
578 * to clear the status stage when using this routine in a control transaction.
579 * \n\n
580 *
581 * \note This routine should only be used on CONTROL type endpoints.
582 * \n\n
583 *
584 * \note This function is not available on all architectures.
585 *
586 * \warning Unlike the standard stream read/write commands, the control stream commands cannot be chained
587 * together; i.e. the entire stream data must be read or written at the one time.
588 *
589 * \param[out] Buffer Pointer to the destination data buffer to write to.
590 * \param[in] Length Number of bytes to send via the currently selected endpoint.
591 *
592 * \return A value from the \ref Endpoint_ControlStream_RW_ErrorCodes_t enum.
593 */
594 uint8_t Endpoint_Read_Control_EStream_LE(void* const Buffer,
595 uint16_t Length) ATTR_NON_NULL_PTR_ARG(1);
596
597 /** EEPROM buffer source version of \ref Endpoint_Read_Control_Stream_BE().
598 *
599 * \note This function automatically clears the control transfer's status stage. Do not manually attempt
600 * to clear the status stage when using this routine in a control transaction.
601 * \n\n
602 *
603 * \note This routine should only be used on CONTROL type endpoints.
604 * \n\n
605 *
606 * \note This function is not available on all architectures.
607 *
608 * \warning Unlike the standard stream read/write commands, the control stream commands cannot be chained
609 * together; i.e. the entire stream data must be read or written at the one time.
610 *
611 * \param[out] Buffer Pointer to the destination data buffer to write to.
612 * \param[in] Length Number of bytes to send via the currently selected endpoint.
613 *
614 * \return A value from the \ref Endpoint_ControlStream_RW_ErrorCodes_t enum.
615 */
616 uint8_t Endpoint_Read_Control_EStream_BE(void* const Buffer,
617 uint16_t Length) ATTR_NON_NULL_PTR_ARG(1);
618 #endif
619 //@}
620
621 /** \name Stream functions for PROGMEM source/destination data */
622 //@{
623
624 #if defined(ARCH_HAS_FLASH_ADDRESS_SPACE) || defined(__DOXYGEN__)
625 /** FLASH buffer source version of \ref Endpoint_Write_Stream_LE().
626 *
627 * \pre The FLASH data must be located in the first 64KB of FLASH for this function to work correctly.
628 *
629 * \note This function is not available on all architectures.
630 *
631 * \param[in] Buffer Pointer to the source data buffer to read from.
632 * \param[in] Length Number of bytes to read for the currently selected endpoint into the buffer.
633 * \param[in] BytesProcessed Pointer to a location where the total number of bytes processed in the current
634 * transaction should be updated, \c NULL if the entire stream should be written at once.
635 *
636 * \return A value from the \ref Endpoint_Stream_RW_ErrorCodes_t enum.
637 */
638 uint8_t Endpoint_Write_PStream_LE(const void* const Buffer,
639 uint16_t Length,
640 uint16_t* const BytesProcessed) ATTR_NON_NULL_PTR_ARG(1);
641
642 /** FLASH buffer source version of \ref Endpoint_Write_Stream_BE().
643 *
644 * \pre The FLASH data must be located in the first 64KB of FLASH for this function to work correctly.
645 *
646 * \note This function is not available on all architectures.
647 *
648 * \param[in] Buffer Pointer to the source data buffer to read from.
649 * \param[in] Length Number of bytes to read for the currently selected endpoint into the buffer.
650 * \param[in] BytesProcessed Pointer to a location where the total number of bytes processed in the current
651 * transaction should be updated, \c NULL if the entire stream should be written at once.
652 *
653 * \return A value from the \ref Endpoint_Stream_RW_ErrorCodes_t enum.
654 */
655 uint8_t Endpoint_Write_PStream_BE(const void* const Buffer,
656 uint16_t Length,
657 uint16_t* const BytesProcessed) ATTR_NON_NULL_PTR_ARG(1);
658
659 /** FLASH buffer source version of \ref Endpoint_Write_Control_Stream_LE().
660 *
661 * \pre The FLASH data must be located in the first 64KB of FLASH for this function to work correctly.
662 *
663 * \note This function automatically clears the control transfer's status stage. Do not manually attempt
664 * to clear the status stage when using this routine in a control transaction.
665 * \n\n
666 *
667 * \note This routine should only be used on CONTROL type endpoints.
668 * \n\n
669 *
670 * \note This function is not available on all architectures.
671 *
672 * \warning Unlike the standard stream read/write commands, the control stream commands cannot be chained
673 * together; i.e. the entire stream data must be read or written at the one time.
674 *
675 * \param[in] Buffer Pointer to the source data buffer to read from.
676 * \param[in] Length Number of bytes to read for the currently selected endpoint into the buffer.
677 *
678 * \return A value from the \ref Endpoint_ControlStream_RW_ErrorCodes_t enum.
679 */
680 uint8_t Endpoint_Write_Control_PStream_LE(const void* const Buffer,
681 uint16_t Length) ATTR_NON_NULL_PTR_ARG(1);
682
683 /** FLASH buffer source version of \ref Endpoint_Write_Control_Stream_BE().
684 *
685 * \pre The FLASH data must be located in the first 64KB of FLASH for this function to work correctly.
686 *
687 * \note This function automatically clears the control transfer's status stage. Do not manually attempt
688 * to clear the status stage when using this routine in a control transaction.
689 * \n\n
690 *
691 * \note This routine should only be used on CONTROL type endpoints.
692 * \n\n
693 *
694 * \note This function is not available on all architectures.
695 *
696 * \warning Unlike the standard stream read/write commands, the control stream commands cannot be chained
697 * together; i.e. the entire stream data must be read or written at the one time.
698 *
699 * \param[in] Buffer Pointer to the source data buffer to read from.
700 * \param[in] Length Number of bytes to read for the currently selected endpoint into the buffer.
701 *
702 * \return A value from the \ref Endpoint_ControlStream_RW_ErrorCodes_t enum.
703 */
704 uint8_t Endpoint_Write_Control_PStream_BE(const void* const Buffer,
705 uint16_t Length) ATTR_NON_NULL_PTR_ARG(1);
706 #endif
707 //@}
708
709 /* Disable C linkage for C++ Compilers: */
710 #if defined(__cplusplus)
711 }
712 #endif
713
714 #endif
715
716 /** @} */
717
Lightweight USB Framework for AVRs