summaryrefslogtreecommitdiff
path: root/Features/Intel/Debugging/BeepDebugFeaturePkg/Readme.md
blob: 143699dbb35d781cdf4ba3db8604441fe968931e (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
# Overview
* **Feature Name:** Beep Debug
* **PI Phase(s) Supported:** PEI, DXE, SMM
* **SMM Required?** Yes

More Information:

## Purpose
Very often it is necessary to debug very close to the reset vector or in production systems that lack serial ports, seven segment displays, or useful LED that are typically used to output useful debug messages.

The BeepDebugFeaturePkg includes some useful beep focused debug libraries.

This isn't intended for production use.

There is not currently seamless integration into the SecCore component that handles the reset vector. In order to debug that early, it will be necessary to use the BeepLib directly in SEC code.

# High-Level Theory of Operation
It provides a library, BeepStatusCodeHandlerLib, used by edk2 StatusCodeHandler.efi, used to do beep if needed.
It also provide a library of BeepMap lib which maps the status code to a beep value.
A library of Beep lib is needed by platform, and this pkg has a Null implementation.

In the library contstructor function, BeepStatusCodeHandlerLib registers the call back function for ReportStatusCode. When called, it calls GetBeepFromStatusCode (); in BeepMapLib to get beep value from status code, and calls Beep () in BeepLib to beep a speaker.

BeepStatusCodeHandlerLib includes three libraries for PEI, RuntimeDxe, and SMM:
* PeiBeepStatusCodeHandlerLib
* RuntimeDxeBeepStatusCodeHandlerLib
* SmmBeepStatusCodeHandlerLib

## Firmware Volumes
These libraries need to be linked into StatusCodeHandler components.
Make sure one puts the StatusCodeHandler.efi after the ReportStatusCodeRouter.efi.

## Modules
* BeepStatusCodeHandlerLib
* BeepMapLib
* BeepLibNull

## BeepStatusCodeHandlerLib
This library registers the callback function for ReportStatusCode, gets beep value from status code, and does the beep.

## BeepMapLib
This library provides a function to get a beep value for a status code.

## BeepLibNull
This library provide a function to perform the beep.

## Key Functions
* In PeiBeepStatusCodeHandlerLib:
```
  EFI_STATUS
  EFIAPI
  BeepStatusCodeReportWorker (
    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 RuntimeDxeBeepStatusCodeHandlerLib:
```
  EFI_STATUS
  EFIAPI
  BeepStatusCodeReportWorker (
    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 SmmBeepStatusCodeHandlerLib:
```
  EFI_STATUS
  EFIAPI
  BeepStatusCodeReportWorker (
    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 BeepMapLib:
```
  UINT32
  EFIAPI
  GetBeepValueFromStatusCode (
    IN EFI_STATUS_CODE_TYPE           CodeType,
    IN EFI_STATUS_CODE_VALUE          Value
    )
```

* In BeepLib:
```
  VOID
  EFIAPI
  Beep (
    IN UINT32  Value
    )
```

## Configuration
* Configure PCD gBeepDebugFeaturePkgTokenSpaceGuid.PcdStatusCodeUseBeep.
  In board DSC file, the board developer needs to configure the type of gBeepDebugFeaturePkgTokenSpaceGuid.PcdStatusCodeUseBeep control desired.
  [PcdsFixedAtBuild] is the feature default value as this has lowest size.
  [PcdsDynamicExDefault] is the most common configuration as it provides dynamic control during debugging.
* Implemented board specific BeepMapLib if custom status code to beep code mapping as needed.
* Provide the board specific BeepLib to perform beeps on the board specific hardware.
```The default library does not cause any hardware to beep```

## Data Flows
Status Code (ReportStatusCode) -> Beep Value (GetBeepValueFromStatusCode).

## Control Flows
ReportStatusCode () -> BeepStatusCodeReportWorker () -> GetBeepValueFromStatusCode () -> Beep ()

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

Standalone build
* build -a IA32 -a X64 -p Debugging\BeepDebugFeaturePkg\BeepDebugFeaturePkg.dsc

AdvanceFeaturePkg build
* build -a IA32 -a X64 -p AdvancedFeaturePkg/AdvancedFeaturePkg.dsc

## Test Point Results
None

## Functional Exit Criteria
N/A

## Feature Enabling Checklist
* Verify in board DSC file that gBeepDebugFeaturePkgTokenSpaceGuid.PcdBeepDebugFeatureEnable set to TRUE
* Verify board specific BeepLib implemented and included in board DSC file.
* Verify that the board has a PlatformHookLib instance.  There is a null library implementation if needed
```
      PlatformHookLib|MdeModulePkg/Library/BasePlatformHookLibNull/BasePlatformHookLibNull.inf
```
* Verify that your board has the StatusCodeHandler components (PEIM or driver) desired.
```
  Example:
    MdeModulePkg/Universal/StatusCodeHandler/RuntimeDxe/StatusCodeHandlerRuntimeDxe.inf {
    <LibraryClasses>
      NULL|BeepDebugFeaturePkg/Library/BeepStatusCodeHandlerLib/RuntimeDxeBeepStatusCodeHandlerLib.inf
    }
  There are default StatusCodeHandlers for PEI, RT, and SMM in BeepDebugFeaturePkg/Include in PreMemory.fdf and PostMemory.fdf for use.  But most boards will already have these components and you will just want to add the appropriate *StatusCodeHandlerLib.inf to each component.
```
* Build
* Remove all the memory from the system and verify audible beep is heard when attempting to boot.

## Common Optimizations
N/A