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

["Wu, Hao A" <hao.a.wu@intel.com>]

> -----Original Message-----
> From: Ni, Ray
> Sent: Thursday, January 31, 2019 11:27 AM
> To: Wu, Hao A; edk2-devel@lists.01.org
> Cc: Wang, Jian J; Dong, Eric
> Subject: RE: [PATCH v2 04/12] MdeModulePkg: Add GUID for LockBox to save
> storage dev to init in S3
> 
> 
> 
> > -----Original Message-----
> > From: Wu, Hao A <hao.a.wu@intel.com>
> > Sent: Thursday, January 31, 2019 10:49 AM
> > To: edk2-devel@lists.01.org
> > Cc: Wu, Hao A <hao.a.wu@intel.com>; Wang, Jian J <jian.j.wang@intel.com>;
> > Ni, Ray <ray.ni@intel.com>; Dong, Eric <eric.dong@intel.com>
> > Subject: [PATCH v2 04/12] 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 OpalPasword 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: Ray Ni <ray.ni@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>
> > ---
> >  MdeModulePkg/MdeModulePkg.dec                       |  3 ++
> >  MdeModulePkg/Include/Guid/S3StorageDeviceInitList.h | 36
> > ++++++++++++++++++++
> >  2 files changed, 39 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..cfbd2a78e7
> > --- /dev/null
> > +++ b/MdeModulePkg/Include/Guid/S3StorageDeviceInitList.h
> > @@ -0,0 +1,36 @@
> > +/** @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 zero or
> > +more // DevicePath instances. Each instance denotes a storage device
> > +that needs to // get initialized during the S3 resume.
> 
> Can you have some pseudo code to describe the structure?

Yes, I will try to draw an illustration (or an example) for the data to be
stored in this LockBox.

Best Regards,
Hao Wu

> 
> > +//
> > +// 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