|
// DOM-IGNORE-BEGIN
|
|
/*******************************************************************************
|
|
Copyright 2015 Microchip Technology Inc. (www.microchip.com)
|
|
|
|
Licensed under the Apache License, Version 2.0 (the "License");
|
|
you may not use this file except in compliance with the License.
|
|
You may obtain a copy of the License at
|
|
|
|
http://www.apache.org/licenses/LICENSE-2.0
|
|
|
|
Unless required by applicable law or agreed to in writing, software
|
|
distributed under the License is distributed on an "AS IS" BASIS,
|
|
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
See the License for the specific language governing permissions and
|
|
limitations under the License.
|
|
|
|
To request to license the code under the MLA license (www.microchip.com/mla_license),
|
|
please contact mla_licensing@microchip.com
|
|
*******************************************************************************/
|
|
//DOM-IGNORE-END
|
|
|
|
#ifndef _USB_HAL_H_
|
|
#define _USB_HAL_H_
|
|
|
|
// *****************************************************************************
|
|
// *****************************************************************************
|
|
// Section: Included Files
|
|
// *****************************************************************************
|
|
// *****************************************************************************
|
|
#include <stdint.h>
|
|
|
|
#if defined(__18CXX) || defined(__XC8)
|
|
#if defined(_PIC14E)
|
|
#include "usb_hal_pic16f1.h"
|
|
#else
|
|
#include "usb_hal_pic18.h"
|
|
#endif
|
|
#elif defined(__C30__) || defined __XC16__
|
|
#if defined(__dsPIC33E__)
|
|
#include "usb_hal_dspic33e.h"
|
|
#elif defined(__PIC24E__)
|
|
#include "usb_hal_pic24e.h"
|
|
#else
|
|
#include "usb_hal_pic24f.h"
|
|
#endif
|
|
#elif defined(__XC32__)
|
|
#if defined(__PIC32MM__)
|
|
#include "usb_hal_pic32mm.h"
|
|
#else
|
|
#error "Silicon Platform not defined"
|
|
#endif
|
|
#else
|
|
#error "Silicon Platform not defined"
|
|
#endif
|
|
|
|
#ifdef __cplusplus // Provide C++ Compatability
|
|
extern "C" {
|
|
#endif
|
|
|
|
// *****************************************************************************
|
|
// *****************************************************************************
|
|
// Section: Constants
|
|
// *****************************************************************************
|
|
// *****************************************************************************
|
|
/* USBHALControlUsbResistors flags */
|
|
#define USB_HAL_PULL_UP_D_PLUS 0x80 // Pull D+ line high
|
|
#define USB_HAL_PULL_UP_D_MINUS 0x40 // Pull D- line high
|
|
#define USB_HAL_PULL_DN_D_PLUS 0x20 // Pull D+ line low
|
|
#define USB_HAL_PULL_DN_D_MINUS 0x10 // Pull D- line low
|
|
/*
|
|
The following are defined for convenience:
|
|
*/
|
|
#define USB_HAL_DEV_CONN_FULL_SPD USB_HAL_PULL_UP_D_PLUS
|
|
#define USB_HAL_DEV_CONN_LOW_SPD USB_HAL_PULL_UP_D_MINUS
|
|
#define USB_HAL_DEV_DISCONNECT 0
|
|
|
|
/* USBHALControlBusPower Commands */
|
|
#define USB_VBUS_DISCHARGE 0 // Dicharge Vbus via resistor
|
|
#define USB_VBUS_CHARGE 1 // Charge Vbus via resistor
|
|
#define USB_VBUS_POWER_ON 3 // Supply power to Vbus
|
|
#define USB_VBUS_POWER_OFF 4 // Do not supply power to Vbus
|
|
|
|
/*
|
|
USBHALGetLastError Error Bits.
|
|
*/
|
|
#define USBHAL_PID_ERR 0x00000001 // Packet ID Error
|
|
#define USBHAL_CRC5 0x00000002 // (Host) Token CRC5 check failed
|
|
#define USBHAL_HOST_EOF 0x00000002 // (Host) EOF not reached before next SOF
|
|
#define USBHAL_CRC16 0x00000004 // Data packet CRC error
|
|
#define USBHAL_DFN8 0x00000008 // Data field size not n*8 bits
|
|
#define USBHAL_BTO_ERR 0x00000010 // Bus turn-around timeout
|
|
#define USBHAL_DMA_ERR 0x00000020 // DMA error, unable to read/write memory
|
|
#define USBHAL_BTS_ERR 0x00000080 // Bit-stuffing error
|
|
#define USBHAL_XFER_ID 0x00000100 // Unable to identify transfer EP
|
|
#define USBHAL_NO_EP 0x00000200 // Invalid endpoint number
|
|
#define USBHAL_DMA_ERR2 0x00000400 // Error starting DMA transaction
|
|
|
|
/* Flags for USBHALSetEpConfiguration */
|
|
#if defined(__18CXX) || defined(__XC8)
|
|
#define USB_HAL_TRANSMIT 0x0400 // Enable EP for transmitting data
|
|
#define USB_HAL_RECEIVE 0x0200 // Enable EP for receiving data
|
|
#define USB_HAL_HANDSHAKE 0x1000 // Enable EP to give ACK/NACK (non isoch)
|
|
|
|
#define USB_HAL_NO_INC 0x0010 // Use for DMA to another device FIFO
|
|
#define USB_HAL_HW_KEEPS 0x0020 // Cause HW to keep EP
|
|
#else
|
|
#define USB_HAL_TRANSMIT 0x0400 // Enable EP for transmitting data
|
|
#define USB_HAL_RECEIVE 0x0800 // Enable EP for receiving data
|
|
#define USB_HAL_HANDSHAKE 0x0100 // Enable EP to give ACK/NACK (non isoch)
|
|
|
|
/* Does not work, Fix this if needed. 3/1/07 - Bud
|
|
#define USB_HAL_NO_INC 0x0010 // Use for DMA to another device FIFO
|
|
#define USB_HAL_HW_KEEPS 0x0020 // Cause HW to keep EP
|
|
*/
|
|
#define USB_HAL_ALLOW_HUB 0x8000 // (host only) Enable low-spd hub support
|
|
#define USB_HAL_NO_RETRY 0x4000 // (host only) disable auto-retry on NACK
|
|
#endif
|
|
// *****************************************************************************
|
|
// *****************************************************************************
|
|
// Section: Data Types
|
|
// *****************************************************************************
|
|
// *****************************************************************************
|
|
|
|
|
|
// *****************************************************************************
|
|
// *****************************************************************************
|
|
// Section: Interface Routines
|
|
// *****************************************************************************
|
|
// *****************************************************************************
|
|
|
|
/*************************************************************************
|
|
Function:
|
|
void USBHALSetBusAddress( uint8_t addr )
|
|
|
|
Description:
|
|
This routine sets the address of the system on the USB
|
|
when acting as a peripheral device.
|
|
|
|
Preconditions:
|
|
1. USBHALInitialize must have been called to
|
|
initialize the USB HAL.
|
|
2. Endpoint zero (0) must be configured as appropriate
|
|
by calls to USBHALSetEpConfiguration.
|
|
3. The system must have been enumerated on the USB (as
|
|
a device).
|
|
|
|
Parameters:
|
|
addr Desired address of this device on the USB.
|
|
|
|
Return Values:
|
|
None
|
|
|
|
Side Effect:
|
|
The bus address has been set.
|
|
|
|
Remarks:
|
|
The address is assigned by the host and is received in
|
|
a SET_ADDRESS setup request.
|
|
|
|
*************************************************************************/
|
|
/*
|
|
This routine is implemented as a macro to a lower-level level routine.
|
|
*/
|
|
|
|
#define USBHALSetBusAddress OTGCORE_SetDeviceAddr
|
|
|
|
void USBHALSetBusAddress( uint8_t addr );
|
|
|
|
|
|
/*************************************************************************
|
|
Function:
|
|
void USBHALControlUsbResistors( uint8_t flags );
|
|
|
|
Description:
|
|
This routine enables or disables the USB pull-up or
|
|
pull-down resistors as requested.
|
|
|
|
Precondition:
|
|
USBInitialize must have been called to initialize the
|
|
USB SW stack.
|
|
|
|
Parameters:
|
|
flags - This is a bit-mapped flags value indicating
|
|
which resistors to enable or disable (see below).
|
|
|
|
Return Values:
|
|
true if successful, false if not.
|
|
|
|
Side Effects:
|
|
The resistors are enabled as requested.
|
|
|
|
Remarks:
|
|
Used for USB peripheral control to connect to or
|
|
disconnect from the bus. Otherwise, used for OTG
|
|
SRP/HNP and host support.
|
|
|
|
*************************************************************************/
|
|
|
|
/*
|
|
This routine is implemented as a macro to a lower-level level routine.
|
|
*/
|
|
#if defined(__18CXX) || defined(__XC8)
|
|
void USBHALControlUsbResistors( uint8_t flags );
|
|
#else
|
|
#define USBHALControlUsbResistors OTGCORE_ControlUsbResistors
|
|
void USBHALControlUsbResistors( uint8_t flags );
|
|
#endif
|
|
|
|
/*
|
|
MCHP: Define a method to check for SE0 & a way to send a reset (SE0).
|
|
*/
|
|
|
|
|
|
/*************************************************************************
|
|
Function:
|
|
bool USBHALSessionIsValid( void )
|
|
|
|
Description:
|
|
This routine determines if there is currently a valid
|
|
USB session or not.
|
|
|
|
Precondition:
|
|
USBInitialize must have been called to initialize the
|
|
USB SW stack.
|
|
|
|
Parameters:
|
|
None
|
|
|
|
Return Values:
|
|
true if the session is currently valid, false if not.
|
|
|
|
Remarks:
|
|
Only used for host and OTG support.
|
|
|
|
*************************************************************************/
|
|
|
|
bool USBHALSessionIsValid( void );
|
|
|
|
|
|
/*************************************************************************
|
|
Function:
|
|
USBHALControlBusPower
|
|
|
|
Description:
|
|
This routine provides a bitmap of the most recent
|
|
error conditions to occur.
|
|
|
|
Precondition:
|
|
USBInitialize must have been called to initialize the
|
|
USB SW stack.
|
|
|
|
Parameters:
|
|
cmd - Identifies desired command (see below).
|
|
|
|
Return Values:
|
|
true if successful, false if not.
|
|
|
|
Remarks:
|
|
Only used for host and OTG support.
|
|
|
|
*************************************************************************/
|
|
|
|
bool USBHALControlBusPower( uint8_t cmd );
|
|
|
|
/*************************************************************************
|
|
Function:
|
|
unsigned long USBHALGetLastError( void )
|
|
|
|
Description:
|
|
This routine provides a bitmap of the most recent
|
|
error conditions to occur.
|
|
|
|
Precondition:
|
|
USBInitialize must have been called to initialize the
|
|
USB SW stack.
|
|
|
|
Parameters:
|
|
None
|
|
|
|
Return Values:
|
|
Bitmap indicating the most recent error condition(s).
|
|
|
|
Side Effect:
|
|
Error record is cleared.
|
|
|
|
Remarks:
|
|
Although record of the error state is cleared, nothing
|
|
is done to fix the condition or recover from the
|
|
error. The client must take appropriate steps.
|
|
|
|
*************************************************************************/
|
|
|
|
unsigned long USBHALGetLastError( void );
|
|
|
|
|
|
|
|
|
|
/*************************************************************************
|
|
Function:
|
|
void USBHALHandleBusEvent ( void )
|
|
|
|
Description:
|
|
This routine checks the USB for any events that may
|
|
have occurred and handles them appropriately. It may
|
|
be called directly to poll the USB and handle events
|
|
or it may be called in response to an interrupt.
|
|
|
|
Precondition:
|
|
USBInitialize must have been called to initialize the
|
|
USB SW stack.
|
|
|
|
Parameters:
|
|
None
|
|
|
|
Return Values:
|
|
None
|
|
|
|
Side Effects:
|
|
Depend on the event that may have occurred.
|
|
|
|
Remarks:
|
|
None
|
|
|
|
*************************************************************************/
|
|
|
|
void USBHALHandleBusEvent ( void );
|
|
|
|
|
|
/*************************************************************************
|
|
Function:
|
|
bool USBHALStallPipe( TRANSFER_FLAGS pipe )
|
|
|
|
Description:
|
|
This routine stalls the given endpoint.
|
|
|
|
Preconditions:
|
|
USBHALInitialize must have been called to initialize
|
|
the USB HAL.
|
|
|
|
Parameters:
|
|
pipe - Uses the TRANSFER_FLAGS (see USBCommon.h) format to
|
|
identify the endpoint and direction making up the
|
|
pipe to stall.
|
|
|
|
Note: Only ep_num and direction fields are required.
|
|
|
|
Return Values:
|
|
true if able to stall endpoint, false if not.
|
|
|
|
Side Effects:
|
|
The endpoint will stall if additional data transfer is
|
|
attempted.
|
|
Given endpoint has been stalled.
|
|
|
|
Remarks:
|
|
Starting another data transfer automatically
|
|
"un-stalls" the endpoint.
|
|
|
|
*************************************************************************/
|
|
/*
|
|
Note: This function is implemented as a macro, calling directly into
|
|
an internal HAL routine.
|
|
*/
|
|
|
|
#define USBHALStallPipe OTGCORE_StallPipe
|
|
|
|
bool USBHALStallPipe( TRANSFER_FLAGS pipe );
|
|
|
|
|
|
/******************************************************************************
|
|
Function:
|
|
bool USBHALUnstallPipe( TRANSFER_FLAGS pipe )
|
|
|
|
Description:
|
|
This routine clears the stall condition for the given pipe.
|
|
|
|
PreCondition:
|
|
Assumes OTGCORE_DeviceEnable has been called and
|
|
OTGCORE_StallPipe has been called on the given pipe.
|
|
|
|
Parameters:
|
|
pipe - Uses the TRANSFER_FLAGS (see USBCommon.h) format to
|
|
identify the endpoint and direction making up the
|
|
pipe to un-stall.
|
|
|
|
Return Values:
|
|
true if able to stall the pipe, false if not.
|
|
|
|
Side Effects:
|
|
The BSTALL and UOWN bits (and all other control bits) in
|
|
the BDT for the given pipe will be cleared.
|
|
|
|
Remarks:
|
|
None
|
|
|
|
*****************************************************************************/
|
|
/*
|
|
Note: This function is implemented as a macro, calling directly into
|
|
an internal HAL routine.
|
|
*/
|
|
|
|
#define USBHALUnstallPipe OTGCORE_UnstallPipe
|
|
|
|
bool USBHALUnstallPipe( TRANSFER_FLAGS pipe );
|
|
|
|
|
|
/**************************************************************************
|
|
Function:
|
|
USBHALGetStalledEndpoints
|
|
|
|
Description:
|
|
This function returns a 16-bit bit-mapped value with a
|
|
bit set in the position of any endpoint that is stalled
|
|
(i.e. if endpoint 0 is stalled then bit 0 is set, if
|
|
endpoint 1 is stalled then bit 1 is set, etc.).
|
|
|
|
Preconditions:
|
|
USBHALInitialize must have been called to initialize
|
|
the USB HAL.
|
|
|
|
Parameters:
|
|
None
|
|
|
|
Return Values:
|
|
Bitmap of the currently stalled endpoints (see overview).
|
|
|
|
Remarks:
|
|
None
|
|
*************************************************************************/
|
|
|
|
/*
|
|
Note: This function is implemented as a macro, calling directly into
|
|
a HAL routine.
|
|
*/
|
|
|
|
#define USBHALGetStalledEndpoints OTGCORE_GetStalledEndpoints
|
|
|
|
uint16_t USBHALGetStalledEndpoints ( void );
|
|
|
|
|
|
/******************************************************************************
|
|
Function:
|
|
bool USBHALFlushPipe( TRANSFER_FLAGS pipe )
|
|
|
|
Description:
|
|
This routine clears any pending transfers on the given
|
|
pipe.
|
|
|
|
Preconditions:
|
|
USBHALInitialize must have been called to initialize the
|
|
USB HAL.
|
|
|
|
The caller must ensure that there is no possible way for
|
|
hardware to be currently accessing the pipe (see notes).
|
|
|
|
Parameters:
|
|
pipe - Uses the TRANSFER_FLAGS (see USBCommon.h) format to
|
|
identify the endpoint and direction making up the
|
|
pipe to flush.
|
|
|
|
Return Values:
|
|
true if successful, false if not.
|
|
|
|
Side Effects:
|
|
Transfer data for this pipe has been zeroed out.
|
|
|
|
Remarks:
|
|
This routine ignores the normal HW protocol for ownership
|
|
of the pipe data and flushes the pipe, even if it is in
|
|
process. Thus, the caller must ensure that data transfer
|
|
cannot be in process. This situation occurs when a
|
|
transfer has been terminated early by the host.
|
|
*****************************************************************************/
|
|
|
|
bool USBHALFlushPipe( TRANSFER_FLAGS pipe );
|
|
|
|
|
|
/**************************************************************************
|
|
Function:
|
|
USBHALTransferData
|
|
|
|
Description:
|
|
This routine prepares to transfer data on the USB.
|
|
If the system is in device mode, the actual transfer
|
|
will not occur until the host performs an OUT request
|
|
to the given endpoint. If the system is in host mode,
|
|
the transfer will not start until the token has been
|
|
sent on the bus.
|
|
|
|
Preconditions:
|
|
1. USBHALInitialize must have been called to
|
|
initialize the USB HAL.
|
|
2. The endpoint through which the data will be
|
|
transferred must be configured as appropriate by a
|
|
call to USBHALSetEpConfiguration.
|
|
3. The bus must have been enumerated (either as a host
|
|
or device). Except for EP0 transfers.
|
|
|
|
Parameters:
|
|
flags - Flags consists of the endpoint number OR'd
|
|
with one or more flags indicating transfer
|
|
direction and such (see "Data Transfer
|
|
Macros" in USBCommon.h):
|
|
|
|
7 6 5 4 3 2 1 0 - Description
|
|
| | | | \_____/
|
|
| | | | +----- Endpoint Number
|
|
| | | +---------- Short or zero-size packet
|
|
| | +------------ Data Toggle 0/1
|
|
| +-------------- Force Data Toggle
|
|
+---------------- 1=Transmit/0=Receive
|
|
|
|
buffer Address of the buffer to receive data.
|
|
|
|
size Number of uint8_ts of data to transfer.
|
|
|
|
Return Values:
|
|
true if the HAL was able to successfully start the
|
|
data transfer, false if not.
|
|
|
|
Side Effects:
|
|
The HAL has prepared to transfer the data on the USB.
|
|
|
|
Remarks:
|
|
The HAL will continue the data transfer, keeping track
|
|
of the buffer address, data remaining, and ping-pong
|
|
buffer details internally when USBHALHandleBusEvent is
|
|
called (either polled or in response to an interrupt).
|
|
The caller will receive notification that the transfer
|
|
has completed when the EVT_XFER event is passed into
|
|
the USBHALBusEventCallout call-out function.
|
|
|
|
*************************************************************************/
|
|
|
|
bool USBHALTransferData ( TRANSFER_FLAGS flags,
|
|
void *buffer,
|
|
unsigned int size );
|
|
|
|
|
|
/*************************************************************************
|
|
Function:
|
|
USBHALSetEpConfiguration
|
|
|
|
Description:
|
|
This routine allows the caller to configure various
|
|
options (see "Flags for USBHALSetEpConfiguration",
|
|
below) and set the behavior for the given endpoint.
|
|
|
|
Precondition:
|
|
USBHALInitialize has been called.
|
|
|
|
Parameters:
|
|
ep_num - Number of endpoint to configure, Must be
|
|
(ep_num >=0) && (ep_num <= USB_DEV_HIGHEST_EP_NUMBER)
|
|
max_pkt_size Size of largest packet this enpoint can
|
|
transfer.
|
|
|
|
flags - Configuration flags (see below)
|
|
|
|
Return Values:
|
|
true if successful, false if not.
|
|
|
|
Side Effects:
|
|
The endpoint has been configured as desired.
|
|
|
|
Remarks:
|
|
The base address and size of the buffer is not set by
|
|
this routine. Those features of an endpoint are
|
|
dynamically managed by the USBHALTransferData routine.
|
|
An endpoint can be "de-configured" by setting its max
|
|
packet size to 0. When doing this, you should also
|
|
set all flags to 0.
|
|
*************************************************************************/
|
|
|
|
bool USBHALSetEpConfiguration ( uint8_t ep_num, uint16_t max_pkt_size, uint16_t flags );
|
|
|
|
/*************************************************************************
|
|
Function:
|
|
USBHALInitialize
|
|
|
|
Description:
|
|
This call performs the basic initialization of the USB
|
|
HAL. This routine must be called before any of the
|
|
other HAL interface routines are called.
|
|
|
|
Precondition:
|
|
The system has been initialized.
|
|
|
|
Parameters:
|
|
flags - Initialization flags
|
|
|
|
Return Values:
|
|
true if successful, false if not.
|
|
|
|
Side Effects:
|
|
The USB HAL SW stack was initialized.
|
|
|
|
Remarks:
|
|
This routine can be called to reset the controller.
|
|
|
|
*************************************************************************/
|
|
|
|
bool USBHALInitialize ( unsigned long flags );
|
|
|
|
|
|
#ifdef __cplusplus // Provide C++ Compatibility
|
|
}
|
|
#endif
|
|
|
|
#endif // _USB_HAL_H_
|
|
/*************************************************************************
|
|
* EOF
|
|
*/
|
|
|