Skip to content

Commit

Permalink
Platforms/Docs: Refresh features in QEMU Q35 readme (#674)
Browse files Browse the repository at this point in the history
## Description

- 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, ...

## How This Was Tested

- markdownlint

## Integration Instructions

N/A

Signed-off-by: Michael Kubacki <[email protected]>
  • Loading branch information
makubacki authored Aug 25, 2023
1 parent b4feacf commit b341487
Show file tree
Hide file tree
Showing 2 changed files with 81 additions and 26 deletions.
24 changes: 18 additions & 6 deletions Platforms/Docs/Common/Features/feature_memoryprotection.md
Original file line number Diff line number Diff line change
@@ -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).
83 changes: 63 additions & 20 deletions Platforms/Docs/Q35/QemuQ35_ReadMe.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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

Expand Down

0 comments on commit b341487

Please sign in to comment.