Legacy Support for USB Keyboards and Mice and the Host Controller Driver Microsoft Corporation December 3, 1998 The operating system brings a Universal Serial Bus (USB) host controller to an operational state using the following steps: 1* Load the host controller driver and find the host controller. 2* Verify the host controller and allocate system resources. 3* Take control of the host controller. 4* Set up host controller registers and host controller communications area (HCCA). 5* Start sending Start of Frame (SOF) tokens on the USB. This article examines the third step of the process—taking control of the host controller—in the context of providing a solution to the problem of legacy keyboard and mouse support when a USB keyboard, mouse, or both are attached to the PC. The information in this article applies to both Microsoft® Windows® 98 and Windows 2000. USB support in Windows 98 and Windows 2000 is designed based on these assumptions: 6* System vendors want to support USB keyboards and mice when the BIOS has control of the system (for example, the USB keyboard works when the BIOS Setup program is running or the system is running in MS-DOS® mode). 7* Host controller hardware and firmware vendors provide some amount of support for the emulation of PS/2-compatible keyboards and mice by USB keyboards and mice. Under conditions where these assumptions are met, this article describes the way Windows host controller drivers hand off USB keyboard and mouse interrupt processing between the operating system and the BIOS. The implementations used by the Open Host Controller Interface (OHCI) host controller driver and Universal Host Controller Interface (UHCI) host controller driver differ because of fundamental differences in the OHCI and UHCI specifications. Both implementations are described in this article. The operating system/BIOS handoff of legacy keyboard and mouse support is a two- way process. In other words, the handoff can occur from the BIOS to the operating system or from the operating system to the BIOS. Both handoff directions are described in this article. An example sequence of events that involves handoff of the host controller in both directions is shown in Figure 1. Figure 1. Example sequence of events in handoff of the host controller The time line in Figure 1 starts with a power-up (cold boot) event on the PC. 8* Immediately after power-up and for some period of time, the BIOS controls the PC and the host controller. During this time interval, a user should be able to use a USB keyboard to enter BIOS Setup and use all keys on the USB keyboard that are valid during BIOS Setup. 9* If the user does not choose to enter BIOS Setup, the BIOS starts the operating system at some point and the operating system takes control of the PC and the host controller. As shown in Figure 1, code in a routine in the operating system host controller driver performs the necessary steps to hand off control of the legacy keyboard support function from the BIOS to the operating system host controller driver (in this article, that routine is called StopBIOS). 10* The next event shown in Figure 1 occurs when the user employs the Shutdown menu to shut down to MS-DOS. This causes the host controller driver to be unloaded; before unloading, it executes a routine that performs the necessary steps to hand off control of the legacy keyboard support function to the BIOS (in this article, that host controller driver routine is called StartBIOS). Hand Off for the OHCI Host Controller The host controller driver is responsible for a per-host controller set of data called device data. At startup and shutdown, the host controller driver manages the host controller through a set of Operational Registers. These registers are part of the host controller and are accessed by the host controller driver using memory references through a noncached virtual pointer. As defined in the OHCI specification, legacy keyboard and mouse emulation is provided by a set of registers controlled by code running in System Management Mode (SMM). When data is received from the keyboard or mouse, the SMM emulation code is notified and translates the USB keyboard/mouse data into a data sequence that is equivalent to what would be produced by a PS/2-compatible keyboard/mouse interface. This emulation scheme is described in the "Operational Theory" section of Appendix B in the OHCI specification. Interrupts generated by the host controller emulation hardware when USB keyboard or mouse data is received are steered by the host controller hardware to either a system management interrupt (SMI) or the standard host controller interrupt. The host controller uses these rules to steer the interrupt: 11* When the InterruptRouting bit in the host controller HcControl register is cleared, interrupts are steered to the standard host controller interrupt. 12* When the InterruptRouting bit is set, interrupts are steered to the SMI interrupt. Note SMM is a processor mode in Intel® Architecture platforms that is transparent to the operating system and application software. SMM is intended for use only by firmware. SMM is one of the processor's major operating modes, on a level with protected mode, real-address mode, or virtual-86 mode. An external signal, SMI#, causes the processor to switch to SMM; this is known as the SMI interrupt. The SMI# signal might be generated, for example, by closing the lid of a portable computer. When the processor recognizes an SMI# signal, the processor waits for all stores to complete and saves state. Then the processor begins to execute the SMM handler in firmware. Power-Up Processes The SMM driver gets control of the processor before any other driver. The SMM driver must set the InterruptRouting bit to cause all host controller interrupts to be routed to the SMI interrupt. The SMM driver then sets system-specific fields in the host controller registers, waits at least the minimum time specified in the USB Specification for assertion of reset on the USB, and then sets up the host controller. Operating System Takes Control of the OHCI Host Controller Later, when the host controller driver is loaded and running, it can determine that the SMM driver is active because the InterruptRouting bit is set in the HcControl register. When it wants the interrupts steered to the standard host controller interrupt, the host controller driver sets the OwnershipChangeRequest bit in the HcCommandStatus register, then monitors the InterruptRouting bit to determine when the ownership change has taken effect. The following pseudocode shows the structure and logic of the entire StopBIOS routine in the Windows OHCI host controller driver. Notice that the StopBIOS routine is called from only one place in the host controller driver, from the OpenHCI_InitializeHardware routine. Get a pointer to a per-device, per-host controller data structure If InterruptRouting bit is set to 1 // SMM driver owns host controller. Set OwnershipChangeRequest bit While total time elapsed is less than 0.5 seconds Wait 1 ms Read InterruptRouting bit If InterruptRouting bit is cleared //SMM has relinquished ownership. Set LEGACY_BIOS_DETECTED bit in per-device, per-host data structure Return (STATUS_SUCCESSFUL) Endif Endwhile // 0.5 sec have elapsed and SMM has not relinquished control. Endif Return (STAUS_UNSUCCESSFUL) Note that a return of STATUS_UNSUCCESSFUL can result in a Code 10 message appearing in the Device Manager entry for the OHCI host controller. BIOS Takes Control of the OHCI Host Controller The following pseudocode shows the structure and logic of the entire StartBIOS module in the Windows OHCI host controller driver. Notice that the StartBIOS routine is called only after the host controller driver will not touch the hardware again. Get pointer to per-device, per-host controller data structure If LEGACY_BIOS_DETECTED flag set in per-device, per-host controller data structure //hand back control of host controller to SMM driver. Set OwnershipChangeRequest bit in HcCmd register Set OwnershipChange interrupt enable bit in HcInt register Set MasterInterruptEnable bit in HcInt register Endif Return(STATUS_SUCCESSFUL) Hand Off for the UHCI Host Controller Section 5 of the Universal Host Controller Interface (UHCI) Design Guide, Revision 1.1 gives an example implementation of mouse and keyboard legacy support and describes one way to hand off control of the host controller between the BIOS and the UHCI host controller driver in the operating system. The key UHCI register used in the example is the legacy support register (LEGSUP). For implementers in a PCI device, the LEGSUP register is located at offset C0-C1h, in function 2 PCI configuration space. The Microsoft UHCI host controller driver also uses the LEGSUP register as the primary interface in implementing the handoff of the host controller between the operating system and the BIOS; the Microsoft host controller driver implementation logic is described in this section of the article. LEGSUP register structure. The LEGSUP register is a bitmap containing 16 bits. The meaning of each of the 16 bits is fully specified in Section 5 of the Universal Host Controller Interface (UHCI) Design Guide, Revision 1.1. A summary description is given in the following table so the reader can interpret the bitmap constant values used in later sections of this article without referring to the Design Guide. Table 1. LEGSUP register structure Bit Name Description 15 (R/WC) A20PTS 1 = A20GATE passthrough sequence has ended. 14 Reserved. 13 (R/W) USBPIRQDEN 1 = USB interrupt is routed to PIRQD (default). 0 = Not routed to PIRQD. This bit can be used to prevent the host controller from generating an interrupt. 12 (RO) USBIRQS 1 = USB IRQ is active. 11 (R/WC) TBY64W 1 = Write to port 64h has occurred. 10 (R/WC) TBY64R 1 = Read to port 64h has occurred. 9 (R/WC) TBY60W 1 = Write to port 60h has occurred. 8 (R/WC) TBY60R 1 = Read to port 60h has occurred. 7 (R/W) SMIEPTE 1 = Enable generation of an SMI when A20GATE passthrough sequence has ended. 0 = Disable (default). 6 (RO) PSS 1 = A20GATE passthrough sequence is currently in progress. 0 = Not executing (default). 5 (R/W) A20PTEN 1 = Enable A20GATE passthrough sequence. 0 = Disable (default). 4 (R/W) USBSMIEN 1 = Enable SMI# generation on USB IRQ. 0 = Disable (default). 3 (R/W) 64WEN 1 = Enable I/O Trap and SMI# generation of port 64h write. 0 = Disable (default). 2 (R/W) 64REN 1 = Enable I/O Trap and SMI# generation of port 64h read. 0 = Disable (default). 1 (R/W) 60WEN 1 = Enable I/O Trap and SMI# generation of port 60h write. 0 = Disable (default). 0 (R/W) 60REN 1 = Enable I/O Trap and SMI# generation of port 60h read. 0 = Disable (default). How the Microsoft host controller driver uses the LEGSUP register. The Microsoft UHCI host controller driver writes the following value to LEGSUP for normal HCD use: 0x2000. Note that this sets bit 13 and clears bit 4, which routes USB interrupts to PIRQD and disables SMI# generation on a USB IRQ event. The host controller driver sets bit 4 for BIOS/SMI use, which enables SMI# generation on a USB IRQ event. SOF MODIFY register. The SOF MODIFY register is a one-byte register that can be used to modify the value used to generate timing on the USB. (For more information, see section 2.1.6 of the Universal Host Controller Interface (UHCI) Design Guide, Revision 1.1.) Guidelines for modification of frame time are contained in Chapter 7 of the USB Specification. How the Microsoft host controller driver uses the SOF MODIFY register. When the Microsoft host controller driver takes control of the host controller from the BIOS, it always reads the value of the SOF MODIFY register value established by the BIOS and saves it in a per-device, per-host controller data structure. USB COMMAND (USBCMD) register structure. The USBCMD register is a bit- map containing 16 bits. The meaning of each of the 16 bits is fully specified in Section 2.1.1 of the Universal Host Controller Interface (UHCI) Design Guide, Revision 1.1. A summary description is given in the following table so the reader can, without referring to the Design Guide, interpret the CMDREG bits that are set and cleared in the pseudocode in later sections of this article. Table 2. USBCMD register structure Bit Name Description 15:8 Reserved. 7 (R/W) MAXP 1 = 64 bits. 0 = 32 bits. 6 (R/W) CF Host controller driver software sets this bit as the last action in its process of configuring the host controller; has no effect on the hardware. Provided only as a semaphore service for the software. 5 (R/W) SWDBG 1 = Debug mode. 0 = Normal mode. 4 (R/W) FGR 1 = host controller sends Global Resume signal on the USB. 3 (R/W) EGSM 1 = host controller enters Global Suspend mode. 2 (R/W) GRESET 1 = host controller sends Global Reset signal on the USB and then resets all its logic. 1 (R/W) HCRESET 1 = host controller resets its internal timers, counters, state machines, and so on to their initial values. 0 (R/W) RS 1 = Run (host controller proceeds with execution of the schedule). 0 = Stop (host controller completes current transaction and then halts). How the Microsoft host controller driver uses the USBCMD register. When it takes control of the host controller from the BIOS, the Microsoft host controller driver clears the RS bit to stop the host controller and clears the CF bit. USB STATUS (USBSTS) register structure. The USBSTS register is a bitmap containing 16 bits. The meaning of each of the 16 bits is fully specified in Section 2.1.2 of the Universal Host Controller Interface (UHCI) Design Guide, Revision 1.1. A summary description is given in the following table so the reader can, without referring to the Design Guide, interpret the CMDSTS bits that are set and cleared in the pseudocode in later sections of this article. Table 3. USBSTS register structure Bit Name Description 15:6 Reserved. 5 (R/WC) HcHalted Set to 1 by host controller when it is halted. 4 (R/WC) Host Controller Process Error Set to 1 by host controller when it encounters a consistency check error while processing a Transfer Descriptor. 3 (R/WC) Host System Error Set to 1 by host controller when a serious error occurs during a host system access. 2 (R/WC) Resume Detect Set to 1 by host controller when it receives a RESUME signal from a USB device. 1 (R/W) USB Error Interrupt Set to 1 by host controller when completion of a USB transaction results in an error condition. 0 (R/W) USBINT Set to 1 by host controller either when completion of a USB transaction causes an interrupt or when a short packet is detected. How the Microsoft host controller driver uses the USBSTS register. During the process of taking control of the host controller from the BIOS, the Microsoft host controller driver monitors the HcHalted bit to determine if and when the host controller is halted. Operating System Takes Control of the UHCI Host Controller When the host controller driver is loaded and running, it can determine whether the platform has a USB BIOS by the bits set in the LEGSUP register. A USB BIOS is a BIOS that contains code to: 13* Configure the host controller. 14* Enable a USB keyboard and mouse. 15* Set up the host controller scheduler. 16* Route USB keyboard and mouse input to the 8042 Keyboard Controller (KBC). When a USB BIOS boots, if it contains the code that does the functions listed above and has legacy keyboard support enabled, then it should always set bit 4 of the host controller LEGSUP register and make sure bit 13 is cleared. Conversely, when a BIOS boots that does not contain the code that does the above functions or when it contains the code but has legacy keyboard support disabled, the BIOS should always set bit 13 of the LEGSUP register and make sure bit 4 is cleared. This will ensure the appropriate interaction between the BIOS and the Windows UHCI host controller driver. The following pseudocode shows the structure and logic of the entire StopBIOS routine in the UHCI host controller. Get a pointer to the per-device, per-host controller data structure Read current value of SOF MODIFY register into data structure Read current value of USB COMMAND REGISTER into data structure Read current value of USB INTERRUPT ENABLE REGISTER into data structure Read upper 20 bits of FRAME LIST BASE ADDRESS REGISTER into data structure // Override SOF MODIFY value from BIOS with value in Registry, if there is one. If SOF MODIFY value is in the Registry Read SOF MODIFY value from Registry Save SOF MODIFY value read from Registry in data structure Endif // Prepare first host controller command. Read current value of USB COMMAND REGISTER Clear RS bit in the USB COMMAND REGISTER // Will stop host controller. Clear CF bit in the USB COMMAND REGISTER // Will signal BIOS that OS has control. Write new value to USB COMMAND REGISTER // Wait until host controller halts. While total time elapsed is less than one millisecond Write 0xFF to Interrupt Status Register // Clear all pending interrupts. If HcHalt bit in USB STATUS REGISTER is set Break // Host controller has halted. Endif Endwhile Read the current value of the LEGSUP register Save read value of LEGSUP register in data structure // If any bits in the bit pattern 0x00BF are set in read LEGSUP value, then the platform // BIOS has legacy keyboard support code and legacy keyboard support is enabled for // the platform. If ((LEGSUP value) AND (0x00BF))!= 0 then Set USBBIOS flag in data structure // Platform has USB BIOS. Clear SMI enable bit (bit 4) in read LEGSUP value Write new value to LEGSUP register Read current value of LEGSUP register Write 0x2000 to the LEGSUP register // Route USB interrupt to PIRQD and // disable SMI# interrupt generation. Endif Return(STATUS_SUCCESSFUL) . mouse and keyboard legacy support and describes one way to hand off control of the host controller between the BIOS and the UHCI host controller driver in the. control of the host controller from the BIOS, the Microsoft host controller driver clears the RS bit to stop the host controller and clears the CF bit. USB STATUS