The USB library host controller driver provides an interface to the host controller’s hardware register interface. This is the lowest level of the driver interface and it interacts directly with the DriverLib USB APIs. The host controller driver provides all of the functionality necessary to provide enumer- ation of devices regardless of the type of device that is connected. This portion of the enumeration code only enumerates the device and allows the higher level drivers to actually handle normal de- vice operations. To allow the application to conserve code and data memory, the host controller driver provides a method to allow applications to only include the host class drivers that are needed for each type of USB device. This allows an application to handle multiple classes of devices but only include the USB library code that the application needs to communicate with the devices that the application supports. While the host controller driver handles the enumeration of devices it re- lies on USB pipes, that are allocated by the higher level class drivers, as the direct communications method with a devices end points.
3.2.1
Enumeration
The USB host controller driver handles all of the details necessary to discover and enumerate any USB device. The USB host controller driver only performs enumeration and relies on the host class drivers to perform any other communications with USB devices including the allocation of the end- points for the device. Most of the code used to enumerate devices is run in interrupt context and is contained in the enumeration handler. In order to complete the enumeration process, the host con- troller driver also requires that the application periodically call theUSBHCDMain()function. When a host class driver or an application needs access to endpoint 0 of a device, it uses theUSBHCD- ControlTransfer()interface to send data to the device or receive data from the device. During the
enumeration process the host controller driver searches a list of host class drivers provided by the application in theUSBHCDRegisterDrivers()call. The details of this structure are covered in the host class drivers section of this document. If the host controller driver finds a host class driver that matches the class of the enumerated device, it calls the open function for that host class driver. If no host class driver is found the host controller driver ignores the device and there is no notification to the application. The host controller driver or the host class driver can provide callbacks up through the USB library to inform the application of enumeration events. The host class drivers are respon- sible for configuring the USB pipes based on the type of device that is discovered. The application is notified of events in two ways: one is from the host class driver for the connected device and the other is from a non-device specific event driver. The class specific events come from the host class driver, while the generic connection, power and other non-device class specific events come from the host event driver if it is included in the application. The section "USB Events Driver" covers the host events driver, the valid events and how to include the host events driver in an application.
3.2.2
USB Host Configurable Features
Like the USB device mode the USB host mode provides the application with the ability to set certain run-time global features of the USB library. The application uses theUSBHCDFeatureSet()to set the configurable features of the USB host library. These features include USB clocking, enabling an external phy, and setting various power settings for the USB host library.
3.2.2.1
USB Host PLL Feature
One of the most important features used by applications informs the USB library of the of how the application has configured the main PLL. On TM4C129 class devices the USB clock is derived from the main PLL and the USB library sets up its own clock based on the value provided by the application. TheUSBLIB_FEATURE_USBPLL is only used on TM4C129 class devices and defaults to 480 MHz. If the PLL is operating at a value other than 480 MHz then the application is required to call theUSBHCDFeatureSet()function with theUSBLIB_FEATURE_USBPLLfeature to provide the PLL frequency to the USB library. The following is an example of setting the PLL frequency to a value other than the default 480 MHz.
Example:Using a 320 MHz PLL setting
uint32_t ui32PLLFrequency;
ui32PLLFrequency = 320000000;
//
// Inform the USB library that the system is running using a 320 MHz PLL. //
USBHCDFeatureSet(0, USBLIB_FEATURE_USBPLL, &ui32PLLFrequency);
3.2.2.2
USB Host System Clock Feature
The USB library needs to know the actual operating frequency of the system clock in order to provide some rough delays that the USB library uses for some of the USB signaling. The application provides the system clock frequency using theUSBLIB_FEATURE_CPUCLKfeature setting. The default for this value is 120 MHz for TM4C129 class devices and 80 MHz for TM4C123 class devices. If the processor is operating at something other than one of these frequencies then the
application must call the USBHCDFeatureSet() function with the USBLIB_FEATURE_CPUCLK
feature to provide the actual system clock frequency.
Example:Using 60 MHz system clock
uint32_t ui32SysClock;
ui32SysClock = 60000000;
//
// Inform the USB library that the system is running at 60 MHz. //
USBHCDFeatureSet(0, USBLIB_FEATURE_CPUCLK, &ui32SysClock);
3.2.2.3
USB Host ULPI Feature
The TM4C129x class devices support using an external ULPI USB phy to allow the host to communicate with high speed devices. This feature is enabled by setting the US- BLIB_FEATURE_USBULPIoption combined with the desired speed. From the applications per- spective this has no affect to normal USB operation other than the necessity to properly enable the USB external phy pins. The following are the possible configuration options when using ULPI:
USBLIB_FEATURE_ULPI_NONE- Disable ULPI and use the internal phy (default).
USBLIB_FEATURE_ULPI_HS- Use an externally connected ULPI phy at high-speed.
USBLIB_FEATURE_ULPI_FS- Use an externally connected ULPI phy at full-speed.
The following is an example of configuring the USB library to use and external phy operating in high speed mode.
Example:Enable high speed external ULPI phy
uint32_t ui32ULPI;
ui32ULPI = USBLIB_FEATURE_ULPI_HS;
//
// Enable the use of an external USB ULPI connected phy. //
USBHCDFeatureSet(0, USBLIB_FEATURE_USBULPI, &ui32ULPI);
3.2.2.4
USB HOST LPM Feature
The TM4C129 class devices added the ability to use the USB LPM feature. This feature is not enabled by default and therefore must be enabled by the application if it wishes to use any LPM features. Once LPM is enabled, the application can use the USB library to issue an LPM suspend transaction to a device by calling theUSBHCDLPMSleep()function and wake devices using the
USBHCDLPMResume()function. There are only two options for LPM which allow the feature to be enabled or disabled with the following values:
USBLIB_FEATURE_LPM_DIS- Disable LPM transactions (default).
USBLIB_FEATURE_LPM_EN- Enable sending and receiving LPM transactions.
Example:Enable LPM transactions.
uint32_t ui32LPMFeature;
ui32LPMFeature = USBLIB_FEATURE_LPM_EN;
//
// Enable LPM transactions. //
USBHCDFeatureSet(0, USBLIB_FEATURE_LPM, &ui32LPMFeature);
3.2.3
USB Pipes
The host controller driver layer uses interfaces called USB pipes as the primary method of commu- nications with USB devices. These USB pipes can be dynamically allocated or statically allocated by the USB class drivers during enumeration. The USB pipes are usually only used within the USB library or by host class drivers and are not usually directly accessed by applications. The USB pipes are allocated and freed by calling theUSBHCDPipeAlloc()andUSBHCDPipeFree()functions and are initially configured by calling theUSBHCDPipeConfig(). TheUSBHCDPipeAlloc()andUS- BHCDPipeConfig() functions are used during USB device enumeration to allocate USB pipes to specific endpoints of the USB device. On disconnect, the USBHCDPipeFree()function is called to free up the USB pipe for use by a new USB device. While in use, the USB pipes can provide status and perform read and write operations. CallingUSBHCDPipeStatus()allows a host class driver to check the status of a pipe. However most access to the USB pipes occurs throughUSB- HCDPipeWrite()andUSBHCDPipeRead()and the callback function provided when the USB pipe was allocated. These are used to read or write to endpoints on USB devices on endpoints other than the control endpoint on endpoint 0. Since endpoint 0 is shared with all devices, the host con- troller interface does not use USB pipes for communications over endpoint 0 and instead uses the
USBHCDControlTransfer()function.
3.2.4
Control Transactions
All USB control transactions are handled through the USBHCDControlTransfer() function. This function is primarily used inside the host controller driver itself during enumeration, however some devices may require using control transactions through endpoint 0. The HID class drivers are a good example of a USB class driver that uses control transactions to send data to a USB device. TheUSBHCDControlTransfer()function should not be called from within interrupt context as control transfers are a blocking operation that relies on interrupts to proceed. Since most callbacks occur in interrupt context, any calls toUSBHCDControlTransfer()should be deferred until running outside the callback event. The USB host HID keyboard example is a good example of performing a control transaction outside of a callback function.
3.2.5
Interrupt Handling
All interrupt handling is done by the USB library host controller driver and most callbacks are done in interrupt context and like interrupt handlers should defer any real processing of events to occur outside the interrupt context. The callbacks are used to notify the upper layers of events that occur during enumeration or during normal operation. Because most of enumeration code is handled by interrupt handlers the enumeration code does require that the application call theUSBHCDMain()
function in order to progress through the enumeration states without running all code in interrupt context.