?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 Hardware Abstraction Layer (HAL) (Header File)
4  
5 Summary:
6 This file abstracts the hardware interface.
7  
8 Description:
9 This file abstracts the hardware interface.
10  
11 This file is located in the "\<Install Directory\>\\Microchip\\Include\\USB"
12 directory.
13  
14 When including this file in a new project, this file can either be
15 referenced from the directory in which it was installed or copied
16 directly into the user application folder. If the first method is
17 chosen to keep the file located in the folder in which it is installed
18 then include paths need to be added so that the library and the
19 application both know where to reference each others files. If the
20 application folder is located in the same folder as the Microchip
21 folder (like the current demo folders), then the following include
22 paths need to be added to the application's project:
23  
24 .
25 ..\\..\\MicrochipInclude
26  
27 If a different directory structure is used, modify the paths as
28 required. An example using absolute paths instead of relative paths
29 would be the following:
30  
31 C:\\Microchip Solutions\\Microchip\\Include
32  
33 C:\\Microchip Solutions\\My Demo Application
34 *******************************************************************************/
35 //DOM-IGNORE-BEGIN
36 /******************************************************************************
37  
38 File Description:
39  
40 This file defines the interface to the USB hardware abstraction layer.
41  
42 Filename: usb_hal.h
43 Dependancies: none
44 Processor: PIC18, PIC24, or PIC32 USB Microcontrollers
45 Hardware: The code is natively intended to be used on the following
46 hardware platforms: PICDEM™ FS USB Demo Board,
47 PIC18F87J50 FS USB Plug-In Module, or
48 Explorer 16 + PIC24 USB PIM. The firmware may be
49 modified for use on other USB platforms by editing the
50 HardwareProfile.h file.
51 Compiler: Microchip C18 (for PIC18) or C30 (for PIC24)
52 Company: Microchip Technology, Inc.
53  
54 Software License Agreement:
55  
56 The software supplied herewith by Microchip Technology Incorporated
57 (the “Company”) for its PICmicro® Microcontroller is intended and
58 supplied to you, the Company’s customer, for use solely and
59 exclusively on Microchip PICmicro Microcontroller products. The
60 software is owned by the Company and/or its supplier, and is
61 protected under applicable copyright laws. All rights are reserved.
62 Any use in violation of the foregoing restrictions may subject the
63 user to criminal sanctions under applicable laws, as well as to
64 civil liability for the breach of the terms and conditions of this
65 license.
66  
67 THIS SOFTWARE IS PROVIDED IN AN “AS IS” CONDITION. NO WARRANTIES,
68 WHETHER EXPRESS, IMPLIED OR STATUTORY, INCLUDING, BUT NOT LIMITED
69 TO, IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
70 PARTICULAR PURPOSE APPLY TO THIS SOFTWARE. THE COMPANY SHALL NOT,
71 IN ANY CIRCUMSTANCES, BE LIABLE FOR SPECIAL, INCIDENTAL OR
72 CONSEQUENTIAL DAMAGES, FOR ANY REASON WHATSOEVER.
73  
74 *************************************************************************/
75  
76 /********************************************************************
77 Change History:
78 Rev Description
79 ---- -----------
80 2.6- No Change
81 2.6a
82  
83 2.7 Minor changes changes to the structure of the conditional
84 compilation statement ordering.
85  
86 2.7a No Change
87 ********************************************************************/
88  
89 #ifndef _USB_HAL_H_
90 #define _USB_HAL_H_
91 //DOM-IGNORE-END
92  
93 #if defined(__18CXX)
94 #include "USB\usb_hal_pic18.h"
95 #elif defined(__C30__)
96 #include "USB\usb_hal_pic24.h"
97 #elif defined(__PIC32MX__)
98 #include "USB\usb_hal_pic32.h"
99 #else
100 #error "Silicon Platform not defined"
101 #endif
102  
103  
104 /**********************
105 Interface Routines
106 **********************/
107  
108 /*************************************************************************
109 Function:
110 void USBHALSetBusAddress( BYTE addr )
111  
112 Description:
113 This routine sets the address of the system on the USB
114 when acting as a peripheral device.
115  
116 Preconditions:
117 1. USBHALInitialize must have been called to
118 initialize the USB HAL.
119 2. Endpoint zero (0) must be configured as appropriate
120 by calls to USBHALSetEpConfiguration.
121 3. The system must have been enumerated on the USB (as
122 a device).
123  
124 Parameters:
125 addr Desired address of this device on the USB.
126  
127 Return Values:
128 None
129  
130 Side Effect:
131 The bus address has been set.
132  
133 Remmarks:
134 The address is assigned by the host and is received in
135 a SET_ADDRESS setup request.
136  
137 *************************************************************************/
138 /*
139 This routine is implemented as a macro to a lower-level level routine.
140 */
141  
142 #define USBHALSetBusAddress OTGCORE_SetDeviceAddr
143  
144 void USBHALSetBusAddress( BYTE addr );
145  
146  
147 /*************************************************************************
148 Function:
149 void USBHALControlUsbResistors( BYTE flags );
150  
151 Description:
152 This routine enables or disables the USB pull-up or
153 pull-down resistors as requested.
154  
155 Precondition:
156 USBInitialize must have been called to initialize the
157 USB SW stack.
158  
159 Parameters:
160 flags - This is a bit-mapped flags value indicating
161 which resistors to enable or disable (see below).
162  
163 Return Values:
164 TRUE if successful, FALSE if not.
165  
166 Side Effects:
167 The resistors are enabled as requested.
168  
169 Remarks:
170 Used for USB peripheral control to connect to or
171 disconnect from the bus. Otherwise, used for OTG
172 SRP/HNP and host support.
173  
174 *************************************************************************/
175  
176 /*
177 This routine is implemented as a macro to a lower-level level routine.
178 */
179 #if defined(__18CXX)
180 void USBHALControlUsbResistors( BYTE flags );
181 #else
182 #define USBHALControlUsbResistors OTGCORE_ControlUsbResistors
183 void USBHALControlUsbResistors( BYTE flags );
184 #endif
185  
186 /* USBHALControlUsbResistors flags */
187 #define USB_HAL_PULL_UP_D_PLUS 0x80 // Pull D+ line high
188 #define USB_HAL_PULL_UP_D_MINUS 0x40 // Pull D- line high
189 #define USB_HAL_PULL_DN_D_PLUS 0x20 // Pull D+ line low
190 #define USB_HAL_PULL_DN_D_MINUS 0x10 // Pull D- line low
191 /*
192 The following are defined for convenience:
193 */
194 #define USB_HAL_DEV_CONN_FULL_SPD USB_HAL_PULL_UP_D_PLUS
195 #define USB_HAL_DEV_CONN_LOW_SPD USB_HAL_PULL_UP_D_MINUS
196 #define USB_HAL_DEV_DISCONNECT 0
197  
198  
199 /*
200 To Do: Define a method to check for SE0 & a way to send a reset (SE0).
201 */
202  
203  
204 /*************************************************************************
205 Function:
206 BOOL USBHALSessionIsValid( void )
207  
208 Description:
209 This routine determines if there is currently a valid
210 USB session or not.
211  
212 Precondition:
213 USBInitialize must have been called to initialize the
214 USB SW stack.
215  
216 Parameters:
217 None
218  
219 Return Values:
220 TRUE if the session is currently valid, FALSE if not.
221  
222 Remarks:
223 Only used for host and OTG support.
224  
225 *************************************************************************/
226  
227 BOOL USBHALSessionIsValid( void );
228  
229  
230 /*************************************************************************
231 Function:
232 USBHALControlBusPower
233  
234 Description:
235 This routine provides a bitmap of the most recent
236 error conditions to occur.
237  
238 Precondition:
239 USBInitialize must have been called to initialize the
240 USB SW stack.
241  
242 Parameters:
243 cmd - Identifies desired command (see below).
244  
245 Return Values:
246 TRUE if successful, FALSE if not.
247  
248 Remarks:
249 Only used for host and OTG support.
250  
251 *************************************************************************/
252  
253 BOOL USBHALControlBusPower( BYTE cmd );
254  
255 /* USBHALControlBusPower Commands */
256 #define USB_VBUS_DISCHARGE 0 // Dicharge Vbus via resistor
257 #define USB_VBUS_CHARGE 1 // Charge Vbus via resistor
258 #define USB_VBUS_POWER_ON 3 // Supply power to Vbus
259 #define USB_VBUS_POWER_OFF 4 // Do not supply power to Vbus
260 /*
261 Note: All commands except USB_VBUS_POWER_ON imply that this device
262 does not actively supply power to Vbus.
263 */
264  
265  
266 /*************************************************************************
267 Function:
268 unsigned long USBHALGetLastError( void )
269  
270 Description:
271 This routine provides a bitmap of the most recent
272 error conditions to occur.
273  
274 Precondition:
275 USBInitialize must have been called to initialize the
276 USB SW stack.
277  
278 Parameters:
279 None
280  
281 Return Values:
282 Bitmap indicating the most recent error condition(s).
283  
284 Side Effect:
285 Error record is cleared.
286  
287 Remarks:
288 Although record of the error state is cleared, nothing
289 is done to fix the condition or recover from the
290 error. The client must take appropriate steps.
291  
292 *************************************************************************/
293  
294 unsigned long USBHALGetLastError( void );
295  
296 /*
297 USBHALGetLastError Error Bits.
298 */
299 #define USBHAL_PID_ERR 0x00000001 // Packet ID Error
300 #define USBHAL_CRC5 0x00000002 // (Host) Token CRC5 check failed
301 #define USBHAL_HOST_EOF 0x00000002 // (Host) EOF not reached before next SOF
302 #define USBHAL_CRC16 0x00000004 // Data packet CRC error
303 #define USBHAL_DFN8 0x00000008 // Data field size not n*8 bits
304 #define USBHAL_BTO_ERR 0x00000010 // Bus turn-around timeout
305 #define USBHAL_DMA_ERR 0x00000020 // DMA error, unable to read/write memory
306 #define USBHAL_BTS_ERR 0x00000080 // Bit-stuffing error
307 #define USBHAL_XFER_ID 0x00000100 // Unable to identify transfer EP
308 #define USBHAL_NO_EP 0x00000200 // Invalid endpoint number
309 #define USBHAL_DMA_ERR2 0x00000400 // Error starting DMA transaction
310  
311  
312 /*************************************************************************
313 Function:
314 void USBHALHandleBusEvent ( void )
315  
316 Description:
317 This routine checks the USB for any events that may
318 have occured and handles them appropriately. It may
319 be called directly to poll the USB and handle events
320 or it may be called in response to an interrupt.
321  
322 Precondition:
323 USBInitialize must have been called to initialize the
324 USB SW stack.
325  
326 Parameters:
327 None
328  
329 Return Values:
330 None
331  
332 Side Effects:
333 Depend on the event that may have occured.
334  
335 Remarks:
336 None
337  
338 *************************************************************************/
339  
340 void USBHALHandleBusEvent ( void );
341  
342  
343 /*************************************************************************
344 Function:
345 BOOL USBHALStallPipe( TRANSFER_FLAGS pipe )
346  
347 Description:
348 This routine stalls the given endpoint.
349  
350 Preconditions:
351 USBHALInitialize must have been called to initialize
352 the USB HAL.
353  
354 Parameters:
355 pipe - Uses the TRANSFER_FLAGS (see USBCommon.h) format to
356 identify the endpoint and direction making up the
357 pipe to stall.
358  
359 Note: Only ep_num and direction fields are required.
360  
361 Return Values:
362 TRUE if able to stall endpoint, FALSE if not.
363  
364 Side Effects:
365 The endpoint will stall if additional data transfer is
366 attempted.
367 Given endpoint has been stalled.
368  
369 Remarks:
370 Starting another data transfer automatically
371 "un-stalls" the endpoint.
372  
373 *************************************************************************/
374 /*
375 Note: This function is implemented as a macro, calling directly into
376 an internal HAL routine.
377 */
378  
379 #define USBHALStallPipe OTGCORE_StallPipe
380  
381 BOOL USBHALStallPipe( TRANSFER_FLAGS pipe );
382  
383  
384 /******************************************************************************
385 Function:
386 BOOL USBHALUnstallPipe( TRANSFER_FLAGS pipe )
387  
388 Description:
389 This routine clears the stall condition for the given pipe.
390  
391 PreCondition:
392 Assumes OTGCORE_DeviceEnable has been called and
393 OTGCORE_StallPipe has been called on the given pipe.
394  
395 Parameters:
396 pipe - Uses the TRANSFER_FLAGS (see USBCommon.h) format to
397 identify the endpoint and direction making up the
398 pipe to unstall.
399  
400 Return Values:
401 TRUE if able to stall the pipe, FALSE if not.
402  
403 Side Effects:
404 The BSTALL and UOWN bits (and all other control bits) in
405 the BDT for the given pipe will be cleared.
406  
407 Remarks:
408 None
409  
410 *****************************************************************************/
411 /*
412 Note: This function is implemented as a macro, calling directly into
413 an internal HAL routine.
414 */
415  
416 #define USBHALUnstallPipe OTGCORE_UnstallPipe
417  
418 BOOL USBHALUnstallPipe( TRANSFER_FLAGS pipe );
419  
420  
421 /**************************************************************************
422 Function:
423 USBHALGetStalledEndpoints
424  
425 Description:
426 This function returns a 16-bit bitmapped value with a
427 bit set in the position of any endpoint that is stalled
428 (i.e. if endpoint 0 is stalled then bit 0 is set, if
429 endpoint 1 is stalled then bit 1 is set, etc.).
430  
431 Preconditions:
432 USBHALInitialize must have been called to initialize
433 the USB HAL.
434  
435 Parameters:
436 None
437  
438 Return Values:
439 Bitmap of the currently stalled endpoints (see overview).
440  
441 Remarks:
442 None
443 *************************************************************************/
444  
445 /*
446 Note: This function is implemented as a macro, calling directly into
447 a HAL routine.
448 */
449  
450 #define USBHALGetStalledEndpoints OTGCORE_GetStalledEndpoints
451  
452 UINT16 USBHALGetStalledEndpoints ( void );
453  
454  
455 /******************************************************************************
456 Function:
457 BOOL USBHALFlushPipe( TRANSFER_FLAGS pipe )
458  
459 Description:
460 This routine clears any pending transfers on the given
461 pipe.
462  
463 Preconditions:
464 USBHALInitialize must have been called to initialize the
465 USB HAL.
466  
467 The caller must ensure that there is no possible way for
468 hardware to be currently accessing the pipe (see notes).
469  
470 Parameters:
471 pipe - Uses the TRANSFER_FLAGS (see USBCommon.h) format to
472 identify the endpoint and direction making up the
473 pipe to flush.
474  
475 Return Values:
476 TRUE if successful, FALSE if not.
477  
478 Side Effects:
479 Transfer data for this pipe has been zero'd out.
480  
481 Remarks:
482 This routine ignores the normal HW protocol for ownership
483 of the pipe data and flushes the pipe, even if it is in
484 process. Thus, the caller must ensure that data transfer
485 cannot be in process. This situation occurs when a
486 transfer has been terminated early by the host.
487 *****************************************************************************/
488  
489 BOOL USBHALFlushPipe( TRANSFER_FLAGS pipe );
490  
491  
492 /**************************************************************************
493 Function:
494 USBHALTransferData
495  
496 Description:
497 This routine prepares to transfer data on the USB.
498 If the system is in device mode, the actual transfer
499 will not occur until the host peforms an OUT request
500 to the given endpoint. If the system is in host mode,
501 the transfer will not start until the token has been
502 sent on the bus.
503  
504 Preconditions:
505 1. USBHALInitialize must have been called to
506 initialize the USB HAL.
507 2. The endpoint through which the data will be
508 transferred must be configured as appropriate by a
509 call to USBHALSetEpConfiguration.
510 3. The bus must have been enumerated (either as a host
511 or device). Except for EP0 transfers.
512  
513 Parameters:
514 flags - Flags consists of the endpoint number OR'd
515 with one or more flags indicating transfer
516 direction and such (see "Data Transfer
517 Macros" in USBCommon.h):
518  
519 7 6 5 4 3 2 1 0 - Description
520 | | | | \_____/
521 | | | | +----- Endpoint Number
522 | | | +---------- Short or zero-size pkt
523 | | +------------ Data Toggle 0/1
524 | +-------------- Force Data Toggle
525 +---------------- 1=Transmit/0=Receive
526  
527 buffer Address of the buffer to receive data.
528  
529 size Number of bytes of data to transfer.
530  
531 Return Values:
532 TRUE if the HAL was able to successfully start the
533 data transfer, FALSE if not.
534  
535 Side Effects:
536 The HAL has prepared to transfer the data on the USB.
537  
538 Ramarks:
539 The HAL will continue the data transfer, keeping track
540 of the buffer address, data remaining, and ping-pong
541 buffer details internally when USBHALHandleBusEvent is
542 called (either polled or in response to an interrupt).
543 The caller will receive notification that the transfer
544 has completed when the EVT_XFER event is passed into
545 the USBHALBusEventCallout call-out function.
546  
547 *************************************************************************/
548  
549 BOOL USBHALTransferData ( TRANSFER_FLAGS flags,
550 void *buffer,
551 unsigned int size );
552  
553  
554 /*************************************************************************
555 Function:
556 USBHALSetEpConfiguration
557  
558 Description:
559 This routine allows the caller to configure various
560 options (see "Flags for USBHALSetEpConfiguration",
561 below) and set the behavior for the given endpoint.
562  
563 Precondition:
564 USBHALInitialize has been called.
565  
566 Parameters:
567 ep_num - Number of endpoint to configur, Must be
568 (ep_num >=0) && (ep_num <= USB_DEV_HIGHEST_EP_NUMBER)
569 max_pkt_size Size of largest packet this enpoint can
570 transfer.
571  
572 flags - Configuration flags (see below)
573  
574 Return Values:
575 TRUE if successful, FALSE if not.
576  
577 Side Effects:
578 The endpoint has been configured as desired.
579  
580 Remarks:
581 The base address and size of the buffer is not set by
582 this routine. Those features of an endpoint are
583 dynamically managed by the USBHALTransferData routine.
584 An endpoint can be "de-configured" by setting its max
585 packet size to 0. When doing this, you should also
586 set all flags to 0.
587 *************************************************************************/
588  
589 BOOL USBHALSetEpConfiguration ( BYTE ep_num, UINT16 max_pkt_size, UINT16 flags );
590  
591 /* Flags for USBHALSetEpConfiguration */
592 #if defined(__18CXX)
593 #define USB_HAL_TRANSMIT 0x0400 // Enable EP for transmitting data
594 #define USB_HAL_RECEIVE 0x0200 // Enable EP for receiving data
595 #define USB_HAL_HANDSHAKE 0x1000 // Enable EP to give ACK/NACK (non isoch)
596  
597 #define USB_HAL_NO_INC 0x0010 // Use for DMA to another device FIFO
598 #define USB_HAL_HW_KEEPS 0x0020 // Cause HW to keep EP
599 #else
600 #define USB_HAL_TRANSMIT 0x0400 // Enable EP for transmitting data
601 #define USB_HAL_RECEIVE 0x0800 // Enable EP for receiving data
602 #define USB_HAL_HANDSHAKE 0x0100 // Enable EP to give ACK/NACK (non isoch)
603  
604 /* Does not work, Fix this if needed. 3/1/07 - Bud
605 #define USB_HAL_NO_INC 0x0010 // Use for DMA to another device FIFO
606 #define USB_HAL_HW_KEEPS 0x0020 // Cause HW to keep EP
607 */
608 #define USB_HAL_ALLOW_HUB 0x8000 // (host only) Enable low-spd hub support
609 #define USB_HAL_NO_RETRY 0x4000 // (host only) disable auto-retry on NACK
610 #endif
611  
612  
613 /*************************************************************************
614 Function:
615 USBHALInitialize
616  
617 Description:
618 This call performs the basic initialization of the USB
619 HAL. This routine must be called before any of the
620 other HAL interface routines are called.
621  
622 Precondition:
623 The system has been initialized.
624  
625 Paramters:
626 flags - Initialization flags
627  
628 Return Values:
629 TRUE if successful, FALSE if not.
630  
631 Side Effects:
632 The USB HAL SW stack was initialized.
633  
634 Remarks:
635 This routine can be called to reset the controller.
636  
637 *************************************************************************/
638  
639 BOOL USBHALInitialize ( unsigned long flags );
640  
641 #endif // _USB_HAL_H_
642 /*************************************************************************
643 * EOF
644 */
645  
{BLAME END}
{FOOTER START}

Powered by WebSVN v2.8.3