UsbBus.h

Go to the documentation of this file.

 
#ifndef _EFI_USB_BUS_H_
#define _EFI_USB_BUS_H_
 
#include <Uefi.h>
 
#include <Protocol/Usb2HostController.h>
#include <Protocol/UsbHostController.h>
#include <Protocol/UsbIo.h>
#include <Protocol/DevicePath.h>
 
#include <Library/BaseLib.h>
#include <Library/DebugLib.h>
#include <Library/BaseMemoryLib.h>
#include <Library/UefiDriverEntryPoint.h>
#include <Library/UefiBootServicesTableLib.h>
#include <Library/UefiLib.h>
#include <Library/DevicePathLib.h>
#include <Library/MemoryAllocationLib.h>
#include <Library/ReportStatusCodeLib.h>
 
#include <IndustryStandard/Usb.h>
 
typedef struct _USB_DEVICE     USB_DEVICE;
typedef struct _USB_INTERFACE  USB_INTERFACE;
typedef struct _USB_BUS        USB_BUS;
typedef struct _USB_HUB_API    USB_HUB_API;
 
#include "UsbUtility.h"
#include "UsbDesc.h"
#include "UsbHub.h"
#include "UsbEnumer.h"
 
//
// USB bus timeout experience values
//
 
#define USB_MAX_LANG_ID    16
#define USB_MAX_INTERFACE  16
#define USB_MAX_DEVICES    128
 
#define USB_BUS_1_MILLISECOND  1000
 
//
// Roothub and hub's polling interval, set by experience,
// The unit of roothub is 100us, means 100ms as interval, and
// the unit of hub is 1ms, means 64ms as interval.
//
#define USB_ROOTHUB_POLL_INTERVAL  (100 * 10000U)
#define USB_HUB_POLL_INTERVAL      64
 
//
// Wait for port stable to work, refers to specification
// [USB20-9.1.2]
//
#define USB_WAIT_PORT_STABLE_STALL  (100 * USB_BUS_1_MILLISECOND)
 
//
// Wait for port statue reg change, set by experience
//
#define USB_WAIT_PORT_STS_CHANGE_STALL  (100)
 
//
// Wait for set device address, refers to specification
// [USB20-9.2.6.3, it says 2ms]
//
#define USB_SET_DEVICE_ADDRESS_STALL  (2 * USB_BUS_1_MILLISECOND)
 
//
// Wait for retry max packet size, set by experience
//
#define USB_RETRY_MAX_PACK_SIZE_STALL  (100 * USB_BUS_1_MILLISECOND)
 
//
// Wait for hub port power-on, refers to specification
// [USB20-11.23.2]
//
#define USB_SET_PORT_POWER_STALL  (2 * USB_BUS_1_MILLISECOND)
 
//
// Wait for port reset, refers to specification
// [USB20-7.1.7.5, it says 10ms for hub and 50ms for
// root hub]
//
// According to USB2.0, Chapter 11.5.1.5 Resetting,
// the worst case for TDRST is 20ms
//
#define USB_SET_PORT_RESET_STALL       (20 * USB_BUS_1_MILLISECOND)
#define USB_SET_ROOT_PORT_RESET_STALL  (50 * USB_BUS_1_MILLISECOND)
 
//
// Wait for port recovery to accept SetAddress, refers to specification
// [USB20-7.1.7.5, it says 10 ms for TRSTRCY]
//
#define USB_SET_PORT_RECOVERY_STALL  (10 * USB_BUS_1_MILLISECOND)
 
//
// Wait for clear roothub port reset, set by experience
//
#define USB_CLR_ROOT_PORT_RESET_STALL  (20 * USB_BUS_1_MILLISECOND)
 
//
// Wait for set roothub port enable, set by experience
//
#define USB_SET_ROOT_PORT_ENABLE_STALL  (20 * USB_BUS_1_MILLISECOND)
 
//
// Send general device request timeout.
//
// The USB Specification 2.0, section 11.24.1 recommends a value of
// 50 milliseconds.  We use a value of 500 milliseconds to work
// around slower hubs and devices.
//
#define USB_GENERAL_DEVICE_REQUEST_TIMEOUT  500
 
//
// Send clear feature request timeout, set by experience
//
#define USB_CLEAR_FEATURE_REQUEST_TIMEOUT  10
 
