---?image=assets/images/gitpitch-audience.jpg
@title[EDK II Debugging]
EDK II Debugging w/ Windows Lab
See the Lab Guide to Copy and Paste code examples
tianocore.org Note: PITCHME.md for UEFI / EDK II Training EDK II Debugging Lab
Copyright (c) 2020, Intel Corporation. All rights reserved.
Redistribution and use in source (original document form) and 'compiled' forms (converted to PDF, epub, HTML and other formats) with or without modification, are permitted provided that the following conditions are met:
-
Redistributions of source code (original document form) must retain the above copyright notice, this list of conditions and the following disclaimer as the first lines of this file unmodified.
-
Redistributions in compiled form (transformed to other DTDs, converted to PDF, epub, HTML and other formats) must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
THIS DOCUMENTATION IS PROVIDED BY TIANOCORE PROJECT "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL TIANOCORE PROJECT BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
@title[Lesson Objective]
- @fa[certificate gp-bullet-gold] Using PCDs to Configure DebugLib -LAB
- @fa[certificate gp-bullet-yellow] Change the DebugLib instance to modify the debug
output - LAB - @fa[certificate gp-bullet-magenta] Debug EDK II using VS Debugger - LAB
---?image=/assets/images/slides/Slide_LabSec.JPG
@title[Lab 1: Adding Debug Statements]
Lab 1: Adding Debug Statements
Note:
In this lab, you'll learn how to add debug statements.
This lab uses code from a previous exercise as a starting point (refer to Writing Simple UEFI Applications). Before proceeding, verify that the SampleApp code is present in your workspace and that the code references the OvmfPkgX64.dsc file.
@title[Lab 1: Catch Up SampleApp]
Lab 1: Catch up from previous lab
@snap[north-west span-60 ]@box[bg-black text-white rounded my-box-pad2 ](
Skip if Lab Writing UEFI App Lab completed (Lab Guide)
- Perform Lab Setup from previous Labs (Lab Guide)
- Create a Directory under the workspace @size[.8em](C:/FW/edk2-ws/edk2 : "SampleApp")
- Copy contents of @size[.8em](C:/../FW/LabSampleCode/SampleAppDebug to C:/FW/edk2-ws/edk2/SampleApp)
- Open @size[.8em](C:/FW/edk2-ws/edk2/EmulatorPkg/EmulatorPkg.dsc)
- Add the following to the [Components] section:
- Save and close the file @size[.8em](C:/FW/edk2-ws/edk2/EmulatorPkg/EmulatorPkg.dsc)
@snap[north-east span-98 ]
# Add new modules here
SampleApp/SampleApp.inf
Note:
@title[Lab 1: Add debug statements SampleApp]
Lab 1: Add debug statments to SampleApp
@snap[north-west span-60 ]@box[bg-black text-white rounded my-box-pad2 ](
@box[bg-black text-white rounded my-box-pad2 ](
)
@snapend
- Open a VS Command Prompt and type @size[.8em](cd C:/FW/edk2-ws/)
- Open @size[.8em](C:/FW/edk2-ws/edk2SampleApp/SampleApp.c)
- Add the following to the include statements at the top of the file after below the last "#include" statement:
@snap[north-east span-98 ]
C:/FW/edk2-ws> setenv.bat
C:/FW/edk2-ws> cd edk2
C:/FW/edk2-ws/edk2> edksetup
#include <Library/DebugLib.h>
Note:
@title[Lab 1: Add debug statements SampleApp 02]
Lab 1: Add debug statements to SampleApp
Locate the UefiMain function. Then copy and paste the following code after the "EFI_INPUT_KEY KEY;" statement: and before the first Print() statement
DEBUG ((0xffffffff, "\n\nUEFI Base Training DEBUG DEMO\n") );
DEBUG ((0xffffffff, "0xffffffff USING DEBUG ALL Mask Bits Set\n") );
DEBUG ((DEBUG_INIT, " 0x%08x USING DEBUG DEBUG_INIT\n" , (UINTN)(DEBUG_INIT)) );
DEBUG ((DEBUG_WARN, " 0x%08x USING DEBUG DEBUG_WARN\n", (UINTN)(DEBUG_WARN)) );
DEBUG ((DEBUG_LOAD, " 0x%08x USING DEBUG DEBUG_LOAD\n", (UINTN)(DEBUG_LOAD)) );
DEBUG ((DEBUG_FS, " 0x%08x USING DEBUG DEBUG_FS\n", (UINTN)(DEBUG_FS)) );
DEBUG ((DEBUG_POOL, " 0x%08x USING DEBUG DEBUG_POOL\n", (UINTN)(DEBUG_POOL)) );
DEBUG ((DEBUG_PAGE, " 0x%08x USING DEBUG DEBUG_PAGE\n", (UINTN)(DEBUG_PAGE)) );
DEBUG ((DEBUG_INFO, " 0x%08x USING DEBUG DEBUG_INFO\n", (UINTN)(DEBUG_INFO)) );
DEBUG ((DEBUG_DISPATCH, " 0x%08x USING DEBUG DEBUG_DISPATCH\n",(UINTN)(DEBUG_DISPATCH)));
DEBUG ((DEBUG_VARIABLE, " 0x%08x USING DEBUG DEBUG_VARIABLE\n",(UINTN)(DEBUG_VARIABLE)));
DEBUG ((DEBUG_BM, " 0x%08x USING DEBUG DEBUG_BM\n", (UINTN)(DEBUG_BM)) );
DEBUG ((DEBUG_BLKIO, " 0x%08x USING DEBUG DEBUG_BLKIO\n", (UINTN)(DEBUG_BLKIO)) );
DEBUG ((DEBUG_NET, " 0x%08x USING DEBUG DEBUG_NET\n", (UINTN)(DEBUG_NET)) );
DEBUG ((DEBUG_UNDI, " 0x%08x USING DEBUG DEBUG_UNDI\n", (UINTN)(DEBUG_UNDI)) );
DEBUG ((DEBUG_LOADFILE, " 0x%08x USING DEBUG DEBUG_LOADFILE\n",(UINTN)(DEBUG_LOADFILE)));
DEBUG ((DEBUG_EVENT, " 0x%08x USING DEBUG DEBUG_EVENT\n", (UINTN)(DEBUG_EVENT)) );
DEBUG ((DEBUG_GCD, " 0x%08x USING DEBUG DEBUG_GCD\n", (UINTN)(DEBUG_EVENT)) );
DEBUG ((DEBUG_CACHE, " 0x%08x USING DEBUG DEBUG_CACHE\n", (UINTN)(DEBUG_EVENT)) );
DEBUG ((DEBUG_VERBOSE, " 0x%08x USING DEBUG DEBUG_VERBOSE\n", (UINTN)(DEBUG_EVENT)) );
DEBUG ((DEBUG_ERROR, " 0x%08x USING DEBUG DEBUG_ERROR\n", (UINTN)(DEBUG_ERROR)) );
Note:
---?image=/assets/images/slides/Slide7.JPG @title[Lab 1: Build,Run and Test Result ]
Lab 1: Build, Run and Test Result
@snap[north-west span-50 ])
)
) @snapend
@snap[north-west span-50 ]
At the VS Command Prompt
C:/FW/edk2-ws/edk2> Build
C:/FW/edk2-ws/edk2> RunEmulator
Run the application from the shell
@color[yellow](Shell>) SampleApp
Check the VS Debug output
Exit
@color[yellow](Shell>) Reset
Note:
Notice the changes in DEBUG output for SampleApp in the Visual Studio Command Prompt. Since the new PCD definitions were only applied to SampleApp, the DEBUG output properties are not changed for other parts of the EmulatorPkg project. At the VS Command Prompt
C:/FW/edk2-ws/edk2> Build
C:/FW/edk2-ws/edk2> RunEmulator
Run the application from the shell
Shell> SampleApp
Check the VS Debug output Exit
Shell> Reset
---?image=/assets/images/slides/Slide_LabSec.JPG
@title[Lab 2: Changing PCD Value]
Lab 2: Changing PCD Value
Note: In this lab, you'll learn how to use PCD values to change debugging capabilities. The previous lab, Adding Debug Statements, did not display all the DEBUG messages added to SampleApp.c. This lab shows how to change this behavior.
@title[Lab 2: Change PCDs for SampleApp]
Lab 2: Change PCDs for SampleApp
@snap[north-west span-100 ]
@snap[north-west span-100 ]
@size[1.15em](Open) C:/FW/edk2-ws/edk2EmulatorPkg/EmulatorPkg.dsc
@size[1.15em](Replace) SampleApp/SampleApp.inf @size[1.15em](with the following:)
SampleApp/SampleApp.inf {
<PcdsFixedAtBuild>
gEfiMdePkgTokenSpaceGuid.PcdDebugPropertyMask|0xff
gEfiMdePkgTokenSpaceGuid.PcdDebugPrintErrorLevel|0xffffffff
}
@size[1.15em](Save and close) C:/FW/edk2-ws/edk2EmulatorPkg/EmulatorPkg.dsc
@snapend
Note:
-
Open C:/FW/edk2-ws/edk2EmulatorPkg/EmulatorPkg.dsc
-
Replace SampleApp/SampleApp.inf with the following:
SampleApp/SampleApp.inf {
<PcdsFixedAtBuild>
gEfiMdePkgTokenSpaceGuid.PcdDebugPropertyMask|0xff
gEfiMdePkgTokenSpaceGuid.PcdDebugPrintErrorLevel|0xffffffff
}
- save
---?image=/assets/images/slides/Slide10.JPG @title[Lab 2: Build,Run and Test Result ]
Lab 2: Build, Run and Test Result
@snap[north-west span-50 ])
)
) @snapend
@snap[north-west span-50 ]
At the VS Command Prompt
C:/FW/edk2-ws/edk2> Build
C:/FW/edk2-ws/edk2> RunEmulator
Run the application from the shell
@color[yellow](Shell>) SampleApp
Check the VS Debug output
Exit
@color[yellow](Shell>) Reset
Note: Notice the changes in DEBUG output for SampleApp in the Visual Studio Command Prompt. Since the new PCD definitions were only applied to SampleApp, the DEBUG output properties are not changed for other parts of the EmulatorPkg project.
At the VS Command Prompt
C:/FW/edk2-ws/edk2> Build
C:/FW/edk2-ws/edk2> RunEmulator
Run the application from the shell
Shell> SampleApp
Check the VS Debug output Exit
Shell> Reset
---?image=/assets/images/slides/Slide_LabSec.JPG
@title[Lab 3: Library Instances for Debugging]
Lab 3: Library Instances for Debugging
Note:
@title[Lab 3: Using Library Instances for Debugging]
Lab 3: Using Library Instances for Debugging
@snap[north-west span-100 ]
@snap[north-west span-100 ]
@size[1.15em](Open) C:/FW/edk2-ws/edk2/EmulatorPkg/EmulatorPkg.dsc
@size[1.15em](Replace) SampleApp/SampleApp.inf { . . . } @size[1.15em](with the following:)
SampleApp/SampleApp.inf {
<LibraryClasses >
DebugLib|MdePkg/Library/UefiDebugLibConOut/UefiDebugLibConOut.inf
}
@size[1.15em](Save and close) C:/FW/edk2-ws/edk2/EmulatorPkg/EmulatorPkg.dsc
@snapend
Note:
- Open C:/FW/edk2-ws/edk2/EmulatorPkg/EmulatorPkg.dsc
- Replace SampleApp/SampleApp.inf { . . .} with the following:
SampleApp/SampleApp.inf {
<LibraryClasses>
DebugLib|MdePkg/Library/UefiDebugLibConOut/UefiDebugLibConOut.inf
}
- Save and close EmulatorPkgPkg.dsc
Lab 3 Changing Library
---?image=/assets/images/slides/Slide13.JPG @title[Lab 3: Build, Run and Test Result]
Lab 3: Build, Run and Test Result
@snap[north-west span-50 ])
)
) @snapend
@snap[north-west span-60 ]
At the VS Command Prompt
C:/FW/edk2-ws/edk2> Build
C:/FW/edk2-ws/edk2> RunEmulator
Run the application from the shell
@color[yellow](Shell>) SampleApp
See that the output from the Debug
statements now goes to the console
Exit
@color[yellow](Shell>) Reset
@snapendNote:
-At the VS Command Prompt
C:/FW/edk2-ws/edk2> Build
C:/FW/edk2-ws/edk2> RunEmulator
- Run the application from the shell
Shell> SampleApp
- See that the output from the Debug statements now goes to the console
- Exit
Shell> Reset
Notice the Debug messages output to the console
---?image=/assets/images/slides/Slide_LabSec.JPG
@title[Lab 4: Serial port Instance of DebugLib]
Lab 4: Null Instance of DebugLib
Note:
The DEBUG output for SampleApp is no debug output
@title[Lab 4: Using Serial port Library Instances]
Lab 4: Using Serial port Library Instances
Open C:/FW/edk2-ws/edk2/EmulatorPkg/EmulatorPkg.dsc
Replace SampleApp/SampleApp.inf { . . .} with the following:
```c SampleApp/SampleApp.inf { DebugLib|MdePkg/Library/BaseDebugLibNull/BaseDebugLibNull.inf } ``` Save and close C:/FW/edk2-ws/edk2/EmulatorPkg/EmulatorPkg.dsc
Note:
Lab 4
---?image=/assets/images/slides/Slide16.JPG @title[Lab 4: Build, Run and Test Result]
Lab 4: Build, Run and Test Result
@snap[north-west span-50 ])
)
) @snapend
@snap[north-west span-60 ]
At the VS Command Prompt
C:/FW/edk2-ws/edk2> Build
C:/FW/edk2-ws/edk2> RunEmulator
Run the application from the shell
@color[yellow](Shell>) SampleApp
Check - now @color[red](NO) Debug output
Exit
@color[yellow](Shell>) Reset
@snapendNote:
-At the VS Command Prompt
C:/FW/edk2-ws/edk2> Build
C:/FW/edk2-ws/edk2> RunEmulator
- Run the application from the shell
Shell> SampleApp
- Check – now NO Debug output
Exit
Shell> Reset
Notice NO Debug messages output to the console or cmd Prompt
---?image=/assets/images/slides/Slide_LabSec.JPG
@title[Lab 5: Debugging EDK II with VS Debugger]
Lab 5: Debugging EDK II with VS Debugger
Note:
---?image=/assets/images/slides/Slide18.JPG @title[Lab 5: Emulator Debug with VS]
Lab 5: Debug with VS
Edit the SampleApp.cand add the "ASSERT_EFI_ERROR" Statement :
```c EFI_STATUS Status; Status = EFI_NO_RESPONSE; // or any other EFI Error . . . ASSERT_EFI_ERROR(Status);
<br>
<br>
<br>
<br>
<br>
<span style="font-size:0.8em" >Save <font face="Consolas">SampleApp.c</font> </span><br>
Note:
Lab 5, add ASSERT
---?image=/assets/images/slides/Slide19.JPG
@title[Lab 5: Emulator Debug with VS - ASSERT ]
<p align="right"><span class="gold" ><b>Lab 5: Debug with VS - ASSERT </b></span></p>
@snap[north-west span-50 ]
<br>
<br>
<p style="line-height:5%" align="left" ><span style="font-size:0.15em; font-family:Consolas;" ><br><br><br><br><br></span></p>
@box[bg-black text-white rounded my-box-pad2 ](<p style="line-height:60% "><span style="font-size:0.5em;" > </span></p>)
<p style="line-height:5%" align="left" ><span style="font-size:0.15em; font-family:Consolas;" ><br><br><br></span></p>
@box[bg-black text-white rounded my-box-pad2 ](<p style="line-height:60% "><span style="font-size:0.5em;" > </span></p>)
<br>
@snapend
@snap[north-west span-60 ]
<br>
<br>
<p style="line-height:80%">
<span style="font-size:0.8em" >At the VS Command Prompt</span></p>
<p style="line-height:45%" align="left" ><span style="font-size:0.57em; font-family:Consolas;" ><br>
C:/FW/edk2-ws/edk2> Build<br>
C:/FW/edk2-ws/edk2> RunEmulator
</span></p>
<p style="line-height:80%" align="left"><span style="font-size:0.8em" >Run the application from the shell</span></p>
<p style="line-height:45%" align="left" ><span style="font-size:0.5em; font-family:Consolas;" ><br>
<font face="Consolas">@color[yellow](Shell>) SampleApp</font> <br><br></span></span></p>
<p style="line-height:70%" align="left"><span style="font-size:0.75em" >Assert in VS Command Prompt<br><br>
</span></p>
@snapend
Note:
-At the VS Command Prompt
C:/FW/edk2-ws/edk2> Build C:/FW/edk2-ws/edk2> RunEmulator
- Run the application from the shell
Shell> SampleApp
- Assert in VS Command Prompt
Exit
Shell> Reset
Lab 5, add ASSERT
---?image=/assets/images/slides/Slide20.JPG
@title[Lab 5: Debug with VS ASSERT 02]
<p align="right"><span class="gold" ><b>Lab 5: Debug with VS - ASSERT </b></span></p>
<p style="line-height:60%"><span style="font-size:0.7em" >
Windows* VS Debugger
Will Pop UP
</span></p>
Note:
Lab 5, add ASSERT
---?image=/assets/images/slides/Slide21.JPG
@title[Lab 5: Debug with VS- CPU bp]
<p align="right"><span class="gold" ><b>Lab 5: Debug with VS - <font face="Consolas">CpuBreakpoint</font></b></span></p>
<br>
<p style="line-height:60%"><span style="font-size:0.7em" >Edit the <font face="Consolas">SampleApp.c</font> and add the "<font face="Consolas">CpuBreakpoint();</font>" Statement and comment out the "<font face="Consolas">ASSERT</font>": </span></p>
```c
CpuBreakpoint();
Save SampleApp.c
Note: Lab 5, add CpuBreakpoint();
---?image=/assets/images/slides/Slide22.JPG @title[Lab 5: Debug with VS - CPU bp 02]
Lab 5: Debug with VS - CpuBreakpoint
@snap[north-west span-50 ])
)
@snapend
@snap[north-west span-60 ]
At the VS Command Prompt
C:/FW/edk2-ws/edk2> Build
C:/FW/edk2-ws/edk2> RunEmulator
Run the application from the shell
@color[yellow](Shell>) SampleApp
VS option to go to VS Debugger
Note:
-At the VS Command Prompt
C:/FW/edk2-ws/edk2> Build
C:/FW/edk2-ws/edk2> RunEmulator
- Run the application from the shell
Shell> SampleApp
- VS Debugger pops up
---?image=/assets/images/slides/Slide23.JPG @title[Invoke Windows Visual Studio Debugger ]
Invoke Windows Visual Studio Debugger
Note:
- Click yes
- Click Break
- Notice that the VS debugger is inside the CpuBreakpoint function.
- Continue by stepping and
---?image=/assets/images/slides/Slide24.JPG @title[Invoke Windows Visual Studio Debugger 02]
Invoke Windows Visual Studio Debugger
Note: Now the visual studio debugger is debugging the sampleapp function and common debug tasks can be done:
- stepping
- checking local variables
- checking the call stack.
@title[Summary]
- @fa[certificate gp-bullet-gold] Using PCDs to Configure DebugLib - LAB
- @fa[certificate gp-bullet-yellow] Change the DebugLib instance to modify the debug
output - LAB - @fa[certificate gp-bullet-magenta] Debug EDK II using VS Debugger - LAB
---?image=assets/images/gitpitch-audience.jpg
@title[Questions]
@title[return to main]
@size[1.2em](Return to Main Training Page)
Return to Training Table of contents for next presentation link
@snap[north span-30 ]
@snapend
---?image=assets/images/gitpitch-audience.jpg
@title[Logo Slide]
![Logo Slide](/assets/images/TianocoreLogo.png =10x)
@title[Acknowledgements]
/**
Redistribution and use in source (original document form) and 'compiled' forms (converted
to PDF, epub, HTML and other formats) with or without modification, are permitted provided
that the following conditions are met:
Redistributions of source code (original document form) must retain the above copyright
notice, this list of conditions and the following disclaimer as the first lines of this
file unmodified.
Redistributions in compiled form (transformed to other DTDs, converted to PDF, epub, HTML
and other formats) must reproduce the above copyright notice, this list of conditions and
the following disclaimer in the documentation and/or other materials provided with the
distribution.
THIS DOCUMENTATION IS PROVIDED BY TIANOCORE PROJECT "AS IS" AND ANY EXPRESS OR IMPLIED
WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL TIANOCORE PROJECT BE
LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
ARISING IN ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE POSSIBILITY
OF SUCH DAMAGE.
Copyright (c) 2020, Intel Corporation. All rights reserved.
**/
---?image=assets/images/binary-strings-black2.jpg
@title[Backup Section]
Note:
@title[Issue: Debugging in EmulatorPkg with Windows 7 and VS]
Issue:
Debugging in EmulatorPkg with Windows 7
and Visual Studio does not work?
Symptom: With Windows 7 a CpuBreakpoint() or ASSERT just exits with an error from the "RunEmulator" command.
Link to fix this issue: wiki- Issue Debugging with Windows 7 and Visual Studio
- Run the RegEdt32
- Navigate to the HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Microsoft\Windows NT\CurrentVersion\AeDebug
- Add a string value entry called "Auto" with a value of "1"
Windows 10 Visual Studio does not seem to have this issue