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