projects / pub / USBasp.git / blob
? search:
summary | shortlog | log | commit | commitdiff | tree
blame | history | raw | HEAD
Oops - ensure that only the relevant/available interrupts are defined and used on...
[pub/USBasp.git] / LUFA / Drivers / USB / Core / PipeStream.h
1 /*
2 LUFA Library
3 Copyright (C) Dean Camera, 2011.
4
5 dean [at] fourwalledcubicle [dot] com
6 www.lufa-lib.org
7 */
8
9 /*
10 Copyright 2011 Dean Camera (dean [at] fourwalledcubicle [dot] com)
11
12 Permission to use, copy, modify, distribute, and sell this
13 software and its documentation for any purpose is hereby granted
14 without fee, provided that the above copyright notice appear in
15 all copies and that both that the copyright notice and this
16 permission notice and warranty disclaimer appear in supporting
17 documentation, and that the name of the author not be used in
18 advertising or publicity pertaining to distribution of the
19 software without specific, written prior permission.
20
21 The author disclaim all warranties with regard to this
22 software, including all implied warranties of merchantability
23 and fitness. In no event shall the author be liable for any
24 special, indirect or consequential damages or any damages
25 whatsoever resulting from loss of use, data or profits, whether
26 in an action of contract, negligence or other tortious action,
27 arising out of or in connection with the use or performance of
28 this software.
29 */
30
31 /** \file
32 * \brief Pipe data stream transmission and reception management.
33 * \copydetails Group_PipeStreamRW
34 *
35 * \note This file should not be included directly. It is automatically included as needed by the USB driver
36 * dispatch header located in LUFA/Drivers/USB/USB.h.
37 */
38
39 /** \ingroup Group_PipeRW
40 * \defgroup Group_PipeStreamRW Read/Write of Multi-Byte Streams
41 * \brief Pipe data stream transmission and reception management.
42 *
43 * Functions, macros, variables, enums and types related to data reading and writing of data streams from
44 * and to pipes.
45 *
46 * @{
47 */
48
49 #ifndef __PIPE_STREAM_H__
50 #define __PIPE_STREAM_H__
51
52 /* Includes: */
53 #include "../../../Common/Common.h"
54 #include "USBMode.h"
55 #include "USBTask.h"
56
57 /* Enable C linkage for C++ Compilers: */
58 #if defined(__cplusplus)
59 extern "C" {
60 #endif
61
62 /* Preprocessor Checks: */
63 #if !defined(__INCLUDE_FROM_USB_DRIVER)
64 #error Do not include this file directly. Include LUFA/Drivers/USB/USB.h instead.
65 #endif
66
67 /* Public Interface - May be used in end-application: */
68 /* Enums: */
69 /** Enum for the possible error return codes of the Pipe_*_Stream_* functions. */
70 enum Pipe_Stream_RW_ErrorCodes_t
71 {
72 PIPE_RWSTREAM_NoError = 0, /**< Command completed successfully, no error. */
73 PIPE_RWSTREAM_PipeStalled = 1, /**< The device stalled the pipe during the transfer. */
74 PIPE_RWSTREAM_DeviceDisconnected = 2, /**< Device was disconnected from the host during
75 * the transfer.
76 */
77 PIPE_RWSTREAM_Timeout = 3, /**< The device failed to accept or send the next packet
78 * within the software timeout period set by the
79 * \ref USB_STREAM_TIMEOUT_MS macro.
80 */
81 PIPE_RWSTREAM_IncompleteTransfer = 4, /**< Indicates that the pipe bank became full/empty before the
82 * complete contents of the stream could be transferred.
83 */
84 };
85
86 /* Function Prototypes: */
87
88 /** \name Stream functions for null data */
89 //@{
90
91 /** Reads and discards the given number of bytes from the pipe, discarding fully read packets from the host
92 * as needed. The last packet is not automatically discarded once the remaining bytes has been read; the
93 * user is responsible for manually discarding the last packet from the device via the \ref Pipe_ClearIN() macro.
94 *
95 * If the BytesProcessed parameter is \c NULL, the entire stream transfer is attempted at once, failing or
96 * succeeding as a single unit. If the BytesProcessed parameter points to a valid storage location, the transfer
97 * will instead be performed as a series of chunks. Each time the pipe bank becomes empty while there is still data
98 * to process (and after the current packet has been acknowledged) the BytesProcessed location will be updated with
99 * the total number of bytes processed in the stream, and the function will exit with an error code of
100 * \ref PIPE_RWSTREAM_IncompleteTransfer. This allows for any abort checking to be performed in the user code - to
101 * continue the transfer, call the function again with identical parameters and it will resume until the BytesProcessed
102 * value reaches the total transfer length.
103 *
104 * <b>Single Stream Transfer Example:</b>
105 * \code
106 * uint8_t ErrorCode;
107 *
108 * if ((ErrorCode = Pipe_Discard_Stream(512, NULL)) != PIPE_RWSTREAM_NoError)
109 * {
110 * // Stream failed to complete - check ErrorCode here
111 * }
112 * \endcode
113 *
114 * <b>Partial Stream Transfers Example:</b>
115 * \code
116 * uint8_t ErrorCode;
117 * uint16_t BytesProcessed;
118 *
119 * BytesProcessed = 0;
120 * while ((ErrorCode = Pipe_Discard_Stream(512, &BytesProcessed)) == PIPE_RWSTREAM_IncompleteTransfer)
121 * {
122 * // Stream not yet complete - do other actions here, abort if required
123 * }
124 *
125 * if (ErrorCode != PIPE_RWSTREAM_NoError)
126 * {
127 * // Stream failed to complete - check ErrorCode here
128 * }
129 * \endcode
130 *
131 * \note The pipe token is set automatically, thus this can be used on bi-directional pipes directly without
132 * having to explicitly change the data direction with a call to \ref Pipe_SetPipeToken().
133 *
134 * \param[in] Length Number of bytes to discard via the currently selected pipe.
135 * \param[in] BytesProcessed Pointer to a location where the total number of bytes already processed should
136 * updated, \c NULL if the entire stream should be processed at once.
137 *
138 * \return A value from the \ref Pipe_Stream_RW_ErrorCodes_t enum.
139 */
140 uint8_t Pipe_Discard_Stream(uint16_t Length,
141 uint16_t* const BytesProcessed);
142
143 /** Writes a given number of zeroed bytes to the pipe, sending full pipe packets from the host to the device
144 * as needed. The last packet is not automatically sent once the remaining bytes has been written; the
145 * user is responsible for manually discarding the last packet from the device via the \ref Pipe_ClearOUT() macro.
146 *
147 * If the BytesProcessed parameter is \c NULL, the entire stream transfer is attempted at once, failing or
148 * succeeding as a single unit. If the BytesProcessed parameter points to a valid storage location, the transfer
149 * will instead be performed as a series of chunks. Each time the pipe bank becomes full while there is still data
150 * to process (and after the current packet transmission has been initiated) the BytesProcessed location will be
151 * updated with the total number of bytes processed in the stream, and the function will exit with an error code of
152 * \ref PIPE_RWSTREAM_IncompleteTransfer. This allows for any abort checking to be performed in the user code - to
153 * continue the transfer, call the function again with identical parameters and it will resume until the BytesProcessed
154 * value reaches the total transfer length.
155 *
156 * <b>Single Stream Transfer Example:</b>
157 * \code
158 * uint8_t ErrorCode;
159 *
160 * if ((ErrorCode = Pipe_Null_Stream(512, NULL)) != PIPE_RWSTREAM_NoError)
161 * {
162 * // Stream failed to complete - check ErrorCode here
163 * }
164 * \endcode
165 *
166 * <b>Partial Stream Transfers Example:</b>
167 * \code
168 * uint8_t ErrorCode;
169 * uint16_t BytesProcessed;
170 *
171 * BytesProcessed = 0;
172 * while ((ErrorCode = Pipe_Null_Stream(512, &BytesProcessed)) == PIPE_RWSTREAM_IncompleteTransfer)
173 * {
174 * // Stream not yet complete - do other actions here, abort if required
175 * }
176 *
177 * if (ErrorCode != PIPE_RWSTREAM_NoError)
178 * {
179 * // Stream failed to complete - check ErrorCode here
180 * }
181 * \endcode
182 *
183 * \note The pipe token is set automatically, thus this can be used on bi-directional pipes directly without
184 * having to explicitly change the data direction with a call to \ref Pipe_SetPipeToken().
185 *
186 * \param[in] Length Number of zero bytes to write via the currently selected pipe.
187 * \param[in] BytesProcessed Pointer to a location where the total number of bytes already processed should
188 * updated, \c NULL if the entire stream should be processed at once.
189 *
190 * \return A value from the \ref Pipe_Stream_RW_ErrorCodes_t enum.
191 */
192 uint8_t Pipe_Null_Stream(uint16_t Length,
193 uint16_t* const BytesProcessed);
194
195 //@}
196
197 /** \name Stream functions for RAM source/destination data */
198 //@{
199
200 /** Writes the given number of bytes to the pipe from the given buffer in little endian,
201 * sending full packets to the device as needed. The last packet filled is not automatically sent;
202 * the user is responsible for manually sending the last written packet to the host via the
203 * \ref Pipe_ClearOUT() macro. Between each USB packet, the given stream callback function is
204 * executed repeatedly until the next packet is ready, allowing for early aborts of stream transfers.
205 *
206 * If the BytesProcessed parameter is \c NULL, the entire stream transfer is attempted at once,
207 * failing or succeeding as a single unit. If the BytesProcessed parameter points to a valid
208 * storage location, the transfer will instead be performed as a series of chunks. Each time
209 * the pipe bank becomes full while there is still data to process (and after the current
210 * packet transmission has been initiated) the BytesProcessed location will be updated with the
211 * total number of bytes processed in the stream, and the function will exit with an error code of
212 * \ref PIPE_RWSTREAM_IncompleteTransfer. This allows for any abort checking to be performed
213 * in the user code - to continue the transfer, call the function again with identical parameters
214 * and it will resume until the BytesProcessed value reaches the total transfer length.
215 *
216 * <b>Single Stream Transfer Example:</b>
217 * \code
218 * uint8_t DataStream[512];
219 * uint8_t ErrorCode;
220 *
221 * if ((ErrorCode = Pipe_Write_Stream_LE(DataStream, sizeof(DataStream),
222 * NULL)) != PIPE_RWSTREAM_NoError)
223 * {
224 * // Stream failed to complete - check ErrorCode here
225 * }
226 * \endcode
227 *
228 * <b>Partial Stream Transfers Example:</b>
229 * \code
230 * uint8_t DataStream[512];
231 * uint8_t ErrorCode;
232 * uint16_t BytesProcessed;
233 *
234 * BytesProcessed = 0;
235 * while ((ErrorCode = Pipe_Write_Stream_LE(DataStream, sizeof(DataStream),
236 * &BytesProcessed)) == PIPE_RWSTREAM_IncompleteTransfer)
237 * {
238 * // Stream not yet complete - do other actions here, abort if required
239 * }
240 *
241 * if (ErrorCode != PIPE_RWSTREAM_NoError)
242 * {
243 * // Stream failed to complete - check ErrorCode here
244 * }
245 * \endcode
246 *
247 * \note The pipe token is set automatically, thus this can be used on bi-directional pipes directly without
248 * having to explicitly change the data direction with a call to \ref Pipe_SetPipeToken().
249 *
250 * \param[in] Buffer Pointer to the source data buffer to read from.
251 * \param[in] Length Number of bytes to read for the currently selected pipe into the buffer.
252 * \param[in] BytesProcessed Pointer to a location where the total number of bytes already processed should
253 * updated, \c NULL if the entire stream should be written at once.
254 *
255 * \return A value from the \ref Pipe_Stream_RW_ErrorCodes_t enum.
256 */
257 uint8_t Pipe_Write_Stream_LE(const void* const Buffer,
258 uint16_t Length,
259 uint16_t* const BytesProcessed) ATTR_NON_NULL_PTR_ARG(1);
260
261 /** Writes the given number of bytes to the pipe from the given buffer in big endian,
262 * sending full packets to the device as needed. The last packet filled is not automatically sent;
263 * the user is responsible for manually sending the last written packet to the host via the
264 * \ref Pipe_ClearOUT() macro. Between each USB packet, the given stream callback function is
265 * executed repeatedly until the next packet is ready, allowing for early aborts of stream transfers.
266 *
267 * \note The pipe token is set automatically, thus this can be used on bi-directional pipes directly without
268 * having to explicitly change the data direction with a call to \ref Pipe_SetPipeToken().
269 *
270 * \param[in] Buffer Pointer to the source data buffer to read from.
271 * \param[in] Length Number of bytes to read for the currently selected pipe into the buffer.
272 * \param[in] BytesProcessed Pointer to a location where the total number of bytes already processed should
273 * updated, \c NULL if the entire stream should be written at once.
274 *
275 * \return A value from the \ref Pipe_Stream_RW_ErrorCodes_t enum.
276 */
277 uint8_t Pipe_Write_Stream_BE(const void* const Buffer,
278 uint16_t Length,
279 uint16_t* const BytesProcessed) ATTR_NON_NULL_PTR_ARG(1);
280
281 /** Reads the given number of bytes from the pipe into the given buffer in little endian,
282 * sending full packets to the device as needed. The last packet filled is not automatically sent;
283 * the user is responsible for manually sending the last written packet to the host via the
284 * \ref Pipe_ClearIN() macro. Between each USB packet, the given stream callback function is
285 * executed repeatedly until the next packet is ready, allowing for early aborts of stream transfers.
286 *
287 * If the BytesProcessed parameter is \c NULL, the entire stream transfer is attempted at once,
288 * failing or succeeding as a single unit. If the BytesProcessed parameter points to a valid
289 * storage location, the transfer will instead be performed as a series of chunks. Each time
290 * the pipe bank becomes empty while there is still data to process (and after the current
291 * packet has been acknowledged) the BytesProcessed location will be updated with the total number
292 * of bytes processed in the stream, and the function will exit with an error code of
293 * \ref PIPE_RWSTREAM_IncompleteTransfer. This allows for any abort checking to be performed
294 * in the user code - to continue the transfer, call the function again with identical parameters
295 * and it will resume until the BytesProcessed value reaches the total transfer length.
296 *
297 * <b>Single Stream Transfer Example:</b>
298 * \code
299 * uint8_t DataStream[512];
300 * uint8_t ErrorCode;
301 *
302 * if ((ErrorCode = Pipe_Read_Stream_LE(DataStream, sizeof(DataStream),
303 * NULL)) != PIPE_RWSTREAM_NoError)
304 * {
305 * // Stream failed to complete - check ErrorCode here
306 * }
307 * \endcode
308 *
309 * <b>Partial Stream Transfers Example:</b>
310 * \code
311 * uint8_t DataStream[512];
312 * uint8_t ErrorCode;
313 * uint16_t BytesProcessed;
314 *
315 * BytesProcessed = 0;
316 * while ((ErrorCode = Pipe_Read_Stream_LE(DataStream, sizeof(DataStream),
317 * &BytesProcessed)) == PIPE_RWSTREAM_IncompleteTransfer)
318 * {
319 * // Stream not yet complete - do other actions here, abort if required
320 * }
321 *
322 * if (ErrorCode != PIPE_RWSTREAM_NoError)
323 * {
324 * // Stream failed to complete - check ErrorCode here
325 * }
326 * \endcode
327 *
328 * \note The pipe token is set automatically, thus this can be used on bi-directional pipes directly without
329 * having to explicitly change the data direction with a call to \ref Pipe_SetPipeToken().
330 *
331 * \param[out] Buffer Pointer to the source data buffer to write to.
332 * \param[in] Length Number of bytes to read for the currently selected pipe to read from.
333 * \param[in] BytesProcessed Pointer to a location where the total number of bytes already processed should
334 * updated, \c NULL if the entire stream should be read at once.
335 *
336 * \return A value from the \ref Pipe_Stream_RW_ErrorCodes_t enum.
337 */
338 uint8_t Pipe_Read_Stream_LE(void* const Buffer,
339 uint16_t Length,
340 uint16_t* const BytesProcessed) ATTR_NON_NULL_PTR_ARG(1);
341
342 /** Reads the given number of bytes from the pipe into the given buffer in big endian,
343 * sending full packets to the device as needed. The last packet filled is not automatically sent;
344 * the user is responsible for manually sending the last written packet to the host via the
345 * \ref Pipe_ClearIN() macro. Between each USB packet, the given stream callback function is
346 * executed repeatedly until the next packet is ready, allowing for early aborts of stream transfers.
347 *
348 * \note The pipe token is set automatically, thus this can be used on bi-directional pipes directly without
349 * having to explicitly change the data direction with a call to \ref Pipe_SetPipeToken().
350 *
351 * \param[out] Buffer Pointer to the source data buffer to write to.
352 * \param[in] Length Number of bytes to read for the currently selected pipe to read from.
353 * \param[in] BytesProcessed Pointer to a location where the total number of bytes already processed should
354 * updated, \c NULL if the entire stream should be read at once.
355 *
356 * \return A value from the \ref Pipe_Stream_RW_ErrorCodes_t enum.
357 */
358 uint8_t Pipe_Read_Stream_BE(void* const Buffer,
359 uint16_t Length,
360 uint16_t* const BytesProcessed) ATTR_NON_NULL_PTR_ARG(1);
361 //@}
362
363 /** \name Stream functions for EEPROM source/destination data */
364 //@{
365
366 /** EEPROM buffer source version of \ref Pipe_Write_Stream_LE().
367 *
368 * \param[in] Buffer Pointer to the source data buffer to read from.
369 * \param[in] Length Number of bytes to read for the currently selected pipe into the buffer.
370 * \param[in] BytesProcessed Pointer to a location where the total number of bytes already processed should
371 * updated, \c NULL if the entire stream should be written at once.
372 *
373 * \return A value from the \ref Pipe_Stream_RW_ErrorCodes_t enum.
374 */
375 uint8_t Pipe_Write_EStream_LE(const void* const Buffer,
376 uint16_t Length,
377 uint16_t* const BytesProcessed) ATTR_NON_NULL_PTR_ARG(1);
378
379 /** EEPROM buffer source version of \ref Pipe_Write_Stream_BE().
380 *
381 * \param[in] Buffer Pointer to the source data buffer to read from.
382 * \param[in] Length Number of bytes to read for the currently selected pipe into the buffer.
383 * \param[in] BytesProcessed Pointer to a location where the total number of bytes already processed should
384 * updated, \c NULL if the entire stream should be written at once.
385 *
386 * \return A value from the \ref Pipe_Stream_RW_ErrorCodes_t enum.
387 */
388 uint8_t Pipe_Write_EStream_BE(const void* const Buffer,
389 uint16_t Length,
390 uint16_t* const BytesProcessed) ATTR_NON_NULL_PTR_ARG(1);
391
392 /** EEPROM buffer source version of \ref Pipe_Read_Stream_LE().
393 *
394 * \param[out] Buffer Pointer to the source data buffer to write to.
395 * \param[in] Length Number of bytes to read for the currently selected pipe to read from.
396 * \param[in] BytesProcessed Pointer to a location where the total number of bytes already processed should
397 * updated, \c NULL if the entire stream should be read at once.
398 *
399 * \return A value from the \ref Pipe_Stream_RW_ErrorCodes_t enum.
400 */
401 uint8_t Pipe_Read_EStream_LE(void* const Buffer,
402 uint16_t Length,
403 uint16_t* const BytesProcessed) ATTR_NON_NULL_PTR_ARG(1);
404
405 /** EEPROM buffer source version of \ref Pipe_Read_Stream_BE().
406 *
407 * \param[out] Buffer Pointer to the source data buffer to write to.
408 * \param[in] Length Number of bytes to read for the currently selected pipe to read from.
409 * \param[in] BytesProcessed Pointer to a location where the total number of bytes already processed should
410 * updated, \c NULL if the entire stream should be read at once.
411 *
412 * \return A value from the \ref Pipe_Stream_RW_ErrorCodes_t enum.
413 */
414 uint8_t Pipe_Read_EStream_BE(void* const Buffer,
415 uint16_t Length,
416 uint16_t* const BytesProcessed) ATTR_NON_NULL_PTR_ARG(1);
417 //@}
418
419 /** \name Stream functions for PROGMEM source/destination data */
420 //@{
421
422 /** FLASH buffer source version of \ref Pipe_Write_Stream_LE().
423 *
424 * \pre The FLASH data must be located in the first 64KB of FLASH for this function to work correctly.
425 *
426 * \param[in] Buffer Pointer to the source data buffer to read from.
427 * \param[in] Length Number of bytes to read for the currently selected pipe into the buffer.
428 * \param[in] BytesProcessed Pointer to a location where the total number of bytes already processed should
429 * updated, \c NULL if the entire stream should be written at once.
430 *
431 * \return A value from the \ref Pipe_Stream_RW_ErrorCodes_t enum.
432 */
433 uint8_t Pipe_Write_PStream_LE(const void* const Buffer,
434 uint16_t Length,
435 uint16_t* const BytesProcessed) ATTR_NON_NULL_PTR_ARG(1);
436
437 /** FLASH buffer source version of \ref Pipe_Write_Stream_BE().
438 *
439 * \pre The FLASH data must be located in the first 64KB of FLASH for this function to work correctly.
440 *
441 * \param[in] Buffer Pointer to the source data buffer to read from.
442 * \param[in] Length Number of bytes to read for the currently selected pipe into the buffer.
443 * \param[in] BytesProcessed Pointer to a location where the total number of bytes already processed should
444 * updated, \c NULL if the entire stream should be written at once.
445 *
446 * \return A value from the \ref Pipe_Stream_RW_ErrorCodes_t enum.
447 */
448 uint8_t Pipe_Write_PStream_BE(const void* const Buffer,
449 uint16_t Length,
450 uint16_t* const BytesProcessed) ATTR_NON_NULL_PTR_ARG(1);
451 //@}
452
453 /* Disable C linkage for C++ Compilers: */
454 #if defined(__cplusplus)
455 }
456 #endif
457
458 #endif
459
460 /** @} */
461
USB isp AVR programmer