19 USB Driver Design Guidelines

There are several categories of USB drivers that cooperate to provide the USB driver stack in a platform. The table below lists these USB drivers.
 ###### Table 30-Classes of USB drivers | **Class of driver** | **Description** | | -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | USB host controller driver | Consumes PCI I/O Protocol on the USB host controller handle and produces the USB2 Host Controller Protocol. | | USB bus driver | Consumes the USB2 Host Controller Protocol and produces a child handle for each USB controller on the USB bus. Installs the Device Path Protocol and USB I/O Protocol onto each child handle. | | USB device driver | Consumes the USB I/O Protocol and produces an I/O abstraction that provides services for the console devices and boot devices required to boot an EFI-conformant operating system. | This chapter shows how to write host controller drivers and USB device drivers. USB drivers must follow all of the general design guidelines described in _Chapter 4_ of this guide. In addition, any USB host controllers that are PCI controllers must also follow the PCI-specific design guidelines (see _Chapter 18_). ********** **Note:** _USB device drivers do not typically include HII functionality because they do not have configurable information. For example, USB device drivers are typically for hot-plug devices._ ********** The figure below shows an example of a USB driver stack and the protocols the USB drivers consume and produce. Because the USB hub is a special kind of device that simply acts as a signal repeater, it is not included in Figure 21.
