Refine the each section format

Signed-off-by: Jiaxin Wu <[email protected]>

Author: Jiaxin Wu

1_mm_introduction.md

@@ -29,9 +29,9 @@
 
 -->
 
-# MM Introduction
+# 1 MM Introduction
 
-## SMM and MM Overview
+## 1.1 SMM and MM Overview
 
 This section describes the main differences between Traditional SMM and Standalone MM. A detailed comparison of the Traditional MM and Standalone MM load process is described in the PI Specification sections "Initializing Management Mode in MM Traditional Mode" and "Initializing Management Mode in Standalone Mode" respectively.
 
@@ -52,12 +52,12 @@ MM Driver:
 - Module type is `MM_STANDALONE`. The entry point of an updatable MM driver follows the PI specification `MM_IMAGE_ENTRY_POINT`.
 - A Standalone MM driver must only refer to MM servers.
 - Launches early in the PEI phase.
-- Two rounds of dispatch depend on the `gEventMmDispatchGuid` event. Refer to section **MM Driver Dispatch** for details.
-- Cannot access any non-MMRAM memory unless the `MmUnblockMemoryRequest()` API is called for the non-MMRAM memory. Refer to section **Non-MMRAM Access** for details.
-- Uses MM self-owned HOBs. Refer to section **MM HOBs** for details.
-- Early memory protection in PEI: `StandaloneMmCore` installs the `EDKII_PI_SMM_MEMORY_ATTRIBUTES_TABLE` once the second round of dispatch finishes. Refer to section **Memory Protection** for details.
+- Two rounds of dispatch depend on the `gEventMmDispatchGuid` event. Refer to section **1.2 MM Driver Dispatch** for details.
+- Cannot access any non-MMRAM memory unless the `MmUnblockMemoryRequest()` API is called for the non-MMRAM memory. Refer to section **1.4 Non-MMRAM Access** for details.
+- Uses MM self-owned HOBs. Refer to section **1.5 MM HOBs** for details.
+- Early memory protection in PEI: `StandaloneMmCore` installs the `EDKII_PI_SMM_MEMORY_ATTRIBUTES_TABLE` once the second round of dispatch finishes. Refer to section **1.7 Memory Protection** for details.
 
-## MM Driver Dispatch
+## 1.2 MM Driver Dispatch
 
 For traditional SMM drivers, they are dispatched within multiple rounds: The dispatch is hooked on the `gEfiEventDxeDispatchGuid` event, which is signaled by DXE Core when DXE Core finishes one round of dispatch.
 
@@ -71,7 +71,7 @@ The following flow chart describes the MM driver dispatch flow:
 ![MM Driver Dispatch Flow](./media/image1.jpg)
 ###### Figure 1: MM Driver Dispatch Flow
 
-## MM Communication Buffer
+## 1.3 MM Communication Buffer
 
 MM communication buffer is specific memory regions used for communication between the Non-MM and MM environment.
 
@@ -89,7 +89,7 @@ Every communication flow is as follows where steps #2, #3, and #4 run inside MM:
 
 By following the above, the `CommBuffer` used by the Communication PPI/Protocol is referred to as the **Primary Buffer**. Additionally, other non-MMRAM memory for specific MM driver usage are termed **Non-Primary Buffer**. Those buffer can be pointed from the MM HOBs, or pointed from the `CommBuffer`. Both the Primary Buffer and Non-Primary Buffer used by MM drivers should be validated for accessibility before use.
 
-## Non-MMRAM Access
+## 1.4 Non-MMRAM Access
 
 Any memory outside of the MMRAM (non-MMRAM) that needs to be accessed by MMI handlers must be explicitly declared as "Unblock Mem" through `MmUnblockMemoryRequest()` (`MdePkg/Include/Library/MmUnblockMemoryLib.h`).
 
@@ -100,13 +100,13 @@ Requirements for marking the non-MMRAM as "Unblocked":
 
 `StandaloneMmIpl` builds the corresponding `EFI_HOB_RESOURCE_DESCRIPTOR` in the MM HOB list for all unblocked non-MMRAM memory access. Any non-MMRAM memory region that is not described by `EFI_HOB_RESOURCE_DESCRIPTOR` in the MM HOB list is not accessible from SMM mode.
 
