Re: [PATCH v5 04/13] MdeModulePkg: Add GUID for LockBox to save storage dev to init in S3

["Dong, Eric" <eric.dong@intel.com>]

Reviewed-by: Eric Dong <eric.dong@intel.com>

> -----Original Message-----
> From: Wu, Hao A
> Sent: Friday, February 15, 2019 2:23 PM
> To: edk2-devel@lists.01.org
> Cc: Wu, Hao A <hao.a.wu@intel.com>; Wang, Jian J <jian.j.wang@intel.com>;
> Dong, Eric <eric.dong@intel.com>
> Subject: [PATCH v5 04/13] 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>
> ---
>  MdeModulePkg/MdeModulePkg.dec                       |  3 +
>  MdeModulePkg/Include/Guid/S3StorageDeviceInitList.h | 64
> ++++++++++++++++++++
>  2 files changed, 67 insertions(+)
> 
> diff --git a/MdeModulePkg/MdeModulePkg.dec
> b/MdeModulePkg/MdeModulePkg.dec index 7f646d7702..a2130bc439
> 100644
> --- a/MdeModulePkg/MdeModulePkg.dec
> +++ b/MdeModulePkg/MdeModulePkg.dec
> @@ -422,6 +422,9 @@
>    ## Include/Guid/S3SmmInitDone.h
>    gEdkiiS3SmmInitDoneGuid = { 0x8f9d4825, 0x797d, 0x48fc, { 0x84, 0x71,
> 0x84, 0x50, 0x25, 0x79, 0x2e, 0xf6 } }
> 
> +  ## Include/Guid/S3StorageDeviceInitList.h
> +  gS3StorageDeviceInitListGuid = { 0x310e9b8c, 0xcf90, 0x421e, { 0x8e,
> + 0x9b, 0x9e, 0xef, 0xb6, 0x17, 0xc8, 0xef } }
> +
>  [Ppis]
>    ## Include/Ppi/AtaController.h
>    gPeiAtaControllerPpiGuid       = { 0xa45e60d1, 0xc719, 0x44aa, { 0xb0, 0x7a,
> 0xaa, 0x77, 0x7f, 0x85, 0x90, 0x6d }}
> diff --git a/MdeModulePkg/Include/Guid/S3StorageDeviceInitList.h
> b/MdeModulePkg/Include/Guid/S3StorageDeviceInitList.h
> new file mode 100644
> index 0000000000..bd300b2696
> --- /dev/null
> +++ b/MdeModulePkg/Include/Guid/S3StorageDeviceInitList.h
> @@ -0,0 +1,64 @@
> +/** @file
> +  Define the LockBox GUID for list of storage devices need to be
> +initialized in
> +  S3.
> +
> +  Copyright (c) 2019, Intel Corporation. All rights reserved.<BR>
> +
> +  This program and the accompanying materials  are licensed and made
> + available under the terms and conditions  of the BSD License which
> + accompanies this distribution.  The  full text of the license may be
> + found at  http://opensource.org/licenses/bsd-license.php
> +
> +  THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS"
> BASIS,
> + WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER
> EXPRESS OR IMPLIED.
> +
> +**/
> +
> +#ifndef __S3_STORAGE_DEVICE_INIT_LIST_H__ #define
> +__S3_STORAGE_DEVICE_INIT_LIST_H__
> +
> +#define S3_STORAGE_DEVICE_INIT_LIST \
> +  { \
> +    0x310e9b8c, 0xcf90, 0x421e, { 0x8e, 0x9b, 0x9e, 0xef, 0xb6, 0x17,
> +0xc8, 0xef } \
> +  }
> +
> +//
> +// The LockBox will store a DevicePath structure that contains one or
> +more // DevicePath instances. Each instance denotes a storage device
> +that needs to // get initialized during the S3 resume.
> +//
> +// For example, if there is only one storage device stored in the list,
> +the // content of this LockBox will be:
> +//
> +// +-------------------------------------------------------+
> +// |                 DevPath Instance #1                   |
> +// | (Terminated by an End of Hardware Device Path node    |
> +// |  with an End Entire Device Path sub-type)             |
> +// +-------------------------------------------------------+
> +//
> +// If there are n (n > 1) storage devices in the list, the content of
> +this // LockBox will be:
> +//
> +// +-------------------------------------------------------+
> +// |                 DevPath Instance #1                   |
> +// | (Terminated by an End of Hardware Device Path node    |
> +// |  with an End This Instance of a Device Path sub-type) | //
> ++-------------------------------------------------------+
> +// |                 DevPath Instance #2                   |
> +// | (Terminated by an End of Hardware Device Path node    |
> +// |  with an End This Instance of a Device Path sub-type) | //
> ++-------------------------------------------------------+
> +// |                        ...                            |
> +// +-------------------------------------------------------+
> +// |                 DevPath Instance #n                   |
> +// | (Terminated by an End of Hardware Device Path node    |
> +// |  with an End Entire Device Path sub-type)             |
> +// +-------------------------------------------------------+
> +//
> +// The attribute of the LockBox should be set to //
> +'LOCK_BOX_ATTRIBUTE_RESTORE_IN_S3_ONLY'.
> +//
> +extern EFI_GUID  gS3StorageDeviceInitListGuid;
> +
> +#endif  // __S3_STORAGE_DEVICE_INIT_LIST_H__
> --
> 2.12.0.windows.1