projects / pub / USBasp.git / blob
? search:


ab11a552492e2f5dcb50a46fe17576bbe60a2682
[pub/USBasp.git] / LUFA / Drivers / USB / LowLevel / Pipe.h
1 /*
2 LUFA Library
3 Copyright (C) Dean Camera, 2010.
4
5 dean [at] fourwalledcubicle [dot] com
6 www.fourwalledcubicle.com
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 /** \ingroup Group_USB
32 * @defgroup Group_PipeManagement Pipe Management
33 *
34 * This module contains functions, macros and enums related to pipe management when in USB Host mode. This
35 * module contains the pipe management macros, as well as pipe interrupt and data send/receive functions
36 * for various data types.
37 *
38 * @{
39 */
40
41 /** @defgroup Group_PipeRW Pipe Data Reading and Writing
42 *
43 * Functions, macros, variables, enums and types related to data reading and writing from and to pipes.
44 */
45
46 /** \ingroup Group_PipeRW
47 * @defgroup Group_PipePrimitiveRW Read/Write of Primitive Data Types
48 *
49 * Functions, macros, variables, enums and types related to data reading and writing of primitive data types
50 * from and to pipes.
51 */
52
53 /** \ingroup Group_PipeRW
54 * @defgroup Group_PipeStreamRW Read/Write of Multi-Byte Streams
55 *
56 * Functions, macros, variables, enums and types related to data reading and writing of data streams from
57 * and to pipes.
58 */
59
60 /** @defgroup Group_PipePacketManagement Pipe Packet Management
61 *
62 * Functions, macros, variables, enums and types related to packet management of pipes.
63 */
64
65 /** @defgroup Group_PipeControlReq Pipe Control Request Management
66 *
67 * Module for host mode request processing. This module allows for the transmission of standard, class and
68 * vendor control requests to the default control endpoint of an attached device while in host mode.
69 *
70 * \see Chapter 9 of the USB 2.0 specification.
71 */
72
73 #ifndef __PIPE_H__
74 #define __PIPE_H__
75
76 /* Includes: */
77 #if defined(__AVR32__)
78 #include <avr32/io.h>
79 #include <stdint.h>
80 #include <stdbool.h>
81 #elif defined(__AVR__)
82 #include <avr/io.h>
83 #include <avr/pgmspace.h>
84 #include <avr/eeprom.h>
85 #include <stdbool.h>
86 #endif
87
88 #include "../../../Common/Common.h"
89 #include "LowLevel.h"
90 #include "../HighLevel/USBTask.h"
91
92 #if !defined(NO_STREAM_CALLBACKS) || defined(__DOXYGEN__)
93 #include "../HighLevel/StreamCallbacks.h"
94 #endif
95
96 /* Enable C linkage for C++ Compilers: */
97 #if defined(__cplusplus)
98 extern "C" {
99 #endif
100
101 /* Preprocessor Checks: */
102 #if !defined(__INCLUDE_FROM_USB_DRIVER)
103 #error Do not include this file directly. Include LUFA/Drivers/USB/USB.h instead.
104 #endif
105
106 #if defined(__AVR32__) && !defined(__AVR32_EPREG_X)
107 #define __AVR32_EPREG_X(x) ((volatile uint32_t*)AVR32_USBB_ ## x)[USB_SelectedEPNumber]
108 #endif
109
110 /* Public Interface - May be used in end-application: */
111 /* Macros: */
112 /** Mask for \ref Pipe_GetErrorFlags(), indicating that an overflow error occurred in the pipe on the received data. */
113 #define PIPE_ERRORFLAG_OVERFLOW (1 << 6)
114
115 /** Mask for \ref Pipe_GetErrorFlags(), indicating that an underflow error occurred in the pipe on the received data. */
116 #define PIPE_ERRORFLAG_UNDERFLOW (1 << 5)
117
118 /** Mask for \ref Pipe_GetErrorFlags(), indicating that a CRC error occurred in the pipe on the received data. */
119 #define PIPE_ERRORFLAG_CRC16 (1 << 4)
120
121 /** Mask for \ref Pipe_GetErrorFlags(), indicating that a hardware timeout error occurred in the pipe. */
122 #define PIPE_ERRORFLAG_TIMEOUT (1 << 3)
123
124 /** Mask for \ref Pipe_GetErrorFlags(), indicating that a hardware PID error occurred in the pipe. */
125 #define PIPE_ERRORFLAG_PID (1 << 2)
126
127 /** Mask for \ref Pipe_GetErrorFlags(), indicating that a hardware data PID error occurred in the pipe. */
128 #define PIPE_ERRORFLAG_DATAPID (1 << 1)
129
130 /** Mask for \ref Pipe_GetErrorFlags(), indicating that a hardware data toggle error occurred in the pipe. */
131 #define PIPE_ERRORFLAG_DATATGL (1 << 0)
132
133 /** Token mask for \ref Pipe_ConfigurePipe(). This sets the pipe as a SETUP token (for CONTROL type pipes),
134 * which will trigger a control request on the attached device when data is written to the pipe.
135 */
136 #define PIPE_TOKEN_SETUP (0 << PTOKEN0)
137
138 /** Token mask for \ref Pipe_ConfigurePipe(). This sets the pipe as a IN token (for non-CONTROL type pipes),
139 * indicating that the pipe data will flow from device to host.
140 */
141 #define PIPE_TOKEN_IN (1 << PTOKEN0)
142
143 /** Token mask for \ref Pipe_ConfigurePipe(). This sets the pipe as a OUT token (for non-CONTROL type pipes),
144 * indicating that the pipe data will flow from host to device.
145 */
146 #define PIPE_TOKEN_OUT (2 << PTOKEN0)
147
148 /** Mask for the bank mode selection for the \ref Pipe_ConfigurePipe() macro. This indicates that the pipe
149 * should have one single bank, which requires less USB FIFO memory but results in slower transfers as
150 * only one USB device (the AVR or the attached device) can access the pipe's bank at the one time.
151 */
152 #define PIPE_BANK_SINGLE (0 << EPBK0)
153
154 /** Mask for the bank mode selection for the \ref Pipe_ConfigurePipe() macro. This indicates that the pipe
155 * should have two banks, which requires more USB FIFO memory but results in faster transfers as one
156 * USB device (the AVR or the attached device) can access one bank while the other accesses the second
157 * bank.
158 */
159 #define PIPE_BANK_DOUBLE (1 << EPBK0)
160
161 /** Pipe address for the default control pipe, which always resides in address 0. This is
162 * defined for convenience to give more readable code when used with the pipe macros.
163 */
164 #define PIPE_CONTROLPIPE 0
165
166 /** Default size of the default control pipe's bank, until altered by the Endpoint0Size value
167 * in the device descriptor of the attached device.
168 */
169 #define PIPE_CONTROLPIPE_DEFAULT_SIZE 64
170
171 /** Pipe number mask, for masking against pipe addresses to retrieve the pipe's numerical address
172 * in the device.
173 */
174 #define PIPE_PIPENUM_MASK 0x07
175
176 /** Total number of pipes (including the default control pipe at address 0) which may be used in
177 * the device. Different USB AVR models support different amounts of pipes, this value reflects
178 * the maximum number of pipes for the currently selected AVR model.
179 */
180 #define PIPE_TOTAL_PIPES 7
181
182 /** Size in bytes of the largest pipe bank size possible in the device. Not all banks on each AVR
183 * model supports the largest bank size possible on the device; different pipe numbers support
184 * different maximum bank sizes. This value reflects the largest possible bank of any pipe on the
185 * currently selected USB AVR model.
186 */
187 #define PIPE_MAX_SIZE 256
188
189 /** Endpoint number mask, for masking against endpoint addresses to retrieve the endpoint's
190 * numerical address in the attached device.
191 */
192 #define PIPE_EPNUM_MASK 0x0F
193
194 /** Endpoint direction mask, for masking against endpoint addresses to retrieve the endpoint's
195 * direction for comparing with the ENDPOINT_DESCRIPTOR_DIR_* masks.
196 */
197 #define PIPE_EPDIR_MASK 0x80
198
199 /* Pseudo-Function Macros: */
200 #if defined(__DOXYGEN__)
201 /** Indicates the number of bytes currently stored in the current pipes's selected bank.
202 *
203 * \note The return width of this function may differ, depending on the maximum pipe bank size
204 * of the selected AVR model.
205 *
206 * \ingroup Group_PipeRW
207 *
208 * \return Total number of bytes in the currently selected Pipe's FIFO buffer
209 */
210 static inline uint16_t Pipe_BytesInPipe(void);
211
212 /** Returns the pipe address of the currently selected pipe. This is typically used to save the
213 * currently selected pipe number so that it can be restored after another pipe has been manipulated.
214 *
215 * \return Index of the currently selected pipe
216 */
217 static inline uint8_t Pipe_GetCurrentPipe(void);
218
219 /** Selects the given pipe number. Any pipe operations which do not require the pipe number to be
220 * indicated will operate on the currently selected pipe.
221 *
222 * \param[in] PipeNumber Index of the pipe to select
223 */
224 static inline void Pipe_SelectPipe(uint8_t PipeNumber);
225
226 /** Resets the desired pipe, including the pipe banks and flags.
227 *
228 * \param[in] PipeNumber Index of the pipe to reset
229 */
230 static inline void Pipe_ResetPipe(uint8_t PipeNumber);
231
232 /** Enables the currently selected pipe so that data can be sent and received through it to and from
233 * an attached device.
234 *
235 * \note Pipes must first be configured properly via \ref Pipe_ConfigurePipe().
236 */
237 static inline void Pipe_EnablePipe(void);
238
239 /** Disables the currently selected pipe so that data cannot be sent and received through it to and
240 * from an attached device.
241 */
242 static inline void Pipe_DisablePipe(void);
243
244 /** Determines if the currently selected pipe is enabled, but not necessarily configured.
245 *
246 * \return Boolean True if the currently selected pipe is enabled, false otherwise
247 */
248 static inline bool Pipe_IsEnabled(void);
249
250 /** Gets the current pipe token, indicating the pipe's data direction and type.
251 *
252 * \return The current pipe token, as a PIPE_TOKEN_* mask
253 */
254 static inline uint8_t Pipe_GetPipeToken(void);
255
256 /** Sets the token for the currently selected pipe to one of the tokens specified by the PIPE_TOKEN_*
257 * masks. This can be used on CONTROL type pipes, to allow for bidirectional transfer of data during
258 * control requests, or on regular pipes to allow for half-duplex bidirectional data transfer to devices
259 * which have two endpoints of opposite direction sharing the same endpoint address within the device.
260 *
261 * \param[in] Token New pipe token to set the selected pipe to, as a PIPE_TOKEN_* mask
262 */
263 static inline void Pipe_SetPipeToken(uint8_t Token);
264
265 /** Configures the currently selected pipe to allow for an unlimited number of IN requests. */
266 static inline void Pipe_SetInfiniteINRequests(void);
267
268 /** Configures the currently selected pipe to only allow the specified number of IN requests to be
269 * accepted by the pipe before it is automatically frozen.
270 *
271 * \param[in] TotalINRequests Total number of IN requests that the pipe may receive before freezing
272 */
273 static inline void Pipe_SetFiniteINRequests(uint8_t TotalINRequests);
274
275 /** Determines if the currently selected pipe is configured.
276 *
277 * \return Boolean true if the selected pipe is configured, false otherwise
278 */
279 static inline bool Pipe_IsConfigured(void);
280
281 /** Retrieves the endpoint number of the endpoint within the attached device that the currently selected
282 * pipe is bound to.
283 *
284 * \return Endpoint number the currently selected pipe is bound to
285 */
286 static inline uint8_t Pipe_BoundEndpointNumber(void);
287
288 /** Sets the period between interrupts for an INTERRUPT type pipe to a specified number of milliseconds.
289 *
290 * \param[in] Milliseconds Number of milliseconds between each pipe poll
291 */
292 static inline void Pipe_SetInterruptPeriod(uint8_t Milliseconds);
293
294 /** Returns a mask indicating which pipe's interrupt periods have elapsed, indicating that the pipe should
295 * be serviced.
296 *
297 * \return Mask whose bits indicate which pipes have interrupted
298 */
299 static inline uint8_t Pipe_GetPipeInterrupts(void);
300
301 /** Determines if the specified pipe number has interrupted (valid only for INTERRUPT type
302 * pipes).
303 *
304 * \param[in] PipeNumber Index of the pipe whose interrupt flag should be tested
305 *
306 * \return Boolean true if the specified pipe has interrupted, false otherwise
307 */
308 static inline bool Pipe_HasPipeInterrupted(uint8_t PipeNumber);
309
310 /** Unfreezes the selected pipe, allowing it to communicate with an attached device. */
311 static inline void Pipe_Unfreeze(void);
312
313 /** Freezes the selected pipe, preventing it from communicating with an attached device. */
314 static inline void Pipe_Freeze(void);
315
316 /** Determines if the currently selected pipe is frozen, and not able to accept data.
317 *
318 * \return Boolean true if the currently selected pipe is frozen, false otherwise
319 */
320 static inline bool Pipe_IsFrozen(void);
321
322 /** Clears the master pipe error flag. */
323 static inline void Pipe_ClearError(void);
324
325 /** Determines if the master pipe error flag is set for the currently selected pipe, indicating that
326 * some sort of hardware error has occurred on the pipe.
327 *
328 * \see \ref Pipe_GetErrorFlags() macro for information on retrieving the exact error flag.
329 *
330 * \return Boolean true if an error has occurred on the selected pipe, false otherwise
331 */
332 static inline bool Pipe_IsError(void);
333
334 /** Clears all the currently selected pipe's hardware error flags, but does not clear the master error
335 * flag for the pipe.
336 */
337 static inline void Pipe_ClearErrorFlags(void);
338
339 /** Gets a mask of the hardware error flags which have occurred on the currently selected pipe. This
340 * value can then be masked against the PIPE_ERRORFLAG_* masks to determine what error has occurred.
341 *
342 * \return Mask comprising of PIPE_ERRORFLAG_* bits indicating what error has occurred on the selected pipe
343 */
344 static inline uint8_t Pipe_GetErrorFlags(void);
345
346 /** Determines if the currently selected pipe may be read from (if data is waiting in the pipe
347 * bank and the pipe is an IN direction, or if the bank is not yet full if the pipe is an OUT
348 * direction). This function will return false if an error has occurred in the pipe, or if the pipe
349 * is an IN direction and no packet (or an empty packet) has been received, or if the pipe is an OUT
350 * direction and the pipe bank is full.
351 *
352 * \note This function is not valid on CONTROL type pipes.
353 *
354 * \ingroup Group_PipePacketManagement
355 *
356 * \return Boolean true if the currently selected pipe may be read from or written to, depending on its direction
357 */
358 static inline bool Pipe_IsReadWriteAllowed(void);
359
360 /** Determines if an IN request has been received on the currently selected pipe.
361 *
362 * \ingroup Group_PipePacketManagement
363 *
364 * \return Boolean true if the current pipe has received an IN packet, false otherwise.
365 */
366 static inline bool Pipe_IsINReceived(void);
367
368 /** Determines if the currently selected pipe is ready to send an OUT request.
369 *
370 * \ingroup Group_PipePacketManagement
371 *
372 * \return Boolean true if the current pipe is ready for an OUT packet, false otherwise.
373 */
374 static inline bool Pipe_IsOUTReady(void);
375
376 /** Determines if no SETUP request is currently being sent to the attached device on the selected
377 * CONTROL type pipe.
378 *
379 * \ingroup Group_PipePacketManagement
380 *
381 * \return Boolean true if the current pipe is ready for a SETUP packet, false otherwise.
382 */
383 static inline bool Pipe_IsSETUPSent(void);
384
385 /** Sends the currently selected CONTROL type pipe's contents to the device as a SETUP packet.
386 *
387 * \ingroup Group_PipePacketManagement
388 */
389 static inline void Pipe_ClearSETUP(void);
390
391 /** Acknowledges the reception of a setup IN request from the attached device on the currently selected
392 * pipe, freeing the bank ready for the next packet.
393 *
394 * \ingroup Group_PipePacketManagement
395 */
396 static inline void Pipe_ClearIN(void);
397
398 /** Sends the currently selected pipe's contents to the device as an OUT packet on the selected pipe, freeing
399 * the bank ready for the next packet.
400 *
401 * \ingroup Group_PipePacketManagement
402 */
403 static inline void Pipe_ClearOUT(void);
404
405 /** Determines if the device sent a NAK (Negative Acknowledge) in response to the last sent packet on
406 * the currently selected pipe. This occurs when the host sends a packet to the device, but the device
407 * is not currently ready to handle the packet (i.e. its endpoint banks are full). Once a NAK has been
408 * received, it must be cleared using \ref Pipe_ClearNAKReceived() before the previous (or any other) packet
409 * can be re-sent.
410 *
411 * \ingroup Group_PipePacketManagement
412 *
413 * \return Boolean true if an NAK has been received on the current pipe, false otherwise
414 */
415 static inline bool Pipe_IsNAKReceived(void);
416
417 /** Clears the NAK condition on the currently selected pipe.
418 *
419 * \ingroup Group_PipePacketManagement
420 *
421 * \see \ref Pipe_IsNAKReceived() for more details.
422 */
423 static inline void Pipe_ClearNAKReceived(void);
424
425 /** Determines if the currently selected pipe has had the STALL condition set by the attached device.
426 *
427 * \ingroup Group_PipePacketManagement
428 *
429 * \return Boolean true if the current pipe has been stalled by the attached device, false otherwise
430 */
431 static inline bool Pipe_IsStalled(void);
432
433 /** Clears the STALL condition detection flag on the currently selected pipe, but does not clear the
434 * STALL condition itself (this must be done via a ClearFeature control request to the device).
435 *
436 * \ingroup Group_PipePacketManagement
437 */
438 static inline void Pipe_ClearStall(void);
439 #else
440 #define Pipe_BytesInPipe() UPBCX
441
442 #define Pipe_GetCurrentPipe() (UPNUM & PIPE_PIPENUM_MASK)
443
444 #define Pipe_SelectPipe(pipenum) MACROS{ UPNUM = (pipenum); }MACROE
445
446 #define Pipe_ResetPipe(pipenum) MACROS{ UPRST = (1 << (pipenum)); UPRST = 0; }MACROE
447
448 #define Pipe_EnablePipe() MACROS{ UPCONX |= (1 << PEN); }MACROE
449
450 #define Pipe_DisablePipe() MACROS{ UPCONX &= ~(1 << PEN); }MACROE
451
452 #define Pipe_IsEnabled() ((UPCONX & (1 << PEN)) ? true : false)
453
454 #define Pipe_GetPipeToken() (UPCFG0X & PIPE_TOKEN_MASK)
455
456 #define Pipe_SetPipeToken(token) MACROS{ UPCFG0X = ((UPCFG0X & ~PIPE_TOKEN_MASK) | (token)); }MACROE
457
458 #define Pipe_SetInfiniteINRequests() MACROS{ UPCONX |= (1 << INMODE); }MACROE
459
460 #define Pipe_SetFiniteINRequests(n) MACROS{ UPCONX &= ~(1 << INMODE); UPINRQX = (n); }MACROE
461
462 #define Pipe_IsConfigured() ((UPSTAX & (1 << CFGOK)) ? true : false)
463
464 #define Pipe_BoundEndpointNumber() ((UPCFG0X >> PEPNUM0) & PIPE_EPNUM_MASK)
465
466 #define Pipe_SetInterruptPeriod(ms) MACROS{ UPCFG2X = (ms); }MACROE
467
468 #define Pipe_GetPipeInterrupts() UPINT
469
470 #define Pipe_HasPipeInterrupted(n) ((UPINT & (1 << (n))) ? true : false)
471
472 #define Pipe_Unfreeze() MACROS{ UPCONX &= ~(1 << PFREEZE); }MACROE
473
474 #define Pipe_Freeze() MACROS{ UPCONX |= (1 << PFREEZE); }MACROE
475
476 #define Pipe_IsFrozen() ((UPCONX & (1 << PFREEZE)) ? true : false)
477
478 #define Pipe_ClearError() MACROS{ UPINTX &= ~(1 << PERRI); }MACROE
479
480 #define Pipe_IsError() ((UPINTX & (1 << PERRI)) ? true : false)
481
482 #define Pipe_ClearErrorFlags() MACROS{ UPERRX = 0; }MACROE
483
484 #define Pipe_GetErrorFlags() ((UPERRX & (PIPE_ERRORFLAG_CRC16 | PIPE_ERRORFLAG_TIMEOUT | \
485 PIPE_ERRORFLAG_PID | PIPE_ERRORFLAG_DATAPID | \
486 PIPE_ERRORFLAG_DATATGL)) | \
487 (UPSTAX & PIPE_ERRORFLAG_OVERFLOW | PIPE_ERRORFLAG_UNDERFLOW))
488
489 #define Pipe_IsReadWriteAllowed() ((UPINTX & (1 << RWAL)) ? true : false)
490
491 #define Pipe_IsINReceived() ((UPINTX & (1 << RXINI)) ? true : false)
492
493 #define Pipe_IsOUTReady() ((UPINTX & (1 << TXOUTI)) ? true : false)
494
495 #define Pipe_IsSETUPSent() ((UPINTX & (1 << TXSTPI)) ? true : false)
496
497 #define Pipe_ClearIN() MACROS{ uint8_t Temp = UPINTX; UPINTX = (Temp & ~(1 << RXINI)); \
498 UPINTX = (Temp & ~(1 << FIFOCON)); }MACROE
499
500 #define Pipe_ClearOUT() MACROS{ uint8_t Temp = UPINTX; UPINTX = (Temp & ~(1 << TXOUTI)); \
501 UPINTX = (Temp & ~(1 << FIFOCON)); }MACROE
502
503 #define Pipe_ClearSETUP() MACROS{ uint8_t Temp = UPINTX; UPINTX = (Temp & ~(1 << TXSTPI)); \
504 UPINTX = (Temp & ~(1 << FIFOCON)); }MACROE
505
506 #define Pipe_IsNAKReceived() ((UPINTX & (1 << NAKEDI)) ? true : false)
507
508 #define Pipe_ClearNAKReceived() MACROS{ UPINTX &= ~(1 << NAKEDI); }MACROE
509
510 #define Pipe_IsStalled() ((UPINTX & (1 << RXSTALLI)) ? true : false)
511
512 #define Pipe_ClearStall() MACROS{ UPINTX &= ~(1 << RXSTALLI); }MACROE
513 #endif
514
515 /* Enums: */
516 /** Enum for the possible error return codes of the Pipe_WaitUntilReady function
517 *
518 * \ingroup Group_PipeRW
519 */
520 enum Pipe_WaitUntilReady_ErrorCodes_t
521 {
522 PIPE_READYWAIT_NoError = 0, /**< Pipe ready for next packet, no error */
523 PIPE_READYWAIT_PipeStalled = 1, /**< The device stalled the pipe while waiting. */
524 PIPE_READYWAIT_DeviceDisconnected = 2, /**< Device was disconnected from the host while waiting. */
525 PIPE_READYWAIT_Timeout = 3, /**< The device failed to accept or send the next packet
526 * within the software timeout period set by the
527 * \ref USB_STREAM_TIMEOUT_MS macro.
528 */
529 };
530
531 /** Enum for the possible error return codes of the Pipe_*_Stream_* functions.
532 *
533 * \ingroup Group_PipeRW
534 */
535 enum Pipe_Stream_RW_ErrorCodes_t
536 {
537 PIPE_RWSTREAM_NoError = 0, /**< Command completed successfully, no error. */
538 PIPE_RWSTREAM_PipeStalled = 1, /**< The device stalled the pipe during the transfer. */
539 PIPE_RWSTREAM_DeviceDisconnected = 2, /**< Device was disconnected from the host during
540 * the transfer.
541 */
542 PIPE_RWSTREAM_Timeout = 3, /**< The device failed to accept or send the next packet
543 * within the software timeout period set by the
544 * \ref USB_STREAM_TIMEOUT_MS macro.
545 */
546 PIPE_RWSTREAM_CallbackAborted = 4, /**< Indicates that the stream's callback function aborted
547 * the transfer early.
548 */
549 };
550
551 /* Inline Functions: */
552 /** Reads one byte from the currently selected pipe's bank, for OUT direction pipes.
553 *
554 * \ingroup Group_PipePrimitiveRW
555 *
556 * \return Next byte in the currently selected pipe's FIFO buffer
557 */
558 static inline uint8_t Pipe_Read_Byte(void) ATTR_WARN_UNUSED_RESULT ATTR_ALWAYS_INLINE;
559 static inline uint8_t Pipe_Read_Byte(void)
560 {
561 #if defined(__AVR32__)
562 return __AVR32_EPREG_X(UEDAT0);
563 #elif defined(__AVR__)
564 return UPDATX;
565 #endif
566 }
567
568 /** Writes one byte from the currently selected pipe's bank, for IN direction pipes.
569 *
570 * \ingroup Group_PipePrimitiveRW
571 *
572 * \param[in] Byte Next byte to write into the the currently selected pipe's FIFO buffer
573 */
574 static inline void Pipe_Write_Byte(const uint8_t Byte) ATTR_ALWAYS_INLINE;
575 static inline void Pipe_Write_Byte(const uint8_t Byte)
576 {
577 #if defined(__AVR32__)
578 __AVR32_EPREG_X(UEDAT0) = Byte;
579 #elif defined(__AVR__)
580 UPDATX = Byte;
581 #endif
582 }
583
584 /** Discards one byte from the currently selected pipe's bank, for OUT direction pipes.
585 *
586 * \ingroup Group_PipePrimitiveRW
587 */
588 static inline void Pipe_Discard_Byte(void) ATTR_ALWAYS_INLINE;
589 static inline void Pipe_Discard_Byte(void)
590 {
591 uint8_t Dummy;
592
593 #if defined(__AVR32__)
594 Dummy = __AVR32_EPREG_X(UEDAT0);
595 #elif defined(__AVR__)
596 Dummy = UPDATX;
597 #endif
598 }
599
600 /** Reads two bytes from the currently selected pipe's bank in little endian format, for OUT
601 * direction pipes.
602 *
603 * \ingroup Group_PipePrimitiveRW
604 *
605 * \return Next word in the currently selected pipe's FIFO buffer
606 */
607 static inline uint16_t Pipe_Read_Word_LE(void) ATTR_WARN_UNUSED_RESULT ATTR_ALWAYS_INLINE;
608 static inline uint16_t Pipe_Read_Word_LE(void)
609 {
610 union
611 {
612 uint16_t Word;
613 uint8_t Bytes[2];
614 } Data;
615
616 #if defined(__AVR32__)
617 Data.Bytes[0] = __AVR32_EPREG_X(UEDAT0);
618 Data.Bytes[1] = __AVR32_EPREG_X(UEDAT0);
619 #elif defined(__AVR__)
620 Data.Bytes[0] = UPDATX;
621 Data.Bytes[1] = UPDATX;
622 #endif
623
624 return Data.Word;
625 }
626
627 /** Reads two bytes from the currently selected pipe's bank in big endian format, for OUT
628 * direction pipes.
629 *
630 * \ingroup Group_PipePrimitiveRW
631 *
632 * \return Next word in the currently selected pipe's FIFO buffer
633 */
634 static inline uint16_t Pipe_Read_Word_BE(void) ATTR_WARN_UNUSED_RESULT ATTR_ALWAYS_INLINE;
635 static inline uint16_t Pipe_Read_Word_BE(void)
636 {
637 union
638 {
639 uint16_t Word;
640 uint8_t Bytes[2];
641 } Data;
642
643 #if defined(__AVR32__)
644 Data.Bytes[1] = __AVR32_EPREG_X(UEDAT0);
645 Data.Bytes[0] = __AVR32_EPREG_X(UEDAT0);
646 #elif defined(__AVR__)
647 Data.Bytes[1] = UPDATX;
648 Data.Bytes[0] = UPDATX;
649 #endif
650
651 return Data.Word;
652 }
653
654 /** Writes two bytes to the currently selected pipe's bank in little endian format, for IN
655 * direction pipes.
656 *
657 * \ingroup Group_PipePrimitiveRW
658 *
659 * \param[in] Word Next word to write to the currently selected pipe's FIFO buffer
660 */
661 static inline void Pipe_Write_Word_LE(const uint16_t Word) ATTR_ALWAYS_INLINE;
662 static inline void Pipe_Write_Word_LE(const uint16_t Word)
663 {
664 #if defined(__AVR32__)
665 __AVR32_EPREG_X(UEDAT0) = (Word & 0xFF);
666 __AVR32_EPREG_X(UEDAT0) = (Word >> 8);
667 #elif defined(__AVR__)
668 UPDATX = (Word & 0xFF);
669 UPDATX = (Word >> 8);
670 #endif
671 }
672
673 /** Writes two bytes to the currently selected pipe's bank in big endian format, for IN
674 * direction pipes.
675 *
676 * \ingroup Group_PipePrimitiveRW
677 *
678 * \param[in] Word Next word to write to the currently selected pipe's FIFO buffer
679 */
680 static inline void Pipe_Write_Word_BE(const uint16_t Word) ATTR_ALWAYS_INLINE;
681 static inline void Pipe_Write_Word_BE(const uint16_t Word)
682 {
683 #if defined(__AVR32__)
684 __AVR32_EPREG_X(UEDAT0) = (Word >> 8);
685 __AVR32_EPREG_X(UEDAT0) = (Word & 0xFF);
686 #elif defined(__AVR__)
687 UPDATX = (Word >> 8);
688 UPDATX = (Word & 0xFF);
689 #endif
690 }
691
692 /** Discards two bytes from the currently selected pipe's bank, for OUT direction pipes.
693 *
694 * \ingroup Group_PipePrimitiveRW
695 */
696 static inline void Pipe_Discard_Word(void) ATTR_ALWAYS_INLINE;
697 static inline void Pipe_Discard_Word(void)
698 {
699 uint8_t Dummy;
700
701 #if defined(__AVR32__)
702 Dummy = __AVR32_EPREG_X(UEDAT0);
703 Dummy = __AVR32_EPREG_X(UEDAT0);
704 #elif defined(__AVR__)
705 Dummy = UPDATX;
706 Dummy = UPDATX;
707 #endif
708 }
709
710 /** Reads four bytes from the currently selected pipe's bank in little endian format, for OUT
711 * direction pipes.
712 *
713 * \ingroup Group_PipePrimitiveRW
714 *
715 * \return Next double word in the currently selected pipe's FIFO buffer
716 */
717 static inline uint32_t Pipe_Read_DWord_LE(void) ATTR_WARN_UNUSED_RESULT ATTR_ALWAYS_INLINE;
718 static inline uint32_t Pipe_Read_DWord_LE(void)
719 {
720 union
721 {
722 uint32_t DWord;
723 uint8_t Bytes[4];
724 } Data;
725
726 #if defined(__AVR32__)
727 Data.Bytes[0] = __AVR32_EPREG_X(UEDAT0);
728 Data.Bytes[1] = __AVR32_EPREG_X(UEDAT0);
729 Data.Bytes[2] = __AVR32_EPREG_X(UEDAT0);
730 Data.Bytes[3] = __AVR32_EPREG_X(UEDAT0);
731 #elif defined(__AVR__)
732 Data.Bytes[0] = UPDATX;
733 Data.Bytes[1] = UPDATX;
734 Data.Bytes[2] = UPDATX;
735 Data.Bytes[3] = UPDATX;
736 #endif
737
738 return Data.DWord;
739 }
740
741 /** Reads four bytes from the currently selected pipe's bank in big endian format, for OUT
742 * direction pipes.
743 *
744 * \ingroup Group_PipePrimitiveRW
745 *
746 * \return Next double word in the currently selected pipe's FIFO buffer
747 */
748 static inline uint32_t Pipe_Read_DWord_BE(void) ATTR_WARN_UNUSED_RESULT ATTR_ALWAYS_INLINE;
749 static inline uint32_t Pipe_Read_DWord_BE(void)
750 {
751 union
752 {
753 uint32_t DWord;
754 uint8_t Bytes[4];
755 } Data;
756
757 #if defined(__AVR32__)
758 Data.Bytes[3] = __AVR32_EPREG_X(UEDAT0);
759 Data.Bytes[2] = __AVR32_EPREG_X(UEDAT0);
760 Data.Bytes[1] = __AVR32_EPREG_X(UEDAT0);
761 Data.Bytes[0] = __AVR32_EPREG_X(UEDAT0);
762 #elif defined(__AVR__)
763 Data.Bytes[3] = UPDATX;
764 Data.Bytes[2] = UPDATX;
765 Data.Bytes[1] = UPDATX;
766 Data.Bytes[0] = UPDATX;
767 #endif
768
769 return Data.DWord;
770 }
771
772 /** Writes four bytes to the currently selected pipe's bank in little endian format, for IN
773 * direction pipes.
774 *
775 * \ingroup Group_PipePrimitiveRW
776 *
777 * \param[in] DWord Next double word to write to the currently selected pipe's FIFO buffer
778 */
779 static inline void Pipe_Write_DWord_LE(const uint32_t DWord) ATTR_ALWAYS_INLINE;
780 static inline void Pipe_Write_DWord_LE(const uint32_t DWord)
781 {
782 #if defined(__AVR32__)
783 __AVR32_EPREG_X(UEDAT0) = (DWord & 0xFF);
784 __AVR32_EPREG_X(UEDAT0) = (DWord >> 8);
785 __AVR32_EPREG_X(UEDAT0) = (DWord >> 16);
786 __AVR32_EPREG_X(UEDAT0) = (DWord >> 24);
787 #elif defined(__AVR__)
788 UPDATX = (DWord & 0xFF);
789 UPDATX = (DWord >> 8);
790 UPDATX = (DWord >> 16);
791 UPDATX = (DWord >> 24);
792 #endif
793 }
794
795 /** Writes four bytes to the currently selected pipe's bank in big endian format, for IN
796 * direction pipes.
797 *
798 * \ingroup Group_PipePrimitiveRW
799 *
800 * \param[in] DWord Next double word to write to the currently selected pipe's FIFO buffer
801 */
802 static inline void Pipe_Write_DWord_BE(const uint32_t DWord) ATTR_ALWAYS_INLINE;
803 static inline void Pipe_Write_DWord_BE(const uint32_t DWord)
804 {
805 #if defined(__AVR32__)
806 __AVR32_EPREG_X(UEDAT0) = (DWord >> 24);
807 __AVR32_EPREG_X(UEDAT0) = (DWord >> 16);
808 __AVR32_EPREG_X(UEDAT0) = (DWord >> 8);
809 __AVR32_EPREG_X(UEDAT0) = (DWord & 0xFF);
810 #elif defined(__AVR__)
811 UPDATX = (DWord >> 24);
812 UPDATX = (DWord >> 16);
813 UPDATX = (DWord >> 8);
814 UPDATX = (DWord & 0xFF);
815 #endif
816 }
817
818 /** Discards four bytes from the currently selected pipe's bank, for OUT direction pipes.
819 *
820 * \ingroup Group_PipePrimitiveRW
821 */
822 static inline void Pipe_Discard_DWord(void) ATTR_ALWAYS_INLINE;
823 static inline void Pipe_Discard_DWord(void)
824 {
825 uint8_t Dummy;
826
827 #if defined(__AVR32__)
828 Dummy = __AVR32_EPREG_X(UEDAT0);
829 Dummy = __AVR32_EPREG_X(UEDAT0);
830 Dummy = __AVR32_EPREG_X(UEDAT0);
831 Dummy = __AVR32_EPREG_X(UEDAT0);
832 #elif defined(__AVR__)
833 Dummy = UPDATX;
834 Dummy = UPDATX;
835 Dummy = UPDATX;
836 Dummy = UPDATX;
837 #endif
838 }
839
840 /* External Variables: */
841 /** Global indicating the maximum packet size of the default control pipe located at address
842 * 0 in the device. This value is set to the value indicated in the attached device's device
843 * descriptor once the USB interface is initialized into host mode and a device is attached
844 * to the USB bus.
845 *
846 * \note This variable should be treated as read-only in the user application, and never manually
847 * changed in value.
848 */
849 extern uint8_t USB_ControlPipeSize;
850
851 /* Function Prototypes: */
852 #if !defined(NO_STREAM_CALLBACKS) || defined(__DOXYGEN__)
853 #define __CALLBACK_PARAM , StreamCallbackPtr_t Callback
854 #else
855 #define __CALLBACK_PARAM
856 #endif
857
858 /** Configures the specified pipe number with the given pipe type, token, target endpoint number in the
859 * attached device, bank size and banking mode. Pipes should be allocated in ascending order by their
860 * address in the device (i.e. pipe 1 should be configured before pipe 2 and so on) to prevent fragmentation
861 * of the USB FIFO memory.
862 *
863 * The pipe type may be one of the EP_TYPE_* macros listed in LowLevel.h, the token may be one of the
864 * PIPE_TOKEN_* masks.
865 *
866 * The bank size must indicate the maximum packet size that the pipe can handle. Different pipe
867 * numbers can handle different maximum packet sizes - refer to the chosen USB AVR's datasheet to
868 * determine the maximum bank size for each pipe.
869 *
870 * The banking mode may be either \ref PIPE_BANK_SINGLE or \ref PIPE_BANK_DOUBLE.
871 *
872 * A newly configured pipe is frozen by default, and must be unfrozen before use via the \ref Pipe_Unfreeze()
873 * before being used. Pipes should be kept frozen unless waiting for data from a device while in IN mode, or
874 * sending data to the device in OUT mode. IN type pipes are also automatically configured to accept infinite
875 * numbers of IN requests without automatic freezing - this can be overridden by a call to
876 * \ref Pipe_SetFiniteINRequests().
877 *
878 * \note The default control pipe does not have to be manually configured, as it is automatically
879 * configured by the library internally.
880 *
881 * \note This routine will select the specified pipe, and the pipe will remain selected once the
882 * routine completes regardless of if the pipe configuration succeeds.
883 *
884 * \return Boolean true if the configuration is successful, false otherwise
885 */
886 bool Pipe_ConfigurePipe(const uint8_t Number, const uint8_t Type, const uint8_t Token, const uint8_t EndpointNumber,
887 const uint16_t Size, const uint8_t Banks);
888
889 /** Spin-loops until the currently selected non-control pipe is ready for the next packed of data to be read
890 * or written to it, aborting in the case of an error condition (such as a timeout or device disconnect).
891 *
892 * \ingroup Group_PipeRW
893 *
894 * \return A value from the Pipe_WaitUntilReady_ErrorCodes_t enum.
895 */
896 uint8_t Pipe_WaitUntilReady(void);
897
898 /** Determines if a pipe has been bound to the given device endpoint address. If a pipe which is bound to the given
899 * endpoint is found, it is automatically selected.
900 *
901 * \param[in] EndpointAddress Address and direction mask of the endpoint within the attached device to check
902 *
903 * \return Boolean true if a pipe bound to the given endpoint address of the specified direction is found, false
904 * otherwise
905 */
906 bool Pipe_IsEndpointBound(const uint8_t EndpointAddress);
907
908 /** Reads and discards the given number of bytes from the pipe, discarding fully read packets from the host
909 * as needed. The last packet is not automatically discarded once the remaining bytes has been read; the
910 * user is responsible for manually discarding the last packet from the device via the \ref Pipe_ClearIN() macro.
911 * Between each USB packet, the given stream callback function is executed repeatedly until the next packet is ready,
912 * allowing for early aborts of stream transfers.
913 *
914 * The callback routine should be created according to the information in \ref Group_StreamCallbacks.
915 * If the token NO_STREAM_CALLBACKS is passed via the -D option to the compiler, stream callbacks are
916 * disabled and this function has the Callback parameter omitted.
917 *
918 * The pipe token is set automatically, thus this can be used on bi-directional pipes directly without
919 * having to explicitly change the data direction with a call to \ref Pipe_SetPipeToken().
920 *
921 * \ingroup Group_PipeStreamRW
922 *
923 * \param[in] Length Number of bytes to send via the currently selected pipe.
924 * \param[in] Callback Name of a callback routine to call between successive USB packet transfers, NULL if no callback
925 *
926 * \return A value from the \ref Pipe_Stream_RW_ErrorCodes_t enum.
927 */
928 uint8_t Pipe_Discard_Stream(uint16_t Length __CALLBACK_PARAM);
929
930 /** Writes the given number of bytes to the pipe from the given buffer in little endian,
931 * sending full packets to the device as needed. The last packet filled is not automatically sent;
932 * the user is responsible for manually sending the last written packet to the host via the
933 * \ref Pipe_ClearOUT() macro. Between each USB packet, the given stream callback function is
934 * executed repeatedly until the next packet is ready, allowing for early aborts of stream transfers.
935 *
936 * The callback routine should be created according to the information in \ref Group_StreamCallbacks.
937 * If the token NO_STREAM_CALLBACKS is passed via the -D option to the compiler, stream callbacks are
938 * disabled and this function has the Callback parameter omitted.
939 *
940 * The pipe token is set automatically, thus this can be used on bi-directional pipes directly without
941 * having to explicitly change the data direction with a call to \ref Pipe_SetPipeToken().
942 *
943 * \ingroup Group_PipeStreamRW
944 *
945 * \param[in] Buffer Pointer to the source data buffer to read from.
946 * \param[in] Length Number of bytes to read for the currently selected pipe into the buffer.
947 * \param[in] Callback Name of a callback routine to call between successive USB packet transfers, NULL if no callback
948 *
949 * \return A value from the \ref Pipe_Stream_RW_ErrorCodes_t enum.
950 */
951 uint8_t Pipe_Write_Stream_LE(const void* Buffer, uint16_t Length __CALLBACK_PARAM) ATTR_NON_NULL_PTR_ARG(1);
952
953 /** EEPROM buffer source version of \ref Pipe_Write_Stream_LE().
954 *
955 * \ingroup Group_PipeStreamRW
956 *
957 * \param[in] Buffer Pointer to the source data buffer to read from.
958 * \param[in] Length Number of bytes to read for the currently selected pipe into the buffer.
959 * \param[in] Callback Name of a callback routine to call between successive USB packet transfers, NULL if no callback
960 *
961 * \note Not available on AVR32 UC3B targets.
962 *
963 * \return A value from the \ref Pipe_Stream_RW_ErrorCodes_t enum.
964 */
965 uint8_t Pipe_Write_EStream_LE(const void* Buffer, uint16_t Length __CALLBACK_PARAM) ATTR_NON_NULL_PTR_ARG(1);
966
967 /** FLASH buffer source version of \ref Pipe_Write_Stream_LE().
968 *
969 * \note The FLASH data must be located in the first 64KB of FLASH for this function to work correctly.
970 *
971 * \ingroup Group_PipeStreamRW
972 *
973 * \param[in] Buffer Pointer to the source data buffer to read from.
974 * \param[in] Length Number of bytes to read for the currently selected pipe into the buffer.
975 * \param[in] Callback Name of a callback routine to call between successive USB packet transfers, NULL if no callback
976 *
977 * \return A value from the \ref Pipe_Stream_RW_ErrorCodes_t enum.
978 */
979 uint8_t Pipe_Write_PStream_LE(const void* Buffer, uint16_t Length __CALLBACK_PARAM) ATTR_NON_NULL_PTR_ARG(1);
980
981 /** Writes the given number of bytes to the pipe from the given buffer in big endian,
982 * sending full packets to the device as needed. The last packet filled is not automatically sent;
983 * the user is responsible for manually sending the last written packet to the host via the
984 * \ref Pipe_ClearOUT() macro. Between each USB packet, the given stream callback function is
985 * executed repeatedly until the next packet is ready, allowing for early aborts of stream transfers.
986 *
987 * The callback routine should be created according to the information in \ref Group_StreamCallbacks.
988 * If the token NO_STREAM_CALLBACKS is passed via the -D option to the compiler, stream callbacks are
989 * disabled and this function has the Callback parameter omitted.
990 *
991 * The pipe token is set automatically, thus this can be used on bi-directional pipes directly without
992 * having to explicitly change the data direction with a call to \ref Pipe_SetPipeToken().
993 *
994 * \ingroup Group_PipeStreamRW
995 *
996 * \param[in] Buffer Pointer to the source data buffer to read from.
997 * \param[in] Length Number of bytes to read for the currently selected pipe into the buffer.
998 * \param[in] Callback Name of a callback routine to call between successive USB packet transfers, NULL if no callback
999 *
1000 * \return A value from the \ref Pipe_Stream_RW_ErrorCodes_t enum.
1001 */
1002 uint8_t Pipe_Write_Stream_BE(const void* Buffer, uint16_t Length __CALLBACK_PARAM) ATTR_NON_NULL_PTR_ARG(1);
1003
1004 /** EEPROM buffer source version of \ref Pipe_Write_Stream_BE().
1005 *
1006 * \ingroup Group_PipeStreamRW
1007 *
1008 * \param[in] Buffer Pointer to the source data buffer to read from.
1009 * \param[in] Length Number of bytes to read for the currently selected pipe into the buffer.
1010 * \param[in] Callback Name of a callback routine to call between successive USB packet transfers, NULL if no callback
1011 *
1012 * \note Not available on AVR32 UC3B targets.
1013 *
1014 * \return A value from the \ref Pipe_Stream_RW_ErrorCodes_t enum.
1015 */
1016 uint8_t Pipe_Write_EStream_BE(const void* Buffer, uint16_t Length __CALLBACK_PARAM) ATTR_NON_NULL_PTR_ARG(1);
1017
1018 /** FLASH buffer source version of \ref Pipe_Write_Stream_BE().
1019 *
1020 * \note The FLASH data must be located in the first 64KB of FLASH for this function to work correctly.
1021 *
1022 * \ingroup Group_PipeStreamRW
1023 *
1024 * \param[in] Buffer Pointer to the source data buffer to read from.
1025 * \param[in] Length Number of bytes to read for the currently selected pipe into the buffer.
1026 * \param[in] Callback Name of a callback routine to call between successive USB packet transfers, NULL if no callback
1027 *
1028 * \return A value from the \ref Pipe_Stream_RW_ErrorCodes_t enum.
1029 */
1030 uint8_t Pipe_Write_PStream_BE(const void* Buffer, uint16_t Length __CALLBACK_PARAM) ATTR_NON_NULL_PTR_ARG(1);
1031
1032 /** Reads the given number of bytes from the pipe into the given buffer in little endian,
1033 * sending full packets to the device as needed. The last packet filled is not automatically sent;
1034 * the user is responsible for manually sending the last written packet to the host via the
1035 * \ref Pipe_ClearIN() macro. Between each USB packet, the given stream callback function is
1036 * executed repeatedly until the next packet is ready, allowing for early aborts of stream transfers.
1037 *
1038 * The callback routine should be created according to the information in \ref Group_StreamCallbacks.
1039 * If the token NO_STREAM_CALLBACKS is passed via the -D option to the compiler, stream callbacks are
1040 * disabled and this function has the Callback parameter omitted.
1041 *
1042 * The pipe token is set automatically, thus this can be used on bi-directional pipes directly without
1043 * having to explicitly change the data direction with a call to \ref Pipe_SetPipeToken().
1044 *
1045 * \ingroup Group_PipeStreamRW
1046 *
1047 * \param[out] Buffer Pointer to the source data buffer to write to.
1048 * \param[in] Length Number of bytes to read for the currently selected pipe to read from.
1049 * \param[in] Callback Name of a callback routine to call between successive USB packet transfers, NULL if no callback
1050 *
1051 * \return A value from the \ref Pipe_Stream_RW_ErrorCodes_t enum.
1052 */
1053 uint8_t Pipe_Read_Stream_LE(void* Buffer, uint16_t Length __CALLBACK_PARAM) ATTR_NON_NULL_PTR_ARG(1);
1054
1055 /** EEPROM buffer source version of \ref Pipe_Read_Stream_LE().
1056 *
1057 * \ingroup Group_PipeStreamRW
1058 *
1059 * \param[out] Buffer Pointer to the source data buffer to write to.
1060 * \param[in] Length Number of bytes to read for the currently selected pipe to read from.
1061 * \param[in] Callback Name of a callback routine to call between successive USB packet transfers, NULL if no callback
1062 *
1063 * \note Not available on AVR32 UC3B targets.
1064 *
1065 * \return A value from the \ref Pipe_Stream_RW_ErrorCodes_t enum.
1066 */
1067 uint8_t Pipe_Read_EStream_LE(void* Buffer, uint16_t Length __CALLBACK_PARAM) ATTR_NON_NULL_PTR_ARG(1);
1068
1069 /** Reads the given number of bytes from the pipe into the given buffer in big endian,
1070 * sending full packets to the device as needed. The last packet filled is not automatically sent;
1071 * the user is responsible for manually sending the last written packet to the host via the
1072 * \ref Pipe_ClearIN() macro. Between each USB packet, the given stream callback function is
1073 * executed repeatedly until the next packet is ready, allowing for early aborts of stream transfers.
1074 *
1075 * The callback routine should be created according to the information in \ref Group_StreamCallbacks.
1076 * If the token NO_STREAM_CALLBACKS is passed via the -D option to the compiler, stream callbacks are
1077 * disabled and this function has the Callback parameter omitted.
1078 *
1079 * The pipe token is set automatically, thus this can be used on bi-directional pipes directly without
1080 * having to explicitly change the data direction with a call to \ref Pipe_SetPipeToken().
1081 *
1082 * \ingroup Group_PipeStreamRW
1083 *
1084 * \param[out] Buffer Pointer to the source data buffer to write to.
1085 * \param[in] Length Number of bytes to read for the currently selected pipe to read from.
1086 * \param[in] Callback Name of a callback routine to call between successive USB packet transfers, NULL if no callback
1087 *
1088 * \return A value from the \ref Pipe_Stream_RW_ErrorCodes_t enum.
1089 */
1090 uint8_t Pipe_Read_Stream_BE(void* Buffer, uint16_t Length __CALLBACK_PARAM) ATTR_NON_NULL_PTR_ARG(1);
1091
1092 /** EEPROM buffer source version of \ref Pipe_Read_Stream_BE().
1093 *
1094 * \ingroup Group_PipeStreamRW
1095 *
1096 * \param[out] Buffer Pointer to the source data buffer to write to.
1097 * \param[in] Length Number of bytes to read for the currently selected pipe to read from.
1098 * \param[in] Callback Name of a callback routine to call between successive USB packet transfers, NULL if no callback
1099 *
1100 * \note Not available on AVR32 UC3B targets.
1101 *
1102 * \return A value from the \ref Pipe_Stream_RW_ErrorCodes_t enum.
1103 */
1104 uint8_t Pipe_Read_EStream_BE(void* Buffer, uint16_t Length __CALLBACK_PARAM) ATTR_NON_NULL_PTR_ARG(1);
1105
1106 /* Private Interface - For use in library only: */
1107 #if !defined(__DOXYGEN__)
1108 /* Macros: */
1109 #define PIPE_TOKEN_MASK (0x03 << PTOKEN0)
1110
1111 #if !defined(ENDPOINT_CONTROLEP)
1112 #define ENDPOINT_CONTROLEP 0
1113 #endif
1114
1115 #define Pipe_AllocateMemory() MACROS{ UPCFG1X |= (1 << ALLOC); }MACROE
1116 #define Pipe_DeallocateMemory() MACROS{ UPCFG1X &= ~(1 << ALLOC); }MACROE
1117
1118 /* Function Prototypes: */
1119 void Pipe_ClearPipes(void);
1120
1121 /* Inline Functions: */
1122 static inline uintN_t Pipe_BytesToEPSizeMask(uint16_t Bytes) ATTR_WARN_UNUSED_RESULT ATTR_CONST ATTR_ALWAYS_INLINE;
1123 static inline uintN_t Pipe_BytesToEPSizeMask(uint16_t Bytes)
1124 {
1125 #if defined(__AVR32__)
1126 // TODO
1127 return 0;
1128 #elif defined(__AVR__)
1129 if (Bytes <= 8)
1130 return (0 << EPSIZE0);
1131 else if (Bytes <= 16)
1132 return (1 << EPSIZE0);
1133 else if (Bytes <= 32)
1134 return (2 << EPSIZE0);
1135 else if (Bytes <= 64)
1136 return (3 << EPSIZE0);
1137 else if (Bytes <= 128)
1138 return (4 << EPSIZE0);
1139 else
1140 return (5 << EPSIZE0);
1141 #endif
1142 }
1143
1144 #endif
1145
1146 /* Disable C linkage for C++ Compilers: */
1147 #if defined(__cplusplus)
1148 }
1149 #endif
1150
1151 #endif
1152
1153 /** @} */
USB isp AVR programmer