?lang_form? ?lang_select? ?lang_submit? ?lang_endform?
{HEADER END}
{BLAME START}

library

?curdirlinks? -

Blame information for rev 32

Line No. Rev Author Line
1 32 kaklik /******************************************************************************
2  
3 USB Host Mass Storage Device Driver Header File
4  
5 Description:
6 This is the header file for a USB Embedded Host that is using the Mass
7 Storage Class.
8  
9 This file should be included with usb_host.h to provide the USB hardware
10 interface. It must be included after the application-specific usb_config.h
11 file and after the USB Embedded Host header file usb_host.h, as definitions
12 in those files are required for proper compilation.
13  
14 Acronyms/abbreviations used by this class:
15 * LUN - Logical Unit Number
16 * CBW - Command Block Wrapper
17 * CSW - Command Status Wrapper
18  
19 To interface with usb_host.c, the routine USBHostMSDClientInitialize() should
20 be specified as the Initialize() function, and USBHostMSDClientEventHandler()
21 should be specified as the EventHandler() function in the
22 usbClientDrvTable[] array declared in usb_config.h.
23  
24 This driver can be configured to use transfer events from usb_host.c.
25 Transfer events require more RAM and ROM than polling, but it cuts down or
26 even eliminates the required polling of the various USBxxxTasks functions.
27 For this class, USBHostMSDTasks() is compiled out if transfer events from
28 usb_host.c are used. However, USBHostTasks() still must be called to
29 provide attach, enumeration, and detach services. If transfer events from
30 usb_host.c are going to be used, USB_ENABLE_TRANSFER_EVENT should be
31 defined. If transfer status is going to be polled,
32 USB_ENABLE_TRANSFER_EVENT should not be defined.
33  
34 This driver can also be configured to provide mass storage transfer events
35 to the next layer. Generating these events requires a small amount of
36 extra ROM, but no extra RAM. The layer above this driver must be
37 configured to receive and respond to the events. If mass storage transfer
38 events are going to be sent to the next layer,
39 USB_MSD_ENABLE_TRANSFER_EVENT should be defined. If mass storage transfer
40 status is going to be polled, USB_MSD_ENABLE_TRANSFER_EVENT should not be
41 defined.
42  
43 Since mass storage is performed with bulk transfers,
44 USB_SUPPORT_BULK_TRANSFERS must be defined. For maximum throughput, it is
45 recommended that ALLOW_MULTIPLE_BULK_TRANSACTIONS_PER_FRAME be defined.
46 For maximum compatibility with mass storage devices, it is recommended that
47 ALLOW_MULTIPLE_NAKS_PER_FRAME not be defined.
48  
49 Summary:
50 This is the header file for a USB Embedded Host that is using the Mass
51 Storage Class.
52  
53 *******************************************************************************/
54 //DOM-IGNORE-BEGIN
55 /*******************************************************************************
56  
57 * FileName: usb_host_msd.h
58 * Dependencies: None
59 * Processor: PIC24/dsPIC30/dsPIC33/PIC32MX
60 * Compiler: C30 v2.01/C32 v0.00.18
61 * Company: Microchip Technology, Inc.
62  
63 Software License Agreement
64  
65 The software supplied herewith by Microchip Technology Incorporated
66 (the “Company”) for its PICmicro® Microcontroller is intended and
67 supplied to you, the Company’s customer, for use solely and
68 exclusively on Microchip PICmicro Microcontroller products. The
69 software is owned by the Company and/or its supplier, and is
70 protected under applicable copyright laws. All rights are reserved.
71 Any use in violation of the foregoing restrictions may subject the
72 user to criminal sanctions under applicable laws, as well as to
73 civil liability for the breach of the terms and conditions of this
74 license.
75  
76 THIS SOFTWARE IS PROVIDED IN AN “AS IS” CONDITION. NO WARRANTIES,
77 WHETHER EXPRESS, IMPLIED OR STATUTORY, INCLUDING, BUT NOT LIMITED
78 TO, IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
79 PARTICULAR PURPOSE APPLY TO THIS SOFTWARE. THE COMPANY SHALL NOT,
80 IN ANY CIRCUMSTANCES, BE LIABLE FOR SPECIAL, INCIDENTAL OR
81 CONSEQUENTIAL DAMAGES, FOR ANY REASON WHATSOEVER.
82  
83 Change History:
84 Rev Description
85 ----- ------------------------------------
86 2.6a- No change
87 2.7a
88 *******************************************************************************/
89 //DOM-IGNORE-END
90  
91 //DOM-IGNORE-BEGIN
92 #ifndef _USBHOSTMSD_H_
93 #define _USBHOSTMSD_H_
94 //DOM-IGNORE-END
95  
96 // *****************************************************************************
97 // *****************************************************************************
98 // Section: Constants
99 // *****************************************************************************
100 // *****************************************************************************
101  
102 // *****************************************************************************
103 // Section: MSD Class Error Codes
104 // *****************************************************************************
105  
106 #define MSD_COMMAND_PASSED 0x00 // Transfer was successful. Returned in dCSWStatus.
107 #define MSD_COMMAND_FAILED 0x01 // Transfer failed. Returned in dCSWStatus.
108 #define MSD_PHASE_ERROR 0x02 // Transfer phase error. Returned in dCSWStatus.
109  
110 #define USB_MSD_ERROR USB_ERROR_CLASS_DEFINED // Error code offset.
111  
112 #define USB_MSD_COMMAND_PASSED USB_SUCCESS // Command was successful.
113 #define USB_MSD_COMMAND_FAILED (USB_MSD_ERROR | MSD_COMMAND_FAILED)// Command failed at the device.
114 #define USB_MSD_PHASE_ERROR (USB_MSD_ERROR | MSD_PHASE_ERROR) // Command had a phase error at the device.
115 #define USB_MSD_OUT_OF_MEMORY (USB_MSD_ERROR | 0x03) // No dynamic memory is available.
116 #define USB_MSD_CBW_ERROR (USB_MSD_ERROR | 0x04) // The CBW was not transferred successfully.
117 #define USB_MSD_CSW_ERROR (USB_MSD_ERROR | 0x05) // The CSW was not transferred successfully.
118 #define USB_MSD_DEVICE_NOT_FOUND (USB_MSD_ERROR | 0x06) // Device with the specified address is not available.
119 #define USB_MSD_DEVICE_BUSY (USB_MSD_ERROR | 0x07) // A transfer is currently in progress.
120 #define USB_MSD_INVALID_LUN (USB_MSD_ERROR | 0x08) // Invalid LUN specified.
121 #define USB_MSD_MEDIA_INTERFACE_ERROR (USB_MSD_ERROR | 0x09) // The media interface layer cannot support the device.
122 #define USB_MSD_RESET_ERROR (USB_MSD_ERROR | 0x0A) // An error occurred while resetting the device.
123 #define USB_MSD_ILLEGAL_REQUEST (USB_MSD_ERROR | 0x0B) // Cannot perform requested operation.
124  
125 // *****************************************************************************
126 // Section: Additional return values for USBHostMSDDeviceStatus (see USBHostDeviceStatus also)
127 // *****************************************************************************
128  
129 #define USB_MSD_DEVICE_DETACHED 0x50 // Device is detached.
130 #define USB_MSD_INITIALIZING 0x51 // Device is initializing.
131 #define USB_MSD_NORMAL_RUNNING 0x52 // Device is running and available for data transfers.
132 #define USB_MSD_RESETTING_DEVICE 0x53 // Device is being reset.
133 #define USB_MSD_ERROR_STATE 0x55 // Device is holding due to a MSD error.
134  
135 // *****************************************************************************
136 // Section: Interface and Protocol Constants
137 // *****************************************************************************
138  
139 #define DEVICE_CLASS_MASS_STORAGE 0x08 // Class code for Mass Storage.
140  
141 #define DEVICE_SUBCLASS_RBC 0x01 // SubClass code for Reduced Block Commands (not supported).
142 #define DEVICE_SUBCLASS_CD_DVD 0x02 // SubClass code for a CD/DVD drive (not supported).
143 #define DEVICE_SUBCLASS_TAPE_DRIVE 0x03 // SubClass code for a tape drive (not supported).
144 #define DEVICE_SUBCLASS_FLOPPY_INTERFACE 0x04 // SubClass code for a floppy disk interface (not supported).
145 #define DEVICE_SUBCLASS_REMOVABLE 0x05 // SubClass code for removable media (not supported).
146 #define DEVICE_SUBCLASS_SCSI 0x06 // SubClass code for a SCSI interface device (supported).
147  
148 #define DEVICE_INTERFACE_PROTOCOL_BULK_ONLY 0x50 // Protocol code for Bulk-only mass storage.
149  
150  
151 // *****************************************************************************
152 // Section: MSD Event Definition
153 // *****************************************************************************
154  
155 // If the application has not defined an offset for MSD events, set it to 0.
156 #ifndef EVENT_MSD_OFFSET
157 #define EVENT_MSD_OFFSET 0
158 #endif
159  
160 #define EVENT_MSD_NONE EVENT_MSD_BASE + EVENT_MSD_OFFSET + 0 // No event occured (NULL event)
161 #define EVENT_MSD_TRANSFER EVENT_MSD_BASE + EVENT_MSD_OFFSET + 1 // A MSD transfer has completed
162 #define EVENT_MSD_RESET EVENT_MSD_BASE + EVENT_MSD_OFFSET + 2 // MSD reset complete
163 #define EVENT_MSD_MAX_LUN EVENT_MSD_BASE + EVENT_MSD_OFFSET + 3 // Set maximum LUN for the device
164  
165 // *****************************************************************************
166 // *****************************************************************************
167 // Section: Function Prototypes and Macro Functions
168 // *****************************************************************************
169 // *****************************************************************************
170  
171 /****************************************************************************
172 Function:
173 BYTE USBHostMSDDeviceStatus( BYTE deviceAddress )
174  
175 Description:
176 This function determines the status of a mass storage device.
177  
178 Precondition:
179 None
180  
181 Parameters:
182 BYTE deviceAddress - address of device to query
183  
184 Return Values:
185 USB_MSD_DEVICE_NOT_FOUND - Illegal device address, or the device is not
186 an MSD
187 USB_MSD_INITIALIZING - MSD is attached and in the process of
188 initializing
189 USB_MSD_NORMAL_RUNNING - MSD is in normal running mode
190 USB_MSD_RESETTING_DEVICE - MSD is resetting
191 USB_MSD_DEVICE_DETACHED - MSD detached. Should not occur
192 USB_MSD_ERROR_STATE - MSD is holding due to an error. No
193 communication is allowed.
194  
195 Other - Return codes from USBHostDeviceStatus() will
196 also be returned if the device is in the
197 process of enumerating.
198  
199 Remarks:
200 None
201 ***************************************************************************/
202  
203 BYTE USBHostMSDDeviceStatus( BYTE deviceAddress );
204  
205  
206 /*******************************************************************************
207 Function:
208 BYTE USBHostMSDRead( BYTE deviceAddress, BYTE deviceLUN, BYTE *commandBlock,
209 BYTE commandBlockLength, BYTE *data, DWORD dataLength );
210  
211 Description:
212 This function starts a mass storage read, utilizing the function
213 USBHostMSDTransfer();
214  
215 Precondition:
216 None
217  
218 Parameters:
219 BYTE deviceAddress - Device address
220 BYTE deviceLUN - Device LUN to access
221 BYTE *commandBlock - Pointer to the command block for the CBW
222 BYTE commandBlockLength - Length of the command block
223 BYTE *data - Pointer to the data buffer
224 DWORD dataLength - Byte size of the data buffer
225  
226 Return Values:
227 USB_SUCCESS - Request started successfully
228 USB_MSD_DEVICE_NOT_FOUND - No device with specified address
229 USB_MSD_DEVICE_BUSY - Device not in proper state for
230 performing a transfer
231 USB_MSD_INVALID_LUN - Specified LUN does not exist
232  
233 Remarks:
234 None
235 *******************************************************************************/
236 #define USBHostMSDRead( deviceAddress,deviceLUN,commandBlock,commandBlockLength,data,dataLength ) \
237 USBHostMSDTransfer( deviceAddress, deviceLUN, 1, commandBlock, commandBlockLength, data, dataLength )
238  
239  
240 /****************************************************************************
241 Function:
242 BYTE USBHostMSDResetDevice( BYTE deviceAddress )
243  
244 Summary:
245 This function starts a bulk-only mass storage reset.
246  
247 Description:
248 This function starts a bulk-only mass storage reset. A reset can be
249 issued only if the device is attached and not being initialized.
250  
251 Precondition:
252 None
253  
254 Parameters:
255 BYTE deviceAddress - Device address
256  
257 Return Values:
258 USB_SUCCESS - Reset started
259 USB_MSD_DEVICE_NOT_FOUND - No device with specified address
260 USB_MSD_ILLEGAL_REQUEST - Device is in an illegal state for reset
261  
262 Remarks:
263 None
264 ***************************************************************************/
265  
266 BYTE USBHostMSDResetDevice( BYTE deviceAddress );
267  
268  
269 /****************************************************************************
270 Function:
271 void USBHostMSDTasks( void )
272  
273 Summary:
274 This function performs the maintenance tasks required by the mass storage
275 class.
276  
277 Description:
278 This function performs the maintenance tasks required by the mass storage
279 class. If transfer events from the host layer are not being used, then
280 it should be called on a regular basis by the application. If transfer
281 events from the host layer are being used, this function is compiled out,
282 and does not need to be called.
283  
284 Precondition:
285 USBHostMSDInitialize() has been called.
286  
287 Parameters:
288 None - None
289  
290 Returns:
291 None
292  
293 Remarks:
294 None
295 ***************************************************************************/
296  
297 void USBHostMSDTasks( void );
298  
299  
300 /****************************************************************************
301 Function:
302 void USBHostMSDTerminateTransfer( BYTE deviceAddress )
303  
304 Description:
305 This function terminates a mass storage transfer.
306  
307 Precondition:
308 None
309  
310 Parameters:
311 BYTE deviceAddress - Device address
312  
313 Returns:
314 None
315  
316 Remarks:
317 After executing this function, the application may have to reset the
318 device in order for the device to continue working properly.
319 ***************************************************************************/
320  
321 void USBHostMSDTerminateTransfer( BYTE deviceAddress );
322  
323  
324 /****************************************************************************
325 Function:
326 BYTE USBHostMSDTransfer( BYTE deviceAddress, BYTE deviceLUN,
327 BYTE direction, BYTE *commandBlock, BYTE commandBlockLength,
328 BYTE *data, DWORD dataLength )
329  
330 Summary:
331 This function starts a mass storage transfer.
332  
333 Description:
334 This function starts a mass storage transfer. Usually, applications will
335 probably utilize a read/write wrapper to access this function.
336  
337 Precondition:
338 None
339  
340 Parameters:
341 BYTE deviceAddress - Device address
342 BYTE deviceLUN - Device LUN to access
343 BYTE direction - 1=read, 0=write
344 BYTE *commandBlock - Pointer to the command block for the CBW
345 BYTE commandBlockLength - Length of the command block
346 BYTE *data - Pointer to the data buffer
347 DWORD dataLength - Byte size of the data buffer
348  
349  
350 Return Values:
351 USB_SUCCESS - Request started successfully
352 USB_MSD_DEVICE_NOT_FOUND - No device with specified address
353 USB_MSD_DEVICE_BUSY - Device not in proper state for performing
354 a transfer
355 USB_MSD_INVALID_LUN - Specified LUN does not exist
356  
357 Remarks:
358 None
359 ***************************************************************************/
360  
361 BYTE USBHostMSDTransfer( BYTE deviceAddress, BYTE deviceLUN, BYTE direction, BYTE *commandBlock,
362 BYTE commandBlockLength, BYTE *data, DWORD dataLength );
363  
364  
365 /****************************************************************************
366 Function:
367 BOOL USBHostMSDTransferIsComplete( BYTE deviceAddress,
368 BYTE *errorCode, DWORD *byteCount )
369  
370 Summary:
371 This function indicates whether or not the last transfer is complete.
372  
373 Description:
374 This function indicates whether or not the last transfer is complete. If
375 the functions returns TRUE, the returned byte count and error code are
376 valid. Since only one transfer can be performed at once and only one
377 endpoint can be used, we only need to know the device address.
378  
379 Precondition:
380 None
381  
382 Parameters:
383 BYTE deviceAddress - Device address
384 BYTE *errorCode - Error code from last transfer
385 DWORD *byteCount - Number of bytes transferred
386  
387 Return Values:
388 TRUE - Transfer is complete, errorCode is valid
389 FALSE - Transfer is not complete, errorCode is not valid
390  
391 Remarks:
392 None
393 ***************************************************************************/
394  
395 BOOL USBHostMSDTransferIsComplete( BYTE deviceAddress, BYTE *errorCode, DWORD *byteCount );
396  
397  
398 /*******************************************************************************
399 Function:
400 BYTE USBHostMSDWrite( BYTE deviceAddress, BYTE deviceLUN, BYTE *commandBlock,
401 BYTE commandBlockLength, BYTE *data, DWORD dataLength );
402  
403 Description:
404 This function starts a mass storage write, utilizing the function
405 USBHostMSDTransfer();
406  
407 Precondition:
408 None
409  
410 Parameters:
411 BYTE deviceAddress - Device address
412 BYTE deviceLUN - Device LUN to access
413 BYTE *commandBlock - Pointer to the command block for the CBW
414 BYTE commandBlockLength - Length of the command block
415 BYTE *data - Pointer to the data buffer
416 DWORD dataLength - Byte size of the data buffer
417  
418 Return Values:
419 USB_SUCCESS - Request started successfully
420 USB_MSD_DEVICE_NOT_FOUND - No device with specified address
421 USB_MSD_DEVICE_BUSY - Device not in proper state for
422 performing a transfer
423 USB_MSD_INVALID_LUN - Specified LUN does not exist
424  
425 Remarks:
426 None
427 *******************************************************************************/
428  
429 #define USBHostMSDWrite( deviceAddress,deviceLUN,commandBlock,commandBlockLength,data,dataLength ) \
430 USBHostMSDTransfer( deviceAddress, deviceLUN, 0, commandBlock, commandBlockLength, data, dataLength )
431  
432  
433 // *****************************************************************************
434 // *****************************************************************************
435 // Section: Host Stack Interface Functions
436 // *****************************************************************************
437 // *****************************************************************************
438  
439 /****************************************************************************
440 Function:
441 BOOL USBHostMSDInitialize( BYTE address, DWORD flags, BYTE clientDriverID )
442  
443 Summary:
444 This function is the initialization routine for this client driver.
445  
446 Description:
447 This function is the initialization routine for this client driver. It
448 is called by the host layer when the USB device is being enumerated. For
449 a mass storage device, we need to make sure that we have room for a new
450 device, and that the device has at least one bulk IN and one bulk OUT
451 endpoint.
452  
453 Precondition:
454 None
455  
456 Parameters:
457 BYTE address - Address of the new device
458 DWORD flags - Initialization flags
459 BYTE clientDriverID - ID to send when issuing a Device Request via
460 USBHostSendDeviceRequest(), USBHostSetDeviceConfiguration(),
461 or USBHostSetDeviceInterface().
462  
463 Return Values:
464 TRUE - We can support the device.
465 FALSE - We cannot support the device.
466  
467 Remarks:
468 None
469 ***************************************************************************/
470  
471 BOOL USBHostMSDInitialize( BYTE address, DWORD flags, BYTE clientDriverID );
472  
473  
474 /****************************************************************************
475 Function:
476 BOOL USBHostMSDEventHandler( BYTE address, USB_EVENT event,
477 void *data, DWORD size )
478  
479 Summary:
480 This function is the event handler for this client driver.
481  
482 Description:
483 This function is the event handler for this client driver. It is called
484 by the host layer when various events occur.
485  
486 Precondition:
487 The device has been initialized.
488  
489 Parameters:
490 BYTE address - Address of the device
491 USB_EVENT event - Event that has occurred
492 void *data - Pointer to data pertinent to the event
493 WORD size - Size of the data
494  
495 Return Values:
496 TRUE - Event was handled
497 FALSE - Event was not handled
498  
499 Remarks:
500 None
501 ***************************************************************************/
502  
503 BOOL USBHostMSDEventHandler( BYTE address, USB_EVENT event, void *data, DWORD size );
504  
505  
506 #endif
{BLAME END}
{FOOTER START}

Powered by WebSVN v2.8.3