HOW-TO: Set Up the EDK2's Windows-Hosted UEFI Environment With Visual Studio 2012

This article shows how to set up the environment for the Widows-hosted UEFI (aka NT32) in the environment provided by EDK2.
This article assumes that you have Visual Studio 2012 installed and that EDK2 has been downloaded to C:\sourcecode\edk2.
If you would like to create the environment in Visual Studio 2010, please click here.
If you would like to create the environment in Visual Studio 2008, please click here.

Create New Visual Studio Project

These steps will set up Visual Studio 2012 so that it can build the Windows-hosted (NT32) environment.

1. Select File -> New Project.

2. Select the "Visual C++" category and select "MakeFile Project." Enter the name as "NT32"
press "OK."










3.The MakeFile Project Wizard will pop up. Click "Finish."












4. The project should appear in the Solution Explorer.
















5. Select the project by right-clicking on the name, then select "Properties" from the right-click menu.

6. Select the category "Configuration Properties", then select "NMake."











7. Under "General", select "Build Command Line." To the far right, a drop down arrow will appear. Click the arrow, then click "<Edit...>"










8. A separate editor box will open. In the box, write the following text, then press "OK."

cd /D c:\sourcecode\edk2
set WORKSPACE=c:\sourcecode\edk2
call edksetup.bat --nt32
build









9. In the "Rebuild All Command Line" editor box, write the following text, then press "OK."

cd /D c:\sourcecode\edk2
set WORKSPACE=c:\sourcecode\edk2
call edksetup.bat --nt32
build clean
build








10. In the "Clean Command Line" editor box, enter the following text, then press "OK."

cd /D c:\sourcecode\edk2
set WORKSPACE=c:\sourcecode\edk2
call edksetup.bat --nt32
build clean

 11. Go to the category "Debugging."











12. Select "Command", and under the drop-down arrow menu, select "<Edit...>" then type the following text before pressing "OK."

c:\sourcecode\edk2\Build\NT32IA32\DEBUG_VS2012x86\IA32\SecMain.exe

13. Select "Work Directory," and in the drop-down arrow menu, select "<Edit...>", then type the following text before pressing "OK."

c:\sourcecode\edk2\Build\NT32IA32\DEBUG_VS2012x86\IA32

14. Press "OK."

15. At the location c:\sourcecode\edk2\BaseTools\Conf, there are two files: target.template and tools_def.template. Copy both files.








16. Paste the files to c:\sourcecode\edk2\Conf and change both files into .txt files.









17. Once you have moved these two files, open target.txt. Find the line that begins with  After TOOL_CHAIN_TAG, the line reads MYTOOLS. Replace MYTOOLS with VS2012x86 and save the file.
TOOL_CHAIN_TAG.

Launching the Windows-Hosted Environment

1. Go to Build -> Build Solution







2. Wait for the build to finish. The text shown to the right should be the what is displayed in the output box when it is finished.




3. Press F5. When a pop-up box appears, press "No."

At this point, at least two windows should open: the debug output console window and then the graphics output window.

The graphics output window will show a fake logo and a progress bar.












The window will then boot into the built-in EFI shell.

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.

HOW-TO: Set Up The EDK's Windows-Hosted UEFI Environment With Visual Studio 2008.

Since I'm working on a little research project of my own using UEFI applications, I thought I'd use the Windows-hosted UEFI (aka NT32) environment provided with the EDK. From previous experience, I know that the ability to debug applications using the Visual Studio environment speeds up my development time considerably. So I thought I'd share how I set up my environment. Then next time, I'll share how I set up for debugging.

This article assumes that you have Visual Studio 2008 installed and that the EDK has been downloaded to C:\EDK.

Create New Visual Studio Project
In this step, the goal is to set up Visual Studio so that it can build the Windows-hosted (NT32) UEFI environment. The build files for this project are located in C:\EDK\SAMPLE\PLATFORM\NT32.

1. Select File|New|Project.

2. Select the "General" project category and select "Makefile Project". Then enter the Name as "NT32". Then click "OK".

3. The Makefile Project Wizard will pop up. Click "Finish"

4. Your new project will appear in the Solution Explorer.

5. Select the NT32 project with the mouse. Select Project|Properties.

6. On the "NT32 Property Pages", change "Configuration" to "All Configurations".

7. Select "Build Command Line" and then select the ... on the right edge.

8. This will pop up a separate editor box. On three separate lines, enter the following text and click "OK".

cd /D c:\edk\sample\platform\nt32
set EDK_SOURCE=c:\edk
call build.bat

9. Now, for "Rebuild All Command Line" enter:

cd /D c:\edk\sample\platform\nt32

set EDK_SOURCE=c:\edk
call build.bat clean
call build.bat

10. Now, for "Clean Command Line" enter:

cd /D c:\edk\sample\platform\nt32

set EDK_SOURCE=c:\edk
call build.bat clean

11. Finally, for the last step, enter:

c:\edk\sample\platform\nt32\uefi\ia32\SecMain.exe

12. Select OK.












13. Edit Config.env, which is located in C:\EDK\Sample\Platform\NT32\Build, and change USE_VC8 = YES. By default, it is set to NO, which will build with Visual Studio 2003 and a large number of build errors.

Launching The Windows-Hosted Environment.
At this point, should be able to build by selecting Build|Build (or using F7). You can run the emulated environment by going to the command prompt and typing:

cd /d c:\edk\sample\platform\nt32\uefi\ia32
SecMain.exe

You will see (at least) two windows: the debug output console window and then the graphics output window. The graphics output window will show a fake logo, a progress bar and then boot into the built-in EFI Shell.



Conclusion
Well, that gets us to the first step. Next time we'll discuss how to set up the debugger and how to make your code debugger friendly.