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