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


df3ac7ddc35ad373f83537c108d4bfa164a664e6
[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 datatypes.
36 */
37
38 #ifndef __PIPE_H__
39 #define __PIPE_H__
40
41 /* Includes: */
42 #include <avr/io.h>
43 #include <stdbool.h>
44
45 #include "../../../Common/Common.h"
46 #include "../HighLevel/USBTask.h"
47
48 #if !defined(NO_STREAM_CALLBACKS) || defined(__DOXYGEN__)
49 #include "StreamCallbacks.h"
50 #endif
51
52 /* Enable C linkage for C++ Compilers: */
53 #if defined(__cplusplus)
54 extern "C" {
55 #endif
56
57 /* Public Interface - May be used in end-application: */
58 /* Macros: */
59 /** Mask for Pipe_GetErrorFlags(), indicating that a CRC error occurred in the pipe on the received data. */
60 #define PIPE_ERRORFLAG_CRC16 (1 << 4)
61
62 /** Mask for Pipe_GetErrorFlags(), indicating that a hardware timeout error occurred in the pipe. */
63 #define PIPE_ERRORFLAG_TIMEOUT (1 << 3)
64
65 /** Mask for Pipe_GetErrorFlags(), indicating that a hardware PID error occurred in the pipe. */
66 #define PIPE_ERRORFLAG_PID (1 << 2)
67
68 /** Mask for Pipe_GetErrorFlags(), indicating that a hardware data PID error occurred in the pipe. */
69 #define PIPE_ERRORFLAG_DATAPID (1 << 1)
70
71 /** Mask for Pipe_GetErrorFlags(), indicating that a hardware data toggle error occurred in the pipe. */
72 #define PIPE_ERRORFLAG_DATATGL (1 << 0)
73
74 /** Token mask for Pipe_ConfigurePipe(). This sets the pipe as a SETUP token (for CONTROL type pipes),
75 * which will trigger a control request on the attached device when data is written to the pipe.
76 */
77 #define PIPE_TOKEN_SETUP (0b00 << PTOKEN0)
78
79 /** Token mask for Pipe_ConfigurePipe(). This sets the pipe as a IN token (for non-CONTROL type pipes),
80 * indicating that the pipe data will flow from device to host.
81 */
82 #define PIPE_TOKEN_IN (0b01 << PTOKEN0)
83
84 /** Token mask for Pipe_ConfigurePipe(). This sets the pipe as a IN token (for non-CONTROL type pipes),
85 * indicating that the pipe data will flow from host to device.
86 */
87 #define PIPE_TOKEN_OUT (0b10 << PTOKEN0)
88
89 /** Mask for the bank mode selection for the Pipe_ConfigurePipe() macro. This indicates that the pipe
90 * should have one single bank, which requires less USB FIFO memory but results in slower transfers as
91 * only one USB device (the AVR or the attached device) can access the pipe's bank at the one time.
92 */
93 #define PIPE_BANK_SINGLE (0 << EPBK0)
94
95 /** Mask for the bank mode selection for the Pipe_ConfigurePipe() macro. This indicates that the pipe
96 * should have two banks, which requires more USB FIFO memory but results in faster transfers as one
97 * USB device (the AVR or the attached device) can access one bank while the other accesses the second
98 * bank.
99 */
100 #define PIPE_BANK_DOUBLE (1 << EPBK0)
101
102 /** Pipe address for the default control pipe, which always resides in address 0. This is
103 * defined for convenience to give more readable code when used with the pipe macros.
104 */
105 #define PIPE_CONTROLPIPE 0
106
107 /** Default size of the default control pipe's bank, until altered by the Endpoint0Size value
108 * in the device descriptor of the attached device.
109 */
110 #define PIPE_CONTROLPIPE_DEFAULT_SIZE 8
111
112 /** Pipe number mask, for masking against pipe addresses to retrieve the pipe's numerical address
113 * in the device.
114 */
115 #define PIPE_PIPENUM_MASK 0x07
116
117 /** Total number of pipes (including the default control pipe at address 0) which may be used in
118 * the device. Different USB AVR models support different amounts of pipes, this value reflects
119 * the maximum number of pipes for the currently selected AVR model.
120 */
121 #define PIPE_TOTAL_PIPES 7
122
123 /** Size in bytes of the largest pipe bank size possible in the device. Not all banks on each AVR
124 * model supports the largest bank size possible on the device; different pipe numbers support
125 * different maximum bank sizes. This value reflects the largest possible bank of any pipe on the
126 * currently selected USB AVR model.
127 */
128 #define PIPE_MAX_SIZE 256
129
130 /** Endpoint number mask, for masking against endpoint addresses to retrieve the endpoint's
131 * numerical address in the attached device.
132 */
133 #define PIPE_EPNUM_MASK 0x07
134
135 /** Endpoint bank size mask, for masking against endpoint addresses to retrieve the endpoint's
136 * bank size in the attached device.
137 */
138 #define PIPE_EPSIZE_MASK 0x7FF
139
140 /** Interrupt definition for the pipe IN interrupt (for INTERRUPT type pipes). Should be used with
141 * the USB_INT_* macros located in USBInterrupt.h.
142 *
143 * This interrupt will fire if enabled on an INTERRUPT type pipe if the pipe interrupt period has
144 * elapsed and the pipe is ready for the next packet from the attached device to be read out from its
145 * FIFO buffer (if received).
146 *
147 * \note This interrupt must be enabled and cleared on *each* pipe which requires it (after the pipe
148 * is selected), and will fire the common pipe interrupt vector.
149 *
150 * \see ENDPOINT_PIPE_vect for more information on the common pipe and endpoint interrupt vector.
151 */
152 #define PIPE_INT_IN UPIENX, (1 << RXINE) , UPINTX, (1 << RXINI)
153
154 /** Interrupt definition for the pipe OUT interrupt (for INTERRUPT type pipes). Should be used with
155 * the USB_INT_* macros located in USBInterrupt.h.
156 *
157 * This interrupt will fire if enabled on an INTERRUPT type endpoint if a the pipe interrupt period
158 * has elapsed and the pipe is ready for a packet to be written to the pipe's FIFO buffer and sent
159 * to the attached device (if required).
160 *
161 * \note This interrupt must be enabled and cleared on *each* pipe which requires it (after the pipe
162 * is selected), and will fire the common pipe interrupt vector.
163 *
164 * \see ENDPOINT_PIPE_vect for more information on the common pipe and endpoint interrupt vector.
165 */
166 #define PIPE_INT_OUT UPIENX, (1 << TXOUTE), UPINTX, (1 << TXOUTI)
167
168 /** Interrupt definition for the pipe SETUP bank ready interrupt (for CONTROL type pipes). Should be
169 * used with the USB_INT_* macros located in USBInterrupt.h.
170 *
171 * This interrupt will fire if enabled on an CONTROL type pipe when the pipe is ready for a new
172 * control request.
173 *
174 * \note This interrupt must be enabled and cleared on *each* pipe which requires it (after the pipe
175 * is selected), and will fire the common pipe interrupt vector.
176 *
177 * \see ENDPOINT_PIPE_vect for more information on the common pipe and endpoint interrupt vector.
178 */
179 #define PIPE_INT_SETUP UPIENX, (1 << TXSTPE) , UPINTX, (1 << TXSTPI)
180
181 /** Interrupt definition for the pipe error interrupt. Should be used with the USB_INT_* macros
182 * located in USBInterrupt.h.
183 *
184 * This interrupt will fire if enabled on a particular pipe if an error occurs on that pipe, such
185 * as a CRC mismatch error.
186 *
187 * \note This interrupt must be enabled and cleared on *each* pipe which requires it (after the pipe
188 * is selected), and will fire the common pipe interrupt vector.
189 *
190 * \see ENDPOINT_PIPE_vect for more information on the common pipe and endpoint interrupt vector.
191 *
192 * \see Pipe_GetErrorFlags() for more information on the pipe errors.
193 */
194 #define PIPE_INT_ERROR UPIENX, (1 << PERRE), UPINTX, (1 << PERRI)
195
196 /** Interrupt definition for the pipe NAK received interrupt. Should be used with the USB_INT_* macros
197 * located in USBInterrupt.h.
198 *
199 * This interrupt will fire if enabled on a particular pipe if an attached device returns a NAK in
200 * response to a sent packet.
201 *
202 * \note This interrupt must be enabled and cleared on *each* pipe which requires it (after the pipe
203 * is selected), and will fire the common pipe interrupt vector.
204 *
205 * \see ENDPOINT_PIPE_vect for more information on the common pipe and endpoint interrupt vector.
206 *
207 * \see Pipe_IsNAKReceived() for more information on pipe NAKs.
208 */
209 #define PIPE_INT_NAK UPIENX, (1 << NAKEDE), UPINTX, (1 << NAKEDI)
210
211 /** Interrupt definition for the pipe STALL received interrupt. Should be used with the USB_INT_* macros
212 * located in USBInterrupt.h.
213 *
214 * This interrupt will fire if enabled on a particular pipe if an attached device returns a STALL on the
215 * currently selected pipe. This will also fire if the pipe is an isochronous pipe and a CRC error occurs.
216 *
217 * \note This interrupt must be enabled and cleared on *each* pipe which requires it (after the pipe
218 * is selected), and will fire the common pipe interrupt vector.
219 *
220 * \see ENDPOINT_PIPE_vect for more information on the common pipe and endpoint interrupt vector.
221 */
222 #define PIPE_INT_STALL UPIENX, (1 << RXSTALLE), UPINTX, (1 << RXSTALLI)
223
224 /** Indicates the number of bytes currently stored in the current pipe's selected bank. */
225 #define Pipe_BytesInPipe() UPBCX
226
227 /** Resets the desired pipe, including the pipe banks and flags. */
228 #define Pipe_ResetPipe(pipenum) MACROS{ UPRST = (1 << pipenum); UPRST = 0; }MACROE
229
230 /** Selects the given pipe number. Any pipe operations which do not require the pipe number to be
231 * indicated will operate on the currently selected pipe.
232 */
233 #define Pipe_SelectPipe(pipenum) MACROS{ UPNUM = pipenum; }MACROE
234
235 /** Returns the pipe address of the currently selected pipe. This is typically used to save the
236 * currently selected pipe number so that it can be restored after another pipe has been manipulated.
237 */
238 #define Pipe_GetCurrentPipe() (UPNUM & PIPE_PIPENUM_MASK)
239
240 /** Enables the currently selected pipe so that data can be sent and received through it to and from
241 * an attached device.
242 *
243 * \note Pipes must first be configured properly rather than just being enabled via the
244 * Pipe_ConfigurePipe() macro, which calls Pipe_EnablePipe() automatically.
245 */
246 #define Pipe_EnablePipe() MACROS{ UPCONX |= (1 << PEN); }MACROE
247
248 /** Disables the currently selected pipe so that data cannot be sent and received through it to and
249 * from an attached device.
250 */
251 #define Pipe_DisablePipe() MACROS{ UPCONX &= ~(1 << PEN); }MACROE
252
253 /** Returns true if the currently selected pipe is enabled, false otherwise. */
254 #define Pipe_IsEnabled() ((UPCONX & (1 << PEN)) ? true : false)
255
256 /** Sets the token for the currently selected endpoint to one of the tokens specified by the PIPE_TOKEN_*
257 * masks. This should only be used on CONTROL type endpoints, to allow for bidirectional transfer of
258 * data during control requests.
259 */
260 #define Pipe_SetToken(token) MACROS{ UPCFG0X = ((UPCFG0X & ~PIPE_TOKEN_MASK) | token); }MACROE
261
262 /** Configures the currently selected pipe to allow for an unlimited number of IN requests. */
263 #define Pipe_SetInfiniteINRequests() MACROS{ UPCONX |= (1 << INMODE); }MACROE
264
265 /** Configures the currently selected pipe to only allow the specified number of IN requests to be
266 * accepted by the pipe before it is automatically frozen.
267 */
268 #define Pipe_SetFiniteINRequests(n) MACROS{ UPCONX &= ~(1 << INMODE); UPINRQX = n; }MACROE
269
270 /** Returns true if the currently selected pipe is configured, false otherwise. */
271 #define Pipe_IsConfigured() ((UPSTAX & (1 << CFGOK)) ? true : false)
272
273 /** Sets the period between interrupts for an INTERRUPT type pipe to a specified number of milliseconds. */
274 #define Pipe_SetInterruptPeriod(ms) MACROS{ UPCFG2X = ms; }MACROE
275
276 /** Returns a mask indicating which pipe's interrupt periods have elapsed, indicating that the pipe should
277 * be serviced.
278 */
279 #define Pipe_GetPipeInterrupts() UPINT
280
281 /** Clears the interrupt flag for the specified pipe number. */
282 #define Pipe_ClearPipeInterrupt(n) MACROS{ UPINT &= ~(1 << n); }MACROE
283
284 /** Returns true if the specified pipe's interrupt period has elapsed, false otherwise. */
285 #define Pipe_HasPipeInterrupted(n) ((UPINT & (1 << n)) ? true : false)
286
287 /** Clears the pipe bank, and switches to the alternate bank if the currently selected pipe is
288 * dual-banked. When cleared, this either frees the bank up for the next packet from the host
289 * (if the endpoint is of the OUT direction) or sends the packet contents to the host (if the
290 * pipe is of the IN direction).
291 */
292 #define Pipe_ClearCurrentBank() MACROS{ UPINTX &= ~(1 << FIFOCON); }MACROE
293
294 /** Unfreezes the pipe, allowing it to communicate with an attached device. */
295 #define Pipe_Unfreeze() MACROS{ UPCONX &= ~(1 << PFREEZE); }MACROE
296
297 /** Freezes the pipe, preventing it from communicating with an attached device. */
298 #define Pipe_Freeze() MACROS{ UPCONX |= (1 << PFREEZE); }MACROE
299
300 /** Clears the master pipe error flag. */
301 #define Pipe_ClearError() MACROS{ UPINTX &= ~(1 << PERRI); }MACROE
302
303 /** Returns true if the master pipe error flag is set for the currently selected pipe, indicating that
304 * some sort of hardware error has occurred on the pipe.
305 *
306 * \see Pipe_GetErrorFlags() macro for information on retreiving the exact error flag.
307 */
308 #define Pipe_IsError() ((UPINTX & (1 << PERRI)) ? true : false)
309
310 /** Clears all the currently selected pipe's hardware error flags, but does not clear the master error
311 * flag for the pipe. */
312 #define Pipe_ClearErrorFlags() MACROS{ UPERRX = 0; }MACROE
313
314 /** Returns a mask of the hardware error flags which have occured on the currently selected pipe. This
315 * value can then be masked against the PIPE_ERRORFLAG_* masks to determine what error has occurred.
316 */
317 #define Pipe_GetErrorFlags() UPERRX
318
319 /** Returns true if the currently selected pipe may be read from (if data is waiting in the pipe
320 * bank and the pipe is an IN direction, or if the bank is not yet full if the pipe is an OUT
321 * direction). This function will return false if an error has occured in the pipe, or if the pipe
322 * is an IN direction and no packet has been received, or if the pipe is an OUT direction and the
323 * pipe bank is full.
324 */
325 #define Pipe_ReadWriteAllowed() ((UPINTX & (1 << RWAL)) ? true : false)
326
327 /** Clears the flag indicating that a SETUP request has been sent to the attached device from the
328 * currently selected CONTROL type pipe.
329 */
330 #define Pipe_ClearSetupSent() MACROS{ UPINTX &= ~(1 << TXSTPI); }MACROE
331
332 /** Returns true if no SETUP request is currently being sent to the attached device, false otherwise. */
333 #define Pipe_IsSetupSent() ((UPINTX & (1 << TXSTPI)) ? true : false)
334
335 /** Returns true if the currently selected pipe has been stalled by the attached device, false otherwise. */
336 #define Pipe_IsStalled() ((UPINTX & (1 << RXSTALLI)) ? true : false)
337
338 /** Clears the stall condition on the currently selected pipe. */
339 #define Pipe_ClearStall() MACROS{ UPINTX &= ~(1 << RXSTALLI); }MACROE
340
341 /** Returns true if an IN request has been received on the currently selected CONTROL type pipe, false
342 * otherwise.
343 */
344 #define Pipe_IsSetupINReceived() ((UPINTX & (1 << RXINI)) ? true : false)
345
346 /** Returns true if the currently selected CONTROL type pipe is ready to send an OUT request, false
347 * otherwise.
348 */
349 #define Pipe_IsSetupOUTReady() ((UPINTX & (1 << TXOUTI)) ? true : false)
350
351 /** Acknowledges the reception of a setup IN request from the attached device on the currently selected
352 * CONTROL type endpoint, allowing for the transmission of a setup OUT packet, or the reception of
353 * another setup IN packet.
354 */
355 #define Pipe_ClearSetupIN() MACROS{ UPINTX &= ~(1 << RXINI); UPINTX &= ~(1 << FIFOCON); }MACROE
356
357 /** Sends the currently selected CONTROL type pipe's contents to the device as a setup OUT packet. */
358 #define Pipe_ClearSetupOUT() MACROS{ UPINTX &= ~(1 << TXOUTI); UPINTX &= ~(1 << FIFOCON); }MACROE
359
360 /** Returns true if the device sent a NAK (Negative Acknowledge) in response to the last sent packet on
361 * the currently selected pipe. This ocurrs when the host sends a packet to the device, but the device
362 * is not currently ready to handle the packet (i.e. its endpoint banks are full). Once a NAK has been
363 * received, it must be cleard using Pipe_ClearNAKReceived() before the previous (or any other) packet
364 * can be re-sent.
365 */
366 #define Pipe_IsNAKReceived() ((UPINTX & (1 << NAKEDI)) ? true : false)
367
368 /** Clears the NAK condition on the currently selected pipe.
369 *
370 * \see Pipe_IsNAKReceived() for more details.
371 */
372 #define Pipe_ClearNAKReceived() MACROS{ UPINTX &= ~(1 << NAKEDI); }MACROE
373
374 /* Enums: */
375 /** Enum for the possible error return codes of the Pipe_WaitUntilReady function */
376 enum Pipe_WaitUntilReady_ErrorCodes_t
377 {
378 PIPE_READYWAIT_NoError = 0, /**< Pipe ready for next packet, no error */
379 PIPE_READYWAIT_PipeStalled = 1, /**< The device stalled the pipe while waiting. */
380 PIPE_READYWAIT_DeviceDisconnected = 2, /**< Device was disconnected from the host while waiting. */
381 PIPE_READYWAIT_Timeout = 3, /**< The device failed to accept or send the next packet
382 * within the software timeout period set by the
383 * USB_STREAM_TIMEOUT_MS macro.
384 */
385 };
386
387 /** Enum for the possible error return codes of the Pipe_*_Stream_* functions. */
388 enum Pipe_Stream_RW_ErrorCodes_t
389 {
390 PIPE_RWSTREAM_ERROR_NoError = 0, /**< Command completed successfully, no error. */
391 PIPE_RWSTREAM_ERROR_PipeStalled = 1, /**< The device stalled the pipe during the transfer. */
392 PIPE_RWSTREAM_ERROR_DeviceDisconnected = 2, /**< Device was disconnected from the host during
393 * the transfer.
394 */
395 PIPE_RWSTREAM_ERROR_Timeout = 3, /**< The device failed to accept or send the next packet
396 * within the software timeout period set by the
397 * USB_STREAM_TIMEOUT_MS macro.
398 */
399 PIPE_RWSTREAM_ERROR_CallbackAborted = 4, /**< Indicates that the stream's callback function aborted
400 * the transfer early.
401 */
402 };
403
404 /* Inline Functions: */
405 /** Reads one byte from the currently selected pipe's bank, for OUT direction pipes. */
406 static inline uint8_t Pipe_Read_Byte(void) ATTR_WARN_UNUSED_RESULT ATTR_ALWAYS_INLINE;
407 static inline uint8_t Pipe_Read_Byte(void)
408 {
409 return UPDATX;
410 }
411
412 /** Writes one byte from the currently selected pipe's bank, for IN direction pipes. */
413 static inline void Pipe_Write_Byte(const uint8_t Byte) ATTR_ALWAYS_INLINE;
414 static inline void Pipe_Write_Byte(const uint8_t Byte)
415 {
416 UPDATX = Byte;
417 }
418
419 /** Discards one byte from the currently selected pipe's bank, for OUT direction pipes. */
420 static inline void Pipe_Discard_Byte(void) ATTR_ALWAYS_INLINE;
421 static inline void Pipe_Discard_Byte(void)
422 {
423 uint8_t Dummy;
424
425 Dummy = UPDATX;
426 }
427
428 /** Reads two bytes from the currently selected pipe's bank in little endian format, for OUT
429 * direction pipes.
430 */
431 static inline uint16_t Pipe_Read_Word_LE(void) ATTR_WARN_UNUSED_RESULT ATTR_ALWAYS_INLINE;
432 static inline uint16_t Pipe_Read_Word_LE(void)
433 {
434 uint16_t Data;
435
436 Data = UPDATX;
437 Data |= (((uint16_t)UPDATX) << 8);
438
439 return Data;
440 }
441
442 /** Reads two bytes from the currently selected pipe's bank in big endian format, for OUT
443 * direction pipes.
444 */
445 static inline uint16_t Pipe_Read_Word_BE(void) ATTR_WARN_UNUSED_RESULT ATTR_ALWAYS_INLINE;
446 static inline uint16_t Pipe_Read_Word_BE(void)
447 {
448 uint16_t Data;
449
450 Data = (((uint16_t)UPDATX) << 8);
451 Data |= UPDATX;
452
453 return Data;
454 }
455
456 /** Writes two bytes to the currently selected pipe's bank in little endian format, for IN
457 * direction pipes.
458 */
459 static inline void Pipe_Write_Word_LE(const uint16_t Word) ATTR_ALWAYS_INLINE;
460 static inline void Pipe_Write_Word_LE(const uint16_t Word)
461 {
462 UPDATX = (Word & 0xFF);
463 UPDATX = (Word >> 8);
464 }
465
466 /** Writes two bytes to the currently selected pipe's bank in big endian format, for IN
467 * direction pipes.
468 */
469 static inline void Pipe_Write_Word_BE(const uint16_t Word) ATTR_ALWAYS_INLINE;
470 static inline void Pipe_Write_Word_BE(const uint16_t Word)
471 {
472 UPDATX = (Word >> 8);
473 UPDATX = (Word & 0xFF);
474 }
475
476 /** Discards two bytes from the currently selected pipe's bank, for OUT direction pipes. */
477 static inline void Pipe_Ignore_Word(void) ATTR_ALWAYS_INLINE;
478 static inline void Pipe_Ignore_Word(void)
479 {
480 uint8_t Dummy;
481
482 Dummy = UPDATX;
483 Dummy = UPDATX;
484 }
485
486 /** Reads four bytes from the currently selected pipe's bank in little endian format, for OUT
487 * direction pipes.
488 */
489 static inline uint32_t Pipe_Read_DWord_LE(void) ATTR_WARN_UNUSED_RESULT ATTR_ALWAYS_INLINE;
490 static inline uint32_t Pipe_Read_DWord_LE(void)
491 {
492 union
493 {
494 uint32_t DWord;
495 uint8_t Bytes[4];
496 } Data;
497
498 Data.Bytes[0] = UPDATX;
499 Data.Bytes[1] = UPDATX;
500 Data.Bytes[2] = UPDATX;
501 Data.Bytes[3] = UPDATX;
502
503 return Data.DWord;
504 }
505
506 /** Reads four bytes from the currently selected pipe's bank in big endian format, for OUT
507 * direction pipes.
508 */
509 static inline uint32_t Pipe_Read_DWord_BE(void) ATTR_WARN_UNUSED_RESULT ATTR_ALWAYS_INLINE;
510 static inline uint32_t Pipe_Read_DWord_BE(void)
511 {
512 union
513 {
514 uint32_t DWord;
515 uint8_t Bytes[4];
516 } Data;
517
518 Data.Bytes[3] = UPDATX;
519 Data.Bytes[2] = UPDATX;
520 Data.Bytes[1] = UPDATX;
521 Data.Bytes[0] = UPDATX;
522
523 return Data.DWord;
524 }
525
526 /** Writes four bytes to the currently selected pipe's bank in little endian format, for IN
527 * direction pipes.
528 */
529 static inline void Pipe_Write_DWord_LE(const uint32_t DWord) ATTR_ALWAYS_INLINE;
530 static inline void Pipe_Write_DWord_LE(const uint32_t DWord)
531 {
532 Pipe_Write_Word_LE(DWord);
533 Pipe_Write_Word_LE(DWord >> 16);
534 }
535
536 /** Writes four bytes to the currently selected pipe's bank in big endian format, for IN
537 * direction pipes.
538 */
539 static inline void Pipe_Write_DWord_BE(const uint32_t DWord) ATTR_ALWAYS_INLINE;
540 static inline void Pipe_Write_DWord_BE(const uint32_t DWord)
541 {
542 Pipe_Write_Word_BE(DWord >> 16);
543 Pipe_Write_Word_BE(DWord);
544 }
545
546 /** Discards four bytes from the currently selected pipe's bank, for OUT direction pipes. */
547 static inline void Pipe_Ignore_DWord(void) ATTR_ALWAYS_INLINE;
548 static inline void Pipe_Ignore_DWord(void)
549 {
550 uint8_t Dummy;
551
552 Dummy = UPDATX;
553 Dummy = UPDATX;
554 Dummy = UPDATX;
555 Dummy = UPDATX;
556 }
557
558 /* External Variables: */
559 /** Global indicating the maximum packet size of the default control pipe located at address
560 * 0 in the device. This value is set to the value indicated in the attached device's device
561 * descriptor once the USB interface is initialized into host mode and a device is attached
562 * to the USB bus.
563 *
564 * \note This variable should be treated as read-only in the user application, and never manually
565 * changed in value.
566 */
567 extern uint8_t USB_ControlPipeSize;
568
569 /* Function Prototypes: */
570 /** Configures the specified pipe number with the given pipe type, token, target endpoint number in the
571 * attached device, bank size and banking mode. Pipes should be allocated in ascending order by their
572 * address in the device (i.e. pipe 1 should be configured before pipe 2 and so on).
573 *
574 * The pipe type may be one of the EP_TYPE_* macros listed in LowLevel.h, the token may be one of the
575 * PIPE_TOKEN_* masks.
576 *
577 * The bank size must indicate the maximum packet size that the pipe can handle. Different pipe
578 * numbers can handle different maximum packet sizes - refer to the chosen USB AVR's datasheet to
579 * determine the maximum bank size for each pipe.
580 *
581 * The banking mode may be either PIPE_BANK_SINGLE or PIPE_BANK_DOUBLE.
582 *
583 * A newly configured pipe is frozen by default, and must be unfrozen before use via the Pipe_Unfreeze() macro.
584 *
585 * \note This routine will select the specified pipe, and the pipe will remain selected once the
586 * routine completes regardless of if the pipe configuration succeeds.
587 *
588 * \return Boolean true if the configuration is successful, false otherwise
589 */
590 bool Pipe_ConfigurePipe(const uint8_t Number, const uint8_t Type, const uint8_t Token, const uint8_t EndpointNumber,
591 const uint16_t Size, const uint8_t Banks);
592
593 /** Spinloops until the currently selected non-control pipe is ready for the next packed of data
594 * to be read or written to it.
595 *
596 * \note This routine should not be called on CONTROL type pipes.
597 *
598 * \return A value from the Pipe_WaitUntilReady_ErrorCodes_t enum.
599 */
600 uint8_t Pipe_WaitUntilReady(void);
601
602 /** Writes the given number of bytes to the pipe from the given buffer in little endian,
603 * sending full packets to the device as needed. The last packet filled is not automatically sent;
604 * the user is responsible for manually sending the last written packet to the host via the
605 * Pipe_ClearCurrentBank() macro. Between each USB packet, the given stream callback function is
606 * executed repeatedly until the next packet is ready, allowing for early aborts of stream transfers.
607 *
608 * The callback routine should be created using the STREAM_CALLBACK() macro. If the token
609 * NO_STREAM_CALLBACKS is passed via the -D option to the compiler, stream callbacks are disabled
610 * and this function has the Callback parameter ommitted.
611 *
612 * \param Buffer Pointer to the source data buffer to read from.
613 * \param Length Number of bytes to read for the currently selected pipe into the buffer.
614 * \param Callback Name of a callback routine to call between sucessive USB packet transfers, NULL if no callback
615 *
616 * \return A value from the Pipe_Stream_RW_ErrorCodes_t enum.
617 */
618 uint8_t Pipe_Write_Stream_LE(const void* Buffer, uint16_t Length
619 #if !defined(NO_STREAM_CALLBACKS) || defined(__DOXYGEN__)
620 , uint8_t (* const Callback)(void)
621 #endif
622 ) ATTR_NON_NULL_PTR_ARG(1);
623
624 /** Writes the given number of bytes to the pipe from the given buffer in big endian,
625 * sending full packets to the device as needed. The last packet filled is not automatically sent;
626 * the user is responsible for manually sending the last written packet to the host via the
627 * Pipe_ClearCurrentBank() macro. Between each USB packet, the given stream callback function is
628 * executed repeatedly until the next packet is ready, allowing for early aborts of stream transfers.
629 *
630 * The callback routine should be created using the STREAM_CALLBACK() macro. If the token
631 * NO_STREAM_CALLBACKS is passed via the -D option to the compiler, stream callbacks are disabled
632 * and this function has the Callback parameter ommitted.
633 *
634 * \param Buffer Pointer to the source data buffer to read from.
635 * \param Length Number of bytes to read for the currently selected pipe into the buffer.
636 * \param Callback Name of a callback routine to call between sucessive USB packet transfers, NULL if no callback
637 *
638 * \return A value from the Pipe_Stream_RW_ErrorCodes_t enum.
639 */
640 uint8_t Pipe_Write_Stream_BE(const void* Buffer, uint16_t Length
641 #if !defined(NO_STREAM_CALLBACKS) || defined(__DOXYGEN__)
642 , uint8_t (* const Callback)(void)
643 #endif
644 ) ATTR_NON_NULL_PTR_ARG(1);
645
646 /** Reads and discards the given number of bytes from the pipe, discarding fully read packets from the host
647 * as needed. The last packet is not automatically discarded once the remaining bytes has been read; the
648 * user is responsible for manually discarding the last packet from the host via the Pipe_ClearCurrentBank() macro.
649 * Between each USB packet, the given stream callback function is executed repeatedly until the next packet is ready,
650 * allowing for early aborts of stream transfers.
651 *
652 * The callback routine should be created using the STREAM_CALLBACK() macro. If the token
653 * NO_STREAM_CALLBACKS is passed via the -D option to the compiler, stream callbacks are disabled
654 * and this function has the Callback parameter ommitted.
655 *
656 * \param Length Number of bytes to send via the currently selected pipe.
657 * \param Callback Name of a callback routine to call between sucessive USB packet transfers, NULL if no callback
658 *
659 * \return A value from the Pipe_Stream_RW_ErrorCodes_t enum.
660 */
661 uint8_t Pipe_Discard_Stream(uint16_t Length
662 #if !defined(NO_STREAM_CALLBACKS) || defined(__DOXYGEN__)
663 , uint8_t (* const Callback)(void)
664 #endif
665 );
666
667 /** Reads the given number of bytes from the pipe into the given buffer in little endian,
668 * sending full packets to the device as needed. The last packet filled is not automatically sent;
669 * the user is responsible for manually sending the last written packet to the host via the
670 * Pipe_ClearCurrentBank() macro. Between each USB packet, the given stream callback function is
671 * executed repeatedly until the next packet is ready, allowing for early aborts of stream transfers.
672 *
673 * The callback routine should be created using the STREAM_CALLBACK() macro. If the token
674 * NO_STREAM_CALLBACKS is passed via the -D option to the compiler, stream callbacks are disabled
675 * and this function has the Callback parameter ommitted.
676 *
677 * \param Buffer Pointer to the source data buffer to write to.
678 * \param Length Number of bytes to read for the currently selected pipe to read from.
679 * \param Callback Name of a callback routine to call between sucessive USB packet transfers, NULL if no callback
680 *
681 * \return A value from the Pipe_Stream_RW_ErrorCodes_t enum.
682 */
683 uint8_t Pipe_Read_Stream_LE(void* Buffer, uint16_t Length
684 #if !defined(NO_STREAM_CALLBACKS) || defined(__DOXYGEN__)
685 , uint8_t (* const Callback)(void)
686 #endif
687 ) ATTR_NON_NULL_PTR_ARG(1);
688
689 /** Reads the given number of bytes from the pipe into the given buffer in big endian,
690 * sending full packets to the device as needed. The last packet filled is not automatically sent;
691 * the user is responsible for manually sending the last written packet to the host via the
692 * Pipe_ClearCurrentBank() macro. Between each USB packet, the given stream callback function is
693 * executed repeatedly until the next packet is ready, allowing for early aborts of stream transfers.
694 *
695 * The callback routine should be created using the STREAM_CALLBACK() macro. If the token
696 * NO_STREAM_CALLBACKS is passed via the -D option to the compiler, stream callbacks are disabled
697 * and this function has the Callback parameter ommitted.
698 *
699 * \param Buffer Pointer to the source data buffer to write to.
700 * \param Length Number of bytes to read for the currently selected pipe to read from.
701 * \param Callback Name of a callback routine to call between sucessive USB packet transfers, NULL if no callback
702 *
703 * \return A value from the Pipe_Stream_RW_ErrorCodes_t enum.
704 */
705 uint8_t Pipe_Read_Stream_BE(void* Buffer, uint16_t Length
706 #if !defined(NO_STREAM_CALLBACKS) || defined(__DOXYGEN__)
707 , uint8_t (* const Callback)(void)
708 #endif
709 ) ATTR_NON_NULL_PTR_ARG(1);
710
711 /* Function Aliases: */
712 /** Alias for Pipe_Discard_Byte().
713 */
714 #define Pipe_Ignore_Byte() Pipe_Discard_Byte()
715
716 /** Alias for Pipe_Discard_Word().
717 */
718 #define Pipe_Ignore_Word() Pipe_Discard_Word()
719
720 /** Alias for Pipe_Discard_DWord().
721 */
722 #define Pipe_Ignore_DWord() Pipe_Discard_DWord()
723
724 /** Alias for Pipe_Read_Word_LE(). By default USB transfers use little endian format, thus
725 * the command with no endianness specifier indicates little endian mode.
726 */
727 #define Pipe_Read_Word() Pipe_Read_Word_LE()
728
729 /** Alias for Pipe_Write_Word_LE(). By default USB transfers use little endian format, thus
730 * the command with no endianness specifier indicates little endian mode.
731 */
732 #define Pipe_Write_Word(Word) Pipe_Write_Word_LE(Word)
733
734 /** Alias for Pipe_Read_DWord_LE(). By default USB transfers use little endian format, thus
735 * the command with no endianness specifier indicates little endian mode.
736 */
737 #define Pipe_Read_DWord() Pipe_Read_DWord_LE()
738
739 /** Alias for Pipe_Write_DWord_LE(). By default USB transfers use little endian format, thus
740 * the command with no endianness specifier indicates little endian mode.
741 */
742 #define Pipe_Write_DWord(DWord) Pipe_Write_DWord_LE(DWord)
743
744 /** Alias for Pipe_Read_Stream_LE(). By default USB transfers use little endian format, thus
745 * the command with no endianness specifier indicates little endian mode.
746 */
747 #if !defined(NO_STREAM_CALLBACKS)
748 #define Pipe_Read_Stream(Buffer, Length, Callback) Pipe_Read_Stream_LE(Buffer, Length, Callback)
749 #else
750 #define Pipe_Read_Stream(Buffer, Length) Pipe_Read_Stream_LE(Buffer, Length)
751 #endif
752
753 /** Alias for Pipe_Write_Stream_LE(). By default USB transfers use little endian format, thus
754 * the command with no endianness specifier indicates little endian mode.
755 */
756 #if !defined(NO_STREAM_CALLBACKS)
757 #define Pipe_Write_Stream(Buffer, Length, Callback) Pipe_Read_Stream_LE(Buffer, Length, Callback)
758 #else
759 #define Pipe_Write_Stream(Buffer, Length) Pipe_Read_Stream_LE(Buffer, Length)
760 #endif
761
762 /* Private Interface - For use in library only: */
763 #if !defined(__DOXYGEN__)
764 /* Macros: */
765 #define PIPE_TOKEN_MASK (0x03 << PTOKEN0)
766
767 #define Pipe_AllocateMemory() MACROS{ UPCFG1X |= (1 << ALLOC); }MACROE
768 #define Pipe_DeallocateMemory() MACROS{ UPCFG1X &= ~(1 << ALLOC); }MACROE
769
770 /* Function Prototypes: */
771 void Pipe_ClearPipes(void);
772
773 /* Inline Functions: */
774 static inline uint8_t Pipe_BytesToEPSizeMask(uint16_t Bytes) ATTR_WARN_UNUSED_RESULT ATTR_CONST ATTR_ALWAYS_INLINE;
775 static inline uint8_t Pipe_BytesToEPSizeMask(uint16_t Bytes)
776 {
777 if (Bytes <= 8)
778 return (0 << EPSIZE0);
779 else if (Bytes <= 16)
780 return (1 << EPSIZE0);
781 else if (Bytes <= 32)
782 return (2 << EPSIZE0);
783 else if (Bytes <= 64)
784 return (3 << EPSIZE0);
785 else if (Bytes <= 128)
786 return (4 << EPSIZE0);
787 else
788 return (5 << EPSIZE0);
789 };
790
791 #endif
792
793 /* Disable C linkage for C++ Compilers: */
794 #if defined(__cplusplus)
795 }
796 #endif
797
798 #endif
USB isp AVR programmer