Home | History | Annotate | Download | only in UhciDxe
      1 /** @file
      2 
      3   The definition for UHCI driver model and HC protocol routines.
      4 
      5 Copyright (c) 2004 - 2015, Intel Corporation. All rights reserved.<BR>
      6 This program and the accompanying materials
      7 are licensed and made available under the terms and conditions of the BSD License
      8 which accompanies this distribution.  The full text of the license may be found at
      9 http://opensource.org/licenses/bsd-license.php
     10 
     11 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
     12 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
     13 
     14 **/
     15 
     16 #ifndef _EFI_UHCI_H_
     17 #define _EFI_UHCI_H_
     18 
     19 
     20 #include <Uefi.h>
     21 
     22 #include <Protocol/Usb2HostController.h>
     23 #include <Protocol/UsbHostController.h>
     24 #include <Protocol/PciIo.h>
     25 
     26 #include <Guid/EventGroup.h>
     27 
     28 #include <Library/DebugLib.h>
     29 #include <Library/BaseMemoryLib.h>
     30 #include <Library/UefiDriverEntryPoint.h>
     31 #include <Library/UefiBootServicesTableLib.h>
     32 #include <Library/UefiLib.h>
     33 #include <Library/BaseLib.h>
     34 #include <Library/MemoryAllocationLib.h>
     35 #include <Library/PcdLib.h>
     36 #include <Library/ReportStatusCodeLib.h>
     37 
     38 #include <IndustryStandard/Pci.h>
     39 
     40 typedef struct _USB_HC_DEV  USB_HC_DEV;
     41 
     42 #include "UsbHcMem.h"
     43 #include "UhciQueue.h"
     44 #include "UhciReg.h"
     45 #include "UhciSched.h"
     46 #include "UhciDebug.h"
     47 #include "ComponentName.h"
     48 
     49 //
     50 // UHC timeout experience values
     51 //
     52 
     53 #define UHC_1_MICROSECOND             1
     54 #define UHC_1_MILLISECOND             (1000 * UHC_1_MICROSECOND)
     55 #define UHC_1_SECOND                  (1000 * UHC_1_MILLISECOND)
     56 
     57 //
     58 // UHCI register operation timeout, set by experience
     59 //
     60 #define UHC_GENERIC_TIMEOUT           UHC_1_SECOND
     61 
     62 //
     63 // Wait for force global resume(FGR) complete, refers to
     64 // specification[UHCI11-2.1.1]
     65 //
     66 #define UHC_FORCE_GLOBAL_RESUME_STALL (20 * UHC_1_MILLISECOND)
     67 
     68 //
     69 // Wait for roothub port reset and recovery, reset stall
     70 // is set by experience, and recovery stall refers to
     71 // specification[UHCI11-2.1.1]
     72 //
     73 #define UHC_ROOT_PORT_RESET_STALL     (50 * UHC_1_MILLISECOND)
     74 #define UHC_ROOT_PORT_RECOVERY_STALL  (10 * UHC_1_MILLISECOND)
     75 
     76 //
     77 // Sync and Async transfer polling interval, set by experience,
     78 // and the unit of Async is 100us.
     79 //
     80 #define UHC_SYNC_POLL_INTERVAL        (1 * UHC_1_MILLISECOND)
     81 #define UHC_ASYNC_POLL_INTERVAL       EFI_TIMER_PERIOD_MILLISECONDS(1)
     82 
     83 //
     84 // UHC raises TPL to TPL_NOTIFY to serialize all its operations
     85 // to protect shared data structures.
     86 //
     87 #define  UHCI_TPL                     TPL_NOTIFY
     88 
     89 #define  USB_HC_DEV_SIGNATURE         SIGNATURE_32 ('u', 'h', 'c', 'i')
     90 
     91 #pragma pack(1)
     92 typedef struct {
     93   UINT8               ProgInterface;
     94   UINT8               SubClassCode;
     95   UINT8               BaseCode;
     96 } USB_CLASSC;
     97 #pragma pack()
     98 
     99 #define UHC_FROM_USB2_HC_PROTO(This)  CR(This, USB_HC_DEV, Usb2Hc, USB_HC_DEV_SIGNATURE)
    100 
    101 //
    102 // USB_HC_DEV support the UHCI hardware controller. It schedules
    103 // the asynchronous interrupt transfer with the same method as
    104 // EHCI: a reversed tree structure. For synchronous interrupt,
    105 // control and bulk transfer, it uses three static queue head to
    106 // schedule them. SyncIntQh is for interrupt transfer. LsCtrlQh is
    107 // for LOW speed control transfer, and FsCtrlBulkQh is for FULL
    108 // speed control or bulk transfer. This is because FULL speed contrl
    109 // or bulk transfer can reclaim the unused bandwidth. Some USB
    110 // device requires this bandwidth reclamation capability.
    111 //
    112 struct _USB_HC_DEV {
    113   UINT32                    Signature;
    114   EFI_USB2_HC_PROTOCOL      Usb2Hc;
    115   EFI_PCI_IO_PROTOCOL       *PciIo;
    116   EFI_DEVICE_PATH_PROTOCOL  *DevicePath;
    117   UINT64                    OriginalPciAttributes;
    118 
    119   //
    120   // Schedule data structures
    121   //
    122   UINT32                    *FrameBase; // the buffer pointed by this pointer is used to store pci bus address of the QH descriptor.
    123   UINT32                    *FrameBaseHostAddr; // the buffer pointed by this pointer is used to store host memory address of the QH descriptor.
    124   UHCI_QH_SW                *SyncIntQh;
    125   UHCI_QH_SW                *CtrlQh;
    126   UHCI_QH_SW                *BulkQh;
    127 
    128   //
    129   // Structures to maintain asynchronus interrupt transfers.
    130   // When asynchronous interrutp transfer is unlinked from
    131   // the frame list, the hardware may still hold a pointer
    132   // to it. To synchronize with hardware, its resoureces are
    133   // released in two steps using Recycle and RecycleWait.
    134   // Check the asynchronous interrupt management routines.
    135   //
    136   LIST_ENTRY                AsyncIntList;
    137   EFI_EVENT                 AsyncIntMonitor;
    138   UHCI_ASYNC_REQUEST        *Recycle;
    139   UHCI_ASYNC_REQUEST        *RecycleWait;
    140 
    141 
    142   UINTN                     RootPorts;
    143   USBHC_MEM_POOL            *MemPool;
    144   EFI_UNICODE_STRING_TABLE  *CtrlNameTable;
    145   VOID                      *FrameMapping;
    146 
    147   //
    148   // ExitBootServicesEvent is used to stop the EHC DMA operation
    149   // after exit boot service.
    150   //
    151   EFI_EVENT                 ExitBootServiceEvent;
    152 };
    153 
    154 extern EFI_DRIVER_BINDING_PROTOCOL   gUhciDriverBinding;
    155 extern EFI_COMPONENT_NAME_PROTOCOL   gUhciComponentName;
    156 extern EFI_COMPONENT_NAME2_PROTOCOL  gUhciComponentName2;
    157 
    158 /**
    159   Test to see if this driver supports ControllerHandle. Any
    160   ControllerHandle that has UsbHcProtocol installed will be supported.
    161 
    162   @param  This                 Protocol instance pointer.
    163   @param  Controller           Handle of device to test.
    164   @param  RemainingDevicePath  Not used.
    165 
    166   @return EFI_SUCCESS          This driver supports this device.
    167   @return EFI_UNSUPPORTED      This driver does not support this device.
    168 
    169 **/
    170 EFI_STATUS
    171 EFIAPI
    172 UhciDriverBindingSupported (
    173   IN EFI_DRIVER_BINDING_PROTOCOL     *This,
    174   IN EFI_HANDLE                      Controller,
    175   IN EFI_DEVICE_PATH_PROTOCOL        *RemainingDevicePath
    176   );
    177 
    178 /**
    179   Starting the Usb UHCI Driver.
    180 
    181   @param  This                 Protocol instance pointer.
    182   @param  Controller           Handle of device to test.
    183   @param  RemainingDevicePath  Not used.
    184 
    185   @retval EFI_SUCCESS          This driver supports this device.
    186   @retval EFI_UNSUPPORTED      This driver does not support this device.
    187   @retval EFI_DEVICE_ERROR     This driver cannot be started due to device Error.
    188                                EFI_OUT_OF_RESOURCES- Failed due to resource shortage.
    189 
    190 **/
    191 EFI_STATUS
    192 EFIAPI
    193 UhciDriverBindingStart (
    194   IN EFI_DRIVER_BINDING_PROTOCOL     *This,
    195   IN EFI_HANDLE                      Controller,
    196   IN EFI_DEVICE_PATH_PROTOCOL        *RemainingDevicePath
    197   );
    198 
    199 /**
    200   Stop this driver on ControllerHandle. Support stoping any child handles
    201   created by this driver.
    202 
    203   @param  This                 Protocol instance pointer.
    204   @param  Controller           Handle of device to stop driver on.
    205   @param  NumberOfChildren     Number of Children in the ChildHandleBuffer.
    206   @param  ChildHandleBuffer    List of handles for the children we need to stop.
    207 
    208   @return EFI_SUCCESS
    209   @return others
    210 
    211 **/
    212 EFI_STATUS
    213 EFIAPI
    214 UhciDriverBindingStop (
    215   IN EFI_DRIVER_BINDING_PROTOCOL     *This,
    216   IN EFI_HANDLE                      Controller,
    217   IN UINTN                           NumberOfChildren,
    218   IN EFI_HANDLE                      *ChildHandleBuffer
    219   );
    220 
    221 #endif
    222