updated for the v2.13 release

Author: davidflowers

doc/help_mla_usb.jar

@@ -38,8 +38,10 @@ please contact [email protected]
     not defined by the USB specification.
 *******************************************************************************/
 
+//DOM-IGNORE-BEGIN
 #ifndef _USB_COMMON_H_
 #define _USB_COMMON_H_
+//DOM-IGNORE-END
 
 #include <limits.h>
 #include <stdbool.h>
@@ -322,6 +324,19 @@ typedef enum
     // per call to these functions.
     EVENT_1MS,
 
+    // In device mode, this event is thrown when we receive a Set Interface request from
+    // the host.  The stack will automatically handle the interface switch, but the app
+    // may need to know about the interface switch for performing tasks such as powering
+    // up/down audio hardware.
+    EVENT_ALT_INTERFACE,
+
+    // If the application layer must do things to the device before the device is 
+    // configured, they should be done at this point.  The application layer should
+    // return true to hold the USB state machine at this point, while any USB or other
+    // processing continues.  When the USB state machine can safely proceed, the application
+    // layer should return FALSE.
+    EVENT_HOLD_BEFORE_CONFIGURATION,
+
     // Class-defined event offsets start here:
     EVENT_GENERIC_BASE  = 400,      // Offset for Generic class events
 
@@ -350,7 +365,7 @@ typedef enum
 // *****************************************************************************
 /* EVENT_TRANSFER Data
 
-This data structure is passed to the appropriate layer
+This data structure is passed to the appropriate layer's
 USB_EVENT_HANDLER when an EVT_XFER event has occurred, indicating
 that a transfer has completed on the USB.  It provides the endpoint,
 direction, and actual size of the transfer.
@@ -368,7 +383,7 @@ typedef struct _transfer_event_data
 // *****************************************************************************
 /* EVENT_VBUS_REQUEST_POWER and EVENT_VBUS_RELEASE_POWER Data
 
-This data structure is passed to the appropriate layer
+This data structure is passed to the appropriate layer's
 USB_EVENT_HANDLER when an EVENT_VBUS_REQUEST_POWER or EVENT_VBUS_RELEASE_POWER
 event has occurred, indicating that a change in Vbus power is being requested.
 */

doc/help_mla_usb.pdf

@@ -1362,7 +1362,11 @@ void USBSoftDetach(void);
   *************************************************************************/
 bool USBHandleBusy(USB_HANDLE handle);
 /*DOM-IGNORE-BEGIN*/
-#define USBHandleBusy(handle) (handle==0?0:((volatile BDT_ENTRY*)handle)->STAT.UOWN)
+#if defined(__XC8__)
+    #define USBHandleBusy(handle) ((handle != 0x0000) && ((*(volatile uint8_t*)handle & _USIE) != 0x00))
+#else
+    #define USBHandleBusy(handle) (handle==0?0:((volatile BDT_ENTRY*)handle)->STAT.UOWN)
+#endif
 /*DOM-IGNORE-END*/
 
 /********************************************************************

inc/usb_common.h

@@ -37,7 +37,7 @@ please contact [email protected]
 /****** Constant definitions *************************************************/
 /*****************************************************************************/
 #define DEVICE_SPECIFIC_IEC_REGISTER_COUNT  9   //Number of IECx registers implemented in the microcontroller (varies from device to device, make sure this is set correctly for the intended CPU)
-
+#define USB_HAL_VBUSTristate()                  //No GPIO driver on VBUS on these devices.
 
 #if(USB_PING_PONG_MODE != USB_PING_PONG__FULL_PING_PONG)
     #error "Unsupported ping pong mode for this device"

inc/usb_device.h

@@ -42,7 +42,9 @@ please contact [email protected]
 // Section: Constants
 // *****************************************************************************
 // *****************************************************************************
+#define USB_HAL_VBUSTristate()                 //No dedicated VBUS pin on these devices.
 
+        
 //----- USBEnableEndpoint() input definitions ----------------------------------
 #define USB_HANDSHAKE_ENABLED   0x10
 #define USB_HANDSHAKE_DISABLED  0x00

inc/usb_hal_dspic33e.h

@@ -59,7 +59,8 @@ please contact [email protected]
 // Section: Constants
 // *****************************************************************************
 // *****************************************************************************
-
+#define USB_HAL_VBUSTristate()                  //No dedicated VBUS pin on these devices.        
+        
 //----- USBEnableEndpoint() input definitions ----------------------------------
 #define USB_HANDSHAKE_ENABLED   0x10
 #define USB_HANDSHAKE_DISABLED  0x00

inc/usb_hal_pic16f1.h