Figure 21-USB driver stack
In this example, the platform hardware provides a single USB host controller on the PCI bus. The PCI bus driver produces a handle with EFI_DEVICE_PATH_PROTOCOL and EFI_PCI_IO_PROTOCOL installed for this USB host controller. The USB host controller driver then consumes EFI_PCI_IO_PROTOCOL on that USB host controller device handle and installs the EFI_USB2_HC_PROTOCOL onto the same handle.
The USB bus driver consumes the services of EFI_USB2_HC_PROTOCOL. It uses these services to enumerate the USB bus. In this example, the USB bus driver detects a USB keyboard, a USB mouse, and a USB mass storage device. As a result, the USB bus driver creates three child handles and installs the EFI_DEVICE_PATH_PROTOCOL and EFI_USB_IO_PROTOCOL onto each of those handles.
The USB mouse driver consumes the EFI_USB_IO_PROTOCOL and produces the EFI_SIMPLE_POINTER_PROTOCOL. The USB keyboard driver consumes the EFI_USB_IO_PROTOCOL to produce the EFI_SIMPLE_TEXT_INPUT_PROTOCOL. The USB mass storage driver consumes the EFI_USB_IO_PROTOCOL to produce the EFI_USB_IO_PROTOCOL.
The protocol interfaces for the USB2 Host Controller Protocol and the USB I/O Protocol are shown below in the following two examples.
Example 202-USB 2 Host Controller Protocol
1
typedef struct _EFI_USB2_HC_PROTOCOL EFI_USB2_HC_PROTOCOL;
2
///
3
/// The EFI_USB2_HC_PROTOCOL provides USB host controller management, basic
4
/// data transactions over a USB bus, and USB root hub access. A device driver
5
/// that wishes to manage a USB bus in a system retrieves the EFI_USB2_HC_PROTOCOL
6
/// instance that is associated with the USB bus to be managed. A device handle
7
/// for a USB host controller minimally contains an EFI_DEVICE_PATH_PROTOCOL
8
/// instance, and an EFI_USB2_HC_PROTOCOL instance.
9
///
10
struct _EFI_USB2_HC_PROTOCOL {
11
  EFI_USB2_HC_PROTOCOL_GET_CAPABILITY             GetCapability;
12
  EFI_USB2_HC_PROTOCOL_RESET                      Reset;
13
  EFI_USB2_HC_PROTOCOL_GET_STATE                  GetState;
14
  EFI_USB2_HC_PROTOCOL_SET_STATE                  SetState;
15
  EFI_USB2_HC_PROTOCOL_CONTROL_TRANSFER           ControlTransfer;
16
  EFI_USB2_HC_PROTOCOL_BULK_TRANSFER              BulkTransfer;
17
  EFI_USB2_HC_PROTOCOL_ASYNC_INTERRUPT_TRANSFER   AsyncInterruptTransfer;
18
  EFI_USB2_HC_PROTOCOL_SYNC_INTERRUPT_TRANSFER    SyncInterruptTransfer;
19
  EFI_USB2_HC_PROTOCOL_ISOCHRONOUS_TRANSFER       IsochronousTransfer;
20
  EFI_USB2_HC_PROTOCOL_ASYNC_ISOCHRONOUS_TRANSFER AsyncIsochronousTransfer;
21
  EFI_USB2_HC_PROTOCOL_GET_ROOTHUB_PORT_STATUS    GetRootHubPortStatus;
22
  EFI_USB2_HC_PROTOCOL_SET_ROOTHUB_PORT_FEATURE   SetRootHubPortFeature;
23
  EFI_USB2_HC_PROTOCOL_CLEAR_ROOTHUB_PORT_FEATURE ClearRootHubPortFeature;
24
​
25
  ///
26
  /// The major revision number of the USB host controller. The revision
27
  /// information indicates the release of the Universal Serial Bus Specification
28
  /// with which the host controller is compliant.
29
  ///
30
  UINT16                                          MajorRevision;
31
​
32
  ///
33
  /// The minor revision number of the USB host controller. The revision
34
  /// information indicates the release of the Universal Serial Bus Specification
35
  /// with which the host controller is compliant.
36
  ///
37
  UINT16                                          MinorRevision;
38
};
Copied!
Example 203-USB I/O Protocol
1
typedef struct _EFI_USB_IO_PROTOCOL EFI_USB_IO_PROTOCOL;
2
​
3
///
4
/// The EFI_USB_IO_PROTOCOL provides four basic transfers types described
5
/// in the USB 1.1 Specification. These include control transfer, interrupt
6
/// transfer, bulk transfer and isochronous transfer. The EFI_USB_IO_PROTOCOL
7
/// also provides some basic USB device/controller management and configuration
8
/// interfaces. A USB device driver uses the services of this protocol to manage
9
/// USB devices.
10
///
11
struct _EFI_USB_IO_PROTOCOL {
12
  //
13
  // IO transfer
14
  //
15
  EFI_USB_IO_CONTROL_TRANSFER              UsbControlTransfer;
16
  EFI_USB_IO_BULK_TRANSFER                 UsbBulkTransfer;
17
  EFI_USB_IO_ASYNC_INTERRUPT_TRANSFER      UsbAsyncInterruptTransfer;
18
  EFI_USB_IO_SYNC_INTERRUPT_TRANSFER       UsbSyncInterruptTransfer;
19
  EFI_USB_IO_ISOCHRONOUS_TRANSFER          UsbIsochronousTransfer;
20
  EFI_USB_IO_ASYNC_ISOCHRONOUS_TRANSFER    UsbAsyncIsochronousTransfer;
21
​
22
  //
23
  // Common device request
24
  //
25
  EFI_USB_IO_GET_DEVICE_DESCRIPTOR         UsbGetDeviceDescriptor;
26
  EFI_USB_IO_GET_CONFIG_DESCRIPTOR         UsbGetConfigDescriptor;
27
  EFI_USB_IO_GET_INTERFACE_DESCRIPTOR      UsbGetInterfaceDescriptor;
28
  EFI_USB_IO_GET_ENDPOINT_DESCRIPTOR       UsbGetEndpointDescriptor;
29
  EFI_USB_IO_GET_STRING_DESCRIPTOR         UsbGetStringDescriptor;
30
  EFI_USB_IO_GET_SUPPORTED_LANGUAGE        UsbGetSupportedLanguages;
31
​
32
  //
33
  // Reset controller's parent port
34
  //
35
  EFI_USB_IO_PORT_RESET UsbPortReset;
36
};
Copied!

18.7.3 Using FDF File to Generate PCI Option ROM Image

19.1 USB Host Controller Driver

Last modified 1yr ago

Copy link

Contents

Figure 21-USB driver stack

Example 202-USB 2 Host Controller Protocol

Example 203-USB I/O Protocol