1 /** @file 2 UfsHcDxe driver is used to provide platform-dependent info, mainly UFS host controller 3 MMIO base, to upper layer UFS drivers. 4 5 Copyright (c) 2014 - 2015, Intel Corporation. All rights reserved.<BR> 6 This program and the accompanying materials 7 are licensed and made available under the terms and conditions of the BSD License 8 which accompanies this distribution. The full text of the license may be found at 9 http://opensource.org/licenses/bsd-license.php. 10 11 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, 12 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. 13 14 **/ 15 16 #ifndef _EFI_UFS_HOST_CONTROLLER_H_ 17 #define _EFI_UFS_HOST_CONTROLLER_H_ 18 19 #include <Uefi.h> 20 21 #include <IndustryStandard/Pci.h> 22 #include <IndustryStandard/Acpi.h> 23 24 #include <Protocol/ComponentName.h> 25 #include <Protocol/ComponentName2.h> 26 #include <Protocol/DriverBinding.h> 27 #include <Protocol/LoadedImage.h> 28 #include <Protocol/DevicePath.h> 29 #include <Protocol/PciIo.h> 30 #include <Protocol/UfsHostController.h> 31 32 #include <Library/BaseLib.h> 33 #include <Library/DebugLib.h> 34 #include <Library/UefiLib.h> 35 #include <Library/DevicePathLib.h> 36 #include <Library/MemoryAllocationLib.h> 37 #include <Library/UefiBootServicesTableLib.h> 38 #include <Library/UefiDriverEntryPoint.h> 39 40 extern EFI_DRIVER_BINDING_PROTOCOL gUfsHcDriverBinding; 41 extern EFI_COMPONENT_NAME_PROTOCOL gUfsHcComponentName; 42 extern EFI_COMPONENT_NAME2_PROTOCOL gUfsHcComponentName2; 43 44 // 45 // Unique signature for private data structure. 46 // 47 #define UFS_HC_PRIVATE_DATA_SIGNATURE SIGNATURE_32 ('U','F','S','H') 48 49 typedef struct _UFS_HOST_CONTROLLER_PRIVATE_DATA UFS_HOST_CONTROLLER_PRIVATE_DATA; 50 51 // 52 // Nvme private data structure. 53 // 54 struct _UFS_HOST_CONTROLLER_PRIVATE_DATA { 55 UINT32 Signature; 56 EFI_HANDLE Handle; 57 58 EDKII_UFS_HOST_CONTROLLER_PROTOCOL UfsHc; 59 EFI_PCI_IO_PROTOCOL *PciIo; 60 UINT8 BarIndex; 61 UINT64 PciAttributes; 62 }; 63 64 #define UFS_HOST_CONTROLLER_PRIVATE_DATA_FROM_UFSHC(a) \ 65 CR (a, \ 66 UFS_HOST_CONTROLLER_PRIVATE_DATA, \ 67 UfsHc, \ 68 UFS_HC_PRIVATE_DATA_SIGNATURE \ 69 ) 70 71 /** 72 Retrieves a Unicode string that is the user readable name of the driver. 73 74 This function retrieves the user readable name of a driver in the form of a 75 Unicode string. If the driver specified by This has a user readable name in 76 the language specified by Language, then a pointer to the driver name is 77 returned in DriverName, and EFI_SUCCESS is returned. If the driver specified 78 by This does not support the language specified by Language, 79 then EFI_UNSUPPORTED is returned. 80 81 @param This[in] A pointer to the EFI_COMPONENT_NAME2_PROTOCOL or 82 EFI_COMPONENT_NAME_PROTOCOL instance. 83 84 @param Language[in] A pointer to a Null-terminated ASCII string 85 array indicating the language. This is the 86 language of the driver name that the caller is 87 requesting, and it must match one of the 88 languages specified in SupportedLanguages. The 89 number of languages supported by a driver is up 90 to the driver writer. Language is specified 91 in RFC 4646 or ISO 639-2 language code format. 92 93 @param DriverName[out] A pointer to the Unicode string to return. 94 This Unicode string is the name of the 95 driver specified by This in the language 96 specified by Language. 97 98 @retval EFI_SUCCESS The Unicode string for the Driver specified by 99 This and the language specified by Language was 100 returned in DriverName. 101 102 @retval EFI_INVALID_PARAMETER Language is NULL. 103 104 @retval EFI_INVALID_PARAMETER DriverName is NULL. 105 106 @retval EFI_UNSUPPORTED The driver specified by This does not support 107 the language specified by Language. 108 109 **/ 110 EFI_STATUS 111 EFIAPI 112 UfsHcComponentNameGetDriverName ( 113 IN EFI_COMPONENT_NAME_PROTOCOL *This, 114 IN CHAR8 *Language, 115 OUT CHAR16 **DriverName 116 ); 117 118 /** 119 Retrieves a Unicode string that is the user readable name of the controller 120 that is being managed by a driver. 121 122 This function retrieves the user readable name of the controller specified by 123 ControllerHandle and ChildHandle in the form of a Unicode string. If the 124 driver specified by This has a user readable name in the language specified by 125 Language, then a pointer to the controller name is returned in ControllerName, 126 and EFI_SUCCESS is returned. If the driver specified by This is not currently 127 managing the controller specified by ControllerHandle and ChildHandle, 128 then EFI_UNSUPPORTED is returned. If the driver specified by This does not 129 support the language specified by Language, then EFI_UNSUPPORTED is returned. 130 131 @param This[in] A pointer to the EFI_COMPONENT_NAME2_PROTOCOL or 132 EFI_COMPONENT_NAME_PROTOCOL instance. 133 134 @param ControllerHandle[in] The handle of a controller that the driver 135 specified by This is managing. This handle 136 specifies the controller whose name is to be 137 returned. 138 139 @param ChildHandle[in] The handle of the child controller to retrieve 140 the name of. This is an optional parameter that 141 may be NULL. It will be NULL for device 142 drivers. It will also be NULL for a bus drivers 143 that wish to retrieve the name of the bus 144 controller. It will not be NULL for a bus 145 driver that wishes to retrieve the name of a 146 child controller. 147 148 @param Language[in] A pointer to a Null-terminated ASCII string 149 array indicating the language. This is the 150 language of the driver name that the caller is 151 requesting, and it must match one of the 152 languages specified in SupportedLanguages. The 153 number of languages supported by a driver is up 154 to the driver writer. Language is specified in 155 RFC 4646 or ISO 639-2 language code format. 156 157 @param ControllerName[out] A pointer to the Unicode string to return. 158 This Unicode string is the name of the 159 controller specified by ControllerHandle and 160 ChildHandle in the language specified by 161 Language from the point of view of the driver 162 specified by This. 163 164 @retval EFI_SUCCESS The Unicode string for the user readable name in 165 the language specified by Language for the 166 driver specified by This was returned in 167 DriverName. 168 169 @retval EFI_INVALID_PARAMETER ControllerHandle is NULL. 170 171 @retval EFI_INVALID_PARAMETER ChildHandle is not NULL and it is not a valid 172 EFI_HANDLE. 173 174 @retval EFI_INVALID_PARAMETER Language is NULL. 175 176 @retval EFI_INVALID_PARAMETER ControllerName is NULL. 177 178 @retval EFI_UNSUPPORTED The driver specified by This is not currently 179 managing the controller specified by 180 ControllerHandle and ChildHandle. 181 182 @retval EFI_UNSUPPORTED The driver specified by This does not support 183 the language specified by Language. 184 185 **/ 186 EFI_STATUS 187 EFIAPI 188 UfsHcComponentNameGetControllerName ( 189 IN EFI_COMPONENT_NAME_PROTOCOL *This, 190 IN EFI_HANDLE ControllerHandle, 191 IN EFI_HANDLE ChildHandle OPTIONAL, 192 IN CHAR8 *Language, 193 OUT CHAR16 **ControllerName 194 ); 195 196 /** 197 Tests to see if this driver supports a given controller. If a child device is provided, 198 it further tests to see if this driver supports creating a handle for the specified child device. 199 200 This function checks to see if the driver specified by This supports the device specified by 201 ControllerHandle. Drivers will typically use the device path attached to 202 ControllerHandle and/or the services from the bus I/O abstraction attached to 203 ControllerHandle to determine if the driver supports ControllerHandle. This function 204 may be called many times during platform initialization. In order to reduce boot times, the tests 205 performed by this function must be very small, and take as little time as possible to execute. This 206 function must not change the state of any hardware devices, and this function must be aware that the 207 device specified by ControllerHandle may already be managed by the same driver or a 208 different driver. This function must match its calls to AllocatePages() with FreePages(), 209 AllocatePool() with FreePool(), and OpenProtocol() with CloseProtocol(). 210 Since ControllerHandle may have been previously started by the same driver, if a protocol is 211 already in the opened state, then it must not be closed with CloseProtocol(). This is required 212 to guarantee the state of ControllerHandle is not modified by this function. 213 214 @param[in] This A pointer to the EFI_DRIVER_BINDING_PROTOCOL instance. 215 @param[in] ControllerHandle The handle of the controller to test. This handle 216 must support a protocol interface that supplies 217 an I/O abstraction to the driver. 218 @param[in] RemainingDevicePath A pointer to the remaining portion of a device path. This 219 parameter is ignored by device drivers, and is optional for bus 220 drivers. For bus drivers, if this parameter is not NULL, then 221 the bus driver must determine if the bus controller specified 222 by ControllerHandle and the child controller specified 223 by RemainingDevicePath are both supported by this 224 bus driver. 225 226 @retval EFI_SUCCESS The device specified by ControllerHandle and 227 RemainingDevicePath is supported by the driver specified by This. 228 @retval EFI_ALREADY_STARTED The device specified by ControllerHandle and 229 RemainingDevicePath is already being managed by the driver 230 specified by This. 231 @retval EFI_ACCESS_DENIED The device specified by ControllerHandle and 232 RemainingDevicePath is already being managed by a different 233 driver or an application that requires exclusive access. 234 Currently not implemented. 235 @retval EFI_UNSUPPORTED The device specified by ControllerHandle and 236 RemainingDevicePath is not supported by the driver specified by This. 237 **/ 238 EFI_STATUS 239 EFIAPI 240 UfsHcDriverBindingSupported ( 241 IN EFI_DRIVER_BINDING_PROTOCOL *This, 242 IN EFI_HANDLE Controller, 243 IN EFI_DEVICE_PATH_PROTOCOL *RemainingDevicePath 244 ); 245 246 /** 247 Starts a device controller or a bus controller. 248 249 The Start() function is designed to be invoked from the EFI boot service ConnectController(). 250 As a result, much of the error checking on the parameters to Start() has been moved into this 251 common boot service. It is legal to call Start() from other locations, 252 but the following calling restrictions must be followed or the system behavior will not be deterministic. 253 1. ControllerHandle must be a valid EFI_HANDLE. 254 2. If RemainingDevicePath is not NULL, then it must be a pointer to a naturally aligned 255 EFI_DEVICE_PATH_PROTOCOL. 256 3. Prior to calling Start(), the Supported() function for the driver specified by This must 257 have been called with the same calling parameters, and Supported() must have returned EFI_SUCCESS. 258 259 @param[in] This A pointer to the EFI_DRIVER_BINDING_PROTOCOL instance. 260 @param[in] ControllerHandle The handle of the controller to start. This handle 261 must support a protocol interface that supplies 262 an I/O abstraction to the driver. 263 @param[in] RemainingDevicePath A pointer to the remaining portion of a device path. This 264 parameter is ignored by device drivers, and is optional for bus 265 drivers. For a bus driver, if this parameter is NULL, then handles 266 for all the children of Controller are created by this driver. 267 If this parameter is not NULL and the first Device Path Node is 268 not the End of Device Path Node, then only the handle for the 269 child device specified by the first Device Path Node of 270 RemainingDevicePath is created by this driver. 271 If the first Device Path Node of RemainingDevicePath is 272 the End of Device Path Node, no child handle is created by this 273 driver. 274 275 @retval EFI_SUCCESS The device was started. 276 @retval EFI_DEVICE_ERROR The device could not be started due to a device error.Currently not implemented. 277 @retval EFI_OUT_OF_RESOURCES The request could not be completed due to a lack of resources. 278 @retval Others The driver failded to start the device. 279 280 **/ 281 EFI_STATUS 282 EFIAPI 283 UfsHcDriverBindingStart ( 284 IN EFI_DRIVER_BINDING_PROTOCOL *This, 285 IN EFI_HANDLE Controller, 286 IN EFI_DEVICE_PATH_PROTOCOL *RemainingDevicePath 287 ); 288 289 /** 290 Stops a device controller or a bus controller. 291 292 The Stop() function is designed to be invoked from the EFI boot service DisconnectController(). 293 As a result, much of the error checking on the parameters to Stop() has been moved 294 into this common boot service. It is legal to call Stop() from other locations, 295 but the following calling restrictions must be followed or the system behavior will not be deterministic. 296 1. ControllerHandle must be a valid EFI_HANDLE that was used on a previous call to this 297 same driver's Start() function. 298 2. The first NumberOfChildren handles of ChildHandleBuffer must all be a valid 299 EFI_HANDLE. In addition, all of these handles must have been created in this driver's 300 Start() function, and the Start() function must have called OpenProtocol() on 301 ControllerHandle with an Attribute of EFI_OPEN_PROTOCOL_BY_CHILD_CONTROLLER. 302 303 @param[in] This A pointer to the EFI_DRIVER_BINDING_PROTOCOL instance. 304 @param[in] ControllerHandle A handle to the device being stopped. The handle must 305 support a bus specific I/O protocol for the driver 306 to use to stop the device. 307 @param[in] NumberOfChildren The number of child device handles in ChildHandleBuffer. 308 @param[in] ChildHandleBuffer An array of child handles to be freed. May be NULL 309 if NumberOfChildren is 0. 310 311 @retval EFI_SUCCESS The device was stopped. 312 @retval EFI_DEVICE_ERROR The device could not be stopped due to a device error. 313 314 **/ 315 EFI_STATUS 316 EFIAPI 317 UfsHcDriverBindingStop ( 318 IN EFI_DRIVER_BINDING_PROTOCOL *This, 319 IN EFI_HANDLE Controller, 320 IN UINTN NumberOfChildren, 321 IN EFI_HANDLE *ChildHandleBuffer 322 ); 323 324 /** 325 Get the MMIO base of the UFS host controller. 326 327 @param[in] This A pointer to the EFI_UFS_HOST_CONTROLLER_PROTOCOL instance. 328 @param[out] MmioBar The MMIO base address of UFS host controller. 329 330 @retval EFI_SUCCESS The operation succeeds. 331 @retval others The operation fails. 332 **/ 333 EFI_STATUS 334 EFIAPI 335 UfsHcGetMmioBar ( 336 IN EDKII_UFS_HOST_CONTROLLER_PROTOCOL *This, 337 OUT UINTN *MmioBar 338 ); 339 340 /** 341 Provides the UFS controller-specific addresses needed to access system memory. 342 343 @param This A pointer to the EFI_UFS_HOST_CONTROLLER_PROTOCOL instance. 344 @param Operation Indicates if the bus master is going to read or write to system memory. 345 @param HostAddress The system memory address to map to the UFS controller. 346 @param NumberOfBytes On input the number of bytes to map. On output the number of bytes 347 that were mapped. 348 @param DeviceAddress The resulting map address for the bus master UFS controller to use to 349 access the hosts HostAddress. 350 @param Mapping A resulting value to pass to Unmap(). 351 352 @retval EFI_SUCCESS The range was mapped for the returned NumberOfBytes. 353 @retval EFI_UNSUPPORTED The HostAddress cannot be mapped as a common buffer. 354 @retval EFI_INVALID_PARAMETER One or more parameters are invalid. 355 @retval EFI_OUT_OF_RESOURCES The request could not be completed due to a lack of resources. 356 @retval EFI_DEVICE_ERROR The system hardware could not map the requested address. 357 358 **/ 359 EFI_STATUS 360 EFIAPI 361 UfsHcMap ( 362 IN EDKII_UFS_HOST_CONTROLLER_PROTOCOL *This, 363 IN EDKII_UFS_HOST_CONTROLLER_OPERATION Operation, 364 IN VOID *HostAddress, 365 IN OUT UINTN *NumberOfBytes, 366 OUT EFI_PHYSICAL_ADDRESS *DeviceAddress, 367 OUT VOID **Mapping 368 ); 369 370 /** 371 Completes the Map() operation and releases any corresponding resources. 372 373 @param This A pointer to the EFI_UFS_HOST_CONTROLLER_PROTOCOL instance. 374 @param Mapping The mapping value returned from Map(). 375 376 @retval EFI_SUCCESS The range was unmapped. 377 @retval EFI_DEVICE_ERROR The data was not committed to the target system memory. 378 379 **/ 380 EFI_STATUS 381 EFIAPI 382 UfsHcUnmap ( 383 IN EDKII_UFS_HOST_CONTROLLER_PROTOCOL *This, 384 IN VOID *Mapping 385 ); 386 387 /** 388 Allocates pages that are suitable for an EfiUfsHcOperationBusMasterCommonBuffer 389 mapping. 390 391 @param This A pointer to the EFI_UFS_HOST_CONTROLLER_PROTOCOL instance. 392 @param Type This parameter is not used and must be ignored. 393 @param MemoryType The type of memory to allocate, EfiBootServicesData or 394 EfiRuntimeServicesData. 395 @param Pages The number of pages to allocate. 396 @param HostAddress A pointer to store the base system memory address of the 397 allocated range. 398 @param Attributes The requested bit mask of attributes for the allocated range. 399 400 @retval EFI_SUCCESS The requested memory pages were allocated. 401 @retval EFI_UNSUPPORTED Attributes is unsupported. The only legal attribute bits are 402 MEMORY_WRITE_COMBINE and MEMORY_CACHED. 403 @retval EFI_INVALID_PARAMETER One or more parameters are invalid. 404 @retval EFI_OUT_OF_RESOURCES The memory pages could not be allocated. 405 406 **/ 407 EFI_STATUS 408 EFIAPI 409 UfsHcAllocateBuffer ( 410 IN EDKII_UFS_HOST_CONTROLLER_PROTOCOL *This, 411 IN EFI_ALLOCATE_TYPE Type, 412 IN EFI_MEMORY_TYPE MemoryType, 413 IN UINTN Pages, 414 OUT VOID **HostAddress, 415 IN UINT64 Attributes 416 ); 417 418 /** 419 Frees memory that was allocated with AllocateBuffer(). 420 421 @param This A pointer to the EFI_UFS_HOST_CONTROLLER_PROTOCOL instance. 422 @param Pages The number of pages to free. 423 @param HostAddress The base system memory address of the allocated range. 424 425 @retval EFI_SUCCESS The requested memory pages were freed. 426 @retval EFI_INVALID_PARAMETER The memory range specified by HostAddress and Pages 427 was not allocated with AllocateBuffer(). 428 429 **/ 430 EFI_STATUS 431 EFIAPI 432 UfsHcFreeBuffer ( 433 IN EDKII_UFS_HOST_CONTROLLER_PROTOCOL *This, 434 IN UINTN Pages, 435 IN VOID *HostAddress 436 ); 437 438 /** 439 Flushes all posted write transactions from the UFS bus to attached UFS device. 440 441 @param This A pointer to the EFI_UFS_HOST_CONTROLLER_PROTOCOL instance. 442 443 @retval EFI_SUCCESS The posted write transactions were flushed from the UFS bus 444 to attached UFS device. 445 @retval EFI_DEVICE_ERROR The posted write transactions were not flushed from the UFS 446 bus to attached UFS device due to a hardware error. 447 448 **/ 449 EFI_STATUS 450 EFIAPI 451 UfsHcFlush ( 452 IN EDKII_UFS_HOST_CONTROLLER_PROTOCOL *This 453 ); 454 455 /** 456 Enable a UFS bus driver to access UFS MMIO registers in the UFS Host Controller memory space. 457 458 @param This A pointer to the EDKII_UFS_HOST_CONTROLLER_PROTOCOL instance. 459 @param Width Signifies the width of the memory operations. 460 @param Offset The offset within the UFS Host Controller MMIO space to start the 461 memory operation. 462 @param Count The number of memory operations to perform. 463 @param Buffer For read operations, the destination buffer to store the results. 464 For write operations, the source buffer to write data from. 465 466 @retval EFI_SUCCESS The data was read from or written to the UFS host controller. 467 @retval EFI_UNSUPPORTED The address range specified by Offset, Width, and Count is not 468 valid for the UFS Host Controller memory space. 469 @retval EFI_OUT_OF_RESOURCES The request could not be completed due to a lack of resources. 470 @retval EFI_INVALID_PARAMETER One or more parameters are invalid. 471 472 **/ 473 EFI_STATUS 474 EFIAPI 475 UfsHcMmioRead ( 476 IN EDKII_UFS_HOST_CONTROLLER_PROTOCOL *This, 477 IN EDKII_UFS_HOST_CONTROLLER_PROTOCOL_WIDTH Width, 478 IN UINT64 Offset, 479 IN UINTN Count, 480 IN OUT VOID *Buffer 481 ); 482 483 /** 484 Enable a UFS bus driver to access UFS MMIO registers in the UFS Host Controller memory space. 485 486 @param This A pointer to the EDKII_UFS_HOST_CONTROLLER_PROTOCOL instance. 487 @param Width Signifies the width of the memory operations. 488 @param Offset The offset within the UFS Host Controller MMIO space to start the 489 memory operation. 490 @param Count The number of memory operations to perform. 491 @param Buffer For read operations, the destination buffer to store the results. 492 For write operations, the source buffer to write data from. 493 494 @retval EFI_SUCCESS The data was read from or written to the UFS host controller. 495 @retval EFI_UNSUPPORTED The address range specified by Offset, Width, and Count is not 496 valid for the UFS Host Controller memory space. 497 @retval EFI_OUT_OF_RESOURCES The request could not be completed due to a lack of resources. 498 @retval EFI_INVALID_PARAMETER One or more parameters are invalid. 499 500 **/ 501 EFI_STATUS 502 EFIAPI 503 UfsHcMmioWrite ( 504 IN EDKII_UFS_HOST_CONTROLLER_PROTOCOL *This, 505 IN EDKII_UFS_HOST_CONTROLLER_PROTOCOL_WIDTH Width, 506 IN UINT64 Offset, 507 IN UINTN Count, 508 IN OUT VOID *Buffer 509 ); 510 511 #endif 512