-## MM HOBs
+## 1.5 MM HOBs
 
 PEI HOBs are used by the traditional SMM. The lifecycle of traditional SMM HOBs is limited to the boot phase, and once entering the runtime phase, HOBs can no longer be accessed or used in the SMM. In contrast, Standalone MM is designed to maintain the validity of its self-owned HOBs throughout the entire lifecycle, including the runtime phase.
 
 `StandaloneMmIpl` is not required to pass the entire PEI HOB list to the SMM foundation. Instead, it must create and pass a specific subset of HOBs that are essential for the operation of the Standalone MM environment. Overall, MM self-owned HOBs can be divided into two categories: **MM Foundation HOBs** and **MM Platform HOBs**.
 
-### MM Foundation HOBs
+### 1.5.1 MM Foundation HOBs
 
 The MM Foundation HOBs are a set of HOBs that are created by the common logic within the `StandaloneMmIpl`. These HOBs provide the necessary information about the firmware environment and memory regions that the MM Core and drivers will interact with. The following HOBs are created by `StandaloneMmIpl` common logic; hence, they should **NOT** be created by the platform part:
 
@@ -123,33 +123,33 @@ The MM Foundation HOBs are a set of HOBs that are created by the common logic wi
 - Single GUIDed (`gEfiAcpiVariableGuid`) HOB to identify the S3 data root region in x86.
 - Single GUIDed (`gMmStatusCodeUseSerialHobGuid`) HOB to describe whether the status code uses the serial port or not.
 
-### MM Platform HOBs
+### 1.5.2 MM Platform HOBs
 
 In addition to the MM Foundation HOBs, the `StandaloneMmIpl` will consume the `MmPlatformHobProducerLib/CreateMmPlatformHob()` to create platform-specific HOBs that are necessary for the Standalone MM environment. These HOBs provide information and configuration details that are unique to the platform on which the system is running. The creation of these HOBs ensures that the MM environment is properly configured to interact with the platform's hardware and firmware features.
 
-## Communication between SMM/Non-SMM
+## 1.6 Communication between SMM/Non-SMM
 The following mechanisms are provided for communication between SMM and Non-SMM:
 
 1. Using `CommBuffer` with Protocol `EFI_MM_COMMUNICATION_PROTOCOL` or PPI `EFI_PEI_MM_COMMUNICATION_PPI`:
    - Requires dependency on the `EFI_MM_COMMUNICATION_PROTOCOL` or `EFI_PEI_MM_COMMUNICATION_PPI`.
    - Triggers an SMI when sharing data between SMM and Non-SMM code.
 
 2. Using "Unblock Mem":
-   - Must meet the usage requirements. Refer to the **Non-MMRAM Access** section for details.
+   - Must meet the usage requirements. Refer to section **1.4 Non-MMRAM Access** for details.
 
 3. Using MM Guided HOBs:
    - For data sizes < 64KB: Embed the data directly into the HOB.
 
 Option #1 is suitable when the data cannot be finalized before launching MM or when the data flow is bidirectional between SMM and Non-SMM code. Option #2 is necessary for ASL code to pass data to the SW SMI handler. It is also an alternative solution to avoid triggering an SMI for latency considerations. Option #3 is ideal when the data size is small than 64K and it can be finalized before launching MM and the data flow is unidirectional between SMM and Non-SMM code.
 
-But in cases where silicon initialization code does not want to rely on the communication PPI, the data size to be passed to MM exceeds 64KB, and the memory cannot be runtime-accessible due to the requirement for Runtime Non-SMM invisibility, then options #1 and #2 are not applicable. Option #3 requires splitting the data into multiple Guided HOBs, which increases code complexity due to the need to reassemble the data in MM. To simplify this, a fourth solution was introduced:
+But in cases where silicon initialization code does not want to rely on the communication PPI, the data size to be passed to MM exceeds 64KB, and the memory cannot be runtime-accessible due to the requirement for Runtime Non-SMM invisibility, then options #1 and #2 are not applicable. Option #3 requires splitting the data into multiple Guided HOBs, which increases code complexity due to the need to reassemble the data in MM. To simplify this, a fourth method was introduced as below:
 
 4. Using MM Memory Allocation HOBs with BSData and Non-Zero GUID:
    - Memory Producer (PEIM): Create a Memory Allocation HOB pointing to a BSData memory region and assign a Non-Zero GUID to the corresponding HOB.
    - MM Core: Migrate the Memory Allocation HOB into MMRAM by copying the data from Non-MMRAM to MMRAM. Refer to `MigrateMemoryAllocationHobs()` in `Edk2/StandaloneMmPkg/Core/StandaloneMmCore.c`.
    - Memory Consumer (MM Drivers): Retrieve the memory from the Memory Allocation HOB using its assigned Non-Zero GUID.
 
