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