[edk2-platforms][PATCH V2 12/47] Features/Intel/S3FeaturePkg: Add initial package

["Kubacki, Michael A" <michael.a.kubacki@intel.com>]

Adds a new feature package for the S3 feature.

Cc: Sai Chaganty <rangasai.v.chaganty@intel.com>
Cc: Liming Gao <liming.gao@intel.com>
Signed-off-by: Michael Kubacki <michael.a.kubacki@intel.com>
---
 Features/Intel/PowerManagement/S3FeaturePkg/S3FeaturePkg.dec       |  30 +++++
 Features/Intel/PowerManagement/S3FeaturePkg/Include/S3Feature.dsc  | 122 ++++++++++++++++++++
 Features/Intel/PowerManagement/S3FeaturePkg/S3FeaturePkg.dsc       |  30 +++++
 Features/Intel/PowerManagement/S3FeaturePkg/Include/PostMemory.fdf |   8 ++
 Features/Intel/PowerManagement/S3FeaturePkg/Include/PreMemory.fdf  |  10 ++
 Features/Intel/PowerManagement/S3FeaturePkg/S3Pei/S3Pei.inf        |  35 ++++++
 Features/Intel/PowerManagement/S3FeaturePkg/S3Pei/S3Pei.c          |  36 ++++++
 Features/Intel/PowerManagement/S3FeaturePkg/Readme.md              |  94 +++++++++++++++
 8 files changed, 365 insertions(+)