-## Memory Protection
+## 1.7 Memory Protection
 
 The `PiSmmCpuStandaloneMm` driver creates a page table used in MM mode according to the `EFI_HOB_RESOURCE_DESCRIPTOR` in the MM HOB list. The newly created page table controls memory accessibility in MM.
 

2_smm_to_mm_porting_guide.md

@@ -29,9 +29,9 @@
 
 -->
 
-# SMM to MM Porting Guide
+# 2 SMM to MM Porting Guide
 
-## Porting Design Overview
+## 2.1 Porting Design Overview
 
 This section provides instructions on how to convert traditional SMM drivers to MM drivers. A traditional SMM driver may need to be split into one or more drivers when transitioning to a Standalone MM driver:
 
@@ -46,7 +46,7 @@ The figure below illustrates how to convert a traditional SMM driver to an MM dr
 ![SMM to MM Conversion](./media/image2.jpg)
 ###### Figure 2: SMM to MM Conversion
 
-## Checkpoints in Converted MM Driver
+## 2.2 Checkpoints in Converted MM Driver
 
 To ensure the converted Standalone MM driver is functional, the following checkpoints should be verified:
 
@@ -58,14 +58,14 @@ To ensure the converted Standalone MM driver is functional, the following checkp
 
 2. **Checkpoint 2: Confirm Necessary HOBs Have Been Migrated to MM HOB Database**
 
-   Refer to section **MM HOBs** for details.
+   Refer to section **1.5 MM HOBs** for details.
    **Note**: HOB creation cannot depend on the end of the PEI notify event if the HOB needs to be accessed in MM. This is because the `StandaloneMmIpl` PEIM is dispatched before the end of PEI, leaving no opportunity for the IPL to migrate newly created HOBs to the MM HOB database.
 
 3. **Checkpoint 3: Check Dependencies on `gBS`, `gDS`, `gRT`, or ACPI-Related Services**
 
    If the original SMM driver depends on DXE protocols (e.g., `gBS` or `gDS`), it can only be used during the DXE phase. And ACPI tables must be installed during the DXE phase.
 
-1. **Checkpoint 4: Check Access to Non-MMRAM**
+4. **Checkpoint 4: Check Access to Non-MMRAM**
 
    Non-MMRAM access typically falls into the following cases:
    - **Case 1**: Accessing a HOB that contains a pointer or address pointing to non-MMRAM.
@@ -75,13 +75,13 @@ To ensure the converted Standalone MM driver is functional, the following checkp
    - **Case 3**: The registered SMI handler uses `gMmst->MmiHandlerRegister(SmiHandler, NULL, ...)` or MM Child Dispatch protocols (e.g., `SwDispatch->Register`).
      If it accesses any non-MMRAM buffer, use `MmUnblockMemoryRequest()` in the PEI phase before the `StandaloneMmIpl` entry point.
 
-2. **Checkpoint 5: Validate Primary & Non-Primary Buffers**
+5. **Checkpoint 5: Validate Primary & Non-Primary Buffers**
 
-   Refer to section **Non-MMRAM Access** for definitions of Primary and Non-Primary Buffers. Both types of buffers used by MM drivers should be validated for accessibility before use:
+   Refer to section **1.3 MM Communication Buffer** for definitions of Primary and Non-Primary Buffers. Both types of buffers used by MM drivers should be validated for accessibility before use:
    - Use `XXXIsPrimaryBufferValid()` to validate the `CommBuffer`.
    - Use `XXXIsNonPrimaryBufferValid()` to validate non-MMRAM memory pointed from the `CommBuffer` or MM HOB.
 
