?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 Generic Client Driver (Header File)
4  
5 Description:
6 This is the Generic client driver file for a USB Embedded Host device. This
7 driver should be used in a project with usb_host.c to provided the USB
8 hardware interface.
9  
10 To interface with USB Embedded Host layer, the routine USBHostGenericInit()
11 should be specified as the Initialize() function, and
12 USBHostGenericEventHandler() should be specified as the EventHandler()
13 function in the usbClientDrvTable[] array declared in usb_config.c.
14  
15 This driver can be configured to either use transfer events from usb_host.c
16 or use a polling mechanism. If USB_ENABLE_TRANSFER_EVENT is defined, this
17 driver will utilize transfer events. Otherwise, this driver will utilize
18 polling.
19  
20 Since the generic class is performed with interrupt transfers,
21 USB_SUPPORT_INTERRUPT_TRANSFERS must be defined.
22  
23 Summary:
24 This is the Generic client driver file for a USB Embedded Host device.
25  
26 *******************************************************************************/
27 //DOM-IGNORE-BEGIN
28 /******************************************************************************
29  
30 * FileName: usb_client_generic.h
31 * Dependencies: None
32 * Processor: PIC24/dsPIC30/dsPIC33/PIC32MX
33 * Compiler: C30 v2.01/C32 v0.00.18
34 * Company: Microchip Technology, Inc.
35  
36 Software License Agreement
37  
38 The software supplied herewith by Microchip Technology Incorporated
39 (the “Company”) for its PICmicro® Microcontroller is intended and
40 supplied to you, the Company’s customer, for use solely and
41 exclusively on Microchip PICmicro Microcontroller products. The
42 software is owned by the Company and/or its supplier, and is
43 protected under applicable copyright laws. All rights are reserved.
44 Any use in violation of the foregoing restrictions may subject the
45 user to criminal sanctions under applicable laws, as well as to
46 civil liability for the breach of the terms and conditions of this
47 license.
48  
49 THIS SOFTWARE IS PROVIDED IN AN “AS IS” CONDITION. NO WARRANTIES,
50 WHETHER EXPRESS, IMPLIED OR STATUTORY, INCLUDING, BUT NOT LIMITED
51 TO, IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
52 PARTICULAR PURPOSE APPLY TO THIS SOFTWARE. THE COMPANY SHALL NOT,
53 IN ANY CIRCUMSTANCES, BE LIABLE FOR SPECIAL, INCIDENTAL OR
54 CONSEQUENTIAL DAMAGES, FOR ANY REASON WHATSOEVER.
55  
56 Change History:
57 Rev Description
58 ---- -----------------------------------------
59 2.6a- No change
60 2.7a
61 *******************************************************************************/
62 #ifndef __USBHOSTGENERIC_H__
63 #define __USBHOSTGENERIC_H__
64 //DOM-IGNORE-END
65  
66 // *****************************************************************************
67 // *****************************************************************************
68 // Section: Constants
69 // *****************************************************************************
70 // *****************************************************************************
71  
72 // This is the default Generic Client Driver endpoint number.
73 #ifndef USB_GENERIC_EP
74 #define USB_GENERIC_EP 1
75 #endif
76  
77 // *****************************************************************************
78 // *****************************************************************************
79 // Section: USB Generic Client Events
80 // *****************************************************************************
81 // *****************************************************************************
82  
83 // This is an optional offset for the values of the generated events.
84 // If necessary, the application can use a non-zero offset for the
85 // generic events to resolve conflicts in event number.
86 #ifndef EVENT_GENERIC_OFFSET
87 #define EVENT_GENERIC_OFFSET 0
88 #endif
89  
90 // This event indicates that a Generic device has been attached.
91 // When USB_HOST_APP_EVENT_HANDLER is called with this event, *data
92 // points to a GENERIC_DEVICE_ID structure, and size is the size of the
93 // GENERIC_DEVICE_ID structure.
94 #define EVENT_GENERIC_ATTACH (EVENT_GENERIC_BASE+EVENT_GENERIC_OFFSET+0)
95  
96 // This event indicates that the specified device has been detached
97 // from the USB. When USB_HOST_APP_EVENT_HANDLER is called with this
98 // event, *data points to a BYTE that contains the device address, and
99 // size is the size of a BYTE.
100 #define EVENT_GENERIC_DETACH (EVENT_GENERIC_BASE+EVENT_GENERIC_OFFSET+1)
101  
102 // This event indicates that a previous write request has completed.
103 // These events are enabled if USB Embedded Host transfer events are
104 // enabled (USB_ENABLE_TRANSFER_EVENT is defined). When
105 // USB_HOST_APP_EVENT_HANDLER is called with this event, *data points
106 // to the buffer that completed transmission, and size is the actual
107 // number of bytes that were written to the device.
108 #define EVENT_GENERIC_TX_DONE (EVENT_GENERIC_BASE+EVENT_GENERIC_OFFSET+2)
109  
110 // This event indicates that a previous read request has completed.
111 // These events are enabled if USB Embedded Host transfer events are
112 // enabled (USB_ENABLE_TRANSFER_EVENT is defined). When
113 // USB_HOST_APP_EVENT_HANDLER is called with this event, *data points
114 // to the receive buffer, and size is the actual number of bytes read
115 // from the device.
116 #define EVENT_GENERIC_RX_DONE (EVENT_GENERIC_BASE+EVENT_GENERIC_OFFSET+3)
117  
118  
119 // *****************************************************************************
120 // *****************************************************************************
121 // Section: USB Data Structures
122 // *****************************************************************************
123 // *****************************************************************************
124  
125 // *****************************************************************************
126 /* Generic Device ID Information
127  
128 This structure contains identification information about an attached device.
129 */
130 typedef struct _GENERIC_DEVICE_ID
131 {
132 WORD vid; // Vendor ID of the device
133 WORD pid; // Product ID of the device
134 #ifdef USB_GENERIC_SUPPORT_SERIAL_NUMBERS
135 WORD *serialNumber; // Pointer to the Unicode serial number string
136 BYTE serialNumberLength; // Length of the serial number string (in Unicode characters)
137 #endif
138 BYTE deviceAddress; // Address of the device on the USB
139 } GENERIC_DEVICE_ID;
140  
141  
142 // *****************************************************************************
143 /* Generic Device Information
144  
145 This structure contains information about an attached device, including
146 status flags and device identification.
147 */
148 typedef struct _GENERIC_DEVICE
149 {
150 GENERIC_DEVICE_ID ID; // Identification information about the device
151 DWORD rxLength; // Number of bytes received in the last IN transfer
152 BYTE clientDriverID; // ID to send when issuing a Device Request
153  
154 #ifndef USB_ENABLE_TRANSFER_EVENT
155 BYTE rxErrorCode; // Error code of last IN transfer
156 BYTE txErrorCode; // Error code of last OUT transfer
157 #endif
158  
159 union
160 {
161 BYTE val; // BYTE representation of device status flags
162 struct
163 {
164 BYTE initialized : 1; // Driver has been initialized
165 BYTE txBusy : 1; // Driver busy transmitting data
166 BYTE rxBusy : 1; // Driver busy receiving data
167 #ifdef USB_GENERIC_SUPPORT_SERIAL_NUMBERS
168 BYTE serialNumberValid : 1; // Serial number is valid
169 #endif
170 };
171 } flags; // Generic client driver status flags
172  
173 } GENERIC_DEVICE;
174  
175  
176 // *****************************************************************************
177 // *****************************************************************************
178 // Section: Global Variables
179 // *****************************************************************************
180 // *****************************************************************************
181  
182 extern GENERIC_DEVICE gc_DevData; // Information about the attached device.
183  
184 // *****************************************************************************
185 // *****************************************************************************
186 // Section: Host Stack Interface Functions
187 // *****************************************************************************
188 // *****************************************************************************
189  
190 /****************************************************************************
191 Function:
192 BOOL USBHostGenericInit ( BYTE address, DWORD flags, BYTE clientDriverID )
193  
194 Summary:
195 This function is called by the USB Embedded Host layer when a "generic"
196 device attaches.
197  
198 Description:
199 This routine is a call out from the USB Embedded Host layer to the USB
200 generic client driver. It is called when a "generic" device has been
201 connected to the host. Its purpose is to initialize and activate the USB
202 Generic client driver.
203  
204 Preconditions:
205 The device has been configured.
206  
207 Parameters:
208 BYTE address - Device's address on the bus
209 DWORD flags - Initialization flags
210 BYTE clientDriverID - ID to send when issuing a Device Request via
211 USBHostIssueDeviceRequest(), USBHostSetDeviceConfiguration(),
212 or USBHostSetDeviceInterface().
213  
214 Return Values:
215 TRUE - Initialization was successful
216 FALSE - Initialization failed
217  
218 Remarks:
219 Multiple client drivers may be used in a single application. The USB
220 Embedded Host layer will call the initialize routine required for the
221 attached device.
222 ***************************************************************************/
223  
224 BOOL USBHostGenericInit ( BYTE address, DWORD flags, BYTE clientDriverID );
225  
226  
227 /****************************************************************************
228 Function:
229 BOOL USBHostGenericEventHandler ( BYTE address, USB_EVENT event,
230 void *data, DWORD size )
231  
232 Summary:
233 This routine is called by the Host layer to notify the general client of
234 events that occur.
235  
236 Description:
237 This routine is called by the Host layer to notify the general client of
238 events that occur. If the event is recognized, it is handled and the
239 routine returns TRUE. Otherwise, it is ignored and the routine returns
240 FALSE.
241  
242 Preconditions:
243 None
244  
245 Parameters:
246 BYTE address - Address of device with the event
247 USB_EVENT event - The bus event that occured
248 void *data - Pointer to event-specific data
249 DWORD size - Size of the event-specific data
250 Return Values:
251 TRUE - The event was handled
252 FALSE - The event was not handled
253  
254 Remarks:
255 None
256 ***************************************************************************/
257  
258 BOOL USBHostGenericEventHandler ( BYTE address, USB_EVENT event, void *data, DWORD size );
259  
260  
261 // *****************************************************************************
262 // *****************************************************************************
263 // Section: Function Prototypes and Macro Functions
264 // *****************************************************************************
265 // *****************************************************************************
266  
267 /****************************************************************************
268 Function:
269 BOOL API_VALID( BYTE address )
270  
271 Description:
272 This function is used internally to ensure that the requested device is
273 attached and initialized before performing an operation.
274  
275 Preconditions:
276 None
277  
278 Parameters:
279 BYTE address - USB address of the device
280  
281 Returns:
282 TRUE - A device with the requested address is attached and initialized.
283 FALSE - A device with the requested address is not available, or it
284 has not been initialized.
285  
286 Remarks:
287 None
288 ***************************************************************************/
289  
290 #define API_VALID(a) ( (((a)==gc_DevData.ID.deviceAddress) && gc_DevData.flags.initialized == 1) ? TRUE : FALSE )
291  
292  
293 /****************************************************************************
294 Function:
295 BOOL USBHostGenericDeviceDetached( BYTE deviceAddress )
296  
297 Description:
298 This interface is used to check if the devich has been detached from the
299 bus.
300  
301 Preconditions:
302 None
303  
304 Parameters:
305 deviceAddress - USB Address of the device.
306  
307 Return Values:
308 TRUE - The device has been detached, or an invalid deviceAddress is given.
309 FALSE - The device is attached
310  
311 Example:
312 <code>
313 if (USBHostGenericDeviceDetached( deviceAddress ))
314 {
315 // Handle detach
316 }
317 </code>
318  
319 Remarks:
320 None
321 ***************************************************************************/
322  
323 #define USBHostGenericDeviceDetached(a) ( (((a)==gc_DevData.ID.deviceAddress) && gc_DevData.flags.initialized == 1) ? FALSE : TRUE )
324 //BOOL USBHostGenericDeviceDetached( BYTE deviceAddress );
325  
326  
327 /****************************************************************************
328 Function:
329 BOOL USBHostGenericGetDeviceAddress(GENERIC_DEVICE_ID *pDevID)
330  
331 Description:
332 This interface is used get the address of a specific generic device on
333 the USB.
334  
335 Preconditions:
336 The device must be connected and enumerated.
337  
338 Parameters:
339 pDevID - Pointer to a structure containing the Device ID Info (VID,
340 PID, serial number, and device address).
341  
342 Return Values:
343 TRUE - The device is connected
344 FALSE - The device is not connected.
345  
346 Example:
347 <code>
348 GENERIC_DEVICE_ID deviceID;
349 WORD serialNumber[] = { '1', '2', '3', '4', '5', '6' };
350 BYTE deviceAddress;
351  
352 deviceID.vid = 0x1234;
353 deviceID.pid = 0x5678;
354 deviceID.serialNumber = &serialNumber;
355  
356 if (USBHostGenericGetDeviceAddress(&deviceID))
357 {
358 deviceAddress = deviceID.deviceAddress;
359 }
360 </code>
361  
362 Remarks:
363 None
364 ***************************************************************************/
365  
366 BOOL USBHostGenericGetDeviceAddress(GENERIC_DEVICE_ID *pDevID);
367  
368  
369 /****************************************************************************
370 Function:
371 DWORD USBHostGenericGetRxLength( BYTE deviceAddress )
372  
373 Description:
374 This function retrieves the number of bytes copied to user's buffer by
375 the most recent call to the USBHostGenericRead() function.
376  
377 Preconditions:
378 The device must be connected and enumerated.
379  
380 Parameters:
381 deviceAddress - USB Address of the device
382  
383 Returns:
384 Returns the number of bytes most recently received from the Generic
385 device with address deviceAddress.
386  
387 Remarks:
388 This function can only be called once per transfer. Subsequent calls will
389 return zero until new data has been received.
390 ***************************************************************************/
391  
392 #define USBHostGenericGetRxLength(a) ( (API_VALID(a)) ? gc_DevData.rxLength : 0 )
393 //DWORD USBHostGenericGetRxLength( BYTE deviceAddress );
394  
395  
396 /****************************************************************************
397 Function:
398 void USBHostGenericRead( BYTE deviceAddress, BYTE *buffer, DWORD length )
399  
400 Description:
401 Use this routine to receive from the device and store it into memory.
402  
403 Preconditions:
404 The device must be connected and enumerated.
405  
406 Parameters:
407 deviceAddress - USB Address of the device.
408 buffer - Pointer to the data buffer
409 length - Number of bytes to be transferred
410  
411 Return Values:
412 USB_SUCCESS - The Read was started successfully
413 (USB error code) - The Read was not started. See USBHostRead() for
414 a list of errors.
415  
416 Example:
417 <code>
418 if (!USBHostGenericRxIsBusy( deviceAddress ))
419 {
420 USBHostGenericRead( deviceAddress, &buffer, sizeof(buffer) );
421 }
422 </code>
423  
424 Remarks:
425 None
426 ***************************************************************************/
427  
428 BYTE USBHostGenericRead( BYTE deviceAddress, void *buffer, DWORD length);
429 /* Macro Implementation:
430 #define USBHostGenericRead(a,b,l) \
431 ( API_VALID(deviceAddress) ? USBHostRead((a),USB_GENERIC_EP,(BYTE *)(b),(l)) : \
432 USB_INVALID_STATE )
433 */
434  
435  
436 /****************************************************************************
437 Function:
438 BOOL USBHostGenericRxIsBusy( BYTE deviceAddress )
439  
440 Summary:
441 This interface is used to check if the client driver is currently busy
442 receiving data from the device.
443  
444 Description:
445 This interface is used to check if the client driver is currently busy
446 receiving data from the device. This function is intended for use with
447 transfer events. With polling, the function USBHostGenericRxIsComplete()
448 should be used.
449  
450 Preconditions:
451 The device must be connected and enumerated.
452  
453 Parameters:
454 deviceAddress - USB Address of the device
455  
456 Return Values:
457 TRUE - The device is receiving data or an invalid deviceAddress is
458 given.
459 FALSE - The device is not receiving data
460  
461 Example:
462 <code>
463 if (!USBHostGenericRxIsBusy( deviceAddress ))
464 {
465 USBHostGenericRead( deviceAddress, &buffer, sizeof( buffer ) );
466 }
467 </code>
468  
469 Remarks:
470 None
471 ***************************************************************************/
472  
473 #define USBHostGenericRxIsBusy(a) ( (API_VALID(a)) ? ((gc_DevData.flags.rxBusy == 1) ? TRUE : FALSE) : TRUE )
474 //BOOL USBHostGenericRxIsBusy( BYTE deviceAddress );
475  
476  
477 /****************************************************************************
478 Function:
479 BOOL USBHostGenericRxIsComplete( BYTE deviceAddress, BYTE *errorCode,
480 DWORD *byteCount )
481  
482 Summary:
483 This routine indicates whether or not the last IN transfer is complete.
484  
485 Description:
486 This routine indicates whether or not the last IN transfer is complete.
487 If it is, then the returned errorCode and byteCount are valid, and
488 reflect the error code and the number of bytes received.
489  
490 This function is intended for use with polling. With transfer events,
491 the function USBHostGenericRxIsBusy() should be used.
492  
493 Preconditions:
494 None
495  
496 Parameters:
497 BYTE deviceAddress - Address of the attached peripheral
498 BYTE *errorCode - Error code of the last transfer, if complete
499 DWORD *byteCount - Bytes transferred during the last transfer, if
500 complete
501  
502 Return Values:
503 TRUE - The IN transfer is complete. errorCode and byteCount are valid.
504 FALSE - The IN transfer is not complete. errorCode and byteCount are
505 invalid.
506  
507 Remarks:
508 None
509 ***************************************************************************/
510  
511 BOOL USBHostGenericRxIsComplete( BYTE deviceAddress,
512 BYTE *errorCode, DWORD *byteCount );
513  
514  
515 /****************************************************************************
516 Function:
517 void USBHostGenericTasks( void )
518  
519 Summary:
520 This routine is used if transfer events are not utilized. It monitors the
521 host status and updates the transmit and receive flags.
522  
523 Description:
524 This routine is used if transfer events are not utilized. It monitors the
525 host status and updates the transmit and receive flags. If serial
526 numbers are supported, then this routine handles the reception of the
527 serial number.
528  
529 Preconditions:
530 None
531  
532 Parameters:
533 None
534  
535 Returns:
536 None
537  
538 Remarks:
539 This function is compiled only if USB_ENABLE_TRANSFER_EVENT is not
540 defined.
541 ***************************************************************************/
542  
543 #ifndef USB_ENABLE_TRANSFER_EVENT
544 void USBHostGenericTasks( void );
545 #endif
546  
547  
548 /****************************************************************************
549 Function:
550 BOOL USBHostGenericTxIsBusy( BYTE deviceAddress )
551  
552 Summary:
553 This interface is used to check if the client driver is currently busy
554 transmitting data to the device.
555  
556 Description:
557 This interface is used to check if the client driver is currently busy
558 transmitting data to the device. This function is intended for use with
559 transfer events. With polling, the function USBHostGenericTxIsComplete()
560 should be used.
561  
562 Preconditions:
563 The device must be connected and enumerated.
564  
565 Parameters:
566 deviceAddress - USB Address of the device
567  
568 Return Values:
569 TRUE - The device is transmitting data or an invalid deviceAddress
570 is given.
571 FALSE - The device is not transmitting data
572  
573 Example:
574 <code>
575 if (!USBHostGenericTxIsBusy( deviceAddress ) )
576 {
577 USBHostGenericWrite( deviceAddress, &buffer, sizeof( buffer ) );
578 }
579 </code>
580  
581 Remarks:
582 None
583 ***************************************************************************/
584  
585 #define USBHostGenericTxIsBusy(a) ( (API_VALID(a)) ? ((gc_DevData.flags.txBusy == 1) ? TRUE : FALSE) : TRUE )
586 //BOOL USBHostGenericTxIsBusy( BYTE deviceAddress );
587  
588  
589 /****************************************************************************
590 Function:
591 BOOL USBHostGenericTxIsComplete( BYTE deviceAddress, BYTE *errorCode )
592  
593 Summary:
594 This routine indicates whether or not the last OUT transfer is complete.
595  
596 Description:
597 This routine indicates whether or not the last OUT transfer is complete.
598 If it is, then the returned errorCode is valid, and reflect the error
599 code of the transfer.
600  
601 This function is intended for use with polling. With transfer events,
602 the function USBHostGenericTxIsBusy() should be used.
603  
604 Preconditions:
605 None
606  
607 Parameters:
608 BYTE deviceAddress - Address of the attached peripheral
609 BYTE *errorCode - Error code of the last transfer, if complete
610  
611 Return Values:
612 TRUE - The OUT transfer is complete. errorCode is valid.
613 FALSE - The OUT transfer is not complete. errorCode is invalid.
614  
615 Remarks:
616 None
617 ***************************************************************************/
618  
619 BOOL USBHostGenericTxIsComplete( BYTE deviceAddress, BYTE *errorCode );
620  
621  
622 /****************************************************************************
623 Function:
624 void USBHostGenericWrite( BYTE deviceAddress, BYTE *buffer, DWORD length )
625  
626 Description:
627 Use this routine to transmit data from memory to the device.
628  
629 Preconditions:
630 The device must be connected and enumerated.
631  
632 Parameters:
633 deviceAddress - USB Address of the device.
634 buffer - Pointer to the data buffer
635 length - Number of bytes to be transferred
636  
637 Return Values:
638 USB_SUCCESS - The Write was started successfully
639 (USB error code) - The Write was not started. See USBHostWrite() for
640 a list of errors.
641  
642 Example:
643 <code>
644 if (!USBHostGenericTxIsBusy( deviceAddress ))
645 {
646 USBHostGenericWrite( deviceAddress, &buffer, sizeof(buffer) );
647 }
648 </code>
649  
650 Remarks:
651 None
652 ***************************************************************************/
653  
654 BYTE USBHostGenericWrite( BYTE deviceAddress, void *buffer, DWORD length);
655 /* Macro Implementation:
656 #define USBHostGenericWrite(a,b,l) \
657 ( API_VALID(deviceAddress) ? USBHostWrite((a),USB_GENERIC_EP,(BYTE *)(b),(l)) : \
658 USB_INVALID_STATE )
659 */
660  
661  
662 /*************************************************************************
663 * EOF usb_client_generic.h
664 */
665  
666 #endif
{BLAME END}
{FOOTER START}

Powered by WebSVN v2.8.3