@@ -48,23 +48,38 @@ please contact [email protected]
 //IEC0-IEC7 on PIC24FJ128GB204 Family devices
 //IEC0-IEC7 on PIC24FJ256GB412 Family devices
 #if defined(__PIC24FJ64GB004__) || defined(__PIC24FJ32GB004__) || defined(__PIC24FJ32GB004__) || defined(__PIC24FJ32GB002__)    \
-    || defined(__PIC24FJ256GB110__) || defined(__PIC24FJ192GB110__) || defined(__PIC24FJ128GB110__) || defined(__PIC24FJ64GB110__) || defined(__PIC24FJ256GB108__) || defined(__PIC24FJ192GB108__) || defined(__PIC24FJ128GB108__) || defined(__PIC24FJ64GB108__)  || defined(__PIC24FJ256GB106__) || defined(__PIC24FJ192GB106__) || defined(__PIC24FJ128GB106__) || defined(__PIC24FJ64GB106__)   \
-    || defined(__PIC24FJ256GB210__) || defined(__PIC24FJ128GB210__)  || defined(__PIC24FJ256GB206__) || defined(__PIC24FJ128GB206__)
+    || defined(__PIC24FJ256GB110__) || defined(__PIC24FJ192GB110__) || defined(__PIC24FJ128GB110__) || defined(__PIC24FJ64GB110__) || defined(__PIC24FJ256GB108__) || defined(__PIC24FJ192GB108__) || defined(__PIC24FJ128GB108__) || defined(__PIC24FJ64GB108__)  || defined(__PIC24FJ256GB106__) || defined(__PIC24FJ192GB106__) || defined(__PIC24FJ128GB106__) || defined(__PIC24FJ64GB106__) 
 
     #define DEVICE_SPECIFIC_IEC_REGISTER_COUNT  6   //Number of IECx registers implemented in the microcontroller (varies from device to device, make sure this is set correctly for the intended CPU)
+    #define USB_HAL_VBUSTristate()                  //No GPIO driver on VBUS on these devices.
+
+#elif defined(__PIC24FJ256GB210__) || defined(__PIC24FJ128GB210__)  || defined(__PIC24FJ256GB206__) || defined(__PIC24FJ128GB206__)
+
+    #define DEVICE_SPECIFIC_IEC_REGISTER_COUNT  6   //Number of IECx registers implemented in the microcontroller (varies from device to device, make sure this is set correctly for the intended CPU)
+    #define USB_HAL_VBUSTristate()    {TRISFbits.TRISF7 = 1;}
 
 #elif defined(__PIC24FJ256DA210__) || defined(__PIC24FJ128DA210__) || defined(__PIC24FJ256DA206__) || defined(__PIC24FJ128DA206__) || defined(__PIC24FJ256DA110__) || defined(__PIC24FJ128DA110__) || defined(__PIC24FJ256DA106__) || defined(__PIC24FJ128DA106__)
 
     #define DEVICE_SPECIFIC_IEC_REGISTER_COUNT  7   //Number of IECx registers implemented in the microcontroller (varies from device to device, make sure this is set correctly for the intended CPU)
+    #define USB_HAL_VBUSTristate()    {TRISFbits.TRISF7 = 1;}
 
-#elif defined(__PIC24FJ128GC010__) || defined(__PIC24FJ64GC010__) || defined(__PIC24FJ128GC006__) || defined(__PIC24FJ64GC006__)    \
-    || defined(__PIC24FJ128GB204__) || defined(__PIC24FJ64GB204) || defined(__PIC24FJ128GB202__) || defined(__PIC24FJ64GB202)       
+#elif defined(__PIC24FJ128GB204__) || defined(__PIC24FJ64GB204__) || defined(__PIC24FJ128GB202__) || defined(__PIC24FJ64GB202__)
 
     #define DEVICE_SPECIFIC_IEC_REGISTER_COUNT  8   //Number of IECx registers implemented in the microcontroller (varies from device to device, make sure this is set correctly for the intended CPU)
+    #define USB_HAL_VBUSTristate()    {TRISBbits.TRISB6 = 1;}
 
+#elif defined(__PIC24FJ128GC010__) || defined(__PIC24FJ64GC010__) || defined(__PIC24FJ128GC006__) || defined(__PIC24FJ64GC006__)    \
+    || defined(__PIC24FJ128GB204__) || defined(__PIC24FJ64GB204__) || defined(__PIC24FJ128GB202__) || defined(__PIC24FJ64GB202__) \
+    || defined(__PIC24FJ256GB410__) || defined(__PIC24FJ256GB412__) || defined(__PIC24FJ256GB406__) \
+    || defined(__PIC24FJ128GB410__) || defined(__PIC24FJ128GB412__) || defined(__PIC24FJ128GB406__) \
+    || defined(__PIC24FJ64GB410__) || defined(__PIC24FJ64GB412__) || defined(__PIC24FJ64GB406__)
+    #define DEVICE_SPECIFIC_IEC_REGISTER_COUNT  8   //Number of IECx registers implemented in the microcontroller (varies from device to device, make sure this is set correctly for the intended CPU)
+    #define USB_HAL_VBUSTristate()    {TRISFbits.TRISF7 = 1;}
 #else
     #error "Unknown processor type selected.  Refer to device datasheet and update the definition for DEVICE_SPECIFIC_IEC_REGISTER_COUNT."