-## Sample: SMM to MM Conversion
+## 2.3 Sample: SMM to MM Conversion
 
 The Tcg2 SMM and MM modules will be used as a sample to highlight the key points to consider when converting a traditional SMM module to an MM module:
 
@@ -127,7 +127,7 @@ The Tcg2 SMM and MM modules will be used as a sample to highlight the key points
 
    The `mTcgNvs` global variable in the Tcg2 SMM module plays a crucial role in TPM operations, especially when updating the ACPI table and handling SMI callback functions.
    `mTcgNvs` is the operation region in the TCG ACPI table and must be a non-MMRAM memory buffer pointed from the `CommBuffer`.
-   According to Section **Non-MMRAM Access**, it must be unblocked using `MmUnblockMemoryRequest()`.
+   According to Section **1.4 Non-MMRAM Access**, it must be unblocked using `MmUnblockMemoryRequest()`.
    The related operation can be found in the `BuildTcg2AcpiCommunicateBufferHob()` function in `Edk2\SecurityPkg\Tcg\Tcg2Config\Tcg2ConfigPei.inf`.
 
 7. **Check Primary & Non-Primary Buffer Validity**

SUMMARY.md

@@ -33,21 +33,21 @@
 
 * [Standalone MM Getting Started Guide](README.md)
 
-* [MM Introduction](1_mm_introduction.md#mm-introduction)
-  * [SMM and MM Overview](1_mm_introduction.md#smm-and-mm-overview)
-  * [MM Driver Dispatch](1_mm_introduction.md#mm-driver-dispatch)
-  * [MM Communication Buffer](1_mm_introduction.md#mm-communication-buffer)
-  * [Non-MMRAM Access](1_mm_introduction.md#non-mmram-access)
-  * [MM HOBs](1_mm_introduction.md#mm-hobs)
-    * [MM Foundation HOBs](1_mm_introduction.md#mm-foundation-hobs)
-    * [MM Platform HOBs](1_mm_introduction.md#mm-platform-hobs)
-  * [Communication between SMM/Non-SMM](1_mm_introduction.md#communication-between-smmnon-smm)
-  * [Memory Protection](1_mm_introduction.md#memory-protection)
+* [1 MM Introduction](1_mm_introduction.md#1-mm-introduction)
+  * [1.1 SMM and MM Overview](1_mm_introduction.md#11-smm-and-mm-overview)
+  * [1.2 MM Driver Dispatch](1_mm_introduction.md#12-mm-driver-dispatch)
+  * [1.3 MM Communication Buffer](1_mm_introduction.md#13-mm-communication-buffer)
+  * [1.4 Non-MMRAM Access](1_mm_introduction.md#14-non-mmram-access)
+  * [1.5 MM HOBs](1_mm_introduction.md#15-mm-hobs)
+    * [1.51 MM Foundation HOBs](1_mm_introduction.md#151-mm-foundation-hobs)
+    * [1.52 MM Platform HOBs](1_mm_introduction.md#152-mm-platform-hobs)
+  * [1.6 Communication between SMM/Non-SMM](1_mm_introduction.md#16-communication-between-smmnon-smm)
+  * [1.7 Memory Protection](1_mm_introduction.md#17-memory-protection)
 
-* [SMM to MM Porting Guide](2_smm_to_mm_porting_guide.md#smm-to-mm-porting-guide)
-  * [Porting Design Overview](2_smm_to_mm_porting_guide.md#porting-design-overview)
-  * [Checkpoints in Converted MM Driver](2_smm_to_mm_porting_guide.md#checkpoints-in-converted-mm-driver)
-  * [Sample: SMM to MM Conversion](2_smm_to_mm_porting_guide.md#sample-smm-to-mm-conversion)
+* [2 SMM to MM Porting Guide](2_smm_to_mm_porting_guide.md#2-smm-to-mm-porting-guide)
+  * [2.1 Porting Design Overview](2_smm_to_mm_porting_guide.md#21-porting-design-overview)
+  * [2.2 Checkpoints in Converted MM Driver](2_smm_to_mm_porting_guide.md#22-checkpoints-in-converted-mm-driver)
+  * [2.3 Sample: SMM to MM Conversion](2_smm_to_mm_porting_guide.md#23-sample-smm-to-mm-conversion)
 
 ---