MdeModulePkg/Bus/Pci/UhciDxe/UhciSched.h

   1 /** @file
   2
   3   The definition for EHCI register operation routines.
   4
   5 Copyright (c) 2007, 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  FrameBase              The base of the frame list.
 135   @param  Qh                     The queue head to link into.
 136
 137   @return None.
 138
 139 **/
 140 VOID
 141 UhciLinkQhToFrameList (
 142   UINT32                  *FrameBase,
 143   UHCI_QH_SW              *Qh
 144   );
 145
 146
 147 /**
 148   Unlink QH from the frame list is easier: find all
 149   the precedence node, and pointer there next to QhSw's
 150   next.
 151
 152   @param  FrameBase              The base address of the frame list.
 153   @param  Qh                     The queue head to unlink.
 154
 155   @return None.
 156
 157 **/
 158 VOID
 159 UhciUnlinkQhFromFrameList (
 160   UINT32                *FrameBase,
 161   UHCI_QH_SW            *Qh
 162   );
 163
 164
 165 /**
 166   Check the result of the transfer.
 167
 168   @param  Uhc                    The UHCI device.
 169   @param  Qh                     The queue head of the transfer.
 170   @param  Td                     The first TDs of the transfer.
 171   @param  TimeOut                TimeOut value in milliseconds.
 172   @param  IsLow                  Is Low Speed Device.
 173   @param  QhResult               The variable to return result.
 174
 175   @retval EFI_SUCCESS            The transfer finished with success.
 176   @retval EFI_DEVICE_ERROR       Transfer failed.
 177
 178 **/
 179 EFI_STATUS
 180 UhciExecuteTransfer (
 181   IN  USB_HC_DEV          *Uhc,
 182   IN  UHCI_QH_SW          *Qh,
 183   IN  UHCI_TD_SW          *Td,
 184   IN  UINTN               TimeOut,
 185   IN  BOOLEAN             IsLow,
 186   OUT UHCI_QH_RESULT      *QhResult
 187   );
 188
 189
 190 /**
 191   Create Async Request node, and Link to List.
 192
 193   @param  Uhc                    The UHCI device.
 194   @param  Qh                     The queue head of the transfer.
 195   @param  FirstTd                First TD of the transfer.
 196   @param  DevAddr                Device Address.
 197   @param  EndPoint               EndPoint Address.
 198   @param  DataLen                Data length.
 199   @param  Interval               Polling Interval when inserted to frame list.
 200   @param  Mapping                Mapping value.
 201   @param  Data                   Data buffer, unmapped.
 202   @param  Callback               Callback after interrupt transfeer.
 203   @param  Context                Callback Context passed as function parameter.
 204   @param  IsLow                  Is Low Speed.
 205
 206   @retval EFI_SUCCESS            An asynchronous transfer is created.
 207   @retval EFI_INVALID_PARAMETER  Paremeter is error.
 208   @retval EFI_OUT_OF_RESOURCES   Failed because of resource shortage.
 209
 210 **/
 211 EFI_STATUS
 212 UhciCreateAsyncReq (
 213   IN USB_HC_DEV                       *Uhc,
 214   IN UHCI_QH_SW                       *Qh,
 215   IN UHCI_TD_SW                       *FirstTd,
 216   IN UINT8                            DevAddr,
 217   IN UINT8                            EndPoint,
 218   IN UINTN                            DataLen,
 219   IN UINTN                            Interval,
 220   IN VOID                             *Mapping,
 221   IN UINT8                            *Data,
 222   IN EFI_ASYNC_USB_TRANSFER_CALLBACK  Callback,
 223   IN VOID                             *Context,
 224   IN BOOLEAN                          IsLow
 225   );
 226
 227
 228 /**
 229   Delete Async Interrupt QH and TDs.
 230
 231   @param  Uhc                    The UHCI device.
 232   @param  DevAddr                Device Address.
 233   @param  EndPoint               EndPoint Address.
 234   @param  Toggle                 The next data toggle to use.
 235
 236   @retval EFI_SUCCESS            The request is deleted.
 237   @retval EFI_INVALID_PARAMETER  Paremeter is error.
 238   @retval EFI_NOT_FOUND          The asynchronous isn't found.
 239
 240 **/
 241 EFI_STATUS
 242 UhciRemoveAsyncReq (
 243   IN  USB_HC_DEV          *Uhc,
 244   IN  UINT8               DevAddr,
 245   IN  UINT8               EndPoint,
 246   OUT UINT8               *Toggle
 247   );
 248
 249
 250 /**
 251   Release all the asynchronous transfers on the lsit.
 252
 253   @param  Uhc                    The UHCI device.
 254
 255   @return None.
 256
 257 **/
 258 VOID
 259 UhciFreeAllAsyncReq (
 260   IN USB_HC_DEV           *Uhc
 261   );
 262
 263
 264 /**
 265   Interrupt transfer periodic check handler.
 266
 267   @param  Event                  The event of the time.
 268   @param  Context                Context of the event, pointer to USB_HC_DEV.
 269
 270   @return None.
 271
 272 **/
 273 VOID
 274 UhciMonitorAsyncReqList (
 275   IN EFI_EVENT            Event,
 276   IN VOID                 *Context
 277   );
 278
 279 #endif