Platforms/Docs: Refresh features in QEMU Q35 readme (microsoft#674)

- Adds missing features with pre-existing feature readmes - Adds a Table of Contents and sorts sections to make navigating the file easier - Adds some more detail in a few areas - [ ] Impacts functionality? - **Functionality** - Does the change ultimately impact how firmware functions? - Examples: Add a new library, publish a new PPI, update an algorithm, ... - [ ] Impacts security? - **Security** - Does the change have a direct security impact on an application, flow, or firmware? - Examples: Crypto algorithm change, buffer overflow fix, parameter validation improvement, ... - [ ] Breaking change? - **Breaking change** - Will anyone consuming this change experience a break in build or boot behavior? - Examples: Add a new library class, move a module to a different repo, call a function in a new library class in a pre-existing module, ... - [ ] Includes tests? - **Tests** - Does the change include any explicit test code? - Examples: Unit tests, integration tests, robot tests, ... - [x] Includes documentation? - **Documentation** - Does the change contain explicit documentation additions outside direct code modifications (and comments)? - Examples: Update readme file, add feature readme file, link to documentation on an a separate Web page, ... - markdownlint N/A Signed-off-by: Michael Kubacki <[email protected]>
Javagedes · Aug 29, 2023 · c996048 · c996048
1 parent b4feacf
commit c996048
Show file tree

Hide file tree

Showing 4 changed files with 94 additions and 39 deletions.
diff --git a/Platforms/Docs/Common/Features/feature_memoryprotection.md b/Platforms/Docs/Common/Features/feature_memoryprotection.md
@@ -1,12 +1,24 @@
 # Memory Protection
 
-For in-depth information on Memory Protection in Project Mu, see
-[feature_memory_protection.md](../../../../MU_BASECORE/Docs/feature_memory_protection.md)
+For in-depth technical details on Memory Protection in Project Mu, see
+[feature_memory_protection.md](https://github.com/microsoft/mu_basecore/blob/HEAD/Docs/feature_memory_protection.md)
 
-Memory protection is ON by default on Q35 and SBSA. To disable memory protection
-add `BLD_*_MEMORY_PROTECTION=FALSE` to your `stuart_build` command. Example:
+Memory protections are important because Unified Extensible Firmware Interface (UEFI) standard accounts for the
+firmware design implemented in 80 to 90 percent of the of PCs and servers sold worldwide. Developed and supported by
+more than 250 industry-leading companies, UEFI firmware is responsible for booting and securing billions of devices
+spanning device classes from embedded applications to multi-role server systems.
+
+While considerable attention has been devoted to hardware trust anchors and operating system security, attackers have
+discovered that UEFI firmware is lacking basic memory protections that have been present in other system software for
+over a decade. Coupled with the inconsistency of security capabilities inherit to vendor firmware implementations,
+UEFI firmware has become an increasingly attractive system attack vector.
+
+`QemuQ35Pkg` and `QemuSbsaPkg` allow experimentation with the memory protections being offered in physical platforms.
+
+Memory protections are ON by default on Q35 and SBSA. To disable memory protection add `BLD_*_MEMORY_PROTECTION=FALSE`
+to your `stuart_build` command. Example:
 
 `stuart_build -c .\Platforms\<Platform>\PlatformBuild.py BLD_*_MEMORY_PROTECTION=FALSE --FlashRom`
 
-Because `MEMORY_PROTECTION` is a build flag, the platform will need to be rebuilt for a change to the
-value to take effect (meaning `--FlashOnly` will not work).
+Because `MEMORY_PROTECTION` is a build flag, the platform will need to be rebuilt for a change to the value to take
+effect (meaning `--FlashOnly` will not work).
diff --git a/Platforms/Docs/Q35/QemuQ35_ReadMe.md b/Platforms/Docs/Q35/QemuQ35_ReadMe.md
@@ -12,6 +12,25 @@ By solely focusing on the Q35 chipset, this package can be optimized such that i
 with other QEMU supported chipsets. The Q35 chipset can be paired with an IA32 or X64 processor to enable a machine
 that can emulate PC class hardware with industry standard features like SMM and PCI-E.
 
+## Table of Contents
+
+- [QemuQ35Pkg](#qemuq35pkg)
+  - [Q35 Platform](#q35-platform)
+  - [Compiling and Running QEMU](#compiling-and-running-qemu)
+  - [Firmware Features](#firmware-features)
+    - [CodeQL](#codeql)
+    - [Color Bar](#color-bar)
+    - [Config](#config)
+    - [Device Firmware Configuration Interface (DFCI)](#device-firmware-configuration-interface-dfci)
+    - [Mu Front Page](#mu-front-page)
+    - [Mu Telemetry / WHEA / HwErrorRecord](#mu-telemetry--whea--hwerrorrecord)
+    - [Platform Runtime Mechanism (PRM)](#platform-runtime-mechanism-prm)
+    - [Trusted Platform Module (TPM)](#trusted-platform-module-tpm)
+    - [UEFI Memory Protections](#uefi-memory-protections)
+  - [Mu Customized Components](#mu-customized-components)
+    - [Modules](#modules)
+    - [Libraries](#libraries)
+
 ## Q35 Platform
 
 Q35 is a machine type that QEMU emulates.
@@ -34,15 +53,34 @@ Specific details can be found here [Development/building.md](../Common/building.
 QemuQ35Pkg is a great environment to demonstrate Project Mu features without any restricted or costly physical
 hardware. Current QEMU Q35 platform supports the following features provided by Project Mu:
 
-### Mu Front Page
+### CodeQL
 
-Enable the Project Mu OEM sample "front page".
-This is a touch friendly, graphical, UEFI HII based UI application that
-allows basic platform and boot device configuration.
+CodeQL is open source and free for open-source projects. It is maintained by GitHub and naturally has excellent
+integration with GitHub projects. CodeQL uses a semantic code analysis engine to discover vulnerabilities in a
+number of programming languages (both compiled and interpreted).
 
-[Details](../Common/Features/feature_frontpage.md)
+Project Mu (and TianoCore) use CodeQL C/C++ queries to find common programming errors and security vulnerabilities in
+firmware code. This platform leverages the CodeQL build plugin from Mu Basecore that makes it very easy to run CodeQL
+against this platform. You simply use provide the `--codeql` argument in your normal `stuart_update` and `stuart_build`
+commands.
+
+[Details](Features/feature_codeql.md)
+
+### Color Bar
+
+Color bars are used to quickly convey the Device state, based upon the DeviceStateLib. Color bars are displayed
+by the ColorBarDisplayDeviceStateLib.
+
+[Details](Features/feature_colorbar.md)
+
+### Config
+
+Project Mu offers a UEFI configuration feature with example implementation in `QemuQ35Pkg`. Background about the
+features and more details about its integration in this repo are available in the detailed readme.
 
-### Device Firmware Configuration Interface
+[Details](Features/feature_config.md)
+
+### Device Firmware Configuration Interface (DFCI)
 
 The DFCI feature enables cloud management services (MDM services like Microsoft Intune) to manage some PC
 bios settings **securely**.  DFCI is a foundational feature that provides a shared identity and ownership
@@ -51,6 +89,15 @@ to securely communicate across untrusted mediums (network or usb).
 
 [Details](../Common/Features/feature_dfci.md)
 
+### Mu Front Page
+
+This feature enables the Project Mu OEM sample "front page".
+
+This is a touch friendly, graphical, UEFI HII based UI application that allows basic platform and boot device
+configuration.
+
+[Details](../Common/Features/feature_frontpage.md)
+
 ### Mu Telemetry / WHEA / HwErrorRecord
 
 The Mu Telemetry feature is an extension of the PI spec defined report status code.  The feature is
@@ -69,25 +116,21 @@ sample PRM modules are used to demonstrate the feature and show how additional m
 
 [Details](Features/feature_prm.md)
 
-### CodeQL
-
-CodeQL is open source and free for open-source projects. It is maintained by GitHub and naturally has excellent
-integration with GitHub projects. CodeQL uses a semantic code analysis engine to discover vulnerabilities in a
-number of programming languages (both compiled and interpreted).
+### Trusted Platform Module (TPM)
 
-Project Mu (and TianoCore) use CodeQL C/C++ queries to find common programming errors and security vulnerabilities in
-firmware code. This platform leverages the CodeQL build plugin from Mu Basecore that makes it very easy to run CodeQL
-against this platform. You simply use provide the `--codeql` argument in your normal `stuart_update` and `stuart_build`
-commands.
+QEMU TPM emulation implements a TPM TIS hardware interface that follows the Trusted Computing Group's TCG PC Client
+Specific TPM Interface Specification (TIS) in addition to a TPM CRB interface that follows the TCG PC Client Platform
+TPM Profile (PTP) Specification. `QemuQ35Pkg` has support to include TPM drivers and connect to the software TPM
+socket interface. Usage is covered in the detailed feature readme.
 
-[Details](Features/feature_codeql.md)
+[Details](Features/feature_tpm.md)
 
-### Q35 Supported Color Bar
+### UEFI Memory Protections
 
-Color bars are used to quickly convey the Device state, based upon the DeviceStateLib. Color bars are displayed
-by the ColorBarDisplayDeviceStateLib.
+UEFI Memory Protections add safety functionality such as page and pool guards, stack guard, and null pointer
+detection. The settings are split between MM and DXE environments for modularity.
 
-[Details](Features/feature_colorbar.md)
+[Details](../Common/Features/feature_memoryprotection.md)
 
 ## Mu Customized Components
 

diff --git a/Platforms/QemuQ35Pkg/PlatformBuild.py b/Platforms/QemuQ35Pkg/PlatformBuild.py
@@ -267,16 +267,16 @@ def SetPlatformEnv(self):
         self.env.SetValue("BLD_*_MEMORY_PROTECTION", "TRUE", "Default")
         # Include the MFCI test cert by default, override on the commandline with "BLD_*_SHIP_MODE=TRUE" if you want the retail MFCI cert
         self.env.SetValue("BLD_*_SHIP_MODE", "FALSE", "Default")
-        self.env.SetValue("CONF_AUTOGEN_INCLUDE_PATH", self.mws.join(self.ws, "Platforms", "QemuQ35Pkg", "Include"), "Platform Defined")
+        self.env.SetValue("CONF_AUTOGEN_INCLUDE_PATH", self.edk2path.GetAbsolutePathOnThisSystemFromEdk2RelativePath("QemuQ35Pkg", "Include"), "Platform Defined")
 
-        self.env.SetValue("YAML_POLICY_FILE", self.mws.join(self.ws, "QemuQ35Pkg", "PolicyData", "PolicyDataUsb.yaml"), "Platform Hardcoded")
-        self.env.SetValue("POLICY_DATA_STRUCT_FOLDER", self.mws.join(self.ws, "QemuQ35Pkg", "Include"), "Platform Defined")
-        self.env.SetValue('POLICY_REPORT_FOLDER', self.mws.join(self.ws, "QemuQ35Pkg", "PolicyData"), "Platform Defined")
-        self.env.SetValue('MU_SCHEMA_DIR', self.mws.join(self.ws, "Platforms", "QemuQ35Pkg", "CfgData"), "Platform Defined")
+        self.env.SetValue("YAML_POLICY_FILE", self.edk2path.GetAbsolutePathOnThisSystemFromEdk2RelativePath("QemuQ35Pkg", "PolicyData", "PolicyDataUsb.yaml"), "Platform Hardcoded")
+        self.env.SetValue("POLICY_DATA_STRUCT_FOLDER", self.edk2path.GetAbsolutePathOnThisSystemFromEdk2RelativePath("QemuQ35Pkg", "Include"), "Platform Defined")
+        self.env.SetValue('POLICY_REPORT_FOLDER', self.edk2path.GetAbsolutePathOnThisSystemFromEdk2RelativePath("QemuQ35Pkg", "PolicyData"), "Platform Defined")
+        self.env.SetValue('MU_SCHEMA_DIR', self.edk2path.GetAbsolutePathOnThisSystemFromEdk2RelativePath("QemuQ35Pkg", "CfgData"), "Platform Defined")
         self.env.SetValue('MU_SCHEMA_FILE_NAME', "QemuQ35PkgCfgData.xml", "Platform Hardcoded")
         self.env.SetValue('CONF_PROFILE_PATHS',
-                          self.mws.join(self.ws, 'Platforms', 'QemuQ35Pkg', 'CfgData', 'Profile0QemuQ35PkgCfgData.csv') + " " +
-                          self.mws.join(self.ws, 'Platforms', 'QemuQ35Pkg', 'CfgData', 'Profile1QemuQ35PkgCfgData.csv'),
+                          self.edk2path.GetAbsolutePathOnThisSystemFromEdk2RelativePath('QemuQ35Pkg', 'CfgData', 'Profile0QemuQ35PkgCfgData.csv') + " " +
+                          self.edk2path.GetAbsolutePathOnThisSystemFromEdk2RelativePath('QemuQ35Pkg', 'CfgData', 'Profile1QemuQ35PkgCfgData.csv'),
                           "Platform Hardcoded"
         )
         self.env.SetValue('CONF_PROFILE_NAMES', "P0,P1", "Platform Hardcoded")
@@ -301,7 +301,7 @@ def SetPlatformEnvAfterTarget(self):
 
     def PlatformPreBuild(self):
         # Here we build the secure policy blob for build system to use and add into the targeted FV
-        policy_example_dir = self.mws.join(self.mws.WORKSPACE, "MmSupervisorPkg", "SupervisorPolicyTools", "MmIsolationPoliciesExample.xml")
+        policy_example_dir = self.edk2path.GetAbsolutePathOnThisSystemFromEdk2RelativePath("MmSupervisorPkg", "SupervisorPolicyTools", "MmIsolationPoliciesExample.xml")
         output_dir = os.path.join(self.env.GetValue("BUILD_OUTPUT_BASE"), "Policy")
         if (not os.path.isdir(output_dir)):
             os.makedirs (output_dir)

diff --git a/Platforms/QemuSbsaPkg/PlatformBuild.py b/Platforms/QemuSbsaPkg/PlatformBuild.py
@@ -246,13 +246,13 @@ def SetPlatformEnv(self):
         # Include the MFCI test cert by default, override on the commandline with "BLD_*_SHIP_MODE=TRUE" if you want the retail MFCI cert
         self.env.SetValue("BLD_*_SHIP_MODE", "FALSE", "Default")
 
-        self.env.SetValue("CONF_AUTOGEN_INCLUDE_PATH", self.mws.join(self.ws, "Platforms", "QemuSbsaPkg", "Include"), "Platform Hardcoded")
-        self.env.SetValue("MU_SCHEMA_DIR", self.mws.join(self.ws, "Platforms", "QemuSbsaPkg", "CfgData"), "Platform Defined")
+        self.env.SetValue("CONF_AUTOGEN_INCLUDE_PATH",self.edk2path.GetAbsolutePathOnThisSystemFromEdk2RelativePath("QemuSbsaPkg", "Include"), "Platform Hardcoded")
+        self.env.SetValue("MU_SCHEMA_DIR", self.edk2path.GetAbsolutePathOnThisSystemFromEdk2RelativePath("QemuSbsaPkg", "CfgData"), "Platform Defined")
         self.env.SetValue("MU_SCHEMA_FILE_NAME", "QemuSbsaPkgCfgData.xml", "Platform Hardcoded")
 
-        self.env.SetValue("YAML_POLICY_FILE", self.mws.join(self.ws, "QemuQ35Pkg", "PolicyData", "PolicyDataUsb.yaml"), "Platform Hardcoded")
-        self.env.SetValue("POLICY_DATA_STRUCT_FOLDER", self.mws.join(self.ws, "QemuQ35Pkg", "Include"), "Platform Defined")
-        self.env.SetValue('POLICY_REPORT_FOLDER', self.mws.join(self.ws, "QemuQ35Pkg", "PolicyData"), "Platform Defined")
+        self.env.SetValue("YAML_POLICY_FILE", self.edk2path.GetAbsolutePathOnThisSystemFromEdk2RelativePath("QemuQ35Pkg", "PolicyData", "PolicyDataUsb.yaml"), "Platform Hardcoded")
+        self.env.SetValue("POLICY_DATA_STRUCT_FOLDER", self.edk2path.GetAbsolutePathOnThisSystemFromEdk2RelativePath("QemuQ35Pkg", "Include"), "Platform Defined")
+        self.env.SetValue('POLICY_REPORT_FOLDER', self.edk2path.GetAbsolutePathOnThisSystemFromEdk2RelativePath("QemuQ35Pkg", "PolicyData"), "Platform Defined")
 
         return 0