-    //#define DEVICE_SPECIFIC_IEC_REGISTER_COUNT  8    // <--- Update this number with the real number for your device and uncomment (and delete the above #error).
+    //#define DEVICE_SPECIFIC_IEC_REGISTER_COUNT  8              // <--- Update this number with the real number for your device and uncomment (and delete the above #error).
+    //#define USB_HAL_VBUSTristate()    {TRISxbits.TRISxx = 1;}  // <-- replace the "x" characters with the correct values for the VBUS GPIO pin (if the microcontroller selected has GPIO functionality on VBUS)
+
 #endif
 
 

inc/usb_hal_pic18.h

@@ -36,7 +36,7 @@ please contact [email protected]
 /****** Constant definitions *************************************************/
 /*****************************************************************************/
 #define DEVICE_SPECIFIC_IEC_REGISTER_COUNT  9   //Number of IECx registers implemented in the microcontroller (varies from device to device, make sure this is set correctly for the intended CPU)
-
+#define USB_HAL_VBUSTristate()                  //No GPIO driver on VBUS on these devices.
 
 #if(USB_PING_PONG_MODE != USB_PING_PONG__FULL_PING_PONG)
     #error "Unsupported ping pong mode for this device"

inc/usb_hal_pic24.h

@@ -48,23 +48,38 @@ please contact [email protected]
 //IEC0-IEC7 on PIC24FJ128GB204 Family devices
 //IEC0-IEC7 on PIC24FJ256GB412 Family devices
 #if defined(__PIC24FJ64GB004__) || defined(__PIC24FJ32GB004__) || defined(__PIC24FJ32GB004__) || defined(__PIC24FJ32GB002__)    \
-    || defined(__PIC24FJ256GB110__) || defined(__PIC24FJ192GB110__) || defined(__PIC24FJ128GB110__) || defined(__PIC24FJ64GB110__) || defined(__PIC24FJ256GB108__) || defined(__PIC24FJ192GB108__) || defined(__PIC24FJ128GB108__) || defined(__PIC24FJ64GB108__)  || defined(__PIC24FJ256GB106__) || defined(__PIC24FJ192GB106__) || defined(__PIC24FJ128GB106__) || defined(__PIC24FJ64GB106__)   \
-    || defined(__PIC24FJ256GB210__) || defined(__PIC24FJ128GB210__)  || defined(__PIC24FJ256GB206__) || defined(__PIC24FJ128GB206__)
+    || defined(__PIC24FJ256GB110__) || defined(__PIC24FJ192GB110__) || defined(__PIC24FJ128GB110__) || defined(__PIC24FJ64GB110__) || defined(__PIC24FJ256GB108__) || defined(__PIC24FJ192GB108__) || defined(__PIC24FJ128GB108__) || defined(__PIC24FJ64GB108__)  || defined(__PIC24FJ256GB106__) || defined(__PIC24FJ192GB106__) || defined(__PIC24FJ128GB106__) || defined(__PIC24FJ64GB106__) 
 
     #define DEVICE_SPECIFIC_IEC_REGISTER_COUNT  6   //Number of IECx registers implemented in the microcontroller (varies from device to device, make sure this is set correctly for the intended CPU)
+    #define USB_HAL_VBUSTristate()                  //No GPIO driver on VBUS on these devices.
+
+#elif defined(__PIC24FJ256GB210__) || defined(__PIC24FJ128GB210__)  || defined(__PIC24FJ256GB206__) || defined(__PIC24FJ128GB206__)
+
+    #define DEVICE_SPECIFIC_IEC_REGISTER_COUNT  6   //Number of IECx registers implemented in the microcontroller (varies from device to device, make sure this is set correctly for the intended CPU)
+    #define USB_HAL_VBUSTristate()    {TRISFbits.TRISF7 = 1;}
 
 #elif defined(__PIC24FJ256DA210__) || defined(__PIC24FJ128DA210__) || defined(__PIC24FJ256DA206__) || defined(__PIC24FJ128DA206__) || defined(__PIC24FJ256DA110__) || defined(__PIC24FJ128DA110__) || defined(__PIC24FJ256DA106__) || defined(__PIC24FJ128DA106__)
 
     #define DEVICE_SPECIFIC_IEC_REGISTER_COUNT  7   //Number of IECx registers implemented in the microcontroller (varies from device to device, make sure this is set correctly for the intended CPU)
+    #define USB_HAL_VBUSTristate()    {TRISFbits.TRISF7 = 1;}
 
