HOW-TO: Debug the EDK2's Windows-Hosted UEFI Environment in Visual Studio 2012

The NT32 environment is very useful for debugging UEFI applications which aren't tied to specific hardware devices. In this article, you will learn how to add debugging support in Visual Studio 2010.
This article assumes that you have Visual Studio 2012 and that you have the Visual Studio project to build the EDK2's NT32 platform in C:\sourcecode\edk2.

To set up EDK2's UEFI environment with Visual Studio 2012, click here.
To debug the UEFI environment with Visual Studio 2010, click here.
To debug the UEFI environment with Visual Studio 2008, click here.

Set-Up

1. Open the NT32 project in Visual Studio 2012.











2. Go to File -> Open File...













3. Because environment variables no longer work for NT32, we need to change the DSC file. Open Nt32Pkg.dsc (located in C:\sourcecode\edk2\Nt32Pkg\Nt32pkg.dsc).








4. Find the section of Nt32Pkg.dsc labeled "Pcd Dynamic Section."










5. Find the line for PcdWinNtGop and change it so it reads as follows
gEfiNt32PkgTokenSpaceGuid.PcdWinNtGop|L"GOP Window 1!GOP Window 2"|VOID*|52




 6.Again, got to File -> Open File...
















7. Open the file Main.c, which is located at c:\sourcecode\edk2\AppPkg\Applications\Main\Main.c








8. In Main.c, go to the line of code that reads as follows:

puts("Hello there fellow Programmer");










9. Press F9. A red dot should appear in front of that line of code. You have created a break in the code.













10. Use the tabs in Visual Studios to switch back to Nt32Pkg.dsc.






11. Find the line of code that has "HelloWorld" in it (The line should read MdeModulePkg/Applications/HelloWorld/HelloWorld.inf).








12. Under that line of code, write the following text:

AppPkg/Applications/Main/Main.inf





13. Scroll down to the very bottom of Nt32Pkg.dsc and write the following text:

DEFINE EMULATE
!include StdLib/StdLib.inc






14. Go to Build->Build Solution.








15. Wait for the Build to finish.
The picture to the right shows what the output box will display when it is finished.

Debugging

16. Press F5, then press "No" in the box that appears.

17. When the Graphics Output Window appears, hit "Enter" twice, or wait for the window to load completely.










18. Type "Main" into the Graphics Output Window.













19. The process should halt and bring you to the Break you set in Main.c in Step 9.







20. From here, F10 will bring you through the code line-by-line as it runs. You can also go to Debug->Continue to let the program continue normally.















You can halt the execution of the emulated UEFI environment at any time by selecting Debug->Break All. Then you can set some breakpoints on a specific function by using Debug->New Breakpoint->Break At Function and typing in the function name. You can force a breakpoint by inserting a __debugbreak() into your code or by hitting F9.

HOW-TO: Debug The EDK2's Windows-Hosted UEFI Environment

Last time, we looked at how to set up the Windows-hosted (NT32) UEFI environment provided by the EDK2.  The NT32 environment is very useful for debugging UEFI applications which aren't tied to specific hardware devices.  So in this article, I'll show how to add on debugging support in Visual Studio 2010.

This article assumes you have already loaded the Visual Studio project to build the EDK2's NT32 platform in C:\edk2 as described previously.

1. Select the NT32 project in the Solution Explorer.  Select Project->Properties.

2. Select "Debugging" on the right.  Select "Command" and click the drop-down arrow.

3. Click "<Edit...>" A separate editor window should open up.  Enter "C:\edk2\Build\NT32\DEBUG_VS2010x86\IA32\SecMain.exe" 

4. Do the same for "Working Directory" and enter "C:\edk2\Build\NT32\DEBUG_VS2010x86\IA32"

5. Click "OK."

6. Now, since Environment variables no longer work for NT32, we need to actually change the DSC file.  Open up Nt32Pkg.dsc (located in C:\edk2\Nt32Pkg\Nt32Pkg.dsc).  

