MdeModulePkg/Bus/Pci/UhciDxe/UhciSched.h

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