diff --git a/Features/Intel/PowerManagement/S3FeaturePkg/S3FeaturePkg.dec b/Features/Intel/PowerManagement/S3FeaturePkg/S3FeaturePkg.dec
new file mode 100644
index 0000000000..2a723ad3d6
--- /dev/null
+++ b/Features/Intel/PowerManagement/S3FeaturePkg/S3FeaturePkg.dec
@@ -0,0 +1,30 @@
+## @file
+# This package provides advanced feature functionality for S3 support.
+# This package should only depend on EDK II Core packages, IntelSiliconPkg, and MinPlatformPkg.
+#
+# The DEC files are used by the utilities that parse DSC and
+# INF files to generate AutoGen.c and AutoGen.h files
+# for the build infrastructure.
+#
+# Copyright (c) 2019, Intel Corporation. All rights reserved.<BR>
+#
+# SPDX-License-Identifier: BSD-2-Clause-Patent
+#
+##
+
+[Defines]
+  DEC_SPECIFICATION = 0x00010017
+  PACKAGE_NAME      = S3FeaturePkg
+  PACKAGE_GUID      = 600F7249-65BD-44E2-80D7-344BD5250198
+  PACKAGE_VERSION   = 0.1
+
+[Includes]
+  Include
+
+[LibraryClasses]
+
+[Guids]
+  gS3FeaturePkgTokenSpaceGuid  =  {0x423c5a51, 0x36e9, 0x4aea, {0x92, 0xdd, 0xdd, 0xae, 0x5b, 0x4a, 0x3d, 0x24}}
+
+[PcdsFeatureFlag]
+  gS3FeaturePkgTokenSpaceGuid.PcdS3FeatureEnable|FALSE|BOOLEAN|0xA0000001
diff --git a/Features/Intel/PowerManagement/S3FeaturePkg/Include/S3Feature.dsc b/Features/Intel/PowerManagement/S3FeaturePkg/Include/S3Feature.dsc
new file mode 100644
index 0000000000..647dc3f93a
--- /dev/null
+++ b/Features/Intel/PowerManagement/S3FeaturePkg/Include/S3Feature.dsc
@@ -0,0 +1,122 @@
+## @file
+# This is a build description file for the S3 advanced feature.
+# This file should be included into another package DSC file to build this feature.
+#
+# The DEC files are used by the utilities that parse DSC and
+# INF files to generate AutoGen.c and AutoGen.h files
+# for the build infrastructure.
+#
+# Copyright (c) 2019, Intel Corporation. All rights reserved.<BR>
+#
+# SPDX-License-Identifier: BSD-2-Clause-Patent
+#
+##
+
+################################################################################
+#
+# Defines Section - statements that will be processed to create a Makefile.
+#
+################################################################################
+[Defines]
+!ifndef $(PEI_ARCH)
+  !error "PEI_ARCH must be specified to build this feature!"
+!endif
+!ifndef $(DXE_ARCH)
+  !error "DXE_ARCH must be specified to build this feature!"
+!endif
+
+################################################################################
+#
+# Library Class section - list of all Library Classes needed by this feature.
+#
+################################################################################
+[LibraryClasses]
+  #######################################
+  # Edk2 Packages
+  #######################################
+  BaseLib|MdePkg/Library/BaseLib/BaseLib.inf
+  BaseMemoryLib|MdePkg/Library/BaseMemoryLibRepStr/BaseMemoryLibRepStr.inf
+  DebugLib|MdePkg/Library/BaseDebugLibNull/BaseDebugLibNull.inf
+  IoLib|MdePkg/Library/BaseIoLibIntrinsic/BaseIoLibIntrinsic.inf
+  PciCf8Lib|MdePkg/Library/BasePciCf8Lib/BasePciCf8Lib.inf
+  PciLib|MdePkg/Library/BasePciLibCf8/BasePciLibCf8.inf
+  PciSegmentLib|MdePkg/Library/BasePciSegmentLibPci/BasePciSegmentLibPci.inf
+
+[LibraryClasses.common.PEI_CORE,LibraryClasses.common.PEIM]
+  #######################################
+  # Edk2 Packages
+  #######################################
+  HobLib|MdePkg/Library/PeiHobLib/PeiHobLib.inf
+  MemoryAllocationLib|MdePkg/Library/PeiMemoryAllocationLib/PeiMemoryAllocationLib.inf
+  PcdLib|MdePkg/Library/PeiPcdLib/PeiPcdLib.inf
+  PeimEntryPoint|MdePkg/Library/PeimEntryPoint/PeimEntryPoint.inf
+  PeiServicesLib|MdePkg/Library/PeiServicesLib/PeiServicesLib.inf
+  PeiServicesTablePointerLib|MdePkg/Library/PeiServicesTablePointerLibIdt/PeiServicesTablePointerLibIdt.inf
+
+  #######################################
+  # Silicon Initialization Package
+  #######################################
+  SmmAccessLib|IntelSiliconPkg/Feature/SmmAccess/Library/PeiSmmAccessLib/PeiSmmAccessLib.inf
+
+################################################################################
+#
+# Component section - list of all components that need built for this feature.
+#
+# Note: The EDK II DSC file is not used to specify how compiled binary images get placed
+#       into firmware volume images. This section is just a list of modules to compile from
+#       source into UEFI-compliant binaries.
+#       It is the FDF file that contains information on combining binary files into firmware
+#       volume images, whose concept is beyond UEFI and is described in PI specification.
+#       There may also be modules listed in this section that are not required in the FDF file,
+#       When a module listed here is excluded from FDF file, then UEFI-compliant binary will be
+#       generated for it, but the binary will not be put into any firmware volume.
+#
+################################################################################
+
+#
+# Feature PEI Components
+#
+
+# @todo: Change below line to [Components.$(PEI_ARCH)] after https://bugzilla.tianocore.org/show_bug.cgi?id=2308
+#        is completed.
+[Components.IA32]
+  #####################################
+  # S3 Feature Package
+  #####################################
+
+  # Add library instances here that are not included in package components and should be tested
+  # in the package build.
+
+  # Add components here that should be included in the package build.
+  PowerManagement/S3FeaturePkg/S3Pei/S3Pei.inf
+
+#
+# Feature DXE Components
+#
+
+# @todo: Change below line to [Components.$(DXE_ARCH)] after https://bugzilla.tianocore.org/show_bug.cgi?id=2308
+#        is completed.
+[Components.X64]
+  #####################################
+  # S3 Feature Package
+  #####################################
+
+  # Add library instances here that are not included in package components and should be tested
+  # in the package build.
+
+  # Add components here that should be included in the package build.
+
+###################################################################################################
+#
+# BuildOptions Section - Define the module specific tool chain flags that should be used as
+#                        the default flags for a module. These flags are appended to any
+#                        standard flags that are defined by the build process. They can be
+#                        applied for any modules or only those modules with the specific
+#                        module style (EDK or EDKII) specified in [Components] section.
+#
+#                        For advanced features, it is recommended to enable [BuildOptions] in
+#                        the applicable INF file so it does not affect the whole board package
+#                        build when this DSC file is active.
+#
+###################################################################################################
+[BuildOptions]
diff --git a/Features/Intel/PowerManagement/S3FeaturePkg/S3FeaturePkg.dsc b/Features/Intel/PowerManagement/S3FeaturePkg/S3FeaturePkg.dsc
new file mode 100644
index 0000000000..28ee49d429
--- /dev/null
+++ b/Features/Intel/PowerManagement/S3FeaturePkg/S3FeaturePkg.dsc
@@ -0,0 +1,30 @@
+## @file
+# This package provides advanced feature functionality for S3 support.
+# This package should only depend on EDK II Core packages, IntelSiliconPkg, and MinPlatformPkg.
+#
+# The DEC files are used by the utilities that parse DSC and
+# INF files to generate AutoGen.c and AutoGen.h files
+# for the build infrastructure.
+#
+# Copyright (c) 2019, Intel Corporation. All rights reserved.<BR>
+#
+# SPDX-License-Identifier: BSD-2-Clause-Patent
+#
+##
+
+[Defines]
+  PLATFORM_NAME                  = S3FeaturePkg
+  PLATFORM_GUID                  = 02E7C519-5A24-4594-8D69-F4117D6E3D25
+  PLATFORM_VERSION               = 0.1
+  DSC_SPECIFICATION              = 0x00010005
+  OUTPUT_DIRECTORY               = Build/$(PLATFORM_NAME)
+  SUPPORTED_ARCHITECTURES        = IA32|X64
+  BUILD_TARGETS                  = DEBUG|RELEASE|NOOPT
+  SKUID_IDENTIFIER               = DEFAULT
+  PEI_ARCH                       = IA32
+  DXE_ARCH                       = X64
+
+#
+# This package always builds the feature.
+#
+!include Include/S3Feature.dsc
diff --git a/Features/Intel/PowerManagement/S3FeaturePkg/Include/PostMemory.fdf b/Features/Intel/PowerManagement/S3FeaturePkg/Include/PostMemory.fdf
new file mode 100644
index 0000000000..9e17f853c6
--- /dev/null
+++ b/Features/Intel/PowerManagement/S3FeaturePkg/Include/PostMemory.fdf
@@ -0,0 +1,8 @@
+## @file
+#  FDF file for post-memory S3 advanced feature modules.
+#
+# Copyright (c) 2019, Intel Corporation. All rights reserved.<BR>
+#
+# SPDX-License-Identifier: BSD-2-Clause-Patent
+#
+##
diff --git a/Features/Intel/PowerManagement/S3FeaturePkg/Include/PreMemory.fdf b/Features/Intel/PowerManagement/S3FeaturePkg/Include/PreMemory.fdf
new file mode 100644
index 0000000000..3cd5cd9628
--- /dev/null
+++ b/Features/Intel/PowerManagement/S3FeaturePkg/Include/PreMemory.fdf
@@ -0,0 +1,10 @@
+## @file
+#  FDF file for pre-memory S3 advanced feature modules.
+#
+# Copyright (c) 2019, Intel Corporation. All rights reserved.<BR>
+#
+# SPDX-License-Identifier: BSD-2-Clause-Patent
+#
+##
+
+  INF PowerManagement/S3FeaturePkg/S3Pei/S3Pei.inf
diff --git a/Features/Intel/PowerManagement/S3FeaturePkg/S3Pei/S3Pei.inf b/Features/Intel/PowerManagement/S3FeaturePkg/S3Pei/S3Pei.inf
new file mode 100644
index 0000000000..46fbb62a46
--- /dev/null
+++ b/Features/Intel/PowerManagement/S3FeaturePkg/S3Pei/S3Pei.inf
@@ -0,0 +1,35 @@
+### @file
+# Component information file for the S3 PEI module.
+#
+# Copyright (c) 2019, Intel Corporation. All rights reserved.<BR>
+#
+# SPDX-License-Identifier: BSD-2-Clause-Patent
+#
+###
+
+[Defines]
+  INF_VERSION       = 0x00010017
+  BASE_NAME         = S3Pei
+  FILE_GUID         = 8683EFB2-FDE1-4AFF-B2DB-E96449FDD4E9
+  VERSION_STRING    = 1.0
+  MODULE_TYPE       = PEIM
+  ENTRY_POINT       = S3PeiEntryPoint
+
+[LibraryClasses]
+  PeimEntryPoint
+  PeiServicesLib
+  SmmAccessLib
+
+[Packages]
+  MdePkg/MdePkg.dec
+  IntelSiliconPkg/IntelSiliconPkg.dec
+  PowerManagement/S3FeaturePkg/S3FeaturePkg.dec
+
+[Sources]
+  S3Pei.c
+
+[FeaturePcd]
+  gS3FeaturePkgTokenSpaceGuid.PcdS3FeatureEnable
+
+[Depex]
+  gEfiPeiMemoryDiscoveredPpiGuid
diff --git a/Features/Intel/PowerManagement/S3FeaturePkg/S3Pei/S3Pei.c b/Features/Intel/PowerManagement/S3FeaturePkg/S3Pei/S3Pei.c
new file mode 100644
index 0000000000..b0aaa04962
--- /dev/null
+++ b/Features/Intel/PowerManagement/S3FeaturePkg/S3Pei/S3Pei.c
@@ -0,0 +1,36 @@
+/** @file
+  Source code file for S3 PEI module
+
+Copyright (c) 2019, Intel Corporation. All rights reserved.<BR>
+SPDX-License-Identifier: BSD-2-Clause-Patent
+
+**/
+
+#include <Library/PeiServicesLib.h>
+#include <Library/SmmAccessLib.h>
+
+/**
+  S3 PEI module entry point
+
+  @param[in]  FileHandle           Not used.
+  @param[in]  PeiServices          General purpose services available to every PEIM.
+
+  @retval     EFI_SUCCESS          The function completes successfully
+  @retval     EFI_OUT_OF_RESOURCES Insufficient resources to create database
+**/
+EFI_STATUS
+EFIAPI
+S3PeiEntryPoint (
+  IN       EFI_PEI_FILE_HANDLE  FileHandle,
+  IN CONST EFI_PEI_SERVICES     **PeiServices
+  )
+{
+  EFI_STATUS Status;
+
+  //
+  // Install EFI_PEI_MM_ACCESS_PPI for S3 resume case
+  //
+  Status = PeiInstallSmmAccessPpi ();
+
+  return Status;
+}
diff --git a/Features/Intel/PowerManagement/S3FeaturePkg/Readme.md b/Features/Intel/PowerManagement/S3FeaturePkg/Readme.md
new file mode 100644
index 0000000000..f9b60b3f0c
--- /dev/null
+++ b/Features/Intel/PowerManagement/S3FeaturePkg/Readme.md
@@ -0,0 +1,94 @@
+# Overview
+* **Feature Name:** S3
+* **PI Phase(s) Supported:** PEI
+* **SMM Required?** Yes
+
+More Information:
+* [A Tour Beyond BIOS - Implementing S3 Resume with EDK II](https://github.com/tianocore-docs/Docs/raw/master/White_Papers/A_Tour_Beyond_BIOS_Implementing_S3_resume_with_EDKII_V2.pdf)
+* [UEFI ACPI & Platform Initialization (PI Specification)](https://uefi.org/specifications)
+
+## Purpose
+The S3 feature provides the set of firmware resources and board enabling instructions to enable S3 firmware feature
+support in a board package. S3 resume is a power saving feature defined in the Advanced Configuration and Power
+Interface (ACPI) specification. The ACPI specification defines a set of power state transitions. In the context of this
+feature, S3 refers to the G1 sleeping - S3 sleeping state.
+
+**Note: The S3 feature is currently not complete. Additional functionality will be enabled in the future.**
+
+# High-Level Theory of Operation
+*_TODO_*
+A description of how the device works at a high-level.
+
+The description should not be constrained to implementation details but provide a simple mental model of how the
+feature is supposed to work.
+
+## Firmware Volumes
+*_TODO_*
+A bulleted list of the firmware volumes that feature module(s) are placed in.
+
+## Modules
+*_TODO_*
+A bulleted list of the modules that make up the feature.
+
+## <Module Name>
+*_TODO_*
+Each module in the feature should have a section that describes the module in a level of detail that is useful
+to better understand the module source code.
+
+## <Library Name>
+*_TODO_*
+Each library in the feature should have a section that describes the library in a level of detail that is useful
+to better understand the library source code.
+
+## Key Functions
+*_TODO_*
+A bulleted list of key functions for interacting with the feature.
+
+Not all features need to be listed. Only functions exposed through external interfaces that are important for feature
+users to be aware of.
+
+## Configuration
+*_TODO_*
+Information that is useful for configuring the feature.
+
+Not all configuration options need to be listed. This section is used to provide more background on configuration
+options than possible elsewhere.
+
+## Data Flows
+*_TODO_*
+Architecturally defined data structures and flows for the feature.
+
+## Control Flows
+*_TODO_*
+Key control flows for the feature.
+
+## Build Flows
+*_TODO_*
+Any special build flows should be described in this section.
+
+This is particularly useful for features that use custom build tools or require non-standard tool configuration. If the
+standard flow in the feature package template is used, this section may be empty.
+
+## Test Point Results
+*_TODO_*
+The test(s) that can verify porting is complete for the feature.
+
+Each feature must describe at least one test point to verify the feature is successful. If the test point is not
+implemented, this should be stated.
+
+## Functional Exit Criteria
+*_TODO_*
+The testable functionality for the feature.
+
+This section should provide an ordered list of criteria that a board integrator can reference to ensure the feature is
+functional on their board.
+
+## Feature Enabling Checklist
+*_TODO_*
+An ordered list of required activities to achieve desired functionality for the feature.
+
+## Common Optimizations
+*_TODO_*
+Common size or performance tuning options for this feature.
+
+This section is recommended but not required. If not used, the contents should be left empty.
-- 
2.16.2.windows.1