-#elif defined(__PIC24FJ128GC010__) || defined(__PIC24FJ64GC010__) || defined(__PIC24FJ128GC006__) || defined(__PIC24FJ64GC006__)    \
-    || defined(__PIC24FJ128GB204__) || defined(__PIC24FJ64GB204) || defined(__PIC24FJ128GB202__) || defined(__PIC24FJ64GB202)       
+#elif defined(__PIC24FJ128GB204__) || defined(__PIC24FJ64GB204__) || defined(__PIC24FJ128GB202__) || defined(__PIC24FJ64GB202__)
 
     #define DEVICE_SPECIFIC_IEC_REGISTER_COUNT  8   //Number of IECx registers implemented in the microcontroller (varies from device to device, make sure this is set correctly for the intended CPU)
+    #define USB_HAL_VBUSTristate()    {TRISBbits.TRISB6 = 1;}
 
+#elif defined(__PIC24FJ128GC010__) || defined(__PIC24FJ64GC010__) || defined(__PIC24FJ128GC006__) || defined(__PIC24FJ64GC006__)    \
+    || defined(__PIC24FJ128GB204__) || defined(__PIC24FJ64GB204__) || defined(__PIC24FJ128GB202__) || defined(__PIC24FJ64GB202__) \
+    || defined(__PIC24FJ256GB410__) || defined(__PIC24FJ256GB412__) || defined(__PIC24FJ256GB406__) \
+    || defined(__PIC24FJ128GB410__) || defined(__PIC24FJ128GB412__) || defined(__PIC24FJ128GB406__) \
+    || defined(__PIC24FJ64GB410__) || defined(__PIC24FJ64GB412__) || defined(__PIC24FJ64GB406__)
+    #define DEVICE_SPECIFIC_IEC_REGISTER_COUNT  8   //Number of IECx registers implemented in the microcontroller (varies from device to device, make sure this is set correctly for the intended CPU)
+    #define USB_HAL_VBUSTristate()    {TRISFbits.TRISF7 = 1;}
 #else
     #error "Unknown processor type selected.  Refer to device datasheet and update the definition for DEVICE_SPECIFIC_IEC_REGISTER_COUNT."
-    //#define DEVICE_SPECIFIC_IEC_REGISTER_COUNT  8    // <--- Update this number with the real number for your device and uncomment (and delete the above #error).
+    //#define DEVICE_SPECIFIC_IEC_REGISTER_COUNT  8              // <--- Update this number with the real number for your device and uncomment (and delete the above #error).
+    //#define USB_HAL_VBUSTristate()    {TRISxbits.TRISxx = 1;}  // <-- replace the "x" characters with the correct values for the VBUS GPIO pin (if the microcontroller selected has GPIO functionality on VBUS)
+
 #endif
 
 
@@ -83,7 +98,7 @@ please contact [email protected]
 #endif
 
 
-//----- USBEnableEndpoint() input defintions ----------------------------------
+//----- USBEnableEndpoint() input definitions ----------------------------------
 #define USB_HANDSHAKE_ENABLED           0x01
 #define USB_HANDSHAKE_DISABLED          0x00
 
@@ -98,7 +113,7 @@ please contact [email protected]
 
 #define USB_STALL_ENDPOINT              0x02
 
-//----- usb_config.h input defintions -----------------------------------------
+//----- usb_config.h input definitions -----------------------------------------
 #define USB_PULLUP_ENABLE               0x00
 //#define USB_PULLUP_DISABLE            0x00
 
@@ -166,7 +181,7 @@ please contact [email protected]
 #define USBRESUMEIFReg                  U1IR
 #define USBRESUMEIFBitNum               5
 
-//----- Event call back defintions --------------------------------------------
+//----- Event call back definitions --------------------------------------------
 #if defined(USB_DISABLE_SOF_HANDLER)
     #define USB_SOF_INTERRUPT           0x00
 #else
@@ -620,12 +635,12 @@ bool USBRemoteWakeupAssertBlocking(void);
     that the read could not be performed (ex: if the comparators are currently off).
 
     Specify true, if you want this function to perform a forceful read operation.
-    In this case, this function will turn on the USB module and/or un-suspend it if
+    In this case, this function will turn on the USB module and/or unsuspend it if
     needed, in order to read the actual value.  The function will always return 0 or 1
     in this case.  However, the function may block for as much time as required to
     ensure that any necessary analog startup/settling/propagation times have
     elapsed, so as to get an accurate reading.  If invasive reads are allowed, and
-    this function turns on the USB module or un-suspends it, the module will remain
+    this function turns on the USB module or unsuspends it, the module will remain
     on and unsuspended subsequent to returning from this function.
     It is the caller's responsibility to turn the USB module off if
     desired/appropriate for the application (ex: because the returned value was