# Overview
* **Feature Name:** Post Code Debug
* **PI Phase(s) Supported:** PEI, DXE, SMM
* **SMM Required?** Yes

More Information:

## Purpose
The PostCodeDebugFeaturePkg include some useful post code debug libraries, such as get post code from status code and show it.
This is an important capability in firmware development to get and analyze the post code.


# High-Level Theory of Operation
It provide a library PostCodeStatusCodeHandlerLib used by edk2 StatusCodeHandler.efi, used to show the post code.
It also provide a library of PostCodeMap lib, it map the status code to post code.
A library of PostCode lib is needed by platform.

In the library contstructor function, PostCodeStatusCodeHandlerLib register the call back function for ReportStatusCode.
When called, it call GetPostCodeFromStatusCode () in PostCodeMapLib to get post code from status code, and call PostCode () in PostCodeLib to show the post code.

PostCodeStatusCodeHandlerLib include 3 libraries for PEI, RuntimeDxe, SMM:
* PeiPostCodeStatusCodeHandlerLib
* RuntimeDxePostCodeStatusCodeHandlerLib
* SmmPostCodeStatusCodeHandlerLib

## Firmware Volumes
Linked with StatusCodeHandler.efi, and make sure put the StatusCodeHandler.efi after the ReportStatusCodeRouter.efi.

## Modules
* PostCodeStatusCodeHandlerLib
* PostCodeMapLib

## PostCodeStatusCodeHandlerLib
This library register the call back function for ReportStatusCode, and get post code from status code, and show post code.

## PostCodeMapLib
This library provide a function to get post code from status code.

## Key Functions
* In PeiPostCodeStatusCodeHandlerLib:
```
  EFI_STATUS
  EFIAPI
  PostCodeStatusCodeReportWorker (
    IN CONST  EFI_PEI_SERVICES        **PeiServices,
    IN EFI_STATUS_CODE_TYPE           CodeType,
    IN EFI_STATUS_CODE_VALUE          Value,
    IN UINT32                         Instance,
    IN CONST EFI_GUID                 *CallerId,
    IN CONST EFI_STATUS_CODE_DATA     *Data OPTIONAL
  )
```

* In RuntimeDxePostCodeStatusCodeHandlerLib:
```
  EFI_STATUS
  EFIAPI
  PostCodeStatusCodeReportWorker (
    IN EFI_STATUS_CODE_TYPE           CodeType,
    IN EFI_STATUS_CODE_VALUE          Value,
    IN UINT32                         Instance,
    IN EFI_GUID                       *CallerId,
    IN EFI_STATUS_CODE_DATA           *Data OPTIONAL
  )
```

* In SmmPostCodeStatusCodeHandlerLib:
```
  EFI_STATUS
  EFIAPI
  PostCodeStatusCodeReportWorker (
    IN EFI_STATUS_CODE_TYPE           CodeType,
    IN EFI_STATUS_CODE_VALUE          Value,
    IN UINT32                         Instance,
    IN EFI_GUID                       *CallerId,
    IN EFI_STATUS_CODE_DATA           *Data OPTIONAL
    )
```

* In PostCodeMapLib:
```
  UINT32
  EFIAPI
  GetPostCodeFromStatusCode (
    IN EFI_STATUS_CODE_TYPE           CodeType,
    IN EFI_STATUS_CODE_VALUE          Value
  )
```

## Configuration
* Link the library to StatusCodeHandler.efi to add this status code handler.
```
  Example:
    MdeModulePkg/Universal/StatusCodeHandler/RuntimeDxe/StatusCodeHandlerRuntimeDxe.inf {
      <LibraryClasses>
        NULL|PostCodeDebugFeaturePkg/Library/PostCodeStatusCodeHandlerLib/RuntimeDxePostCodeStatusCodeHandlerLib.inf
    }
```
  Refer to PostCodeDebugFeature.dsc for another example.
* Config PCD gPostCodeDebugFeaturePkgTokenSpaceGuid.PcdStatusCodeUsePostCode.
  In platform .dsc file, need to config the type of gPostCodeDebugFeaturePkgTokenSpaceGuid.PcdStatusCodeUsePostCode.
  Use PcdsFixedAtBuild to save binary size, and use PcdsDynamic if want to enable/disable in runtime.
* Implemented platform's special PostCodeMapLib if needed.
* Provide the platform's special PostCodeLib.
* Make sure put the StatusCodeHandler.efi after the ReportStatusCodeRouter.efi.

## Data Flows
Status Code (ReportStatusCode) -> Post Code (GetPostCodeFromStatusCode).

## Control Flows
ReportStatusCode () -> PostCodeStatusCodeReportWorker () -> GetPostCodeFromStatusCode () -> PostCode ()

## Build Flows
Supported build targets
* VS2019
* CLANGPDB
* GCC5

## Test Point Results
There are no test points defined.

## Functional Exit Criteria
N/A

## Feature Enabling Checklist
* Set the PCD gPostCodeDebugFeaturePkgTokenSpaceGuid.PcdPostCodeDebugFeatureEnable to TRUE.
* Select the PCD type desired and set the PCD gPostCodeDebugFeaturePkgTokenSpaceGuid.PcdStatusCodeUsePostCode to TRUE.
* Implemented a platform specific PostCodeMapLib if needed.
* Verify the post code can be shown correctly.

## Common Optimizations
* Set gPostCodeDebugFeaturePkgTokenSpaceGuid.PcdStatusCodeUsePostCode based on a larger, board specific, size
  optimization or performance optimization setting.