//
// Bus raises TPL to TPL_NOTIFY to serialize all its operations
// to protect shared data structures.
//
#define  USB_BUS_TPL  TPL_NOTIFY
 
#define  USB_INTERFACE_SIGNATURE  SIGNATURE_32 ('U', 'S', 'B', 'I')
#define  USB_BUS_SIGNATURE        SIGNATURE_32 ('U', 'S', 'B', 'B')
 
#define USB_BIT(a)                 ((UINTN)(1 << (a)))
#define USB_BIT_IS_SET(Data, Bit)  ((BOOLEAN)(((Data) & (Bit)) == (Bit)))
 
#define USB_INTERFACE_FROM_USBIO(a) \
          CR(a, USB_INTERFACE, UsbIo, USB_INTERFACE_SIGNATURE)
 
#define USB_BUS_FROM_THIS(a) \
          CR(a, USB_BUS, BusId, USB_BUS_SIGNATURE)
 
//
// Used to locate USB_BUS
// UsbBusProtocol is the private protocol.
// gEfiCallerIdGuid will be used as its protocol guid.
//
typedef struct _EFI_USB_BUS_PROTOCOL {
  UINT64    Reserved;
} EFI_USB_BUS_PROTOCOL;
 
//
// Stands for the real USB device. Each device may
// has several separately working interfaces.
//
struct _USB_DEVICE {
  USB_BUS                               *Bus;
 
  //
  // Configuration information
  //
  UINT8                                 Speed;
  UINT8                                 Address;
  UINT32                                MaxPacket0;
 
  //
  // The device's descriptors and its configuration
  //
  USB_DEVICE_DESC                       *DevDesc;
  USB_CONFIG_DESC                       *ActiveConfig;
 
  UINT16                                LangId[USB_MAX_LANG_ID];
  UINT16                                TotalLangId;
 
  UINT8                                 NumOfInterface;
  USB_INTERFACE                         *Interfaces[USB_MAX_INTERFACE];
 
  //
  // Parent child relationship
  //
  EFI_USB2_HC_TRANSACTION_TRANSLATOR    Translator;
 
  UINT8                                 ParentAddr;
  USB_INTERFACE                         *ParentIf;
  UINT8                                 ParentPort; // Start at 0
  UINT8                                 Tier;
  BOOLEAN                               DisconnectFail;
};
 
//
// Stands for different functions of USB device
//
struct _USB_INTERFACE {
  UINTN                       Signature;
  USB_DEVICE                  *Device;
  USB_INTERFACE_DESC          *IfDesc;
  USB_INTERFACE_SETTING       *IfSetting;
 
  //
  // Handles and protocols
  //
  EFI_HANDLE                  Handle;
  EFI_USB_IO_PROTOCOL         UsbIo;
  EFI_DEVICE_PATH_PROTOCOL    *DevicePath;
  BOOLEAN                     IsManaged;
 
  //
  // Hub device special data
  //
  BOOLEAN                     IsHub;
  USB_HUB_API                 *HubApi;
  UINT8                       NumOfPort;
  EFI_EVENT                   HubNotify;
 
  //
  // Data used only by normal hub devices
  //
  USB_ENDPOINT_DESC           *HubEp;
  UINT8                       *ChangeMap;
 
  //
  // Data used only by root hub to hand over device to
  // companion UHCI driver if low/full speed devices are
  // connected to EHCI.
  //
  UINT8                       MaxSpeed;
};
 
//
// Stands for the current USB Bus
//
struct _USB_BUS {
  UINTN                       Signature;
  EFI_USB_BUS_PROTOCOL        BusId;
 
  //
  // Managed USB host controller
  //
  EFI_HANDLE                  HostHandle;
  EFI_DEVICE_PATH_PROTOCOL    *DevicePath;
  EFI_USB2_HC_PROTOCOL        *Usb2Hc;
  EFI_USB_HC_PROTOCOL         *UsbHc;
 
  //
  // Recorded the max supported usb devices.
  // XHCI can support up to 255 devices.
  // EHCI/UHCI/OHCI supports up to 127 devices.
  //
  UINT32                      MaxDevices;
  //
  // An array of device that is on the bus. Devices[0] is
  // for root hub. Device with address i is at Devices[i].
  //
  USB_DEVICE                  *Devices[256];
 
