1 /** @file 2 Values defined and used by the Opal UEFI Driver. 3 4 Copyright (c) 2016, Intel Corporation. All rights reserved.<BR> 5 This program and the accompanying materials 6 are licensed and made available under the terms and conditions of the BSD License 7 which accompanies this distribution. The full text of the license may be found at 8 http://opensource.org/licenses/bsd-license.php 9 10 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, 11 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. 12 13 **/ 14 15 #ifndef _OPAL_DRIVER_H_ 16 #define _OPAL_DRIVER_H_ 17 18 #include <PiDxe.h> 19 20 #include <Protocol/PciIo.h> 21 #include <Protocol/SmmCommunication.h> 22 #include <Protocol/BlockIo.h> 23 #include <Protocol/LoadedImage.h> 24 #include <Protocol/DevicePath.h> 25 #include <Protocol/DevicePathToText.h> 26 #include <Protocol/StorageSecurityCommand.h> 27 28 #include <Library/UefiLib.h> 29 #include <Library/UefiBootServicesTableLib.h> 30 #include <Library/UefiRuntimeServicesTableLib.h> 31 #include <Library/BaseMemoryLib.h> 32 #include <Library/MemoryAllocationLib.h> 33 #include <Library/BaseLib.h> 34 #include <Library/PrintLib.h> 35 #include <Library/DebugLib.h> 36 #include <Library/DevicePathLib.h> 37 #include <Library/HiiLib.h> 38 #include <Library/UefiHiiServicesLib.h> 39 #include <Library/TcgStorageOpalLib.h> 40 #include <Library/OpalPasswordSupportLib.h> 41 #include <Library/Tcg2PhysicalPresenceLib.h> 42 43 #define EFI_DRIVER_NAME_UNICODE L"1.0 UEFI Opal Driver" 44 45 // UEFI 2.1 46 #define LANGUAGE_RFC_3066_ENGLISH ((CHAR8*)"en") 47 48 // UEFI/EFI < 2.1 49 #define LANGUAGE_ISO_639_2_ENGLISH ((CHAR8*)"eng") 50 51 52 #define UNLOCK_VAR_NAME (const CHAR16*)L"UNLOCK" 53 #define OPAL_FILTER_DRIVER_VAR_NAME L"FILTER_DRIVER" 54 55 56 #define CONCAT_(x, y) x ## y 57 #define CONCAT(x, y) CONCAT_(x, y) 58 59 #define UNICODE_STR(x) CONCAT( L, x ) 60 61 extern EFI_DRIVER_BINDING_PROTOCOL gOpalDriverBinding; 62 extern EFI_COMPONENT_NAME_PROTOCOL gOpalComponentName; 63 extern EFI_COMPONENT_NAME2_PROTOCOL gOpalComponentName2; 64 65 /** 66 Unloads UEFI Driver. Very useful for debugging and testing. 67 68 @param ImageHandle Image handle this driver. 69 70 @retval EFI_SUCCESS This function always complete successfully. 71 @retval EFI_INVALID_PARAMETER The input ImageHandle is not valid. 72 **/ 73 EFI_STATUS 74 EFIAPI 75 EfiDriverUnload( 76 EFI_HANDLE ImageHandle 77 ); 78 79 80 /** 81 Test to see if this driver supports Controller. 82 83 @param This Protocol instance pointer. 84 @param ControllerHandle Handle of device to test 85 @param RemainingDevicePath Optional parameter use to pick a specific child 86 device to start. 87 88 @retval EFI_SUCCESS This driver supports this device. 89 @retval EFI_ALREADY_STARTED This driver is already running on this device. 90 @retval other This driver does not support this device. 91 92 **/ 93 EFI_STATUS 94 EFIAPI 95 OpalEfiDriverBindingSupported( 96 EFI_DRIVER_BINDING_PROTOCOL* This, 97 EFI_HANDLE Controller, 98 EFI_DEVICE_PATH_PROTOCOL* RemainingDevicePath 99 ); 100 101 /** 102 Enables Opal Management on a supported device if available. 103 104 The start function is designed to be called after the Opal UEFI Driver has confirmed the 105 "controller", which is a child handle, contains the EF_STORAGE_SECURITY_COMMAND protocols. 106 This function will complete the other necessary checks, such as verifying the device supports 107 the correct version of Opal. Upon verification, it will add the device to the 108 Opal HII list in order to expose Opal managmeent options. 109 110 @param[in] This A pointer to the EFI_DRIVER_BINDING_PROTOCOL instance. 111 @param[in] ControllerHandle The handle of the controller to start. This handle 112 must support a protocol interface that supplies 113 an I/O abstraction to the driver. 114 @param[in] RemainingDevicePath A pointer to the remaining portion of a device path. This 115 parameter is ignored by device drivers, and is optional for bus 116 drivers. For a bus driver, if this parameter is NULL, then handles 117 for all the children of Controller are created by this driver. 118 If this parameter is not NULL and the first Device Path Node is 119 not the End of Device Path Node, then only the handle for the 120 child device specified by the first Device Path Node of 121 RemainingDevicePath is created by this driver. 122 If the first Device Path Node of RemainingDevicePath is 123 the End of Device Path Node, no child handle is created by this 124 driver. 125 126 @retval EFI_SUCCESS Opal management was enabled. 127 @retval EFI_DEVICE_ERROR The device could not be started due to a device error.Currently not implemented. 128 @retval EFI_OUT_OF_RESOURCES The request could not be completed due to a lack of resources. 129 @retval Others The driver failed to start the device. 130 131 **/ 132 EFI_STATUS 133 EFIAPI 134 OpalEfiDriverBindingStart( 135 EFI_DRIVER_BINDING_PROTOCOL* This, 136 EFI_HANDLE Controller, 137 EFI_DEVICE_PATH_PROTOCOL* RemainingDevicePath 138 ); 139 140 /** 141 Stop this driver on Controller. 142 143 @param This Protocol instance pointer. 144 @param Controller Handle of device to stop driver on 145 @param NumberOfChildren Number of Handles in ChildHandleBuffer. If number of 146 children is zero stop the entire bus driver. 147 @param ChildHandleBuffer List of Child Handles to Stop. 148 149 @retval EFI_SUCCESS This driver is removed Controller. 150 @retval other This driver could not be removed from this device. 151 152 **/ 153 EFI_STATUS 154 EFIAPI 155 OpalEfiDriverBindingStop( 156 EFI_DRIVER_BINDING_PROTOCOL* This, 157 EFI_HANDLE Controller, 158 UINTN NumberOfChildren, 159 EFI_HANDLE* ChildHandleBuffer 160 ); 161 162 /** 163 Retrieves a Unicode string that is the user readable name of the driver. 164 165 This function retrieves the user readable name of a driver in the form of a 166 Unicode string. If the driver specified by This has a user readable name in 167 the language specified by Language, then a pointer to the driver name is 168 returned in DriverName, and EFI_SUCCESS is returned. If the driver specified 169 by This does not support the language specified by Language, 170 then EFI_UNSUPPORTED is returned. 171 172 @param This[in] A pointer to the EFI_COMPONENT_NAME2_PROTOCOL or 173 EFI_COMPONENT_NAME_PROTOCOL instance. 174 175 @param Language[in] A pointer to a Null-terminated ASCII string 176 array indicating the language. This is the 177 language of the driver name that the caller is 178 requesting, and it must match one of the 179 languages specified in SupportedLanguages. The 180 number of languages supported by a driver is up 181 to the driver writer. Language is specified 182 in RFC 4646 or ISO 639-2 language code format. 183 184 @param DriverName[out] A pointer to the Unicode string to return. 185 This Unicode string is the name of the 186 driver specified by This in the language 187 specified by Language. 188 189 @retval EFI_SUCCESS The Unicode string for the Driver specified by 190 This and the language specified by Language was 191 returned in DriverName. 192 193 @retval EFI_INVALID_PARAMETER Language is NULL. 194 195 @retval EFI_INVALID_PARAMETER DriverName is NULL. 196 197 @retval EFI_UNSUPPORTED The driver specified by This does not support 198 the language specified by Language. 199 200 **/ 201 EFI_STATUS 202 EFIAPI 203 OpalEfiDriverComponentNameGetDriverName( 204 EFI_COMPONENT_NAME_PROTOCOL* This, 205 CHAR8* Language, 206 CHAR16** DriverName 207 ); 208 209 /** 210 Retrieves a Unicode string that is the user readable name of the controller 211 that is being managed by a driver. 212 213 This function retrieves the user readable name of the controller specified by 214 ControllerHandle and ChildHandle in the form of a Unicode string. If the 215 driver specified by This has a user readable name in the language specified by 216 Language, then a pointer to the controller name is returned in ControllerName, 217 and EFI_SUCCESS is returned. If the driver specified by This is not currently 218 managing the controller specified by ControllerHandle and ChildHandle, 219 then EFI_UNSUPPORTED is returned. If the driver specified by This does not 220 support the language specified by Language, then EFI_UNSUPPORTED is returned. 221 222 @param This[in] A pointer to the EFI_COMPONENT_NAME2_PROTOCOL or 223 EFI_COMPONENT_NAME_PROTOCOL instance. 224 225 @param ControllerHandle[in] The handle of a controller that the driver 226 specified by This is managing. This handle 227 specifies the controller whose name is to be 228 returned. 229 230 @param ChildHandle[in] The handle of the child controller to retrieve 231 the name of. This is an optional parameter that 232 may be NULL. It will be NULL for device 233 drivers. It will also be NULL for a bus drivers 234 that wish to retrieve the name of the bus 235 controller. It will not be NULL for a bus 236 driver that wishes to retrieve the name of a 237 child controller. 238 239 @param Language[in] A pointer to a Null-terminated ASCII string 240 array indicating the language. This is the 241 language of the driver name that the caller is 242 requesting, and it must match one of the 243 languages specified in SupportedLanguages. The 244 number of languages supported by a driver is up 245 to the driver writer. Language is specified in 246 RFC 4646 or ISO 639-2 language code format. 247 248 @param ControllerName[out] A pointer to the Unicode string to return. 249 This Unicode string is the name of the 250 controller specified by ControllerHandle and 251 ChildHandle in the language specified by 252 Language from the point of view of the driver 253 specified by This. 254 255 @retval EFI_SUCCESS The Unicode string for the user readable name in 256 the language specified by Language for the 257 driver specified by This was returned in 258 DriverName. 259 260 @retval EFI_INVALID_PARAMETER ControllerHandle is NULL. 261 262 @retval EFI_INVALID_PARAMETER ChildHandle is not NULL and it is not a valid 263 EFI_HANDLE. 264 265 @retval EFI_INVALID_PARAMETER Language is NULL. 266 267 @retval EFI_INVALID_PARAMETER ControllerName is NULL. 268 269 @retval EFI_UNSUPPORTED The driver specified by This is not currently 270 managing the controller specified by 271 ControllerHandle and ChildHandle. 272 273 @retval EFI_UNSUPPORTED The driver specified by This does not support 274 the language specified by Language. 275 276 **/ 277 EFI_STATUS 278 EFIAPI 279 OpalEfiDriverComponentNameGetControllerName( 280 EFI_COMPONENT_NAME_PROTOCOL* This, 281 EFI_HANDLE ControllerHandle, 282 EFI_HANDLE ChildHandle, 283 CHAR8* Language, 284 CHAR16** ControllerName 285 ); 286 287 /** 288 Retrieves a Unicode string that is the user readable name of the driver. 289 290 This function retrieves the user readable name of a driver in the form of a 291 Unicode string. If the driver specified by This has a user readable name in 292 the language specified by Language, then a pointer to the driver name is 293 returned in DriverName, and EFI_SUCCESS is returned. If the driver specified 294 by This does not support the language specified by Language, 295 then EFI_UNSUPPORTED is returned. 296 297 @param This[in] A pointer to the EFI_COMPONENT_NAME2_PROTOCOL or 298 EFI_COMPONENT_NAME_PROTOCOL instance. 299 300 @param Language[in] A pointer to a Null-terminated ASCII string 301 array indicating the language. This is the 302 language of the driver name that the caller is 303 requesting, and it must match one of the 304 languages specified in SupportedLanguages. The 305 number of languages supported by a driver is up 306 to the driver writer. Language is specified 307 in RFC 4646 or ISO 639-2 language code format. 308 309 @param DriverName[out] A pointer to the Unicode string to return. 310 This Unicode string is the name of the 311 driver specified by This in the language 312 specified by Language. 313 314 @retval EFI_SUCCESS The Unicode string for the Driver specified by 315 This and the language specified by Language was 316 returned in DriverName. 317 318 @retval EFI_INVALID_PARAMETER Language is NULL. 319 320 @retval EFI_INVALID_PARAMETER DriverName is NULL. 321 322 @retval EFI_UNSUPPORTED The driver specified by This does not support 323 the language specified by Language. 324 325 **/ 326 EFI_STATUS 327 EFIAPI 328 OpalEfiDriverComponentName2GetDriverName( 329 EFI_COMPONENT_NAME2_PROTOCOL* This, 330 CHAR8* Language, 331 CHAR16** DriverName 332 ); 333 334 /** 335 Retrieves a Unicode string that is the user readable name of the controller 336 that is being managed by a driver. 337 338 This function retrieves the user readable name of the controller specified by 339 ControllerHandle and ChildHandle in the form of a Unicode string. If the 340 driver specified by This has a user readable name in the language specified by 341 Language, then a pointer to the controller name is returned in ControllerName, 342 and EFI_SUCCESS is returned. If the driver specified by This is not currently 343 managing the controller specified by ControllerHandle and ChildHandle, 344 then EFI_UNSUPPORTED is returned. If the driver specified by This does not 345 support the language specified by Language, then EFI_UNSUPPORTED is returned. 346 347 @param This[in] A pointer to the EFI_COMPONENT_NAME2_PROTOCOL or 348 EFI_COMPONENT_NAME_PROTOCOL instance. 349 350 @param ControllerHandle[in] The handle of a controller that the driver 351 specified by This is managing. This handle 352 specifies the controller whose name is to be 353 returned. 354 355 @param ChildHandle[in] The handle of the child controller to retrieve 356 the name of. This is an optional parameter that 357 may be NULL. It will be NULL for device 358 drivers. It will also be NULL for a bus drivers 359 that wish to retrieve the name of the bus 360 controller. It will not be NULL for a bus 361 driver that wishes to retrieve the name of a 362 child controller. 363 364 @param Language[in] A pointer to a Null-terminated ASCII string 365 array indicating the language. This is the 366 language of the driver name that the caller is 367 requesting, and it must match one of the 368 languages specified in SupportedLanguages. The 369 number of languages supported by a driver is up 370 to the driver writer. Language is specified in 371 RFC 4646 or ISO 639-2 language code format. 372 373 @param ControllerName[out] A pointer to the Unicode string to return. 374 This Unicode string is the name of the 375 controller specified by ControllerHandle and 376 ChildHandle in the language specified by 377 Language from the point of view of the driver 378 specified by This. 379 380 @retval EFI_SUCCESS The Unicode string for the user readable name in 381 the language specified by Language for the 382 driver specified by This was returned in 383 DriverName. 384 385 @retval EFI_INVALID_PARAMETER ControllerHandle is NULL. 386 387 @retval EFI_INVALID_PARAMETER ChildHandle is not NULL and it is not a valid 388 EFI_HANDLE. 389 390 @retval EFI_INVALID_PARAMETER Language is NULL. 391 392 @retval EFI_INVALID_PARAMETER ControllerName is NULL. 393 394 @retval EFI_UNSUPPORTED The driver specified by This is not currently 395 managing the controller specified by 396 ControllerHandle and ChildHandle. 397 398 @retval EFI_UNSUPPORTED The driver specified by This does not support 399 the language specified by Language. 400 401 **/ 402 EFI_STATUS 403 EFIAPI 404 OpalEfiDriverComponentName2GetControllerName( 405 EFI_COMPONENT_NAME2_PROTOCOL* This, 406 EFI_HANDLE ControllerHandle, 407 EFI_HANDLE ChildHandle, 408 CHAR8* Language, 409 CHAR16** ControllerName 410 ); 411 412 #endif //_OPAL_DRIVER_H_ 413
