?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 Device header file
4  
5 Summary:
6 This file, with its associated C source file, provides the main substance of
7 the USB device side stack. These files will receive, transmit, and process
8 various USB commands as well as take action when required for various events
9 that occur on the bus.
10  
11 Description:
12 This file, with its associated C source file, provides the main substance of
13 the USB device side stack. These files will receive, transmit, and process
14 various USB commands as well as take action when required for various events
15 that occur on the bus.
16  
17 This file is located in the "\<Install Directory\>\\Microchip\\Include\\USB"
18 directory.
19  
20 When including this file in a new project, this file can either be
21 referenced from the directory in which it was installed or copied
22 directly into the user application folder. If the first method is
23 chosen to keep the file located in the folder in which it is installed
24 then include paths need to be added so that the library and the
25 application both know where to reference each others files. If the
26 application folder is located in the same folder as the Microchip
27 folder (like the current demo folders), then the following include
28 paths need to be added to the application's project:
29  
30 ..\\..\\Microchip\\Include
31  
32 .
33  
34 If a different directory structure is used, modify the paths as
35 required. An example using absolute paths instead of relative paths
36 would be the following:
37  
38 C:\\Microchip Solutions\\Microchip\\Include
39  
40 C:\\Microchip Solutions\\My Demo Application
41  
42 ******************************************************************************/
43 //DOM-IGNORE-BEGIN
44 /******************************************************************************
45 FileName: usb_device.h
46 Dependencies: See INCLUDES section
47 Processor: PIC18 or PIC24 USB Microcontrollers
48 Hardware: The code is natively intended to be used on the following
49 hardware platforms: PICDEM™ FS USB Demo Board,
50 PIC18F87J50 FS USB Plug-In Module, or
51 Explorer 16 + PIC24 USB PIM. The firmware may be
52 modified for use on other USB platforms by editing the
53 HardwareProfile.h file.
54 Complier: Microchip C18 (for PIC18) or C30 (for PIC24)
55 Company: Microchip Technology, Inc.
56  
57 Software License Agreement:
58  
59 The software supplied herewith by Microchip Technology Incorporated
60 (the “Company”) for its PIC® Microcontroller is intended and
61 supplied to you, the Company’s customer, for use solely and
62 exclusively on Microchip PIC Microcontroller products. The
63 software is owned by the Company and/or its supplier, and is
64 protected under applicable copyright laws. All rights are reserved.
65 Any use in violation of the foregoing restrictions may subject the
66 user to criminal sanctions under applicable laws, as well as to
67 civil liability for the breach of the terms and conditions of this
68 license.
69  
70 THIS SOFTWARE IS PROVIDED IN AN “AS IS” CONDITION. NO WARRANTIES,
71 WHETHER EXPRESS, IMPLIED OR STATUTORY, INCLUDING, BUT NOT LIMITED
72 TO, IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
73 PARTICULAR PURPOSE APPLY TO THIS SOFTWARE. THE COMPANY SHALL NOT,
74 IN ANY CIRCUMSTANCES, BE LIABLE FOR SPECIAL, INCIDENTAL OR
75 CONSEQUENTIAL DAMAGES, FOR ANY REASON WHATSOEVER.
76 *******************************************************************/
77  
78 /********************************************************************
79 Change History:
80 Rev Description
81 ---- -----------
82 2.1 Added "(" & ")" to EP definitions
83 updated for simplicity and to use common
84 coding style
85  
86 2.6 Removed many of the device specific information to the
87 HAL layer files. Moved many of the CH9 defintions to the
88 CH9 file.
89  
90 2.6a No Change
91  
92 2.7 Fixed error where USBHandleGetAddr() didn't convert the
93 return address from a physical address to a virtual address
94 for PIC32.
95  
96 Added macro versions of USBDeviceAttach() and USBDeviceDetach()
97 so they will compile without error when using polling mode.
98  
99 2.7a No Change
100  
101 ********************************************************************/
102  
103 #ifndef USBDEVICE_H
104 #define USBDEVICE_H
105 //DOM-IGNORE-END
106  
107 /** DEFINITIONS ****************************************************/
108  
109 //USB_HANDLE is a pointer to an entry in the BDT. This pointer can be used
110 // to read the length of the last transfer, the status of the last transfer,
111 // and various other information. Insure to initialize USB_HANDLE objects
112 // to NULL so that they are in a known state during their first usage.
113 #define USB_HANDLE void*
114  
115 #define USB_EP0_ROM 0x00 //Data comes from RAM
116 #define USB_EP0_RAM 0x01 //Data comes from ROM
117 #define USB_EP0_BUSY 0x80 //The PIPE is busy
118 #define USB_EP0_INCLUDE_ZERO 0x40 //include a trailing zero packet
119 #define USB_EP0_NO_DATA 0x00 //no data to send
120 #define USB_EP0_NO_OPTIONS 0x00 //no options set
121  
122 /********************************************************************
123 * Standard Request Codes
124 * USB 2.0 Spec Ref Table 9-4
125 *******************************************************************/
126  
127 /* USB Device States as returned by USBGetDeviceState(). Only the defintions
128 for these states should be used. The actual value for each state should
129 not be relied upon as constant and may change based on the implementation. */
130 typedef enum
131 {
132 /* Detached is the state in which the device is not attached to the bus. When
133 in the detached state a device should not have any pull-ups attached to either
134 the D+ or D- line. */
135 DETACHED_STATE
136 /*DOM-IGNORE-BEGIN*/ = 0x00 /*DOM-IGNORE-END*/,
137 /* Attached is the state in which the device is attached ot the bus but the
138 hub/port that it is attached to is not yet configured. */
139 ATTACHED_STATE
140 /*DOM-IGNORE-BEGIN*/ = 0x01 /*DOM-IGNORE-END*/,
141 /* Powered is the state in which the device is attached to the bus and the
142 hub/port that it is attached to is configured. */
143 POWERED_STATE
144 /*DOM-IGNORE-BEGIN*/ = 0x02 /*DOM-IGNORE-END*/,
145 /* Default state is the state after the device receives a RESET command from
146 the host. */
147 DEFAULT_STATE
148 /*DOM-IGNORE-BEGIN*/ = 0x04 /*DOM-IGNORE-END*/,
149 /* Address pending state is not an official state of the USB defined states.
150 This state is internally used to indicate that the device has received a
151 SET_ADDRESS command but has not received the STATUS stage of the transfer yet.
152 The device is should not switch addresses until after the STATUS stage is
153 complete. */
154 ADR_PENDING_STATE
155 /*DOM-IGNORE-BEGIN*/ = 0x08 /*DOM-IGNORE-END*/,
156 /* Address is the state in which the device has its own specific address on the
157 bus. */
158 ADDRESS_STATE
159 /*DOM-IGNORE-BEGIN*/ = 0x10 /*DOM-IGNORE-END*/,
160 /* Configured is the state where the device has been fully enumerated and is
161 operating on the bus. The device is now allowed to excute its application
162 specific tasks. It is also allowed to increase its current consumption to the
163 value specified in the configuration descriptor of the current configuration.
164 */
165 CONFIGURED_STATE
166 /*DOM-IGNORE-BEGIN*/ = 0x20 /*DOM-IGNORE-END*/
167 } USB_DEVICE_STATE;
168  
169  
170 /* USB device stack events description here - DWF */
171 typedef enum
172 {
173 // Notification that a SET_CONFIGURATION() command was received (device)
174 EVENT_CONFIGURED
175 /*DOM-IGNORE-BEGIN*/ = EVENT_DEVICE_STACK_BASE /*DOM-IGNORE-END*/,
176  
177 // A SET_DESCRIPTOR request was received (device)
178 EVENT_SET_DESCRIPTOR,
179  
180 // An endpoint 0 request was received that the stack did not know how to
181 // handle. This is most often a request for one of the class drivers.
182 // Please refer to the class driver documenation for information related
183 // to what to do if this request is received. (device)
184 EVENT_EP0_REQUEST,
185  
186 // // A USB transfer has completed. The data associated with this event is of
187 // // the data type HOST_TRANSFER_DATA if the event is generated from the host
188 // // stack.
189 // EVENT_TRANSFER,
190 //
191 // // A USB Start of Frame token has been received. This event is not
192 // // used by the Host stack.
193 // EVENT_SOF,
194 //
195 // // Device-mode resume received. This event is not used by the Host stack.
196 // EVENT_RESUME,
197 //
198 // // Device-mode suspend/idle event received. This event is not used by the
199 // // Host stack.
200 // EVENT_SUSPEND,
201 //
202 // // Device-mode bus reset received. This event is not used by the Host
203 // // stack.
204 // EVENT_RESET,
205  
206 // // Device Mode: A setup packet received (data: SETUP_PKT). This event is
207 // // not used by the Host stack.
208 // EVENT_SETUP,
209  
210 // Device-mode USB cable has been attached. This event is not used by the
211 // Host stack. The client driver may provide an application event when a
212 // device attaches.
213 EVENT_ATTACH
214  
215 } USB_DEVICE_STACK_EVENTS;
216  
217 /** Function Prototypes **********************************************/
218  
219 /**************************************************************************
220 Function:
221 void USBDeviceTasks(void)
222  
223 Summary:
224 This function is the main state machine of the USB device side stack.
225 This function should be called periodically to receive and transmit
226 packets through the stack. This function should be called preferably
227 once every 100us during the enumeration process. After the enumeration
228 process this function still needs to be called periodically to respond
229 to various situations on the bus but is more relaxed in its time
230 requirements. This function should also be called at least as fast as
231 the OUT data expected from the PC.
232  
233 Description:
234 This function is the main state machine of the USB device side stack.
235 This function should be called periodically to receive and transmit
236 packets through the stack. This function should be called preferably
237 once every 100us during the enumeration process. After the enumeration
238 process this function still needs to be called periodically to respond
239 to various situations on the bus but is more relaxed in its time
240 requirements. This function should also be called at least as fast as
241 the OUT data expected from the PC.
242  
243 Typical usage:
244 <code>
245 void main(void)
246 {
247 USBDeviceInit()
248 while(1)
249 {
250 USBDeviceTasks();
251 if((USBGetDeviceState() \< CONFIGURED_STATE) ||
252 (USBIsDeviceSuspended() == TRUE))
253 {
254 //Either the device is not configured or we are suspended
255 // so we don't want to do execute any application code
256 continue; //go back to the top of the while loop
257 }
258 else
259 {
260 //Otherwise we are free to run user application code.
261 UserApplication();
262 }
263 }
264 }
265 </code>
266  
267 Conditions:
268 None
269 Remarks:
270 This function should be called preferably once every 100us during the
271 enumeration process. After the enumeration process this function still
272 needs to be called periodically to respond to various situations on the
273 bus but is more relaxed in its time requirements.
274 **************************************************************************/
275 void USBDeviceTasks(void);
276  
277 /**************************************************************************
278 Function:
279 void USBDeviceInit(void)
280  
281 Description:
282 This function initializes the device stack it in the default state. The
283 USB module will be completely reset including all of the internal
284 variables, registers, and interrupt flags.
285  
286 Precondition:
287 This function must be called before any of the other USB Device
288 functions can be called, including USBDeviceTasks().
289  
290 Parameters:
291 None
292  
293 Return Values:
294 None
295  
296 Remarks:
297 None
298  
299 **************************************************************************/
300 void USBDeviceInit(void);
301  
302 /********************************************************************
303 Function:
304 BOOL USBGetRemoteWakeupStatus(void)
305  
306 Summary:
307 This function indicates if remote wakeup has been enabled by the host.
308 Devices that support remote wakeup should use this function to
309 determine if it should send a remote wakeup.
310  
311 Description:
312 This function indicates if remote wakeup has been enabled by the host.
313 Devices that support remote wakeup should use this function to
314 determine if it should send a remote wakeup.
315  
316 If a device does not support remote wakeup (the Remote wakeup bit, bit
317 5, of the bmAttributes field of the Configuration descriptor is set to
318 1), then it should not send a remote wakeup command to the PC and this
319 function is not of any use to the device. If a device does support
320 remote wakeup then it should use this function as described below.
321  
322 If this function returns FALSE and the device is suspended, it should
323 not issue a remote wakeup (resume).
324  
325 If this function returns TRUE and the device is suspended, it should
326 issue a remote wakeup (resume).
327  
328 A device can add remote wakeup support by having the _RWU symbol added
329 in the configuration descriptor (located in the usb_descriptors.c file
330 in the project). This done in the 8th byte of the configuration
331 descriptor. For example:
332  
333 <code lang="c">
334 ROM BYTE configDescriptor1[]={
335 0x09, // Size
336 USB_DESCRIPTOR_CONFIGURATION, // descriptor type
337 DESC_CONFIG_WORD(0x0022), // Total length
338 1, // Number of interfaces
339 1, // Index value of this cfg
340 0, // Configuration string index
341 _DEFAULT | _SELF | _RWU, // Attributes, see usb_device.h
342 50, // Max power consumption in 2X mA(100mA)
343  
344 //The rest of the configuration descriptor should follow
345 </code>
346  
347 For more information about remote wakeup, see the following section of
348 the USB v2.0 specification available at www.usb.org:
349 * Section 9.2.5.2
350 * Table 9-10
351 * Section 7.1.7.7
352 * Section 9.4.5
353  
354 Conditions:
355 None
356  
357 Return Values:
358 TRUE - Remote Wakeup has been enabled by the host
359 FALSE - Remote Wakeup is not currently enabled
360  
361 Remarks:
362 None
363  
364 *******************************************************************/
365 BOOL USBGetRemoteWakeupStatus(void);
366 /*DOM-IGNORE-BEGIN*/
367 #define USBGetRemoteWakeupStatus() RemoteWakeup
368 /*DOM-IGNORE-END*/
369  
370 /***************************************************************************
371 Function:
372 USB_DEVICE_STATE USBGetDeviceState(void)
373  
374 Summary:
375 This function will return the current state of the device on the USB.
376 This function should return CONFIGURED_STATE before an application
377 tries to send information on the bus.
378 Description:
379 This function returns the current state of the device on the USB. This
380 \function is used to determine when the device is ready to communicate
381 on the bus. Applications should not try to send or receive data until
382 this function returns CONFIGURED_STATE.
383  
384 It is also important that applications yield as much time as possible
385 to the USBDeviceTasks() function as possible while the this function
386 \returns any value between ATTACHED_STATE through CONFIGURED_STATE.
387  
388 For more information about the various device states, please refer to
389 the USB specification section 9.1 available from www.usb.org.
390  
391 Typical usage:
392 <code>
393 void main(void)
394 {
395 USBDeviceInit()
396 while(1)
397 {
398 USBDeviceTasks();
399 if((USBGetDeviceState() \< CONFIGURED_STATE) ||
400 (USBIsDeviceSuspended() == TRUE))
401 {
402 //Either the device is not configured or we are suspended
403 // so we don't want to do execute any application code
404 continue; //go back to the top of the while loop
405 }
406 else
407 {
408 //Otherwise we are free to run user application code.
409 UserApplication();
410 }
411 }
412 }
413 </code>
414 Conditions:
415 None
416 Return Values:
417 USB_DEVICE_STATE - the current state of the device on the bus
418  
419 Remarks:
420 None
421 ***************************************************************************/
422 USB_DEVICE_STATE USBGetDeviceState(void);
423 /*DOM-IGNORE-BEGIN*/
424 #define USBGetDeviceState() USBDeviceState
425 /*DOM-IGNORE-END*/
426  
427 /***************************************************************************
428 Function:
429 BOOL USBGetSuspendState(void)
430  
431 Summary:
432 This function indicates if this device is currently suspended. When a
433 device is suspended it will not be able to transfer data over the bus.
434 Description:
435 This function indicates if this device is currently suspended. When a
436 device is suspended it will not be able to transfer data over the bus.
437 This function can be used by the application to skip over section of
438 code that do not need to exectute if the device is unable to send data
439 over the bus.
440  
441 Typical usage:
442 <code>
443 void main(void)
444 {
445 USBDeviceInit()
446 while(1)
447 {
448 USBDeviceTasks();
449 if((USBGetDeviceState() \< CONFIGURED_STATE) ||
450 (USBIsDeviceSuspended() == TRUE))
451 {
452 //Either the device is not configured or we are suspended
453 // so we don't want to do execute any application code
454 continue; //go back to the top of the while loop
455 }
456 else
457 {
458 //Otherwise we are free to run user application code.
459 UserApplication();
460 }
461 }
462 }
463 </code>
464 Conditions:
465 None
466 Return Values:
467 TRUE - this device is suspended.
468 FALSE - this device is not suspended.
469 Remarks:
470 None
471 ***************************************************************************/
472 BOOL USBGetSuspendState(void);
473  
474 /*******************************************************************************
475 Function:
476 void USBEnableEndpoint(BYTE ep, BYTE options)
477  
478 Summary:
479 This function will enable the specified endpoint with the specified
480 options
481 Description:
482 This function will enable the specified endpoint with the specified
483 options.
484  
485 Typical Usage:
486 <code>
487 void USBCBInitEP(void)
488 {
489 USBEnableEndpoint(MSD_DATA_IN_EP,USB_IN_ENABLED|USB_OUT_ENABLED|USB_HANDSHAKE_ENABLED|USB_DISALLOW_SETUP);
490 USBMSDInit();
491 }
492 </code>
493  
494 In the above example endpoint number MSD_DATA_IN_EP is being configured
495 for both IN and OUT traffic with handshaking enabled. Also since
496 MSD_DATA_IN_EP is not endpoint 0 (MSD does not allow this), then we can
497 explicitly disable SETUP packets on this endpoint.
498 Conditions:
499 None
500 Input:
501 BYTE ep - the endpoint to be configured
502 BYTE options - optional settings for the endpoint. The options should
503 be ORed together to form a single options string. The
504 available optional settings for the endpoint. The
505 options should be ORed together to form a single options
506 string. The available options are the following\:
507 * USB_HANDSHAKE_ENABLED enables USB handshaking (ACK,
508 NAK)
509 * USB_HANDSHAKE_DISABLED disables USB handshaking (ACK,
510 NAK)
511 * USB_OUT_ENABLED enables the out direction
512 * USB_OUT_DISABLED disables the out direction
513 * USB_IN_ENABLED enables the in direction
514 * USB_IN_DISABLED disables the in direction
515 * USB_ALLOW_SETUP enables control transfers
516 * USB_DISALLOW_SETUP disables control transfers
517 * USB_STALL_ENDPOINT STALLs this endpoint
518 Return:
519 None
520 Remarks:
521 None
522 *****************************************************************************/
523 void USBEnableEndpoint(BYTE ep, BYTE options);
524  
525 /*******************************************************************************
526 Function:
527 BOOL USBIsDeviceSuspended(void)
528  
529 Summary:
530 This function indicates if the USB module is in suspend mode.
531  
532 Description:
533 This function indicates if the USB module is in suspend mode. This function
534 does NOT indicate that a suspend request has been received. It only
535 reflects the state of the USB module.
536  
537 Typical Usage:
538 <code>
539 if(USBIsDeviceSuspended() == TRUE)
540 {
541 return;
542 }
543 // otherwise do some application specific tasks
544 </code>
545  
546 Conditions:
547 None
548 Input:
549 None
550 Return:
551 None
552 Remarks:
553 None
554 *****************************************************************************/
555 BOOL USBIsDeviceSuspended(void);
556 /*DOM-IGNORE-BEGIN*/
557 #define USBIsDeviceSuspended() USBSuspendControl
558 /*DOM-IGNORE-END*/
559  
560 /*******************************************************************************
561 Function:
562 void USBSoftDetach(void);
563  
564 Summary:
565 This function performs a detach from the USB bus via software.
566  
567 Description:
568 This function performs a detach from the USB bus via software.
569  
570 Conditions:
571 None
572 Input:
573 None
574 Return:
575 None
576 Remarks:
577 Caution should be used when detaching from the bus. Some PC drivers and
578 programs may require additional time after a detach before a device can be
579 reattached to the bus.
580 *****************************************************************************/
581 void USBSoftDetach(void);
582 /*DOM-IGNORE-BEGIN*/
583 #define USBSoftDetach() U1CON = 0; U1IE = 0; USBDeviceState = DETACHED_STATE;
584 /*DOM-IGNORE-END*/
585  
586 /*************************************************************************
587 Function:
588 USB_HANDLE USBTransferOnePacket(BYTE ep, BYTE dir, BYTE* data, BYTE len)
589  
590 Summary:
591 Transfers a single packet (one transaction) of data on the USB bus.
592  
593 Description:
594 The USBTransferOnePacket() function prepares a USB endpoint
595 so that it may send data to the host (an IN transaction), or
596 receive data from the host (an OUT transaction). The
597 USBTransferOnePacket() function can be used both to receive and
598 send data to the host. This function is the primary API function
599 provided by the USB stack firmware for sending or receiving application
600 data over the USB port.
601  
602 The USBTransferOnePacket() is intended for use with all application
603 endpoints. It is not used for sending or receiving applicaiton data
604 through endpoint 0 by using control transfers. Separate API
605 functions, such as USBEP0Receive(), USBEP0SendRAMPtr(), and
606 USBEP0SendROMPtr() are provided for this purpose.
607  
608 The USBTransferOnePacket() writes to the Buffer Descriptor Table (BDT)
609 entry associated with an endpoint buffer, and sets the UOWN bit, which
610 prepares the USB hardware to allow the transaction to complete. The
611 application firmware can use the USBHandleBusy() macro to check the
612 status of the transaction, to see if the data has been successfully
613 transmitted yet.
614  
615  
616 Typical Usage
617 <code>
618 //make sure that the we are in the configured state
619 if(USBGetDeviceState() == CONFIGURED_STATE)
620 {
621 //make sure that the last transaction isn't busy by checking the handle
622 if(!USBHandleBusy(USBInHandle))
623 {
624 //Write the new data that we wish to send to the host to the INPacket[] array
625 INPacket[0] = USEFUL_APPLICATION_VALUE1;
626 INPacket[1] = USEFUL_APPLICATION_VALUE2;
627 //INPacket[2] = ... (fill in the rest of the packet data)
628  
629 //Send the data contained in the INPacket[] array through endpoint "EP_NUM"
630 USBInHandle = USBTransferOnePacket(EP_NUM,IN_TO_HOST,(BYTE*)&INPacket[0],sizeof(INPacket));
631 }
632 }
633 </code>
634  
635 Conditions:
636 Before calling USBTransferOnePacket(), the following should be true.
637 1. The USB stack has already been initialized (USBDeviceInit() was called).
638 2. A transaction is not already pending on the specified endpoint. This
639 is done by checking the previous request using the USBHandleBusy()
640 macro (see the typical usage example).
641 3. The host has already sent a set configuration request and the
642 enumeration process is complete.
643 This can be checked by verifying that the USBGetDeviceState()
644 macro returns "CONFIGURED_STATE", prior to calling
645 USBTransferOnePacket().
646  
647 Input:
648 BYTE ep - The endpoint number that the data will be transmitted or
649 received on
650 BYTE dir - The direction of the transfer
651 This value is either OUT_FROM_HOST or IN_TO_HOST
652 BYTE* data - For IN transactions: pointer to the RAM buffer containing
653 the data to be sent to the host. For OUT transactions: pointer
654 to the RAM buffer that the received data should get written to.
655 BYTE len - Length of the data needing to be sent (for IN transactions).
656 For OUT transactions, the len parameter should normally be set
657 to the endpoint size specified in the endpoint descriptor.
658  
659 Return Values:
660 USB_HANDLE - handle to the transfer. The handle is a pointer to
661 the BDT entry associated with this transaction. The
662 status of the transaction (ex: if it is complete or still
663 pending) can be checked using the USBHandleBusy() macro
664 and supplying the USB_HANDLE provided by
665 USBTransferOnePacket().
666  
667 Remarks:
668 If calling the USBTransferOnePacket() function from within the USBCBInitEP()
669 callback function, the set configuration is still being processed and the
670 USBDeviceState may not be == CONFIGURED_STATE yet. In this special case,
671 the USBTransferOnePacket() may still be called, but make sure that the
672 endpoint has been enabled and initialized by the USBEnableEndpoint()
673 function first.
674  
675 *************************************************************************/
676 USB_HANDLE USBTransferOnePacket(BYTE ep,BYTE dir,BYTE* data,BYTE len);
677  
678 /*************************************************************************
679 Function:
680 BOOL USBHandleBusy(USB_HANDLE handle)
681  
682 Summary:
683 Checks to see if the input handle is busy
684  
685 Description:
686 Checks to see if the input handle is busy
687  
688 Typical Usage
689 <code>
690 //make sure that the last transfer isn't busy by checking the handle
691 if(!USBHandleBusy(USBGenericInHandle))
692 {
693 //Send the data contained in the INPacket[] array out on
694 // endpoint USBGEN_EP_NUM
695 USBGenericInHandle = USBGenWrite(USBGEN_EP_NUM,(BYTE*)&INPacket[0],sizeof(INPacket));
696 }
697 </code>
698  
699 Conditions:
700 None
701 Input:
702 USB_HANDLE handle - handle of the transfer that you want to check the
703 status of
704 Return Values:
705 TRUE - The specified handle is busy
706 FALSE - The specified handle is free and available for a transfer
707 Remarks:
708 None
709 *************************************************************************/
710 BOOL USBHandleBusy(USB_HANDLE handle);
711 /*DOM-IGNORE-BEGIN*/
712 #define USBHandleBusy(handle) (handle==0?0:((volatile BDT_ENTRY*)handle)->STAT.UOWN)
713 /*DOM-IGNORE-END*/
714  
715 /********************************************************************
716 Function:
717 WORD USBHandleGetLength(USB_HANDLE handle)
718  
719 Summary:
720 Retrieves the length of the destination buffer of the input
721 handle
722  
723 Description:
724 Retrieves the length of the destination buffer of the input
725 handle
726  
727 PreCondition:
728 None
729  
730 Parameters:
731 USB_HANDLE handle - the handle to the transfer you want the
732 address for.
733  
734 Return Values:
735 WORD - length of the current buffer that the input handle
736 points to. If the transfer is complete then this is the
737 length of the data transmitted or the length of data
738 actually received.
739  
740 Remarks:
741 None
742  
743 *******************************************************************/
744 WORD USBHandleGetLength(USB_HANDLE handle);
745 /*DOM-IGNORE-BEGIN*/
746 #define USBHandleGetLength(handle) (((volatile BDT_ENTRY*)handle)->CNT)
747 /*DOM-IGNORE-END*/
748  
749 /********************************************************************
750 Function:
751 WORD USBHandleGetAddr(USB_HANDLE)
752  
753 Summary:
754 Retrieves the address of the destination buffer of the input
755 handle
756  
757 Description:
758 Retrieves the address of the destination buffer of the input
759 handle
760  
761 PreCondition:
762 None
763  
764 Parameters:
765 USB_HANDLE handle - the handle to the transfer you want the
766 address for.
767  
768 Return Values:
769 WORD - address of the current buffer that the input handle
770 points to.
771  
772 Remarks:
773 None
774  
775 *******************************************************************/
776 WORD USBHandleGetAddr(USB_HANDLE);
777 /*DOM-IGNORE-BEGIN*/
778 #define USBHandleGetAddr(handle) ConvertToVirtualAddress((((volatile BDT_ENTRY*)handle)->ADR))
779 /*DOM-IGNORE-END*/
780  
781 /********************************************************************
782 Function:
783 void USBEP0Transmit(BYTE options)
784  
785 Summary:
786 Sets the address of the data to send over the
787 control endpoint
788  
789 PreCondition:
790 None
791  
792 Paramters:
793 options - the various options that you want
794 when sending the control data. Options are:
795 USB_EP0_ROM
796 USB_EP0_RAM
797 USB_EP0_BUSY
798 USB_EP0_INCLUDE_ZERO
799 USB_EP0_NO_DATA
800 USB_EP0_NO_OPTIONS
801  
802 Return Values:
803 None
804  
805 Remarks:
806 None
807  
808 *******************************************************************/
809 void USBEP0Transmit(BYTE options);
810 /*DOM-IGNORE-BEGIN*/
811 #define USBEP0Transmit(options) inPipes[0].info.Val = options | USB_EP0_BUSY
812 /*DOM-IGNORE-END*/
813  
814 /*************************************************************************
815 Function:
816 void USBEP0SendRAMPtr(BYTE* src, WORD size, BYTE Options)
817  
818 Summary:
819 Sets the source, size, and options of the data you wish to send from a
820 RAM source
821 Conditions:
822 None
823 Input:
824 src - address of the data to send
825 size - the size of the data needing to be transmitted
826 options - the various options that you want when sending the control
827 data. Options are\:
828 * USB_EP0_ROM
829 * USB_EP0_RAM
830 * USB_EP0_BUSY
831 * USB_EP0_INCLUDE_ZERO
832 * USB_EP0_NO_DATA
833 * USB_EP0_NO_OPTIONS
834 Remarks:
835 None
836 *************************************************************************/
837 void USBEP0SendRAMPtr(BYTE* src, WORD size, BYTE Options);
838 /*DOM-IGNORE-BEGIN*/
839 #define USBEP0SendRAMPtr(src,size,options) {\
840 inPipes[0].pSrc.bRam = src;\
841 inPipes[0].wCount.Val = size;\
842 inPipes[0].info.Val = options | USB_EP0_BUSY | USB_EP0_RAM;\
843 }
844 /*DOM-IGNORE-END*/
845  
846 /**************************************************************************
847 Function:
848 void USBEP0SendROMPtr(BYTE* src, WORD size, BYTE Options)
849  
850 Summary:
851 Sets the source, size, and options of the data you wish to send from a
852 ROM source
853 Conditions:
854 None
855 Input:
856 src - address of the data to send
857 size - the size of the data needing to be transmitted
858 options - the various options that you want when sending the control
859 data. Options are\:
860 * USB_EP0_ROM
861 * USB_EP0_RAM
862 * USB_EP0_BUSY
863 * USB_EP0_INCLUDE_ZERO
864 * USB_EP0_NO_DATA
865 * USB_EP0_NO_OPTIONS
866 Remarks:
867 None
868 **************************************************************************/
869 void USBEP0SendROMPtr(BYTE* src, WORD size, BYTE Options);
870 /*DOM-IGNORE-BEGIN*/
871 #define USBEP0SendROMPtr(src,size,options) {\
872 inPipes[0].pSrc.bRom = src;\
873 inPipes[0].wCount.Val = size;\
874 inPipes[0].info.Val = options | USB_EP0_BUSY | USB_EP0_ROM;\
875 }
876 /*DOM-IGNORE-END*/
877  
878 /***************************************************************************
879 Function:
880 void USBEP0Receive(BYTE* dest, WORD size, void (*function))
881 Summary:
882 Sets the destination, size, and a function to call on the completion of
883 the next control write.
884 Conditions:
885 None
886 Input:
887 dest - address of where the incoming data will go (make sure that this
888 address is directly accessable by the USB module for parts with
889 dedicated USB RAM this address must be in that space)
890 size - the size of the data being received (is almost always going tobe
891 presented by the preceeding setup packet SetupPkt.wLength)
892 (*function) - a function that you want called once the data is received. If
893 this is specificed as NULL then no function is called.
894 Remarks:
895 None
896 ***************************************************************************/
897 void USBEP0Receive(BYTE* dest, WORD size, void (*function));
898 /*DOM-IGNORE-BEGIN*/
899 #define USBEP0Receive(dest,size,function) {outPipes[0].pDst.bRam = dest;outPipes[0].wCount.Val = size;outPipes[0].pFunc = function;outPipes[0].info.bits.busy = 1; }
900 /*DOM-IGNORE-END*/
901  
902 /********************************************************************
903 Function:
904 USB_HANDLE USBTxOnePacket(BYTE ep, BYTE* data, WORD len)
905  
906 Summary:
907 Sends the specified data out the specified endpoint
908  
909 PreCondition:
910 None
911  
912 Parameters:
913 ep - the endpoint you want to send the data out of
914 data - the data that you wish to send
915 len - the length of the data that you wish to send
916  
917 Return Values:
918 USB_HANDLE - a handle for the transfer. This information
919 should be kept to track the status of the transfer
920  
921 Remarks:
922 None
923  
924 *******************************************************************/
925 USB_HANDLE USBTxOnePacket(BYTE ep, BYTE* data, WORD len);
926 /*DOM-IGNORE-BEGIN*/
927 #define USBTxOnePacket(ep,data,len) USBTransferOnePacket(ep,IN_TO_HOST,data,len)
928 /*DOM-IGNORE-END*/
929  
930 /********************************************************************
931 Function:
932 USB_HANDLE USBRxOnePacket(BYTE ep, BYTE* data, WORD len)
933  
934 Summary:
935 Receives the specified data out the specified endpoint
936  
937 PreCondition:
938 None
939  
940 Parameters:
941 ep - the endpoint you want to receive the data into
942 data - where the data will go when it arrives
943 len - the length of the data that you wish to receive
944  
945 Return Values:
946 None
947  
948 Remarks:
949 None
950  
951 *******************************************************************/
952 USB_HANDLE USBRxOnePacket(BYTE ep, BYTE* data, WORD len);
953 /*DOM-IGNORE-BEGIN*/
954 #define USBRxOnePacket(ep,data,len) USBTransferOnePacket(ep,OUT_FROM_HOST,data,len)
955 /*DOM-IGNORE-END*/
956  
957 /********************************************************************
958 Function:
959 void USBStallEndpoint(BYTE ep, BYTE dir)
960  
961 Summary:
962 STALLs the specified endpoint
963  
964 PreCondition:
965 None
966  
967 Parameters:
968 BYTE ep - the endpoint the data will be transmitted on
969 BYTE dir - the direction of the transfer
970  
971 Return Values:
972 None
973  
974 Remarks:
975 None
976  
977 *******************************************************************/
978 void USBStallEndpoint(BYTE ep, BYTE dir);
979  
980 /**************************************************************************
981 Function:
982 void USBDeviceDetach(void)
983  
984 Summary:
985 This function indicates to the USB module that the USB device has been
986 detached from the bus.
987  
988 Description:
989 This function indicates to the USB module that the USB device has been
990 detached from the bus. This function needs to be called in order for the
991 device to start to properly prepare for the next attachment.
992  
993 Precondition:
994 Should only be called when USB_INTERRUPT is defined.
995  
996 Parameters:
997 None
998  
999 Return Values:
1000 None
1001  
1002 Remarks:
1003 None
1004  
1005 **************************************************************************/
1006 void USBDeviceDetach(void);
1007  
1008 /*DOM-IGNORE-BEGIN*/
1009 #if !defined(USB_INTERRUPT)
1010 #define USBDeviceDetach()
1011 #endif
1012 /*DOM-IGNORE-END*/
1013  
1014 /**************************************************************************
1015 Function:
1016 void USBDeviceAttach(void)
1017  
1018 Summary:
1019 This function indicates to the USB module that the USB device has been
1020 attached to the bus.
1021  
1022 Description:
1023 This function indicates to the USB module that the USB device has been
1024 attached to the bus. This function needs to be called in order for the
1025 device to start to enumerate on the bus.
1026  
1027 Precondition:
1028 Should only be called when USB_INTERRUPT is defined.
1029  
1030 For normal USB devices:
1031 Make sure that if the module was previously on, that it has been turned off
1032 for a long time (ex: 100ms+) before calling this function to re-enable the module.
1033 If the device turns off the D+ (for full speed) or D- (for low speed) ~1.5k ohm
1034 pull up resistor, and then turns it back on very quickly, common hosts will sometimes
1035 reject this event, since no human could ever unplug and reattach a USB device in a
1036 microseconds (or nanoseconds) timescale. The host could simply treat this as some kind
1037 of glitch and ignore the event altogether.
1038 Parameters:
1039 None
1040  
1041 Return Values:
1042 None
1043 ****************************************************************************/
1044 void USBDeviceAttach(void);
1045  
1046 /*DOM-IGNORE-BEGIN*/
1047 #if !defined(USB_INTERRUPT)
1048 #define USBDeviceAttach()
1049 #endif
1050 /*DOM-IGNORE-END*/
1051  
1052 /*******************************************************************************
1053 Function:
1054 BOOL USB_APPLICATION_EVENT_HANDLER(BYTE address, USB_EVENT event, void *pdata, WORD size);
1055  
1056 Summary:
1057 This function is called whenever the USB stack wants to notify the user of
1058 an event.
1059  
1060 Description:
1061 This function is called whenever the USB stack wants to notify the user of
1062 an event. This function should be implemented by the user.
1063  
1064 Example Usage:
1065 Conditions:
1066 None
1067  
1068 Input:
1069 BYTE address - the address of the device when the event happened
1070 BYTE event - The event input specifies which event happened. The
1071 possible options are listed in the USB_DEVICE_STACK_EVENTS
1072 enumeration.
1073  
1074 Return:
1075 None
1076 Remarks:
1077 None
1078 *****************************************************************************/
1079 BOOL USB_APPLICATION_EVENT_HANDLER(BYTE address, USB_EVENT event, void *pdata, WORD size);
1080  
1081 /*******************************************************************************
1082 Function:
1083 ROM void *USBDeviceCBGetDescriptor (UINT16 *length, DESCRIPTOR_ID *id);
1084  
1085 Summary:
1086 This function is called whenever the USB stack gets a USB GET_DESCRIPTOR
1087 request.
1088  
1089 Description:
1090 This function is called whenever the USB stack gets a USB GET_DESCRIPTOR
1091 request. This function is responsible for returning a pointer to the
1092 requested descriptor and setting that the length for the that descriptor.
1093  
1094 This function should be implemented by the user. This function might be
1095 generated automatically by the USB configuration tool.
1096  
1097 Conditions:
1098 None
1099  
1100 Input:
1101 BYTE *length - pointer to a variable that should be set to the length of
1102 the requested descriptor.
1103 BYTE *id - This structure contains information about the requested
1104 descriptor
1105  
1106 Return:
1107 ROM void* - pointer to the requested descriptor.
1108 Remarks:
1109 None
1110 *****************************************************************************/
1111 ROM void *USBDeviceCBGetDescriptor (UINT16 *length, DESCRIPTOR_ID *id);
1112  
1113 /**************************************************************************
1114 Function:
1115 void USBCancelIO(BYTE endpoint)
1116  
1117 Description:
1118 This function cancels the transfers pending on the specified endpoint.
1119 This function can only be used after a SETUP packet is received and
1120 before that setup packet is handled. This is the time period in which
1121 the EVENT_EP0_REQUEST is thrown, before the event handler function
1122 returns to the stack.
1123  
1124 Precondition:
1125  
1126 Parameters:
1127 BYTE endpoint - the endpoint number you wish to cancel the transfers for
1128  
1129 Return Values:
1130 None
1131  
1132 Remarks:
1133 None
1134  
1135 **************************************************************************/
1136 void USBCancelIO(BYTE endpoint);
1137  
1138  
1139 /** Section: MACROS ******************************************************/
1140  
1141 /* The DESC_CONFIG_WORD() macro is implemented for convinence. Since the
1142 configuration descriptor array is a BYTE array, each entry needs to be a
1143 BYTE in LSB format. The DESC_CONFIG_WORD() macro breaks up a WORD into
1144 the appropriate BYTE entries in LSB.
1145 Typical Usage:
1146 <code>
1147 ROM BYTE configDescriptor1[]={
1148 0x09, // Size of this descriptor in bytes
1149 USB_DESCRIPTOR_CONFIGURATION, // CONFIGURATION descriptor type
1150 DESC_CONFIG_WORD(0x0022), // Total length of data for this cfg
1151 </code>
1152 */
1153 #define DESC_CONFIG_WORD(a) (a&0xFF),((a>>8)&0xFF)
1154  
1155 /* The DESC_CONFIG_DWORD() macro is implemented for convinence. Since the
1156 configuration descriptor array is a BYTE array, each entry needs to be a
1157 BYTE in LSB format. The DESC_CONFIG_DWORD() macro breaks up a DWORD into
1158 the appropriate BYTE entries in LSB.
1159 */
1160 #define DESC_CONFIG_DWORD(a) (a&0xFF),((a>>8)&0xFF),((a>>16)&0xFF),((a>>24)&0xFF)
1161  
1162 /* The DESC_CONFIG_BYTE() macro is implemented for convinence. The
1163 DESC_CONFIG_BYTE() macro provides a consistant macro for use with a byte
1164 when generating a configuratin descriptor when using either the
1165 DESC_CONFIG_WORD() or DESC_CONFIG_DWORD() macros.
1166 */
1167 #define DESC_CONFIG_BYTE(a) (a)
1168  
1169  
1170  
1171  
1172  
1173  
1174  
1175  
1176  
1177  
1178  
1179  
1180  
1181  
1182  
1183  
1184  
1185 /* DOM-IGNORE-BEGIN */
1186 /*******************************************************************************
1187 ********************************************************************************
1188 ********************************************************************************
1189 This section contains implementation specific information that may vary
1190 between releases as the implementation needs to change. This section is
1191 included for compilation reasons only.
1192 ********************************************************************************
1193 ********************************************************************************
1194 *******************************************************************************/
1195  
1196 #if defined(USB_POLLING)
1197 #define USB_VOLATILE
1198 #else
1199 #define USB_VOLATILE volatile
1200 #endif
1201  
1202 #define CTRL_TRF_RETURN void
1203 #define CTRL_TRF_PARAMS void
1204  
1205 // Defintion of the PIPE structure
1206 // This structure is used to keep track of data that is sent out
1207 // of the stack automatically.
1208 typedef struct __attribute__ ((packed))
1209 {
1210 union __attribute__ ((packed))
1211 {
1212 //Various options of pointers that are available to
1213 // get the data from
1214 BYTE *bRam;
1215 ROM BYTE *bRom;
1216 WORD *wRam;
1217 ROM WORD *wRom;
1218 }pSrc;
1219 union __attribute__ ((packed))
1220 {
1221 struct __attribute__ ((packed))
1222 {
1223 //is this transfer from RAM or ROM?
1224 BYTE ctrl_trf_mem :1;
1225 BYTE reserved :5;
1226 //include a zero length packet after
1227 //data is done if data_size%ep_size = 0?
1228 BYTE includeZero :1;
1229 //is this PIPE currently in use
1230 BYTE busy :1;
1231 }bits;
1232 BYTE Val;
1233 }info;
1234 WORD_VAL wCount;
1235 }IN_PIPE;
1236  
1237 extern USB_VOLATILE IN_PIPE inPipes[];
1238  
1239 typedef struct __attribute__ ((packed))
1240 {
1241 union __attribute__ ((packed))
1242 {
1243 //Various options of pointers that are available to
1244 // get the data from
1245 BYTE *bRam;
1246 WORD *wRam;
1247 }pDst;
1248 union __attribute__ ((packed))
1249 {
1250 struct __attribute__ ((packed))
1251 {
1252 BYTE reserved :7;
1253 //is this PIPE currently in use
1254 BYTE busy :1;
1255 }bits;
1256 BYTE Val;
1257 }info;
1258 WORD_VAL wCount;
1259 CTRL_TRF_RETURN (*pFunc)(CTRL_TRF_PARAMS);
1260 }OUT_PIPE;
1261  
1262 /************* DWF - SHOULD BE REIMPLEMENTED AS AN EVENT *******************/
1263 //#if defined(ENABLE_EP0_DATA_RECEIVED_CALLBACK)
1264 // void USBCBEP0DataReceived(void);
1265 // #define USBCB_EP0_DATA_RECEIVED() USBCBEP0DataReceived()
1266 //#else
1267 // #define USBCB_EP0_DATA_RECEIVED()
1268 //#endif
1269  
1270 extern USB_VOLATILE BOOL RemoteWakeup;
1271 extern USB_VOLATILE USB_DEVICE_STATE USBDeviceState;
1272 extern USB_VOLATILE BYTE USBActiveConfiguration;
1273 /******************************************************************************/
1274 /* DOM-IGNORE-END */
1275  
1276 #endif //USBD_H
{BLAME END}
{FOOTER START}

Powered by WebSVN v2.8.3