SecurityPkg/Tcg/Opal/OpalPasswordDxe/OpalDriver.h

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