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