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