MdeModulePkg/Bus/Pci/UhciDxe/UhciSched.h

   1 /** @file
   2
   3   The definition for EHCI register operation routines.
   4
   5 Copyright (c) 2007 - 2010, Intel Corporation. All rights reserved.<BR>
   6 SPDX-License-Identifier: BSD-2-Clause-Patent
   7
   8 **/
   9
  10 #ifndef _EFI_UHCI_SCHED_H_
  11 #define _EFI_UHCI_SCHED_H_
  12
  13 #define UHCI_ASYNC_INT_SIGNATURE  SIGNATURE_32 ('u', 'h', 'c', 'a')
  14 //
  15 // The failure mask for USB transfer return status. If any of
  16 // these bit is set, the transfer failed. EFI_USB_ERR_NOEXECUTE
  17 // and EFI_USB_ERR_NAK are not considered as error condition:
  18 // the transfer is still going on.
  19 //
  20 #define USB_ERR_FAIL_MASK  (EFI_USB_ERR_STALL   | EFI_USB_ERR_BUFFER | \
  21                             EFI_USB_ERR_BABBLE  | EFI_USB_ERR_CRC    | \
  22                             EFI_USB_ERR_TIMEOUT | EFI_USB_ERR_BITSTUFF | \
  23                             EFI_USB_ERR_SYSTEM)
  24
  25 //
  26 // Structure to return the result of UHCI QH execution.
  27 // Result is the final result of the QH's QTD. NextToggle
  28 // is the next data toggle to use. Complete is the actual
  29 // length of data transferred.
  30 //
  31 typedef struct {
  32   UINT32    Result;
  33   UINT8     NextToggle;
  34   UINTN     Complete;
  35 } UHCI_QH_RESULT;
  36
  37 typedef struct _UHCI_ASYNC_REQUEST UHCI_ASYNC_REQUEST;
  38
  39 //
  40 // Structure used to manager the asynchronous interrupt transfers.
  41 //
  42 struct _UHCI_ASYNC_REQUEST {
  43   UINTN                              Signature;
  44   LIST_ENTRY                         Link;
  45   UHCI_ASYNC_REQUEST                 *Recycle;
  46
  47   //
  48   // Endpoint attributes
  49   //
  50   UINT8                              DevAddr;
  51   UINT8                              EndPoint;
  52   BOOLEAN                            IsLow;
  53   UINTN                              Interval;
  54
  55   //
  56   // Data and UHC structures
  57   //
  58   UHCI_QH_SW                         *QhSw;
  59   UHCI_TD_SW                         *FirstTd;
  60   UINT8                              *Data;   // Allocated host memory, not mapped memory
  61   UINTN                              DataLen;
  62   VOID                               *Mapping;
  63
  64   //
  65   // User callback and its context
  66   //
  67   EFI_ASYNC_USB_TRANSFER_CALLBACK    Callback;
  68   VOID                               *Context;
  69 };
  70
  71 #define UHCI_ASYNC_INT_FROM_LINK(a) \
  72           CR (a, UHCI_ASYNC_REQUEST, Link, UHCI_ASYNC_INT_SIGNATURE)
  73
  74 /**
  75   Create Frame List Structure.
  76
  77   @param  Uhc                    The UHCI device.
  78
  79   @return EFI_OUT_OF_RESOURCES   Can't allocate memory resources.
  80   @return EFI_UNSUPPORTED        Map memory fail.
  81   @return EFI_SUCCESS            Success.
  82
  83 **/
  84 EFI_STATUS
  85 UhciInitFrameList (
  86   IN USB_HC_DEV  *Uhc
  87   );
  88
  89 /**
  90   Destory FrameList buffer.
  91
  92   @param  Uhc                    The UHCI device.
  93
  94   @return None.
  95
  96 **/
  97 VOID
  98 UhciDestoryFrameList (
  99   IN USB_HC_DEV  *Uhc
 100   );
 101
 102 /**
 103   Convert the poll rate to the maxium 2^n that is smaller
 104   than Interval.
 105
 106   @param  Interval               The poll rate to convert.
 107
 108   @return The converted poll rate.
 109
 110 **/
 111 UINTN
 112 UhciConvertPollRate (
 113   IN  UINTN  Interval
 114   );
 115
 116 /**
 117   Link a queue head (for asynchronous interrupt transfer) to
 118   the frame list.
 119
 120   @param  Uhc                    The UHCI device.
 121   @param  Qh                     The queue head to link into.
 122
 123 **/
 124 VOID
 125 UhciLinkQhToFrameList (
 126   USB_HC_DEV  *Uhc,
 127   UHCI_QH_SW  *Qh
 128   );
 129
 130 /**
 131   Unlink QH from the frame list is easier: find all
 132   the precedence node, and pointer there next to QhSw's
 133   next.
 134
 135   @param  Uhc                    The UHCI device.
 136   @param  Qh                     The queue head to unlink.
 137
 138 **/
 139 VOID
 140 UhciUnlinkQhFromFrameList (
 141   USB_HC_DEV  *Uhc,
 142   UHCI_QH_SW  *Qh
 143   );
 144
 145 /**
 146   Check the result of the transfer.
 147
 148   @param  Uhc                    The UHCI device.
 149   @param  Qh                     The queue head of the transfer.
 150   @param  Td                     The first TDs of the transfer.
 151   @param  TimeOut                TimeOut value in milliseconds.
 152   @param  IsLow                  Is Low Speed Device.
 153   @param  QhResult               The variable to return result.
 154
 155   @retval EFI_SUCCESS            The transfer finished with success.
 156   @retval EFI_DEVICE_ERROR       Transfer failed.
 157
 158 **/
 159 EFI_STATUS
 160 UhciExecuteTransfer (
 161   IN  USB_HC_DEV      *Uhc,
 162   IN  UHCI_QH_SW      *Qh,
 163   IN  UHCI_TD_SW      *Td,
 164   IN  UINTN           TimeOut,
 165   IN  BOOLEAN         IsLow,
 166   OUT UHCI_QH_RESULT  *QhResult
 167   );
 168
 169 /**
 170   Create Async Request node, and Link to List.
 171
 172   @param  Uhc                    The UHCI device.
 173   @param  Qh                     The queue head of the transfer.
 174   @param  FirstTd                First TD of the transfer.
 175   @param  DevAddr                Device Address.
 176   @param  EndPoint               EndPoint Address.
 177   @param  DataLen                Data length.
 178   @param  Interval               Polling Interval when inserted to frame list.
 179   @param  Data                   Data buffer, unmapped.
 180   @param  Callback               Callback after interrupt transfeer.
 181   @param  Context                Callback Context passed as function parameter.
 182   @param  IsLow                  Is Low Speed.
 183
 184   @retval EFI_SUCCESS            An asynchronous transfer is created.
 185   @retval EFI_INVALID_PARAMETER  Paremeter is error.
 186   @retval EFI_OUT_OF_RESOURCES   Failed because of resource shortage.
 187
 188 **/
 189 EFI_STATUS
 190 UhciCreateAsyncReq (
 191   IN USB_HC_DEV                       *Uhc,
 192   IN UHCI_QH_SW                       *Qh,
 193   IN UHCI_TD_SW                       *FirstTd,
 194   IN UINT8                            DevAddr,
 195   IN UINT8                            EndPoint,
 196   IN UINTN                            DataLen,
 197   IN UINTN                            Interval,
 198   IN UINT8                            *Data,
 199   IN EFI_ASYNC_USB_TRANSFER_CALLBACK  Callback,
 200   IN VOID                             *Context,
 201   IN BOOLEAN                          IsLow
 202   );
 203
 204 /**
 205   Delete Async Interrupt QH and TDs.
 206
 207   @param  Uhc                    The UHCI device.
 208   @param  DevAddr                Device Address.
 209   @param  EndPoint               EndPoint Address.
 210   @param  Toggle                 The next data toggle to use.
 211
 212   @retval EFI_SUCCESS            The request is deleted.
 213   @retval EFI_INVALID_PARAMETER  Paremeter is error.
 214   @retval EFI_NOT_FOUND          The asynchronous isn't found.
 215
 216 **/
 217 EFI_STATUS
 218 UhciRemoveAsyncReq (
 219   IN  USB_HC_DEV  *Uhc,
 220   IN  UINT8       DevAddr,
 221   IN  UINT8       EndPoint,
 222   OUT UINT8       *Toggle
 223   );
 224
 225 /**
 226   Release all the asynchronous transfers on the lsit.
 227
 228   @param  Uhc                    The UHCI device.
 229
 230   @return None.
 231
 232 **/
 233 VOID
 234 UhciFreeAllAsyncReq (
 235   IN USB_HC_DEV  *Uhc
 236   );
 237
 238 /**
 239   Interrupt transfer periodic check handler.
 240
 241   @param  Event                  The event of the time.
 242   @param  Context                Context of the event, pointer to USB_HC_DEV.
 243
 244   @return None.
 245
 246 **/
 247 VOID
 248 EFIAPI
 249 UhciMonitorAsyncReqList (
 250   IN EFI_EVENT  Event,
 251   IN VOID       *Context
 252   );
 253
 254 #endif