  //
  // USB Bus driver need to control the recursive connect policy of the bus, only those wanted
  // usb child device will be recursively connected.
  //
  // WantedUsbIoDPList tracks the Usb child devices which user want to recursively fully connecte,
  // every wanted child device is stored in a item of the WantedUsbIoDPList, whose structure is
  // DEVICE_PATH_LIST_ITEM
  //
  LIST_ENTRY    WantedUsbIoDPList;
};
 
//
// USB Hub Api
//
struct _USB_HUB_API {
  USB_HUB_INIT                  Init;
  USB_HUB_GET_PORT_STATUS       GetPortStatus;
  USB_HUB_CLEAR_PORT_CHANGE     ClearPortChange;
  USB_HUB_SET_PORT_FEATURE      SetPortFeature;
  USB_HUB_CLEAR_PORT_FEATURE    ClearPortFeature;
  USB_HUB_RESET_PORT            ResetPort;
  USB_HUB_RELEASE               Release;
};
 
#define USB_US_LAND_ID  0x0409
 
#define DEVICE_PATH_LIST_ITEM_SIGNATURE  SIGNATURE_32('d','p','l','i')
typedef struct _DEVICE_PATH_LIST_ITEM {
  UINTN                       Signature;
  LIST_ENTRY                  Link;
  EFI_DEVICE_PATH_PROTOCOL    *DevicePath;
} DEVICE_PATH_LIST_ITEM;
 
typedef struct {
  USB_CLASS_DEVICE_PATH       UsbClass;
  EFI_DEVICE_PATH_PROTOCOL    End;
} USB_CLASS_FORMAT_DEVICE_PATH;
 
EFI_STATUS
EFIAPI
UsbBusFreeUsbDPList (
  IN     LIST_ENTRY  *UsbIoDPList
  );
 
EFI_STATUS
EFIAPI
UsbBusAddWantedUsbIoDP (
  IN EFI_USB_BUS_PROTOCOL      *UsbBusId,
  IN EFI_DEVICE_PATH_PROTOCOL  *RemainingDevicePath
  );
 
BOOLEAN
EFIAPI
UsbBusIsWantedUsbIO (
  IN USB_BUS        *Bus,
  IN USB_INTERFACE  *UsbIf
  );
 
EFI_STATUS
EFIAPI
UsbBusRecursivelyConnectWantedUsbIo (
  IN EFI_USB_BUS_PROTOCOL  *UsbBusId
  );
 
EFI_STATUS
EFIAPI
UsbIoControlTransfer (
  IN  EFI_USB_IO_PROTOCOL     *This,
  IN  EFI_USB_DEVICE_REQUEST  *Request,
  IN  EFI_USB_DATA_DIRECTION  Direction,
  IN  UINT32                  Timeout,
  IN  OUT VOID                *Data       OPTIONAL,
  IN  UINTN                   DataLength  OPTIONAL,
  OUT UINT32                  *UsbStatus
  );
 
EFI_STATUS
EFIAPI
UsbIoBulkTransfer (
  IN  EFI_USB_IO_PROTOCOL  *This,
  IN  UINT8                Endpoint,
  IN  OUT VOID             *Data,
  IN  OUT UINTN            *DataLength,
  IN  UINTN                Timeout,
  OUT UINT32               *UsbStatus
  );
 
EFI_STATUS
EFIAPI
UsbIoSyncInterruptTransfer (
  IN  EFI_USB_IO_PROTOCOL  *This,
  IN  UINT8                Endpoint,
  IN  OUT VOID             *Data,
  IN  OUT UINTN            *DataLength,
  IN  UINTN                Timeout,
  OUT UINT32               *UsbStatus
  );
 
EFI_STATUS
EFIAPI
UsbIoAsyncInterruptTransfer (
  IN EFI_USB_IO_PROTOCOL              *This,
  IN UINT8                            Endpoint,
  IN BOOLEAN                          IsNewTransfer,
  IN UINTN                            PollInterval        OPTIONAL,
  IN UINTN                            DataLength          OPTIONAL,
  IN EFI_ASYNC_USB_TRANSFER_CALLBACK  Callback            OPTIONAL,
  IN VOID                             *Context            OPTIONAL
  );
 
