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


730a338d1baafa404b06b3f3635f14ad70cd4a80
[pub/USBasp.git] / LUFA / Drivers / USB / HighLevel / PipeStream.h
1 /*
2 LUFA Library
3 Copyright (C) Dean Camera, 2010.
4
5 dean [at] fourwalledcubicle [dot] com
6 www.lufa-lib.org
7 */
8
9 /*
10 Copyright 2010 Dean Camera (dean [at] fourwalledcubicle [dot] com)
11
12 Permission to use, copy, modify, distribute, and sell this
13 software and its documentation for any purpose is hereby granted
14 without fee, provided that the above copyright notice appear in
15 all copies and that both that the copyright notice and this
16 permission notice and warranty disclaimer appear in supporting
17 documentation, and that the name of the author not be used in
18 advertising or publicity pertaining to distribution of the
19 software without specific, written prior permission.
20
21 The author disclaim all warranties with regard to this
22 software, including all implied warranties of merchantability
23 and fitness. In no event shall the author be liable for any
24 special, indirect or consequential damages or any damages
25 whatsoever resulting from loss of use, data or profits, whether
26 in an action of contract, negligence or other tortious action,
27 arising out of or in connection with the use or performance of
28 this software.
29 */
30
31 /** \file
32 * \brief USB host pipe stream function definitions.
33 *
34 * This file contains structures, function prototypes and macros related to the sending and receiving of
35 * arbitrary data streams through the device's data pipes when the library is initialized in USB host mode.
36 *
37 * \note This file should not be included directly. It is automatically included as needed by the USB driver
38 * dispatch header located in LUFA/Drivers/USB/USB.h.
39 */
40
41 /** \ingroup Group_PipeRW
42 * @defgroup Group_PipeStreamRW Read/Write of Multi-Byte Streams
43 *
44 * Functions, macros, variables, enums and types related to data reading and writing of data streams from
45 * and to pipes.
46 *
47 * @{
48 */
49
50 #ifndef __PIPE_STREAM_H__
51 #define __PIPE_STREAM_H__
52
53 /* Includes: */
54 #include <avr/pgmspace.h>
55 #include <avr/eeprom.h>
56 #include <stdbool.h>
57
58 #include "../../../Common/Common.h"
59 #include "USBTask.h"
60
61 #if !defined(NO_STREAM_CALLBACKS) || defined(__DOXYGEN__)
62 #include "StreamCallbacks.h"
63 #endif
64
65 /* Enable C linkage for C++ Compilers: */
66 #if defined(__cplusplus)
67 extern "C" {
68 #endif
69
70 /* Preprocessor Checks: */
71 #if !defined(__INCLUDE_FROM_USB_DRIVER)
72 #error Do not include this file directly. Include LUFA/Drivers/USB/USB.h instead.
73 #endif
74
75 #if !defined(NO_STREAM_CALLBACKS) || defined(__DOXYGEN__)
76 #define __CALLBACK_PARAM , StreamCallbackPtr_t Callback
77 #else
78 #define __CALLBACK_PARAM
79 #endif
80
81 /* Public Interface - May be used in end-application: */
82 /* Enums: */
83 /** Enum for the possible error return codes of the Pipe_*_Stream_* functions. */
84 enum Pipe_Stream_RW_ErrorCodes_t
85 {
86 PIPE_RWSTREAM_NoError = 0, /**< Command completed successfully, no error. */
87 PIPE_RWSTREAM_PipeStalled = 1, /**< The device stalled the pipe during the transfer. */
88 PIPE_RWSTREAM_DeviceDisconnected = 2, /**< Device was disconnected from the host during
89 * the transfer.
90 */
91 PIPE_RWSTREAM_Timeout = 3, /**< The device failed to accept or send the next packet
92 * within the software timeout period set by the
93 * \ref USB_STREAM_TIMEOUT_MS macro.
94 */
95 PIPE_RWSTREAM_CallbackAborted = 4, /**< Indicates that the stream's callback function aborted
96 * the transfer early.
97 */
98 };
99
100 /* Function Prototypes: */
101 /** Reads and discards the given number of bytes from the pipe, discarding fully read packets from the host
102 * as needed. The last packet is not automatically discarded once the remaining bytes has been read; the
103 * user is responsible for manually discarding the last packet from the device via the \ref Pipe_ClearIN() macro.
104 * Between each USB packet, the given stream callback function is executed repeatedly until the next packet is ready,
105 * allowing for early aborts of stream transfers.
106 *
107 * The callback routine should be created according to the information in \ref Group_StreamCallbacks.
108 * If the token NO_STREAM_CALLBACKS is passed via the -D option to the compiler, stream callbacks are
109 * disabled and this function has the Callback parameter omitted.
110 *
111 * The pipe token is set automatically, thus this can be used on bi-directional pipes directly without
112 * having to explicitly change the data direction with a call to \ref Pipe_SetPipeToken().
113 *
114 * \param[in] Length Number of bytes to send via the currently selected pipe.
115 * \param[in] Callback Name of a callback routine to call between successive USB packet transfers, NULL if no callback.
116 *
117 * \return A value from the \ref Pipe_Stream_RW_ErrorCodes_t enum.
118 */
119 uint8_t Pipe_Discard_Stream(uint16_t Length
120 __CALLBACK_PARAM);
121
122 /** Writes the given number of bytes to the pipe from the given buffer in little endian,
123 * sending full packets to the device as needed. The last packet filled is not automatically sent;
124 * the user is responsible for manually sending the last written packet to the host via the
125 * \ref Pipe_ClearOUT() macro. Between each USB packet, the given stream callback function is
126 * executed repeatedly until the next packet is ready, allowing for early aborts of stream transfers.
127 *
128 * The callback routine should be created according to the information in \ref Group_StreamCallbacks.
129 * If the token NO_STREAM_CALLBACKS is passed via the -D option to the compiler, stream callbacks are
130 * disabled and this function has the Callback parameter omitted.
131 *
132 * The pipe token is set automatically, thus this can be used on bi-directional pipes directly without
133 * having to explicitly change the data direction with a call to \ref Pipe_SetPipeToken().
134 *
135 * \param[in] Buffer Pointer to the source data buffer to read from.
136 * \param[in] Length Number of bytes to read for the currently selected pipe into the buffer.
137 * \param[in] Callback Name of a callback routine to call between successive USB packet transfers, NULL if no callback.
138 *
139 * \return A value from the \ref Pipe_Stream_RW_ErrorCodes_t enum.
140 */
141 uint8_t Pipe_Write_Stream_LE(const void* Buffer,
142 uint16_t Length
143 __CALLBACK_PARAM) ATTR_NON_NULL_PTR_ARG(1);
144
145 /** EEPROM buffer source version of \ref Pipe_Write_Stream_LE().
146 *
147 * \param[in] Buffer Pointer to the source data buffer to read from.
148 * \param[in] Length Number of bytes to read for the currently selected pipe into the buffer.
149 * \param[in] Callback Name of a callback routine to call between successive USB packet transfers, NULL if no callback.
150 *
151 * \return A value from the \ref Pipe_Stream_RW_ErrorCodes_t enum.
152 */
153 uint8_t Pipe_Write_EStream_LE(const void* Buffer,
154 uint16_t Length
155 __CALLBACK_PARAM) ATTR_NON_NULL_PTR_ARG(1);
156
157 /** FLASH buffer source version of \ref Pipe_Write_Stream_LE().
158 *
159 * \pre The FLASH data must be located in the first 64KB of FLASH for this function to work correctly.
160 *
161 * \param[in] Buffer Pointer to the source data buffer to read from.
162 * \param[in] Length Number of bytes to read for the currently selected pipe into the buffer.
163 * \param[in] Callback Name of a callback routine to call between successive USB packet transfers, NULL if no callback.
164 *
165 * \return A value from the \ref Pipe_Stream_RW_ErrorCodes_t enum.
166 */
167 uint8_t Pipe_Write_PStream_LE(const void* Buffer,
168 uint16_t Length
169 __CALLBACK_PARAM) ATTR_NON_NULL_PTR_ARG(1);
170
171 /** Writes the given number of bytes to the pipe from the given buffer in big endian,
172 * sending full packets to the device as needed. The last packet filled is not automatically sent;
173 * the user is responsible for manually sending the last written packet to the host via the
174 * \ref Pipe_ClearOUT() macro. Between each USB packet, the given stream callback function is
175 * executed repeatedly until the next packet is ready, allowing for early aborts of stream transfers.
176 *
177 * The callback routine should be created according to the information in \ref Group_StreamCallbacks.
178 * If the token NO_STREAM_CALLBACKS is passed via the -D option to the compiler, stream callbacks are
179 * disabled and this function has the Callback parameter omitted.
180 *
181 * The pipe token is set automatically, thus this can be used on bi-directional pipes directly without
182 * having to explicitly change the data direction with a call to \ref Pipe_SetPipeToken().
183 *
184 * \param[in] Buffer Pointer to the source data buffer to read from.
185 * \param[in] Length Number of bytes to read for the currently selected pipe into the buffer.
186 * \param[in] Callback Name of a callback routine to call between successive USB packet transfers, NULL if no callback.
187 *
188 * \return A value from the \ref Pipe_Stream_RW_ErrorCodes_t enum.
189 */
190 uint8_t Pipe_Write_Stream_BE(const void* Buffer,
191 uint16_t Length
192 __CALLBACK_PARAM) ATTR_NON_NULL_PTR_ARG(1);
193
194 /** EEPROM buffer source version of \ref Pipe_Write_Stream_BE().
195 *
196 * \param[in] Buffer Pointer to the source data buffer to read from.
197 * \param[in] Length Number of bytes to read for the currently selected pipe into the buffer.
198 * \param[in] Callback Name of a callback routine to call between successive USB packet transfers, NULL if no callback.
199 *
200 * \return A value from the \ref Pipe_Stream_RW_ErrorCodes_t enum.
201 */
202 uint8_t Pipe_Write_EStream_BE(const void* Buffer,
203 uint16_t Length
204 __CALLBACK_PARAM) ATTR_NON_NULL_PTR_ARG(1);
205
206 /** FLASH buffer source version of \ref Pipe_Write_Stream_BE().
207 *
208 * \pre The FLASH data must be located in the first 64KB of FLASH for this function to work correctly.
209 *
210 * \param[in] Buffer Pointer to the source data buffer to read from.
211 * \param[in] Length Number of bytes to read for the currently selected pipe into the buffer.
212 * \param[in] Callback Name of a callback routine to call between successive USB packet transfers, NULL if no callback.
213 *
214 * \return A value from the \ref Pipe_Stream_RW_ErrorCodes_t enum.
215 */
216 uint8_t Pipe_Write_PStream_BE(const void* Buffer,
217 uint16_t Length
218 __CALLBACK_PARAM) ATTR_NON_NULL_PTR_ARG(1);
219
220 /** Reads the given number of bytes from the pipe into the given buffer in little endian,
221 * sending full packets to the device as needed. The last packet filled is not automatically sent;
222 * the user is responsible for manually sending the last written packet to the host via the
223 * \ref Pipe_ClearIN() macro. Between each USB packet, the given stream callback function is
224 * executed repeatedly until the next packet is ready, allowing for early aborts of stream transfers.
225 *
226 * The callback routine should be created according to the information in \ref Group_StreamCallbacks.
227 * If the token NO_STREAM_CALLBACKS is passed via the -D option to the compiler, stream callbacks are
228 * disabled and this function has the Callback parameter omitted.
229 *
230 * The pipe token is set automatically, thus this can be used on bi-directional pipes directly without
231 * having to explicitly change the data direction with a call to \ref Pipe_SetPipeToken().
232 *
233 * \param[out] Buffer Pointer to the source data buffer to write to.
234 * \param[in] Length Number of bytes to read for the currently selected pipe to read from.
235 * \param[in] Callback Name of a callback routine to call between successive USB packet transfers, NULL if no callback.
236 *
237 * \return A value from the \ref Pipe_Stream_RW_ErrorCodes_t enum.
238 */
239 uint8_t Pipe_Read_Stream_LE(void* Buffer,
240 uint16_t Length
241 __CALLBACK_PARAM) ATTR_NON_NULL_PTR_ARG(1);
242
243 /** EEPROM buffer source version of \ref Pipe_Read_Stream_LE().
244 *
245 * \param[out] Buffer Pointer to the source data buffer to write to.
246 * \param[in] Length Number of bytes to read for the currently selected pipe to read from.
247 * \param[in] Callback Name of a callback routine to call between successive USB packet transfers, NULL if no callback.
248 *
249 * \return A value from the \ref Pipe_Stream_RW_ErrorCodes_t enum.
250 */
251 uint8_t Pipe_Read_EStream_LE(void* Buffer,
252 uint16_t Length
253 __CALLBACK_PARAM) ATTR_NON_NULL_PTR_ARG(1);
254
255 /** Reads the given number of bytes from the pipe into the given buffer in big endian,
256 * sending full packets to the device as needed. The last packet filled is not automatically sent;
257 * the user is responsible for manually sending the last written packet to the host via the
258 * \ref Pipe_ClearIN() macro. Between each USB packet, the given stream callback function is
259 * executed repeatedly until the next packet is ready, allowing for early aborts of stream transfers.
260 *
261 * The callback routine should be created according to the information in \ref Group_StreamCallbacks.
262 * If the token NO_STREAM_CALLBACKS is passed via the -D option to the compiler, stream callbacks are
263 * disabled and this function has the Callback parameter omitted.
264 *
265 * The pipe token is set automatically, thus this can be used on bi-directional pipes directly without
266 * having to explicitly change the data direction with a call to \ref Pipe_SetPipeToken().
267 *
268 * \param[out] Buffer Pointer to the source data buffer to write to.
269 * \param[in] Length Number of bytes to read for the currently selected pipe to read from.
270 * \param[in] Callback Name of a callback routine to call between successive USB packet transfers, NULL if no callback.
271 *
272 * \return A value from the \ref Pipe_Stream_RW_ErrorCodes_t enum.
273 */
274 uint8_t Pipe_Read_Stream_BE(void* Buffer,
275 uint16_t Length
276 __CALLBACK_PARAM) ATTR_NON_NULL_PTR_ARG(1);
277
278 /** EEPROM buffer source version of \ref Pipe_Read_Stream_BE().
279 *
280 * \param[out] Buffer Pointer to the source data buffer to write to.
281 * \param[in] Length Number of bytes to read for the currently selected pipe to read from.
282 * \param[in] Callback Name of a callback routine to call between successive USB packet transfers, NULL if no callback.
283 *
284 * \return A value from the \ref Pipe_Stream_RW_ErrorCodes_t enum.
285 */
286 uint8_t Pipe_Read_EStream_BE(void* Buffer,
287 uint16_t Length
288 __CALLBACK_PARAM) ATTR_NON_NULL_PTR_ARG(1);
289
290 /* Disable C linkage for C++ Compilers: */
291 #if defined(__cplusplus)
292 }
293 #endif
294
295 #endif
296
297 /** @} */
298
USB isp AVR programmer