MdeModulePkg/Bus/Pci/SdMmcPciHcDxe/SdMmcPciHcDxe.h

   1 /** @file
   2
   3   Provides some data structure definitions used by the SD/MMC host controller driver.
   4
   5 Copyright (c) 2018-2019, NVIDIA CORPORATION. All rights reserved.
   6 Copyright (c) 2015 - 2020, Intel Corporation. All rights reserved.<BR>
   7 SPDX-License-Identifier: BSD-2-Clause-Patent
   8
   9 **/
  10
  11 #ifndef _SD_MMC_PCI_HC_DXE_H_
  12 #define _SD_MMC_PCI_HC_DXE_H_
  13
  14 #include <Uefi.h>
  15
  16 #include <IndustryStandard/Pci.h>
  17 #include <IndustryStandard/Emmc.h>
  18 #include <IndustryStandard/Sd.h>
  19
  20 #include <Library/UefiDriverEntryPoint.h>
  21 #include <Library/DebugLib.h>
  22 #include <Library/UefiBootServicesTableLib.h>
  23 #include <Library/BaseMemoryLib.h>
  24 #include <Library/MemoryAllocationLib.h>
  25 #include <Library/UefiLib.h>
  26 #include <Library/DevicePathLib.h>
  27 #include <Library/PcdLib.h>
  28
  29 #include <Protocol/DevicePath.h>
  30 #include <Protocol/PciIo.h>
  31 #include <Protocol/DriverBinding.h>
  32 #include <Protocol/ComponentName.h>
  33 #include <Protocol/ComponentName2.h>
  34 #include <Protocol/SdMmcOverride.h>
  35 #include <Protocol/SdMmcPassThru.h>
  36
  37 #include "SdMmcPciHci.h"
  38
  39 extern EFI_COMPONENT_NAME_PROTOCOL   gSdMmcPciHcComponentName;
  40 extern EFI_COMPONENT_NAME2_PROTOCOL  gSdMmcPciHcComponentName2;
  41 extern EFI_DRIVER_BINDING_PROTOCOL   gSdMmcPciHcDriverBinding;
  42
  43 extern EDKII_SD_MMC_OVERRIDE  *mOverride;
  44
  45 #define SD_MMC_HC_PRIVATE_SIGNATURE  SIGNATURE_32 ('s', 'd', 't', 'f')
  46
  47 #define SD_MMC_HC_PRIVATE_FROM_THIS(a) \
  48     CR(a, SD_MMC_HC_PRIVATE_DATA, PassThru, SD_MMC_HC_PRIVATE_SIGNATURE)
  49
  50 //
  51 // Generic time out value, 1 microsecond as unit.
  52 //
  53 #define SD_MMC_HC_GENERIC_TIMEOUT  (PcdGet32 (PcdSdMmcGenericTimeoutValue))
  54
  55 //
  56 // SD/MMC async transfer timer interval, set by experience.
  57 // The unit is 100us, takes 1ms as interval.
  58 //
  59 #define SD_MMC_HC_ASYNC_TIMER  EFI_TIMER_PERIOD_MILLISECONDS(1)
  60 //
  61 // SD/MMC removable device enumeration timer interval, set by experience.
  62 // The unit is 100us, takes 100ms as interval.
  63 //
  64 #define SD_MMC_HC_ENUM_TIMER  EFI_TIMER_PERIOD_MILLISECONDS(100)
  65
  66 typedef enum {
  67   UnknownCardType,
  68   SdCardType,
  69   SdioCardType,
  70   MmcCardType,
  71   EmmcCardType
  72 } SD_MMC_CARD_TYPE;
  73
  74 typedef enum {
  75   RemovableSlot,
  76   EmbeddedSlot,
  77   SharedBusSlot,
  78   UnknownSlot
  79 } EFI_SD_MMC_SLOT_TYPE;
  80
  81 typedef struct {
  82   BOOLEAN                              Enable;
  83   EFI_SD_MMC_SLOT_TYPE                 SlotType;
  84   BOOLEAN                              MediaPresent;
  85   BOOLEAN                              Initialized;
  86   SD_MMC_CARD_TYPE                     CardType;
  87   UINT64                               CurrentFreq;
  88   EDKII_SD_MMC_OPERATING_PARAMETERS    OperatingParameters;
  89 } SD_MMC_HC_SLOT;
  90
  91 typedef struct {
  92   UINTN                            Signature;
  93
  94   EFI_HANDLE                       ControllerHandle;
  95   EFI_PCI_IO_PROTOCOL              *PciIo;
  96
  97   EFI_SD_MMC_PASS_THRU_PROTOCOL    PassThru;
  98
  99   UINT64                           PciAttributes;
 100   //
 101   // The field is used to record the previous slot in GetNextSlot().
 102   //
 103   UINT8                            PreviousSlot;
 104   //
 105   // For Non-blocking operation.
 106   //
 107   EFI_EVENT                        TimerEvent;
 108   //
 109   // For Sd removable device enumeration.
 110   //
 111   EFI_EVENT                        ConnectEvent;
 112   LIST_ENTRY                       Queue;
 113
 114   SD_MMC_HC_SLOT                   Slot[SD_MMC_HC_MAX_SLOT];
 115   SD_MMC_HC_SLOT_CAP               Capability[SD_MMC_HC_MAX_SLOT];
 116   UINT64                           MaxCurrent[SD_MMC_HC_MAX_SLOT];
 117   UINT16                           ControllerVersion[SD_MMC_HC_MAX_SLOT];
 118
 119   //
 120   // Some controllers may require to override base clock frequency
 121   // value stored in Capabilities Register 1.
 122   //
 123   UINT32                           BaseClkFreq[SD_MMC_HC_MAX_SLOT];
 124 } SD_MMC_HC_PRIVATE_DATA;
 125
 126 typedef struct {
 127   SD_MMC_BUS_MODE                 BusTiming;
 128   UINT8                           BusWidth;
 129   UINT32                          ClockFreq;
 130   EDKII_SD_MMC_DRIVER_STRENGTH    DriverStrength;
 131 } SD_MMC_BUS_SETTINGS;
 132
 133 #define SD_MMC_HC_TRB_SIG  SIGNATURE_32 ('T', 'R', 'B', 'T')
 134
 135 #define SD_MMC_TRB_RETRIES  5
 136
 137 //
 138 // TRB (Transfer Request Block) contains information for the cmd request.
 139 //
 140 typedef struct {
 141   UINT32                                 Signature;
 142   LIST_ENTRY                             TrbList;
 143
 144   UINT8                                  Slot;
 145   UINT16                                 BlockSize;
 146
 147   EFI_SD_MMC_PASS_THRU_COMMAND_PACKET    *Packet;
 148   VOID                                   *Data;
 149   UINT32                                 DataLen;
 150   BOOLEAN                                Read;
 151   EFI_PHYSICAL_ADDRESS                   DataPhy;
 152   VOID                                   *DataMap;
 153   SD_MMC_HC_TRANSFER_MODE                Mode;
 154   SD_MMC_HC_ADMA_LENGTH_MODE             AdmaLengthMode;
 155
 156   EFI_EVENT                              Event;
 157   BOOLEAN                                Started;
 158   BOOLEAN                                CommandComplete;
 159   UINT64                                 Timeout;
 160   UINT32                                 Retries;
 161
 162   BOOLEAN                                PioModeTransferCompleted;
 163   UINT32                                 PioBlockIndex;
 164
 165   SD_MMC_HC_ADMA_32_DESC_LINE            *Adma32Desc;
 166   SD_MMC_HC_ADMA_64_V3_DESC_LINE         *Adma64V3Desc;
 167   SD_MMC_HC_ADMA_64_V4_DESC_LINE         *Adma64V4Desc;
 168   EFI_PHYSICAL_ADDRESS                   AdmaDescPhy;
 169   VOID                                   *AdmaMap;
 170   UINT32                                 AdmaPages;
 171
 172   SD_MMC_HC_PRIVATE_DATA                 *Private;
 173 } SD_MMC_HC_TRB;
 174
 175 #define SD_MMC_HC_TRB_FROM_THIS(a) \
 176     CR(a, SD_MMC_HC_TRB, TrbList, SD_MMC_HC_TRB_SIG)
 177
 178 //
 179 // Task for Non-blocking mode.
 180 //
 181 typedef struct {
 182   UINT32                                 Signature;
 183   LIST_ENTRY                             Link;
 184
 185   UINT8                                  Slot;
 186   EFI_SD_MMC_PASS_THRU_COMMAND_PACKET    *Packet;
 187   BOOLEAN                                IsStart;
 188   EFI_EVENT                              Event;
 189   UINT64                                 RetryTimes;
 190   BOOLEAN                                InfiniteWait;
 191   VOID                                   *Map;
 192   VOID                                   *MapAddress;
 193 } SD_MMC_HC_QUEUE;
 194
 195 //
 196 // Prototypes
 197 //
 198
 199 /**
 200   Execute card identification procedure.
 201
 202   @param[in] Private        A pointer to the SD_MMC_HC_PRIVATE_DATA instance.
 203   @param[in] Slot           The slot number of the SD card to send the command to.
 204
 205   @retval EFI_SUCCESS       The card is identified correctly.
 206   @retval Others            The card can't be identified.
 207
 208 **/
 209 typedef
 210 EFI_STATUS
 211 (*CARD_TYPE_DETECT_ROUTINE) (
 212   IN SD_MMC_HC_PRIVATE_DATA  *Private,
 213   IN UINT8                   Slot
 214   );
 215
 216 /**
 217   Sends SD command to an SD card that is attached to the SD controller.
 218
 219   The PassThru() function sends the SD command specified by Packet to the SD card
 220   specified by Slot.
 221
 222   If Packet is successfully sent to the SD card, then EFI_SUCCESS is returned.
 223
 224   If a device error occurs while sending the Packet, then EFI_DEVICE_ERROR is returned.
 225
 226   If Slot is not in a valid range for the SD controller, then EFI_INVALID_PARAMETER
 227   is returned.
 228
 229   If Packet defines a data command but both InDataBuffer and OutDataBuffer are NULL,
 230   EFI_INVALID_PARAMETER is returned.
 231
 232   @param[in]     This           A pointer to the EFI_SD_MMC_PASS_THRU_PROTOCOL instance.
 233   @param[in]     Slot           The slot number of the SD card to send the command to.
 234   @param[in,out] Packet         A pointer to the SD command data structure.
 235   @param[in]     Event          If Event is NULL, blocking I/O is performed. If Event is
 236                                 not NULL, then nonblocking I/O is performed, and Event
 237                                 will be signaled when the Packet completes.
 238
 239   @retval EFI_SUCCESS           The SD Command Packet was sent by the host.
 240   @retval EFI_DEVICE_ERROR      A device error occurred while attempting to send the SD
 241                                 command Packet.
 242   @retval EFI_INVALID_PARAMETER Packet, Slot, or the contents of the Packet is invalid.
 243   @retval EFI_INVALID_PARAMETER Packet defines a data command but both InDataBuffer and
 244                                 OutDataBuffer are NULL.
 245   @retval EFI_NO_MEDIA          SD Device not present in the Slot.
 246   @retval EFI_UNSUPPORTED       The command described by the SD Command Packet is not
 247                                 supported by the host controller.
 248   @retval EFI_BAD_BUFFER_SIZE   The InTransferLength or OutTransferLength exceeds the
 249                                 limit supported by SD card ( i.e. if the number of bytes
 250                                 exceed the Last LBA).
 251
 252 **/
 253 EFI_STATUS
 254 EFIAPI
 255 SdMmcPassThruPassThru (
 256   IN     EFI_SD_MMC_PASS_THRU_PROTOCOL        *This,
 257   IN     UINT8                                Slot,
 258   IN OUT EFI_SD_MMC_PASS_THRU_COMMAND_PACKET  *Packet,
 259   IN     EFI_EVENT                            Event    OPTIONAL
 260   );
 261
 262 /**
 263   Used to retrieve next slot numbers supported by the SD controller. The function
 264   returns information about all available slots (populated or not-populated).
 265
 266   The GetNextSlot() function retrieves the next slot number on an SD controller.
 267   If on input Slot is 0xFF, then the slot number of the first slot on the SD controller
 268   is returned.
 269
 270   If Slot is a slot number that was returned on a previous call to GetNextSlot(), then
 271   the slot number of the next slot on the SD controller is returned.
 272
 273   If Slot is not 0xFF and Slot was not returned on a previous call to GetNextSlot(),
 274   EFI_INVALID_PARAMETER is returned.
 275
 276   If Slot is the slot number of the last slot on the SD controller, then EFI_NOT_FOUND
 277   is returned.
 278
 279   @param[in]     This           A pointer to the EFI_SD_MMMC_PASS_THRU_PROTOCOL instance.
 280   @param[in,out] Slot           On input, a pointer to a slot number on the SD controller.
 281                                 On output, a pointer to the next slot number on the SD controller.
 282                                 An input value of 0xFF retrieves the first slot number on the SD
 283                                 controller.
 284
 285   @retval EFI_SUCCESS           The next slot number on the SD controller was returned in Slot.
 286   @retval EFI_NOT_FOUND         There are no more slots on this SD controller.
 287   @retval EFI_INVALID_PARAMETER Slot is not 0xFF and Slot was not returned on a previous call
 288                                 to GetNextSlot().
 289
 290 **/
 291 EFI_STATUS
 292 EFIAPI
 293 SdMmcPassThruGetNextSlot (
 294   IN     EFI_SD_MMC_PASS_THRU_PROTOCOL  *This,
 295   IN OUT UINT8                          *Slot
 296   );
 297
 298 /**
 299   Used to allocate and build a device path node for an SD card on the SD controller.
 300
 301   The BuildDevicePath() function allocates and builds a single device node for the SD
 302   card specified by Slot.
 303
 304   If the SD card specified by Slot is not present on the SD controller, then EFI_NOT_FOUND
 305   is returned.
 306
 307   If DevicePath is NULL, then EFI_INVALID_PARAMETER is returned.
 308
 309   If there are not enough resources to allocate the device path node, then EFI_OUT_OF_RESOURCES
 310   is returned.
 311
 312   Otherwise, DevicePath is allocated with the boot service AllocatePool(), the contents of
 313   DevicePath are initialized to describe the SD card specified by Slot, and EFI_SUCCESS is
 314   returned.
 315
 316   @param[in]     This           A pointer to the EFI_SD_MMMC_PASS_THRU_PROTOCOL instance.
 317   @param[in]     Slot           Specifies the slot number of the SD card for which a device
 318                                 path node is to be allocated and built.
 319   @param[in,out] DevicePath     A pointer to a single device path node that describes the SD
 320                                 card specified by Slot. This function is responsible for
 321                                 allocating the buffer DevicePath with the boot service
 322                                 AllocatePool(). It is the caller's responsibility to free
 323                                 DevicePath when the caller is finished with DevicePath.
 324
 325   @retval EFI_SUCCESS           The device path node that describes the SD card specified by
 326                                 Slot was allocated and returned in DevicePath.
 327   @retval EFI_NOT_FOUND         The SD card specified by Slot does not exist on the SD controller.
 328   @retval EFI_INVALID_PARAMETER DevicePath is NULL.
 329   @retval EFI_OUT_OF_RESOURCES  There are not enough resources to allocate DevicePath.
 330
 331 **/
 332 EFI_STATUS
 333 EFIAPI
 334 SdMmcPassThruBuildDevicePath (
 335   IN     EFI_SD_MMC_PASS_THRU_PROTOCOL  *This,
 336   IN     UINT8                          Slot,
 337   IN OUT EFI_DEVICE_PATH_PROTOCOL       **DevicePath
 338   );
 339
 340 /**
 341   This function retrieves an SD card slot number based on the input device path.
 342
 343   The GetSlotNumber() function retrieves slot number for the SD card specified by
 344   the DevicePath node. If DevicePath is NULL, EFI_INVALID_PARAMETER is returned.
 345
 346   If DevicePath is not a device path node type that the SD Pass Thru driver supports,
 347   EFI_UNSUPPORTED is returned.
 348
 349   @param[in]  This              A pointer to the EFI_SD_MMC_PASS_THRU_PROTOCOL instance.
 350   @param[in]  DevicePath        A pointer to the device path node that describes a SD
 351                                 card on the SD controller.
 352   @param[out] Slot              On return, points to the slot number of an SD card on
 353                                 the SD controller.
 354
 355   @retval EFI_SUCCESS           SD card slot number is returned in Slot.
 356   @retval EFI_INVALID_PARAMETER Slot or DevicePath is NULL.
 357   @retval EFI_UNSUPPORTED       DevicePath is not a device path node type that the SD
 358                                 Pass Thru driver supports.
 359
 360 **/
 361 EFI_STATUS
 362 EFIAPI
 363 SdMmcPassThruGetSlotNumber (
 364   IN  EFI_SD_MMC_PASS_THRU_PROTOCOL  *This,
 365   IN  EFI_DEVICE_PATH_PROTOCOL       *DevicePath,
 366   OUT UINT8                          *Slot
 367   );
 368
 369 /**
 370   Resets an SD card that is connected to the SD controller.
 371
 372   The ResetDevice() function resets the SD card specified by Slot.
 373
 374   If this SD controller does not support a device reset operation, EFI_UNSUPPORTED is
 375   returned.
 376
 377   If Slot is not in a valid slot number for this SD controller, EFI_INVALID_PARAMETER
 378   is returned.
 379
 380   If the device reset operation is completed, EFI_SUCCESS is returned.
 381
 382   @param[in]  This              A pointer to the EFI_SD_MMC_PASS_THRU_PROTOCOL instance.
 383   @param[in]  Slot              Specifies the slot number of the SD card to be reset.
 384
 385   @retval EFI_SUCCESS           The SD card specified by Slot was reset.
 386   @retval EFI_UNSUPPORTED       The SD controller does not support a device reset operation.
 387   @retval EFI_INVALID_PARAMETER Slot number is invalid.
 388   @retval EFI_NO_MEDIA          SD Device not present in the Slot.
 389   @retval EFI_DEVICE_ERROR      The reset command failed due to a device error
 390
 391 **/
 392 EFI_STATUS
 393 EFIAPI
 394 SdMmcPassThruResetDevice (
 395   IN EFI_SD_MMC_PASS_THRU_PROTOCOL  *This,
 396   IN UINT8                          Slot
 397   );
 398
 399 //
 400 // Driver model protocol interfaces
 401 //
 402
 403 /**
 404   Tests to see if this driver supports a given controller. If a child device is provided,
 405   it further tests to see if this driver supports creating a handle for the specified child device.
 406
 407   This function checks to see if the driver specified by This supports the device specified by
 408   ControllerHandle. Drivers will typically use the device path attached to
 409   ControllerHandle and/or the services from the bus I/O abstraction attached to
 410   ControllerHandle to determine if the driver supports ControllerHandle. This function
 411   may be called many times during platform initialization. In order to reduce boot times, the tests
 412   performed by this function must be very small, and take as little time as possible to execute. This
 413   function must not change the state of any hardware devices, and this function must be aware that the
 414   device specified by ControllerHandle may already be managed by the same driver or a
 415   different driver. This function must match its calls to AllocatePages() with FreePages(),
 416   AllocatePool() with FreePool(), and OpenProtocol() with CloseProtocol().
 417   Since ControllerHandle may have been previously started by the same driver, if a protocol is
 418   already in the opened state, then it must not be closed with CloseProtocol(). This is required
 419   to guarantee the state of ControllerHandle is not modified by this function.
 420
 421   @param[in]  This                 A pointer to the EFI_DRIVER_BINDING_PROTOCOL instance.
 422   @param[in]  ControllerHandle     The handle of the controller to test. This handle
 423                                    must support a protocol interface that supplies
 424                                    an I/O abstraction to the driver.
 425   @param[in]  RemainingDevicePath  A pointer to the remaining portion of a device path.  This
 426                                    parameter is ignored by device drivers, and is optional for bus
 427                                    drivers. For bus drivers, if this parameter is not NULL, then
 428                                    the bus driver must determine if the bus controller specified
 429                                    by ControllerHandle and the child controller specified
 430                                    by RemainingDevicePath are both supported by this
 431                                    bus driver.
 432
 433   @retval EFI_SUCCESS              The device specified by ControllerHandle and
 434                                    RemainingDevicePath is supported by the driver specified by This.
 435   @retval EFI_ALREADY_STARTED      The device specified by ControllerHandle and
 436                                    RemainingDevicePath is already being managed by the driver
 437                                    specified by This.
 438   @retval EFI_ACCESS_DENIED        The device specified by ControllerHandle and
 439                                    RemainingDevicePath is already being managed by a different
 440                                    driver or an application that requires exclusive access.
 441                                    Currently not implemented.
 442   @retval EFI_UNSUPPORTED          The device specified by ControllerHandle and
 443                                    RemainingDevicePath is not supported by the driver specified by This.
 444 **/
 445 EFI_STATUS
 446 EFIAPI
 447 SdMmcPciHcDriverBindingSupported (
 448   IN EFI_DRIVER_BINDING_PROTOCOL  *This,
 449   IN EFI_HANDLE                   Controller,
 450   IN EFI_DEVICE_PATH_PROTOCOL     *RemainingDevicePath
 451   );
 452
 453 /**
 454   Starts a device controller or a bus controller.
 455
 456   The Start() function is designed to be invoked from the EFI boot service ConnectController().
 457   As a result, much of the error checking on the parameters to Start() has been moved into this
 458   common boot service. It is legal to call Start() from other locations,
 459   but the following calling restrictions must be followed or the system behavior will not be deterministic.
 460   1. ControllerHandle must be a valid EFI_HANDLE.
 461   2. If RemainingDevicePath is not NULL, then it must be a pointer to a naturally aligned
 462      EFI_DEVICE_PATH_PROTOCOL.
 463   3. Prior to calling Start(), the Supported() function for the driver specified by This must
 464      have been called with the same calling parameters, and Supported() must have returned EFI_SUCCESS.
 465
 466   @param[in]  This                 A pointer to the EFI_DRIVER_BINDING_PROTOCOL instance.
 467   @param[in]  ControllerHandle     The handle of the controller to start. This handle
 468                                    must support a protocol interface that supplies
 469                                    an I/O abstraction to the driver.
 470   @param[in]  RemainingDevicePath  A pointer to the remaining portion of a device path.  This
 471                                    parameter is ignored by device drivers, and is optional for bus
 472                                    drivers. For a bus driver, if this parameter is NULL, then handles
 473                                    for all the children of Controller are created by this driver.
 474                                    If this parameter is not NULL and the first Device Path Node is
 475                                    not the End of Device Path Node, then only the handle for the
 476                                    child device specified by the first Device Path Node of
 477                                    RemainingDevicePath is created by this driver.
 478                                    If the first Device Path Node of RemainingDevicePath is
 479                                    the End of Device Path Node, no child handle is created by this
 480                                    driver.
 481
 482   @retval EFI_SUCCESS              The device was started.
 483   @retval EFI_DEVICE_ERROR         The device could not be started due to a device error.Currently not implemented.
 484   @retval EFI_OUT_OF_RESOURCES     The request could not be completed due to a lack of resources.
 485   @retval Others                   The driver failded to start the device.
 486
 487 **/
 488 EFI_STATUS
 489 EFIAPI
 490 SdMmcPciHcDriverBindingStart (
 491   IN EFI_DRIVER_BINDING_PROTOCOL  *This,
 492   IN EFI_HANDLE                   Controller,
 493   IN EFI_DEVICE_PATH_PROTOCOL     *RemainingDevicePath
 494   );
 495
 496 /**
 497   Stops a device controller or a bus controller.
 498
 499   The Stop() function is designed to be invoked from the EFI boot service DisconnectController().
 500   As a result, much of the error checking on the parameters to Stop() has been moved
 501   into this common boot service. It is legal to call Stop() from other locations,
 502   but the following calling restrictions must be followed or the system behavior will not be deterministic.
 503   1. ControllerHandle must be a valid EFI_HANDLE that was used on a previous call to this
 504      same driver's Start() function.
 505   2. The first NumberOfChildren handles of ChildHandleBuffer must all be a valid
 506      EFI_HANDLE. In addition, all of these handles must have been created in this driver's
 507      Start() function, and the Start() function must have called OpenProtocol() on
 508      ControllerHandle with an Attribute of EFI_OPEN_PROTOCOL_BY_CHILD_CONTROLLER.
 509
 510   @param[in]  This              A pointer to the EFI_DRIVER_BINDING_PROTOCOL instance.
 511   @param[in]  ControllerHandle  A handle to the device being stopped. The handle must
 512                                 support a bus specific I/O protocol for the driver
 513                                 to use to stop the device.
 514   @param[in]  NumberOfChildren  The number of child device handles in ChildHandleBuffer.
 515   @param[in]  ChildHandleBuffer An array of child handles to be freed. May be NULL
 516                                 if NumberOfChildren is 0.
 517
 518   @retval EFI_SUCCESS           The device was stopped.
 519   @retval EFI_DEVICE_ERROR      The device could not be stopped due to a device error.
 520
 521 **/
 522 EFI_STATUS
 523 EFIAPI
 524 SdMmcPciHcDriverBindingStop (
 525   IN  EFI_DRIVER_BINDING_PROTOCOL  *This,
 526   IN  EFI_HANDLE                   Controller,
 527   IN  UINTN                        NumberOfChildren,
 528   IN  EFI_HANDLE                   *ChildHandleBuffer
 529   );
 530
 531 //
 532 // EFI Component Name Functions
 533 //
 534
 535 /**
 536   Retrieves a Unicode string that is the user readable name of the driver.
 537
 538   This function retrieves the user readable name of a driver in the form of a
 539   Unicode string. If the driver specified by This has a user readable name in
 540   the language specified by Language, then a pointer to the driver name is
 541   returned in DriverName, and EFI_SUCCESS is returned. If the driver specified
 542   by This does not support the language specified by Language,
 543   then EFI_UNSUPPORTED is returned.
 544
 545   @param  This[in]              A pointer to the EFI_COMPONENT_NAME2_PROTOCOL or
 546                                 EFI_COMPONENT_NAME_PROTOCOL instance.
 547
 548   @param  Language[in]          A pointer to a Null-terminated ASCII string
 549                                 array indicating the language. This is the
 550                                 language of the driver name that the caller is
 551                                 requesting, and it must match one of the
 552                                 languages specified in SupportedLanguages. The
 553                                 number of languages supported by a driver is up
 554                                 to the driver writer. Language is specified
 555                                 in RFC 4646 or ISO 639-2 language code format.
 556
 557   @param  DriverName[out]       A pointer to the Unicode string to return.
 558                                 This Unicode string is the name of the
 559                                 driver specified by This in the language
 560                                 specified by Language.
 561
 562   @retval EFI_SUCCESS           The Unicode string for the Driver specified by
 563                                 This and the language specified by Language was
 564                                 returned in DriverName.
 565
 566   @retval EFI_INVALID_PARAMETER Language is NULL.
 567
 568   @retval EFI_INVALID_PARAMETER DriverName is NULL.
 569
 570   @retval EFI_UNSUPPORTED       The driver specified by This does not support
 571                                 the language specified by Language.
 572
 573 **/
 574 EFI_STATUS
 575 EFIAPI
 576 SdMmcPciHcComponentNameGetDriverName (
 577   IN  EFI_COMPONENT_NAME_PROTOCOL  *This,
 578   IN  CHAR8                        *Language,
 579   OUT CHAR16                       **DriverName
 580   );
 581
 582 /**
 583   Retrieves a Unicode string that is the user readable name of the controller
 584   that is being managed by a driver.
 585
 586   This function retrieves the user readable name of the controller specified by
 587   ControllerHandle and ChildHandle in the form of a Unicode string. If the
 588   driver specified by This has a user readable name in the language specified by
 589   Language, then a pointer to the controller name is returned in ControllerName,
 590   and EFI_SUCCESS is returned.  If the driver specified by This is not currently
 591   managing the controller specified by ControllerHandle and ChildHandle,
 592   then EFI_UNSUPPORTED is returned.  If the driver specified by This does not
 593   support the language specified by Language, then EFI_UNSUPPORTED is returned.
 594
 595   @param  This[in]              A pointer to the EFI_COMPONENT_NAME2_PROTOCOL or
 596                                 EFI_COMPONENT_NAME_PROTOCOL instance.
 597
 598   @param  ControllerHandle[in]  The handle of a controller that the driver
 599                                 specified by This is managing.  This handle
 600                                 specifies the controller whose name is to be
 601                                 returned.
 602
 603   @param  ChildHandle[in]       The handle of the child controller to retrieve
 604                                 the name of.  This is an optional parameter that
 605                                 may be NULL.  It will be NULL for device
 606                                 drivers.  It will also be NULL for a bus drivers
 607                                 that wish to retrieve the name of the bus
 608                                 controller.  It will not be NULL for a bus
 609                                 driver that wishes to retrieve the name of a
 610                                 child controller.
 611
 612   @param  Language[in]          A pointer to a Null-terminated ASCII string
 613                                 array indicating the language.  This is the
 614                                 language of the driver name that the caller is
 615                                 requesting, and it must match one of the
 616                                 languages specified in SupportedLanguages. The
 617                                 number of languages supported by a driver is up
 618                                 to the driver writer. Language is specified in
 619                                 RFC 4646 or ISO 639-2 language code format.
 620
 621   @param  ControllerName[out]   A pointer to the Unicode string to return.
 622                                 This Unicode string is the name of the
 623                                 controller specified by ControllerHandle and
 624                                 ChildHandle in the language specified by
 625                                 Language from the point of view of the driver
 626                                 specified by This.
 627
 628   @retval EFI_SUCCESS           The Unicode string for the user readable name in
 629                                 the language specified by Language for the
 630                                 driver specified by This was returned in
 631                                 DriverName.
 632
 633   @retval EFI_INVALID_PARAMETER ControllerHandle is not a valid EFI_HANDLE.
 634
 635   @retval EFI_INVALID_PARAMETER ChildHandle is not NULL and it is not a valid
 636                                 EFI_HANDLE.
 637
 638   @retval EFI_INVALID_PARAMETER Language is NULL.
 639
 640   @retval EFI_INVALID_PARAMETER ControllerName is NULL.
 641
 642   @retval EFI_UNSUPPORTED       The driver specified by This is not currently
 643                                 managing the controller specified by
 644                                 ControllerHandle and ChildHandle.
 645
 646   @retval EFI_UNSUPPORTED       The driver specified by This does not support
 647                                 the language specified by Language.
 648
 649 **/
 650 EFI_STATUS
 651 EFIAPI
 652 SdMmcPciHcComponentNameGetControllerName (
 653   IN  EFI_COMPONENT_NAME_PROTOCOL  *This,
 654   IN  EFI_HANDLE                   ControllerHandle,
 655   IN  EFI_HANDLE                   ChildHandle  OPTIONAL,
 656   IN  CHAR8                        *Language,
 657   OUT CHAR16                       **ControllerName
 658   );
 659
 660 /**
 661   Create a new TRB for the SD/MMC cmd request.
 662
 663   @param[in] Private        A pointer to the SD_MMC_HC_PRIVATE_DATA instance.
 664   @param[in] Slot           The slot number of the SD card to send the command to.
 665   @param[in] Packet         A pointer to the SD command data structure.
 666   @param[in] Event          If Event is NULL, blocking I/O is performed. If Event is
 667                             not NULL, then nonblocking I/O is performed, and Event
 668                             will be signaled when the Packet completes.
 669
 670   @return Created Trb or NULL.
 671
 672 **/
 673 SD_MMC_HC_TRB *
 674 SdMmcCreateTrb (
 675   IN SD_MMC_HC_PRIVATE_DATA               *Private,
 676   IN UINT8                                Slot,
 677   IN EFI_SD_MMC_PASS_THRU_COMMAND_PACKET  *Packet,
 678   IN EFI_EVENT                            Event
 679   );
 680
 681 /**
 682   Free the resource used by the TRB.
 683
 684   @param[in] Trb            The pointer to the SD_MMC_HC_TRB instance.
 685
 686 **/
 687 VOID
 688 SdMmcFreeTrb (
 689   IN SD_MMC_HC_TRB  *Trb
 690   );
 691
 692 /**
 693   Check if the env is ready for execute specified TRB.
 694
 695   @param[in] Private        A pointer to the SD_MMC_HC_PRIVATE_DATA instance.
 696   @param[in] Trb            The pointer to the SD_MMC_HC_TRB instance.
 697
 698   @retval EFI_SUCCESS       The env is ready for TRB execution.
 699   @retval EFI_NOT_READY     The env is not ready for TRB execution.
 700   @retval Others            Some erros happen.
 701
 702 **/
 703 EFI_STATUS
 704 SdMmcCheckTrbEnv (
 705   IN SD_MMC_HC_PRIVATE_DATA  *Private,
 706   IN SD_MMC_HC_TRB           *Trb
 707   );
 708
 709 /**
 710   Wait for the env to be ready for execute specified TRB.
 711
 712   @param[in] Private        A pointer to the SD_MMC_HC_PRIVATE_DATA instance.
 713   @param[in] Trb            The pointer to the SD_MMC_HC_TRB instance.
 714
 715   @retval EFI_SUCCESS       The env is ready for TRB execution.
 716   @retval EFI_TIMEOUT       The env is not ready for TRB execution in time.
 717   @retval Others            Some erros happen.
 718
 719 **/
 720 EFI_STATUS
 721 SdMmcWaitTrbEnv (
 722   IN SD_MMC_HC_PRIVATE_DATA  *Private,
 723   IN SD_MMC_HC_TRB           *Trb
 724   );
 725
 726 /**
 727   Execute the specified TRB.
 728
 729   @param[in] Private        A pointer to the SD_MMC_HC_PRIVATE_DATA instance.
 730   @param[in] Trb            The pointer to the SD_MMC_HC_TRB instance.
 731
 732   @retval EFI_SUCCESS       The TRB is sent to host controller successfully.
 733   @retval Others            Some erros happen when sending this request to the host controller.
 734
 735 **/
 736 EFI_STATUS
 737 SdMmcExecTrb (
 738   IN SD_MMC_HC_PRIVATE_DATA  *Private,
 739   IN SD_MMC_HC_TRB           *Trb
 740   );
 741
 742 /**
 743   Check the TRB execution result.
 744
 745   @param[in] Private        A pointer to the SD_MMC_HC_PRIVATE_DATA instance.
 746   @param[in] Trb            The pointer to the SD_MMC_HC_TRB instance.
 747
 748   @retval EFI_SUCCESS       The TRB is executed successfully.
 749   @retval EFI_NOT_READY     The TRB is not completed for execution.
 750   @retval Others            Some erros happen when executing this request.
 751
 752 **/
 753 EFI_STATUS
 754 SdMmcCheckTrbResult (
 755   IN SD_MMC_HC_PRIVATE_DATA  *Private,
 756   IN SD_MMC_HC_TRB           *Trb
 757   );
 758
 759 /**
 760   Wait for the TRB execution result.
 761
 762   @param[in] Private        A pointer to the SD_MMC_HC_PRIVATE_DATA instance.
 763   @param[in] Trb            The pointer to the SD_MMC_HC_TRB instance.
 764
 765   @retval EFI_SUCCESS       The TRB is executed successfully.
 766   @retval Others            Some erros happen when executing this request.
 767
 768 **/
 769 EFI_STATUS
 770 SdMmcWaitTrbResult (
 771   IN SD_MMC_HC_PRIVATE_DATA  *Private,
 772   IN SD_MMC_HC_TRB           *Trb
 773   );
 774
 775 /**
 776   Execute EMMC device identification procedure.
 777
 778   Refer to EMMC Electrical Standard Spec 5.1 Section 6.4 for details.
 779
 780   @param[in] Private        A pointer to the SD_MMC_HC_PRIVATE_DATA instance.
 781   @param[in] Slot           The slot number of the SD card to send the command to.
 782
 783   @retval EFI_SUCCESS       There is a EMMC card.
 784   @retval Others            There is not a EMMC card.
 785
 786 **/
 787 EFI_STATUS
 788 EmmcIdentification (
 789   IN SD_MMC_HC_PRIVATE_DATA  *Private,
 790   IN UINT8                   Slot
 791   );
 792
 793 /**
 794   Execute EMMC device identification procedure.
 795
 796   Refer to EMMC Electrical Standard Spec 5.1 Section 6.4 for details.
 797
 798   @param[in] Private        A pointer to the SD_MMC_HC_PRIVATE_DATA instance.
 799   @param[in] Slot           The slot number of the SD card to send the command to.
 800
 801   @retval EFI_SUCCESS       There is a EMMC card.
 802   @retval Others            There is not a EMMC card.
 803
 804 **/
 805 EFI_STATUS
 806 SdCardIdentification (
 807   IN SD_MMC_HC_PRIVATE_DATA  *Private,
 808   IN UINT8                   Slot
 809   );
 810
 811 /**
 812   SD/MMC card clock supply.
 813
 814   Refer to SD Host Controller Simplified spec 3.0 Section 3.2.1 for details.
 815
 816   @param[in] Private         A pointer to the SD_MMC_HC_PRIVATE_DATA instance.
 817   @param[in] Slot            The slot number of the SD card to send the command to.
 818   @param[in] BusTiming       BusTiming at which the frequency change is done.
 819   @param[in] FirstTimeSetup  Flag to indicate whether the clock is being setup for the first time.
 820   @param[in] ClockFreq       The max clock frequency to be set. The unit is KHz.
 821
 822   @retval EFI_SUCCESS       The clock is supplied successfully.
 823   @retval Others            The clock isn't supplied successfully.
 824
 825 **/
 826 EFI_STATUS
 827 SdMmcHcClockSupply (
 828   IN SD_MMC_HC_PRIVATE_DATA  *Private,
 829   IN UINT8                   Slot,
 830   IN SD_MMC_BUS_MODE         BusTiming,
 831   IN BOOLEAN                 FirstTimeSetup,
 832   IN UINT64                  ClockFreq
 833   );
 834
 835 /**
 836   Software reset the specified SD/MMC host controller.
 837
 838   @param[in] Private        A pointer to the SD_MMC_HC_PRIVATE_DATA instance.
 839   @param[in] Slot           The slot number of the SD card to send the command to.
 840
 841   @retval EFI_SUCCESS       The software reset executes successfully.
 842   @retval Others            The software reset fails.
 843
 844 **/
 845 EFI_STATUS
 846 SdMmcHcReset (
 847   IN SD_MMC_HC_PRIVATE_DATA  *Private,
 848   IN UINT8                   Slot
 849   );
 850
 851 /**
 852   Initial SD/MMC host controller with lowest clock frequency, max power and max timeout value
 853   at initialization.
 854
 855   @param[in] Private        A pointer to the SD_MMC_HC_PRIVATE_DATA instance.
 856   @param[in] Slot           The slot number of the SD card to send the command to.
 857
 858   @retval EFI_SUCCESS       The host controller is initialized successfully.
 859   @retval Others            The host controller isn't initialized successfully.
 860
 861 **/
 862 EFI_STATUS
 863 SdMmcHcInitHost (
 864   IN SD_MMC_HC_PRIVATE_DATA  *Private,
 865   IN UINT8                   Slot
 866   );
 867
 868 #endif