EFI_STATUS
EFIAPI
UsbIoIsochronousTransfer (
  IN  EFI_USB_IO_PROTOCOL  *This,
  IN  UINT8                DeviceEndpoint,
  IN  OUT VOID             *Data,
  IN  UINTN                DataLength,
  OUT UINT32               *Status
  );
 
EFI_STATUS
EFIAPI
UsbIoAsyncIsochronousTransfer (
  IN EFI_USB_IO_PROTOCOL              *This,
  IN UINT8                            DeviceEndpoint,
  IN OUT VOID                         *Data,
  IN UINTN                            DataLength,
  IN EFI_ASYNC_USB_TRANSFER_CALLBACK  IsochronousCallBack,
  IN VOID                             *Context              OPTIONAL
  );
 
EFI_STATUS
EFIAPI
UsbIoGetDeviceDescriptor (
  IN  EFI_USB_IO_PROTOCOL        *This,
  OUT EFI_USB_DEVICE_DESCRIPTOR  *Descriptor
  );
 
EFI_STATUS
EFIAPI
UsbIoGetActiveConfigDescriptor (
  IN  EFI_USB_IO_PROTOCOL        *This,
  OUT EFI_USB_CONFIG_DESCRIPTOR  *Descriptor
  );
 
EFI_STATUS
EFIAPI
UsbIoGetInterfaceDescriptor (
  IN  EFI_USB_IO_PROTOCOL           *This,
  OUT EFI_USB_INTERFACE_DESCRIPTOR  *Descriptor
  );
 
EFI_STATUS
EFIAPI
UsbIoGetEndpointDescriptor (
  IN  EFI_USB_IO_PROTOCOL          *This,
  IN  UINT8                        Index,
  OUT EFI_USB_ENDPOINT_DESCRIPTOR  *Descriptor
  );
 
EFI_STATUS
EFIAPI
UsbIoGetSupportedLanguages (
  IN  EFI_USB_IO_PROTOCOL  *This,
  OUT UINT16               **LangIDTable,
  OUT UINT16               *TableSize
  );
 
EFI_STATUS
EFIAPI
UsbIoGetStringDescriptor (
  IN  EFI_USB_IO_PROTOCOL  *This,
  IN  UINT16               LangID,
  IN  UINT8                StringIndex,
  OUT CHAR16               **String
  );
 
EFI_STATUS
EFIAPI
UsbIoPortReset (
  IN EFI_USB_IO_PROTOCOL  *This
  );
 
EFI_STATUS
EFIAPI
UsbBusBuildProtocol (
  IN EFI_DRIVER_BINDING_PROTOCOL  *This,
  IN EFI_HANDLE                   Controller,
  IN EFI_DEVICE_PATH_PROTOCOL     *RemainingDevicePath
  );
 
EFI_STATUS
EFIAPI
UsbBusDriverEntryPoint (
  IN EFI_HANDLE        ImageHandle,
  IN EFI_SYSTEM_TABLE  *SystemTable
  );
 
EFI_STATUS
EFIAPI
UsbBusControllerDriverSupported (
  IN EFI_DRIVER_BINDING_PROTOCOL  *This,
  IN EFI_HANDLE                   Controller,
  IN EFI_DEVICE_PATH_PROTOCOL     *RemainingDevicePath
  );
 
EFI_STATUS
EFIAPI
UsbBusControllerDriverStart (
  IN EFI_DRIVER_BINDING_PROTOCOL  *This,
  IN EFI_HANDLE                   Controller,
  IN EFI_DEVICE_PATH_PROTOCOL     *RemainingDevicePath
  );
 
EFI_STATUS
EFIAPI
UsbBusControllerDriverStop (
  IN EFI_DRIVER_BINDING_PROTOCOL  *This,
  IN EFI_HANDLE                   Controller,
  IN UINTN                        NumberOfChildren,
  IN EFI_HANDLE                   *ChildHandleBuffer
  );
 
extern EFI_USB_IO_PROTOCOL           mUsbIoProtocol;
extern EFI_DRIVER_BINDING_PROTOCOL   mUsbBusDriverBinding;
extern EFI_COMPONENT_NAME_PROTOCOL   mUsbBusComponentName;
extern EFI_COMPONENT_NAME2_PROTOCOL  mUsbBusComponentName2;
 
#endif