HOW-TO: Run Main

Okay, I've got it all set up and I want to write a basic C app so I went looking for examples. I found examples, but didn't know how to get them to build and none of the docs showed me how. So here's how I figured out how to get a basic app built.
This article will describe how to run Main, a project that contains a simple C application.  

This article assumes you have downloaded EDK2 into C:\edk2 and have set up the Visual Studio project to build the EDK2's NT32 platform.  The files for Main are located in C:\edk2\AppPkg\Applications\Main

1. Open Nt32Pkg.dsc.  It is located in C:\edk2\NT32Pkg.  


2. Under the [Components.IA32] section, add "AppPkg/Applications/Main/Main.inf" 
What you are building (Nt32Pkg) is actually the platform package (or just the platform). You are adding an application (Main) to the platform (Nt32Pkg) so that it will be built. The DSC file controls which drivers and applications will be built. Libraries, drivers and applications have the generic name 
"modules."   

3. At the very bottom of Nt32Pkg.dsc, add the following:
DEFINE EMULATE
!include StdLib\StdLib.inc 
Main uses the standard C library, which is not used by any other modules in the Nt32 platform. So need to add the C library the platform so that that it will be built. The EMULATE flag tweaks the C Library so that it works well with emulated (or hosted) environments like NT32.


4. Be sure edk2 is up-to-date.


5. You should be able to run the project from Visual Studio by using CTRL+F5.  You can also run it from the command prompt by typing:
cd /d c:\edk2\Build\NT32\DEBUG_VS2010x86\IA32
SecMain.exe


6. Two windows will pop up and will run the emulated Shell environment.  You can now run Main from the Shell.  Type the following into the console window:
map -r
f8:
Main.efi





Ok, I got it built and now I can go about modifying it and creating new stuff.

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: Set Up The EDK2's Windows-Hosted UEFI Environment With Visual Studio 2010.

This article shows how to set up the environment for the Windows-hosted UEFI (aka NT32) in the environment provided by EDK2.  This is similar to a previous article, but this time, we are using EDK2 and Visual Studio 2010.
This article assumes that you have Visual Studio 2010 installed and that EDKII has been downloaded  to C:\edk2


Create New Visual Studio Project
This step's goal is to set up Visual Studio so that it can build the Windows-hosted (NT32) environment

1.  Select File->New->Project 










2. Select the "General" project category and select "Makefile Project."  Enter the name as "NT32" and 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 project with your mouse and then click Project->Properties 






6. Set the Configuration to "All Configurations" and select "NMake" on the right 

7. Select "Build Command Line" and click the drop-down arrow on the right.  Click "<Edit...>"  

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

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






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

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


10. For "Clean Command Line," enter

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


11. Click "OK."


12. Edit target.txt, which is located in C:\edk2\Conf, and change TOOL_CHAIN_TAG = VS2010x86.  By default, it is set to MYTOOLS, which builds in Visual Studio 2008 and will cause build errors.


Launching the Windows-Hosted Environment
At this point, you should be able to build by selecting Build->Build Solution (or using F7).  You can run the emulated environment by going to the command prompt and typing:
cd /d c:\edk2\Build\NT32\DEBUG_VS2010x86\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
That gets us past the first step.  Next time, we'll show how to set up the debugger and make the code debugger-friendly in VS 2010.

UEFI Summer Summit, 16-20 July at Microsoft.

Well, the plugfests have been coming fast and furious. Taipei, Sunnyvale, Taipei again and now Redmond. The release of Microsoft Windows 8, UEFI-optimized versions of Redhat and other Linux distros, and IPv6 have put a lot of pressure on making UEFI interoperability a reality. Pile the new crowd of plug-in PCIe cards that have UEFI option ROMs, and even a USB display device, and you can see why getting everyone together in one place makes sense. More details and registration at  www.uefi.org.
I'll be there. I'm sure the usual suspects will be there also. Look me up in the Insyde rooms.
On a separate note, I've added a guest blogger, my daughter Shannon Lewis, a computer game science student at UC Irvine, and probably the youngest official UEFI adopter. You'll be seeing some updates to older articles, as well as new UEFI programming articles.