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