1 /** @file 2 Header file for EmmcDxe Driver. 3 4 This file defines common data structures, macro definitions and some module 5 internal function header files. 6 7 Copyright (c) 2015 - 2016, Intel Corporation. All rights reserved.<BR> 8 This program and the accompanying materials 9 are licensed and made available under the terms and conditions of the BSD License 10 which accompanies this distribution. The full text of the license may be found at 11 http://opensource.org/licenses/bsd-license.php 12 13 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, 14 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. 15 16 **/ 17 18 #ifndef _EMMC_DXE_H_ 19 #define _EMMC_DXE_H_ 20 21 #include <Uefi.h> 22 #include <IndustryStandard/Emmc.h> 23 24 #include <Protocol/SdMmcPassThru.h> 25 #include <Protocol/BlockIo.h> 26 #include <Protocol/BlockIo2.h> 27 #include <Protocol/StorageSecurityCommand.h> 28 #include <Protocol/EraseBlock.h> 29 30 #include <Protocol/DevicePath.h> 31 32 #include <Library/DebugLib.h> 33 #include <Library/UefiDriverEntryPoint.h> 34 #include <Library/BaseLib.h> 35 #include <Library/UefiLib.h> 36 #include <Library/BaseMemoryLib.h> 37 #include <Library/MemoryAllocationLib.h> 38 #include <Library/UefiBootServicesTableLib.h> 39 #include <Library/DevicePathLib.h> 40 #include <Library/UefiRuntimeServicesTableLib.h> 41 42 #include "EmmcBlockIo.h" 43 // 44 // Global Variables 45 // 46 extern EFI_DRIVER_BINDING_PROTOCOL gEmmcDxeDriverBinding; 47 extern EFI_COMPONENT_NAME_PROTOCOL gEmmcDxeComponentName; 48 extern EFI_COMPONENT_NAME2_PROTOCOL gEmmcDxeComponentName2; 49 50 #define EMMC_PARTITION_SIGNATURE SIGNATURE_32 ('E', 'm', 'm', 'P') 51 52 #define EMMC_PARTITION_DATA_FROM_BLKIO(a) \ 53 CR(a, EMMC_PARTITION, BlockIo, EMMC_PARTITION_SIGNATURE) 54 55 #define EMMC_PARTITION_DATA_FROM_BLKIO2(a) \ 56 CR(a, EMMC_PARTITION, BlockIo2, EMMC_PARTITION_SIGNATURE) 57 58 #define EMMC_PARTITION_DATA_FROM_SSP(a) \ 59 CR(a, EMMC_PARTITION, StorageSecurity, EMMC_PARTITION_SIGNATURE) 60 61 #define EMMC_PARTITION_DATA_FROM_ERASEBLK(a) \ 62 CR(a, EMMC_PARTITION, EraseBlock, EMMC_PARTITION_SIGNATURE) 63 64 // 65 // Take 2.5 seconds as generic time out value, 1 microsecond as unit. 66 // 67 #define EMMC_GENERIC_TIMEOUT 2500 * 1000 68 69 #define EMMC_REQUEST_SIGNATURE SIGNATURE_32 ('E', 'm', 'R', 'e') 70 71 typedef struct _EMMC_DEVICE EMMC_DEVICE; 72 typedef struct _EMMC_DRIVER_PRIVATE_DATA EMMC_DRIVER_PRIVATE_DATA; 73 74 // 75 // Asynchronous I/O request. 76 // 77 typedef struct { 78 UINT32 Signature; 79 LIST_ENTRY Link; 80 81 EFI_SD_MMC_COMMAND_BLOCK SdMmcCmdBlk; 82 EFI_SD_MMC_STATUS_BLOCK SdMmcStatusBlk; 83 EFI_SD_MMC_PASS_THRU_COMMAND_PACKET Packet; 84 85 BOOLEAN IsEnd; 86 87 EFI_BLOCK_IO2_TOKEN *Token; 88 EFI_EVENT Event; 89 } EMMC_REQUEST; 90 91 #define EMMC_REQUEST_FROM_LINK(a) \ 92 CR(a, EMMC_REQUEST, Link, EMMC_REQUEST_SIGNATURE) 93 94 typedef struct { 95 UINT32 Signature; 96 BOOLEAN Enable; 97 EMMC_PARTITION_TYPE PartitionType; 98 EFI_HANDLE Handle; 99 EFI_DEVICE_PATH_PROTOCOL *DevicePath; 100 EFI_BLOCK_IO_PROTOCOL BlockIo; 101 EFI_BLOCK_IO2_PROTOCOL BlockIo2; 102 EFI_BLOCK_IO_MEDIA BlockMedia; 103 EFI_STORAGE_SECURITY_COMMAND_PROTOCOL StorageSecurity; 104 EFI_ERASE_BLOCK_PROTOCOL EraseBlock; 105 106 LIST_ENTRY Queue; 107 108 EMMC_DEVICE *Device; 109 } EMMC_PARTITION; 110 111 // 112 // Up to 6 slots per EMMC PCI host controller 113 // 114 #define EMMC_MAX_DEVICES 6 115 // 116 // Up to 8 partitions per EMMC device. 117 // 118 #define EMMC_MAX_PARTITIONS 8 119 #define EMMC_MODEL_NAME_MAX_LEN 32 120 121 struct _EMMC_DEVICE { 122 EFI_HANDLE Handle; 123 EFI_DEVICE_PATH_PROTOCOL *DevicePath; 124 UINT8 Slot; 125 BOOLEAN SectorAddressing; 126 127 EMMC_PARTITION Partition[EMMC_MAX_PARTITIONS]; 128 EMMC_CSD Csd; 129 EMMC_CID Cid; 130 EMMC_EXT_CSD ExtCsd; 131 EFI_UNICODE_STRING_TABLE *ControllerNameTable; 132 // 133 // The model name consists of three fields in CID register 134 // 1) OEM/Application ID (2 bytes) 135 // 2) Product Name (5 bytes) 136 // 3) Product Serial Number (4 bytes) 137 // The delimiters of these fields are whitespace. 138 // 139 CHAR16 ModelName[EMMC_MODEL_NAME_MAX_LEN]; 140 EMMC_DRIVER_PRIVATE_DATA *Private; 141 } ; 142 143 // 144 // EMMC DXE driver private data structure 145 // 146 struct _EMMC_DRIVER_PRIVATE_DATA { 147 EFI_SD_MMC_PASS_THRU_PROTOCOL *PassThru; 148 EFI_HANDLE Controller; 149 EFI_DEVICE_PATH_PROTOCOL *ParentDevicePath; 150 EFI_HANDLE DriverBindingHandle; 151 152 EMMC_DEVICE Device[EMMC_MAX_DEVICES]; 153 } ; 154 155 /** 156 Tests to see if this driver supports a given controller. If a child device is provided, 157 it further tests to see if this driver supports creating a handle for the specified child device. 158 159 This function checks to see if the driver specified by This supports the device specified by 160 ControllerHandle. Drivers will typically use the device path attached to 161 ControllerHandle and/or the services from the bus I/O abstraction attached to 162 ControllerHandle to determine if the driver supports ControllerHandle. This function 163 may be called many times during platform initialization. In order to reduce boot times, the tests 164 performed by this function must be very small, and take as little time as possible to execute. This 165 function must not change the state of any hardware devices, and this function must be aware that the 166 device specified by ControllerHandle may already be managed by the same driver or a 167 different driver. This function must match its calls to AllocatePages() with FreePages(), 168 AllocatePool() with FreePool(), and OpenProtocol() with CloseProtocol(). 169 Since ControllerHandle may have been previously started by the same driver, if a protocol is 170 already in the opened state, then it must not be closed with CloseProtocol(). This is required 171 to guarantee the state of ControllerHandle is not modified by this function. 172 173 @param[in] This A pointer to the EFI_DRIVER_BINDING_PROTOCOL instance. 174 @param[in] ControllerHandle The handle of the controller to test. This handle 175 must support a protocol interface that supplies 176 an I/O abstraction to the driver. 177 @param[in] RemainingDevicePath A pointer to the remaining portion of a device path. This 178 parameter is ignored by device drivers, and is optional for bus 179 drivers. For bus drivers, if this parameter is not NULL, then 180 the bus driver must determine if the bus controller specified 181 by ControllerHandle and the child controller specified 182 by RemainingDevicePath are both supported by this 183 bus driver. 184 185 @retval EFI_SUCCESS The device specified by ControllerHandle and 186 RemainingDevicePath is supported by the driver specified by This. 187 @retval EFI_ALREADY_STARTED The device specified by ControllerHandle and 188 RemainingDevicePath is already being managed by the driver 189 specified by This. 190 @retval EFI_ACCESS_DENIED The device specified by ControllerHandle and 191 RemainingDevicePath is already being managed by a different 192 driver or an application that requires exclusive access. 193 Currently not implemented. 194 @retval EFI_UNSUPPORTED The device specified by ControllerHandle and 195 RemainingDevicePath is not supported by the driver specified by This. 196 **/ 197 EFI_STATUS 198 EFIAPI 199 EmmcDxeDriverBindingSupported ( 200 IN EFI_DRIVER_BINDING_PROTOCOL *This, 201 IN EFI_HANDLE Controller, 202 IN EFI_DEVICE_PATH_PROTOCOL *RemainingDevicePath 203 ); 204 205 /** 206 Starts a device controller or a bus controller. 207 208 The Start() function is designed to be invoked from the EFI boot service ConnectController(). 209 As a result, much of the error checking on the parameters to Start() has been moved into this 210 common boot service. It is legal to call Start() from other locations, 211 but the following calling restrictions must be followed or the system behavior will not be deterministic. 212 1. ControllerHandle must be a valid EFI_HANDLE. 213 2. If RemainingDevicePath is not NULL, then it must be a pointer to a naturally aligned 214 EFI_DEVICE_PATH_PROTOCOL. 215 3. Prior to calling Start(), the Supported() function for the driver specified by This must 216 have been called with the same calling parameters, and Supported() must have returned EFI_SUCCESS. 217 218 @param[in] This A pointer to the EFI_DRIVER_BINDING_PROTOCOL instance. 219 @param[in] ControllerHandle The handle of the controller to start. This handle 220 must support a protocol interface that supplies 221 an I/O abstraction to the driver. 222 @param[in] RemainingDevicePath A pointer to the remaining portion of a device path. This 223 parameter is ignored by device drivers, and is optional for bus 224 drivers. For a bus driver, if this parameter is NULL, then handles 225 for all the children of Controller are created by this driver. 226 If this parameter is not NULL and the first Device Path Node is 227 not the End of Device Path Node, then only the handle for the 228 child device specified by the first Device Path Node of 229 RemainingDevicePath is created by this driver. 230 If the first Device Path Node of RemainingDevicePath is 231 the End of Device Path Node, no child handle is created by this 232 driver. 233 234 @retval EFI_SUCCESS The device was started. 235 @retval EFI_DEVICE_ERROR The device could not be started due to a device error.Currently not implemented. 236 @retval EFI_OUT_OF_RESOURCES The request could not be completed due to a lack of resources. 237 @retval Others The driver failded to start the device. 238 239 **/ 240 EFI_STATUS 241 EFIAPI 242 EmmcDxeDriverBindingStart ( 243 IN EFI_DRIVER_BINDING_PROTOCOL *This, 244 IN EFI_HANDLE Controller, 245 IN EFI_DEVICE_PATH_PROTOCOL *RemainingDevicePath 246 ); 247 248 /** 249 Stops a device controller or a bus controller. 250 251 The Stop() function is designed to be invoked from the EFI boot service DisconnectController(). 252 As a result, much of the error checking on the parameters to Stop() has been moved 253 into this common boot service. It is legal to call Stop() from other locations, 254 but the following calling restrictions must be followed or the system behavior will not be deterministic. 255 1. ControllerHandle must be a valid EFI_HANDLE that was used on a previous call to this 256 same driver's Start() function. 257 2. The first NumberOfChildren handles of ChildHandleBuffer must all be a valid 258 EFI_HANDLE. In addition, all of these handles must have been created in this driver's 259 Start() function, and the Start() function must have called OpenProtocol() on 260 ControllerHandle with an Attribute of EFI_OPEN_PROTOCOL_BY_CHILD_CONTROLLER. 261 262 @param[in] This A pointer to the EFI_DRIVER_BINDING_PROTOCOL instance. 263 @param[in] ControllerHandle A handle to the device being stopped. The handle must 264 support a bus specific I/O protocol for the driver 265 to use to stop the device. 266 @param[in] NumberOfChildren The number of child device handles in ChildHandleBuffer. 267 @param[in] ChildHandleBuffer An array of child handles to be freed. May be NULL 268 if NumberOfChildren is 0. 269 270 @retval EFI_SUCCESS The device was stopped. 271 @retval EFI_DEVICE_ERROR The device could not be stopped due to a device error. 272 273 **/ 274 EFI_STATUS 275 EFIAPI 276 EmmcDxeDriverBindingStop ( 277 IN EFI_DRIVER_BINDING_PROTOCOL *This, 278 IN EFI_HANDLE Controller, 279 IN UINTN NumberOfChildren, 280 IN EFI_HANDLE *ChildHandleBuffer 281 ); 282 283 /** 284 Retrieves a Unicode string that is the user readable name of the driver. 285 286 This function retrieves the user readable name of a driver in the form of a 287 Unicode string. If the driver specified by This has a user readable name in 288 the language specified by Language, then a pointer to the driver name is 289 returned in DriverName, and EFI_SUCCESS is returned. If the driver specified 290 by This does not support the language specified by Language, 291 then EFI_UNSUPPORTED is returned. 292 293 @param This[in] A pointer to the EFI_COMPONENT_NAME2_PROTOCOL or 294 EFI_COMPONENT_NAME_PROTOCOL instance. 295 296 @param Language[in] A pointer to a Null-terminated ASCII string 297 array indicating the language. This is the 298 language of the driver name that the caller is 299 requesting, and it must match one of the 300 languages specified in SupportedLanguages. The 301 number of languages supported by a driver is up 302 to the driver writer. Language is specified 303 in RFC 4646 or ISO 639-2 language code format. 304 305 @param DriverName[out] A pointer to the Unicode string to return. 306 This Unicode string is the name of the 307 driver specified by This in the language 308 specified by Language. 309 310 @retval EFI_SUCCESS The Unicode string for the Driver specified by 311 This and the language specified by Language was 312 returned in DriverName. 313 314 @retval EFI_INVALID_PARAMETER Language is NULL. 315 316 @retval EFI_INVALID_PARAMETER DriverName is NULL. 317 318 @retval EFI_UNSUPPORTED The driver specified by This does not support 319 the language specified by Language. 320 321 **/ 322 EFI_STATUS 323 EFIAPI 324 EmmcDxeComponentNameGetDriverName ( 325 IN EFI_COMPONENT_NAME_PROTOCOL *This, 326 IN CHAR8 *Language, 327 OUT CHAR16 **DriverName 328 ); 329 330 /** 331 Retrieves a Unicode string that is the user readable name of the controller 332 that is being managed by a driver. 333 334 This function retrieves the user readable name of the controller specified by 335 ControllerHandle and ChildHandle in the form of a Unicode string. If the 336 driver specified by This has a user readable name in the language specified by 337 Language, then a pointer to the controller name is returned in ControllerName, 338 and EFI_SUCCESS is returned. If the driver specified by This is not currently 339 managing the controller specified by ControllerHandle and ChildHandle, 340 then EFI_UNSUPPORTED is returned. If the driver specified by This does not 341 support the language specified by Language, then EFI_UNSUPPORTED is returned. 342 343 @param This[in] A pointer to the EFI_COMPONENT_NAME2_PROTOCOL or 344 EFI_COMPONENT_NAME_PROTOCOL instance. 345 346 @param ControllerHandle[in] The handle of a controller that the driver 347 specified by This is managing. This handle 348 specifies the controller whose name is to be 349 returned. 350 351 @param ChildHandle[in] The handle of the child controller to retrieve 352 the name of. This is an optional parameter that 353 may be NULL. It will be NULL for device 354 drivers. It will also be NULL for a bus drivers 355 that wish to retrieve the name of the bus 356 controller. It will not be NULL for a bus 357 driver that wishes to retrieve the name of a 358 child controller. 359 360 @param Language[in] A pointer to a Null-terminated ASCII string 361 array indicating the language. This is the 362 language of the driver name that the caller is 363 requesting, and it must match one of the 364 languages specified in SupportedLanguages. The 365 number of languages supported by a driver is up 366 to the driver writer. Language is specified in 367 RFC 4646 or ISO 639-2 language code format. 368 369 @param ControllerName[out] A pointer to the Unicode string to return. 370 This Unicode string is the name of the 371 controller specified by ControllerHandle and 372 ChildHandle in the language specified by 373 Language from the point of view of the driver 374 specified by This. 375 376 @retval EFI_SUCCESS The Unicode string for the user readable name in 377 the language specified by Language for the 378 driver specified by This was returned in 379 DriverName. 380 381 @retval EFI_INVALID_PARAMETER ControllerHandle is NULL. 382 383 @retval EFI_INVALID_PARAMETER ChildHandle is not NULL and it is not a valid 384 EFI_HANDLE. 385 386 @retval EFI_INVALID_PARAMETER Language is NULL. 387 388 @retval EFI_INVALID_PARAMETER ControllerName is NULL. 389 390 @retval EFI_UNSUPPORTED The driver specified by This is not currently 391 managing the controller specified by 392 ControllerHandle and ChildHandle. 393 394 @retval EFI_UNSUPPORTED The driver specified by This does not support 395 the language specified by Language. 396 397 **/ 398 EFI_STATUS 399 EFIAPI 400 EmmcDxeComponentNameGetControllerName ( 401 IN EFI_COMPONENT_NAME_PROTOCOL *This, 402 IN EFI_HANDLE ControllerHandle, 403 IN EFI_HANDLE ChildHandle OPTIONAL, 404 IN CHAR8 *Language, 405 OUT CHAR16 **ControllerName 406 ); 407 408 /** 409 Send command SELECT to the device to select/deselect the device. 410 411 @param[in] Device A pointer to the EMMC_DEVICE instance. 412 @param[in] Rca The relative device address to use. 413 414 @retval EFI_SUCCESS The request is executed successfully. 415 @retval EFI_OUT_OF_RESOURCES The request could not be executed due to a lack of resources. 416 @retval Others The request could not be executed successfully. 417 418 **/ 419 EFI_STATUS 420 EmmcSelect ( 421 IN EMMC_DEVICE *Device, 422 IN UINT16 Rca 423 ); 424 425 /** 426 Send command SEND_STATUS to the device to get device status. 427 428 @param[in] Device A pointer to the EMMC_DEVICE instance. 429 @param[in] Rca The relative device address to use. 430 @param[out] DevStatus The buffer to store the device status. 431 432 @retval EFI_SUCCESS The request is executed successfully. 433 @retval EFI_OUT_OF_RESOURCES The request could not be executed due to a lack of resources. 434 @retval Others The request could not be executed successfully. 435 436 **/ 437 EFI_STATUS 438 EmmcSendStatus ( 439 IN EMMC_DEVICE *Device, 440 IN UINT16 Rca, 441 OUT UINT32 *DevStatus 442 ); 443 444 /** 445 Send command SEND_CSD to the device to get the CSD register data. 446 447 @param[in] Device A pointer to the EMMC_DEVICE instance. 448 @param[in] Rca The relative device address to use. 449 @param[out] Csd The buffer to store the EMMC_CSD register data. 450 451 @retval EFI_SUCCESS The request is executed successfully. 452 @retval EFI_OUT_OF_RESOURCES The request could not be executed due to a lack of resources. 453 @retval Others The request could not be executed successfully. 454 455 **/ 456 EFI_STATUS 457 EmmcGetCsd ( 458 IN EMMC_DEVICE *Device, 459 IN UINT16 Rca, 460 OUT EMMC_CSD *Csd 461 ); 462 463 /** 464 Send command SEND_CID to the device to get the CID register data. 465 466 @param[in] Device A pointer to the EMMC_DEVICE instance. 467 @param[in] Rca The relative device address to use. 468 @param[out] Cid The buffer to store the EMMC_CID register data. 469 470 @retval EFI_SUCCESS The request is executed successfully. 471 @retval EFI_OUT_OF_RESOURCES The request could not be executed due to a lack of resources. 472 @retval Others The request could not be executed successfully. 473 474 **/ 475 EFI_STATUS 476 EmmcGetCid ( 477 IN EMMC_DEVICE *Device, 478 IN UINT16 Rca, 479 OUT EMMC_CID *Cid 480 ); 481 482 /** 483 Send command SEND_EXT_CSD to the device to get the EXT_CSD register data. 484 485 @param[in] Device A pointer to the EMMC_DEVICE instance. 486 @param[out] ExtCsd The buffer to store the EXT_CSD register data. 487 488 @retval EFI_SUCCESS The request is executed successfully. 489 @retval EFI_OUT_OF_RESOURCES The request could not be executed due to a lack of resources. 490 @retval Others The request could not be executed successfully. 491 492 **/ 493 EFI_STATUS 494 EmmcGetExtCsd ( 495 IN EMMC_DEVICE *Device, 496 OUT EMMC_EXT_CSD *ExtCsd 497 ); 498 499 #endif 500 501