7.  Find the section labeled "Pcd Dynamic Section."  

8.  Find the line for PcdWinNtGop and change it so it reads
gEfiNt32PkgTokenSpaceGuid.PcdWinNtGop|L"GOP Window 1!GOP Window 2"|VOID*|52

9.  Save and close the file.

Debugging
Now you are ready to actually debug.  Press F5 (or select Debug->Start Debugging).  It will always ask you if you want to rebuild the project, since we haven't added any source files which Visual Studio can use to determine if the project source has been changed.  For now, choose yes and you will see the program begin to execute normally

You can halt the execution of the emulated UEFI environment at any time by selecting Debug->Break All.  Then you can  set some breakpoints on a specific function by using Debug->New Breakpoint->Break At Function and type in the function name.  You can force a breakpoint by inserting a __debugbreak() into your code

As the code executes, you will notice that the Visual Studio output window talks about various DLLs being loaded.  The Windows-hosted environment actually loads your UEFI drivers and applications as DLLs (look in PUT_FILEPATH_HERE).  The actual main program is called SecMain.exe

HOW-TO: Debug The EDK's Windows-Hosted UEFI Environment

Last time we took a quick look at how to set up the Windows-hosted (NT32) UEFI environment provided by the EDK. The NT32 environment is very useful for debugging UEFI applications which aren't tied to specific hardware devices. So this week, I'll show how to add on debugging support.

This article assumes that you have already loaded the Visual Studio project to build the EDK's NT32 platform in C:\EDK as described previously.

1. Select the NT32 project in the Solution Explorer.

2. Select Project|Properties

3. In the "NT32 Properties Pages" select "Debugging"

4. Select "Command" and enter "SecMain.exe".
5. Select "Working Directory" and enter "c:\edk\sample\platform\nt32\uefi\ia32".

6. Select "Environment" and select the ...

7. An editor will pop up. In the editor box, enter the following and the click "OK". These are environment variables which govern how the emulator works, how much memory it uses, what virtual devices it has access to, etc. We will discuss these more in the next article.

EFI_WIN_NT_PHYSICAL_DISKS=a:RW;2880;512!g:RW;262144;512

EFI_WIN_NT_VIRTUAL_DISKS=FW;40960;512
EFI_WIN_NT_SERIAL_PORT=COM1!COM2
EFI_WIN_NT_GOP=Graphics Output Window 1!Graphics Output Window 2
EFI_WIN_NT_UGA=UGA Window 1!UGA Window 2
EFI_FIRMWARE_VOLUMES=..\Fv\FvRecovery.fd
EFI_WIN_NT_FILE_SYSTEM=.!%EDK_SOURCE%\Other\Maintained\Application\UefiShell\bin\ia32\Apps
EFI_MEMORY_SIZE=64!64
EFI_BOOT_MODE=1
EFI_WIN_NT_CPU_MODEL=Intel(R) Processor Model
EFI_WIN_NT_CPU_SPEED=3000

8. Click "OK"

Debugging

Now you are ready to actually debug. Press F5 (or select Debug|Start Debugging). It will always ask you if you want to rebuild the project, since we havne't added any source files which Visual Studio can use to determine if the project source has been changed. For now, choose Yes and then you will see the program begin to execute normally.

You can halt the execution of the emulated UEFI environment at any time by selecting Debug|Break All. Then you can set some breakpoints on a specific function using Debug|New Breakpoint|Break At Function and type in the function name. You can force a breakpoint by inserting a __debugbreak() into your code.

As the code executes you will notice that the Visual Studio window talks about various DLLs being loaded. The Windows-hosted environment actually loads your UEFI drivers and applications as DLLs (look in C:\Edk\Sample\Platform\Nt32\Uefi\Ia32). The actual main program is called SecMain.exe.

Conclusion
So now we're debugging. But what else can we do with the Windows-hosted (NT32) environment? Next time we'll look at how the environment can be configured.