MdeModulePkg: Add GUID for LockBox to save storage dev to init in S3

REF:https://bugzilla.tianocore.org/show_bug.cgi?id=1409

This commit will add the GUID definitions for LockBox which is used to
save a list of storage devices that need to get initialized during the S3
resume.

The content of the LockBox will be a DevicePath structure that contains
zero or more DevicePath instances. Each instance denotes a storage device
that needs to get initialized during the S3 resume.

The producers of the content of this LockBox will be drivers like
OpalPassword DXE driver. This kind of drivers requires some specific
storage devices to be initialized during the PEI phase of in S3 resume.
(For the OpalPassword case, it requires the managing devices to be
automatically unlocked during the S3 resume).

The attribute of the LockBox should be set to
LOCK_BOX_ATTRIBUTE_RESTORE_IN_S3_ONLY.

The consumers of the content of this LockBox will be PEI storage device
controller/bus drivers (e.g. NvmExpressPei) during S3 resume. This kind of
drivers can use the DevicePath instances stored in the LockBox to get a
list of devices that need to get initialized. In such way, an on-demand
(partial) device enumeration/initialization can be performed to benefit
the S3 resume performance.

Cc: Jian J Wang <jian.j.wang@intel.com>
Cc: Eric Dong <eric.dong@intel.com>
Contributed-under: TianoCore Contribution Agreement 1.1
Signed-off-by: Hao Wu <hao.a.wu@intel.com>
Reviewed-by: Ray Ni <ray.ni@Intel.com>
Reviewed-by: Eric Dong <eric.dong@intel.com>

diff --git a/MdeModulePkg/Include/Guid/S3StorageDeviceInitList.h b/MdeModulePkg/Include/Guid/S3StorageDeviceInitList.h
new file mode 100644 (file)
index 0000000..bd300b2
--- /dev/null
+++ b/MdeModulePkg/Include/Guid/S3StorageDeviceInitList.h
@@ -0,0 +1,64 @@
+/** @file\r
+  Define the LockBox GUID for list of storage devices need to be initialized in\r
+  S3.\r
+\r
+  Copyright (c) 2019, Intel Corporation. All rights reserved.<BR>\r
+\r
+  This program and the accompanying materials\r
+  are licensed and made available under the terms and conditions\r
+  of the BSD License which accompanies this distribution.  The\r
+  full text of the license may be found at\r
+  http://opensource.org/licenses/bsd-license.php\r
+\r
+  THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,\r
+  WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.\r
+\r
+**/\r
+\r
+#ifndef __S3_STORAGE_DEVICE_INIT_LIST_H__\r
+#define __S3_STORAGE_DEVICE_INIT_LIST_H__\r
+\r
+#define S3_STORAGE_DEVICE_INIT_LIST \\r
+  { \\r
+    0x310e9b8c, 0xcf90, 0x421e, { 0x8e, 0x9b, 0x9e, 0xef, 0xb6, 0x17, 0xc8, 0xef } \\r
+  }\r
+\r
+//\r
+// The LockBox will store a DevicePath structure that contains one or more\r
+// DevicePath instances. Each instance denotes a storage device that needs to\r
+// get initialized during the S3 resume.\r
+//\r
+// For example, if there is only one storage device stored in the list, the\r
+// content of this LockBox will be:\r
+//\r
+// +-------------------------------------------------------+\r
+// |                 DevPath Instance #1                   |\r
+// | (Terminated by an End of Hardware Device Path node    |\r
+// |  with an End Entire Device Path sub-type)             |\r
+// +-------------------------------------------------------+\r
+//\r
+// If there are n (n > 1) storage devices in the list, the content of this\r
+// LockBox will be:\r
+//\r
+// +-------------------------------------------------------+\r
+// |                 DevPath Instance #1                   |\r
+// | (Terminated by an End of Hardware Device Path node    |\r
+// |  with an End This Instance of a Device Path sub-type) |\r
+// +-------------------------------------------------------+\r
+// |                 DevPath Instance #2                   |\r
+// | (Terminated by an End of Hardware Device Path node    |\r
+// |  with an End This Instance of a Device Path sub-type) |\r
+// +-------------------------------------------------------+\r
+// |                        ...                            |\r
+// +-------------------------------------------------------+\r
+// |                 DevPath Instance #n                   |\r
+// | (Terminated by an End of Hardware Device Path node    |\r
+// |  with an End Entire Device Path sub-type)             |\r
+// +-------------------------------------------------------+\r
+//\r
+// The attribute of the LockBox should be set to\r
+// 'LOCK_BOX_ATTRIBUTE_RESTORE_IN_S3_ONLY'.\r
+//\r
+extern EFI_GUID  gS3StorageDeviceInitListGuid;\r
+\r
+#endif  // __S3_STORAGE_DEVICE_INIT_LIST_H__\r

diff --git a/MdeModulePkg/MdeModulePkg.dec b/MdeModulePkg/MdeModulePkg.dec
index 7f646d7702aeb2b43dfba7c126af91d38a9d21de..a2130bc43991b6dc402e8ab4e1b4ce19c23f752a 100644 (file)
--- a/MdeModulePkg/MdeModulePkg.dec
+++ b/MdeModulePkg/MdeModulePkg.dec
@@ -422,6 +422,9 @@
   ## Include/Guid/S3SmmInitDone.h\r
   gEdkiiS3SmmInitDoneGuid = { 0x8f9d4825, 0x797d, 0x48fc, { 0x84, 0x71, 0x84, 0x50, 0x25, 0x79, 0x2e, 0xf6 } }\r
 \r
+  ## Include/Guid/S3StorageDeviceInitList.h\r
+  gS3StorageDeviceInitListGuid = { 0x310e9b8c, 0xcf90, 0x421e, { 0x8e, 0x9b, 0x9e, 0xef, 0xb6, 0x17, 0xc8, 0xef } }\r
+\r
 [Ppis]\r
   ## Include/Ppi/AtaController.h\r
   gPeiAtaControllerPpiGuid       = { 0xa45e60d1, 0xc719, 0x44aa, { 0xb0, 0x7a, 0xaa, 0x77, 0x7f, 0x85, 0x90, 0x6d }}\r