The Minnowboard Chronicles Episode 15: More UEFI Application Development in ‘C’

Alan Sguigna

May 14, 2017
2:55 pm

In Episode 12, I wrote a simple “Hello World!” application in ‘C’ using the built-in UEFI shell functions. In Episode 13, I failed in an attempt to re-write that application using standard ‘C’ library functions, such as printf(). I’ve learned a lot since then – here’s how to write more sophisticated programs.

From Episode 12 Writing UEFI Applications, I took a simple ‘C’ program and adapted it to print “Hello World” to the screen.

#include <Uefi.h>

#include <Library/UefiApplicationEntryPoint.h>

#include <Library/UefiLib.h>

EFI_STATUS

EFIAPI

UefiMain (

IN EFI_HANDLE ImageHandle,

IN EFI_SYSTEM_TABLE *SystemTable

)

{

Print(L"Hello World \n");

return EFI_SUCCESS;

}

Note that this program differs from other simple ‘C’ programs in that the entry point is not the familiar main(INT argc, CHAR16 **argv) that I wanted to use to pass in a command line string. Also, it uses the UEFI shell “print” command rather than the “printf” that I am used to.

I decided to start with a program that echoes the command line to the screen, similar to the “echo” shell command.

So, one step at a time. I first wanted to learn how to modify my program to accept command line parameters and manipulate them. I found out that I needed to change the module entry point from “UefiMain” to “ShellAppMain” to pass parameters in on the command line. And, to do that, the HelloWorld.inf file must be updated to have ENTRY_POINT set to ShellCEntryLib, Packages must include ShellPkg/ShellPkg.dec, and LibraryClasses must include ShellCEntryLib. And finally, the DuetPkgX64.dsc file must have the path to ShellCEntryLib explicitly added:

ShellCEntryLib|ShellPkg/Library/UefiShellCEntryLib/UefiShellCEntryLib.inf

So here is a “new and improved” version of MyHelloWorld.c that takes the user input from the command line and echoes it back on the screen:

/**

My Hello World!

**/

#include <Uefi.h>

#include <Library/UefiApplicationEntryPoint.h>

#include <Library/UefiLib.h>

INTN

EFIAPI

ShellAppMain (

IN UINTN Argc,

IN CHAR16 **Argv[]

)

{

int i;

for (i = 1; i < Argc; i++)

Print(L"%s ", Argv[i]);

Print(L"\n");

return EFI_SUCCESS;

}

The MyHelloWorld.inf file that is used within the build is as follows:

## @file

[Defines]

INF_VERSION = 0x00010006

BASE_NAME = MyHelloWorld

FILE_GUID = 6467c5d1-d0f0-4b47-a6a4-0545624972ef

MODULE_TYPE = UEFI_APPLICATION

VERSION_STRING = 1.0

ENTRY_POINT = ShellCEntryLib

# The following information is for reference only and not required by the build.

VALID_ARCHITECTURES = X64

[Sources]

MyHelloWorld.c

[Packages]

MdePkg/MdePkg.dec

ShellPkg/ShellPkg.dec

[LibraryClasses]

UefiApplicationEntryPoint

UefiLib

ShellCEntryLib

[Guids]

[Ppis]

[Protocols]

[FeaturePcd]

[Pcd]

And finally, the DuetPkgX64.dsc file which is the driver for the build (that is, it uses the defined source code, packages and library classes to build the application) is as follows:

## @file

# An EFI/Framework Emulation Platform with UEFI HII interface supported.

# Developer's UEFI Emulation. DUET provides an EFI/UEFI IA32/X64 environment on legacy BIOS,

# to help developing and debugging native EFI/UEFI drivers.

# This program and the accompanying materials

# are licensed and made available under the terms and conditions of the BSD License

# which accompanies this distribution. The full text of the license may be found at

# http://opensource.org/licenses/bsd-license.php

# THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,

# WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.

################################################################################

# Defines Section – statements that will be processed to create a Makefile.

################################################################################

[Defines]

PLATFORM_NAME = DuetPkg

PLATFORM_GUID = 199E24E0-0989-42aa-87F2-611A8C397E72

PLATFORM_VERSION = 0.4

DSC_SPECIFICATION = 0x00010005

OUTPUT_DIRECTORY = Build/DuetPkgX64

SUPPORTED_ARCHITECTURES = X64

BUILD_TARGETS = DEBUG

SKUID_IDENTIFIER = DEFAULT

FLASH_DEFINITION = DuetPkg/DuetPkg.fdf

################################################################################

# Library Class section – list of all Library Classes needed by this Platform.

################################################################################

[LibraryClasses]

# Entry point

PeimEntryPoint|MdePkg/Library/PeimEntryPoint/PeimEntryPoint.inf

DxeCoreEntryPoint|MdePkg/Library/DxeCoreEntryPoint/DxeCoreEntryPoint.inf

UefiDriverEntryPoint|MdePkg/Library/UefiDriverEntryPoint/UefiDriverEntryPoint.inf

UefiApplicationEntryPoint|MdePkg/Library/UefiApplicationEntryPoint/UefiApplicationEntryPoint.inf

# Basic

BaseLib|MdePkg/Library/BaseLib/BaseLib.inf

SynchronizationLib|MdePkg/Library/BaseSynchronizationLib/BaseSynchronizationLib.inf

BaseMemoryLib|MdePkg/Library/BaseMemoryLib/BaseMemoryLib.inf

PrintLib|MdePkg/Library/BasePrintLib/BasePrintLib.inf

CpuLib|MdePkg/Library/BaseCpuLib/BaseCpuLib.inf

IoLib|MdePkg/Library/BaseIoLibIntrinsic/BaseIoLibIntrinsic.inf

PciLib|MdePkg/Library/BasePciLibCf8/BasePciLibCf8.inf

PciCf8Lib|MdePkg/Library/BasePciCf8Lib/BasePciCf8Lib.inf

PciExpressLib|MdePkg/Library/BasePciExpressLib/BasePciExpressLib.inf

CacheMaintenanceLib|MdePkg/Library/BaseCacheMaintenanceLib/BaseCacheMaintenanceLib.inf

PeCoffLib|MdePkg/Library/BasePeCoffLib/BasePeCoffLib.inf

PeCoffGetEntryPointLib|MdePkg/Library/BasePeCoffGetEntryPointLib/BasePeCoffGetEntryPointLib.inf

# UEFI & PI

UefiBootServicesTableLib|MdePkg/Library/UefiBootServicesTableLib/UefiBootServicesTableLib.inf

UefiRuntimeServicesTableLib|MdePkg/Library/UefiRuntimeServicesTableLib/UefiRuntimeServicesTableLib.inf

UefiRuntimeLib|MdePkg/Library/UefiRuntimeLib/UefiRuntimeLib.inf

UefiLib|MdePkg/Library/UefiLib/UefiLib.inf

UefiHiiServicesLib|MdeModulePkg/Library/UefiHiiServicesLib/UefiHiiServicesLib.inf

HiiLib|MdeModulePkg/Library/UefiHiiLib/UefiHiiLib.inf

DevicePathLib|MdePkg/Library/UefiDevicePathLib/UefiDevicePathLib.inf

UefiDecompressLib|MdePkg/Library/BaseUefiDecompressLib/BaseUefiDecompressLib.inf

DxeServicesLib|MdePkg/Library/DxeServicesLib/DxeServicesLib.inf

DxeServicesTableLib|MdePkg/Library/DxeServicesTableLib/DxeServicesTableLib.inf

UefiCpuLib|UefiCpuPkg/Library/BaseUefiCpuLib/BaseUefiCpuLib.inf

ShellCEntryLib|ShellPkg/Library/UefiShellCEntryLib/UefiShellCEntryLib.inf

# Generic Modules

UefiUsbLib|MdePkg/Library/UefiUsbLib/UefiUsbLib.inf

UefiScsiLib|MdePkg/Library/UefiScsiLib/UefiScsiLib.inf

OemHookStatusCodeLib|MdeModulePkg/Library/OemHookStatusCodeLibNull/OemHookStatusCodeLibNull.inf

GenericBdsLib|IntelFrameworkModulePkg/Library/GenericBdsLib/GenericBdsLib.inf

SecurityManagementLib|MdeModulePkg/Library/DxeSecurityManagementLib/DxeSecurityManagementLib.inf

CapsuleLib|MdeModulePkg/Library/DxeCapsuleLibNull/DxeCapsuleLibNull.inf

PeCoffExtraActionLib|MdePkg/Library/BasePeCoffExtraActionLibNull/BasePeCoffExtraActionLibNull.inf

CustomizedDisplayLib|MdeModulePkg/Library/CustomizedDisplayLib/CustomizedDisplayLib.inf

# Platform

PlatformBdsLib|DuetPkg/Library/DuetBdsLib/PlatformBds.inf

TimerLib|DuetPkg/Library/DuetTimerLib/DuetTimerLib.inf

# Misc

PerformanceLib|MdePkg/Library/BasePerformanceLibNull/BasePerformanceLibNull.inf

DebugAgentLib|MdeModulePkg/Library/DebugAgentLibNull/DebugAgentLibNull.inf

PcdLib|MdePkg/Library/BasePcdLibNull/BasePcdLibNull.inf

MemoryAllocationLib|MdePkg/Library/UefiMemoryAllocationLib/UefiMemoryAllocationLib.inf

HobLib|MdePkg/Library/DxeHobLib/DxeHobLib.inf

ExtractGuidedSectionLib|MdePkg/Library/DxeExtractGuidedSectionLib/DxeExtractGuidedSectionLib.inf

PlatformHookLib|MdeModulePkg/Library/BasePlatformHookLibNull/BasePlatformHookLibNull.inf

SerialPortLib|MdeModulePkg/Library/BaseSerialPortLib16550/BaseSerialPortLib16550.inf

MtrrLib|UefiCpuPkg/Library/MtrrLib/MtrrLib.inf

LockBoxLib|MdeModulePkg/Library/LockBoxNullLib/LockBoxNullLib.inf

CpuExceptionHandlerLib|UefiCpuPkg/Library/CpuExceptionHandlerLib/DxeCpuExceptionHandlerLib.inf

LocalApicLib|UefiCpuPkg/Library/BaseXApicLib/BaseXApicLib.inf

# To save size, use NULL library for DebugLib and ReportStatusCodeLib.

# If need status code output, do library instance overriden as below DxeMain.inf does

DebugLib|MdePkg/Library/BaseDebugLibNull/BaseDebugLibNull.inf

DebugPrintErrorLevelLib|MdePkg/Library/BaseDebugPrintErrorLevelLib/BaseDebugPrintErrorLevelLib.inf

ReportStatusCodeLib|MdePkg/Library/BaseReportStatusCodeLibNull/BaseReportStatusCodeLibNull.inf

[LibraryClasses.common.DXE_CORE]

HobLib|MdePkg/Library/DxeCoreHobLib/DxeCoreHobLib.inf

MemoryAllocationLib|MdeModulePkg/Library/DxeCoreMemoryAllocationLib/DxeCoreMemoryAllocationLib.inf

################################################################################

# Pcd Section – list of all EDK II PCD Entries defined by this Platform

################################################################################

[PcdsFixedAtBuild]

gEfiMdePkgTokenSpaceGuid.PcdReportStatusCodePropertyMask|0x0

gEfiMdePkgTokenSpaceGuid.PcdDebugPropertyMask|0x0

gEfiMdePkgTokenSpaceGuid.PcdDebugPrintErrorLevel|0x0

gEfiMdeModulePkgTokenSpaceGuid.PcdResetOnMemoryTypeInformationChange|FALSE

[PcdsFeatureFlag]

gEfiMdeModulePkgTokenSpaceGuid.PcdTurnOffUsbLegacySupport|TRUE

###################################################################################################

# Components Section – list of the modules and components that will be processed by compilation

# tools and the EDK II tools to generate PE32/PE32+/Coff image files.

# Note: The EDK II DSC file is not used to specify how compiled binary images get placed

# into firmware volume images. This section is just a list of modules to compile from

# source into UEFI-compliant binaries.

# It is the FDF file that contains information on combining binary files into firmware

# volume images, whose concept is beyond UEFI and is described in PI specification.

# Binary modules do not need to be listed in this section, as they should be

# specified in the FDF file. For example: Shell binary (Shell_Full.efi), FAT binary (Fat.efi),

# Logo (Logo.bmp), and etc.

# There may also be modules listed in this section that are not required in the FDF file,

# When a module listed here is excluded from FDF file, then UEFI-compliant binary will be

# generated for it, but the binary will not be put into any firmware volume.

###################################################################################################

[Components]

DuetPkg/DxeIpl/DxeIpl.inf {

<LibraryClasses>

# If no following overriden for ReportStatusCodeLib library class,

# All other module can *not* output debug information even they are use not NULL library

# instance for DebugLib and ReportStatusCodeLib

ReportStatusCodeLib|MdeModulePkg/Library/DxeReportStatusCodeLib/DxeReportStatusCodeLib.inf

}

MdeModulePkg/Core/Dxe/DxeMain.inf {

# Enable debug output for DxeCore module, this is a sample for how to enable debug output

# for a module. If need turn on debug output for other module, please copy following overriden

# PCD and library instance to other module's override section.

<PcdsFixedAtBuild>

gEfiMdePkgTokenSpaceGuid.PcdReportStatusCodePropertyMask|0x07

gEfiMdePkgTokenSpaceGuid.PcdDebugPropertyMask|0x2F

gEfiMdePkgTokenSpaceGuid.PcdDebugPrintErrorLevel|0x80000042

<LibraryClasses>

DebugLib|IntelFrameworkModulePkg/Library/PeiDxeDebugLibReportStatusCode/PeiDxeDebugLibReportStatusCode.inf

ReportStatusCodeLib|DuetPkg/Library/DxeCoreReportStatusCodeLibFromHob/DxeCoreReportStatusCodeLibFromHob.inf

}

MdeModulePkg/Universal/PCD/Dxe/Pcd.inf

MdeModulePkg/Universal/WatchdogTimerDxe/WatchdogTimer.inf

MdeModulePkg/Core/RuntimeDxe/RuntimeDxe.inf

MdeModulePkg/Universal/MonotonicCounterRuntimeDxe/MonotonicCounterRuntimeDxe.inf

DuetPkg/FSVariable/FSVariable.inf

MdeModulePkg/Universal/CapsuleRuntimeDxe/CapsuleRuntimeDxe.inf

MdeModulePkg/Universal/MemoryTest/NullMemoryTestDxe/NullMemoryTestDxe.inf

MdeModulePkg/Universal/SecurityStubDxe/SecurityStubDxe.inf

MdeModulePkg/Universal/Console/ConPlatformDxe/ConPlatformDxe.inf

MdeModulePkg/Universal/Console/ConSplitterDxe/ConSplitterDxe.inf {

<LibraryClasses>

PcdLib|MdePkg/Library/DxePcdLib/DxePcdLib.inf

}

MdeModulePkg/Universal/HiiDatabaseDxe/HiiDatabaseDxe.inf

MdeModulePkg/Universal/SetupBrowserDxe/SetupBrowserDxe.inf

MdeModulePkg/Universal/DisplayEngineDxe/DisplayEngineDxe.inf

MdeModulePkg/Universal/Console/GraphicsConsoleDxe/GraphicsConsoleDxe.inf

MdeModulePkg/Universal/Console/TerminalDxe/TerminalDxe.inf

MdeModulePkg/Universal/DevicePathDxe/DevicePathDxe.inf

MdeModulePkg/Universal/SmbiosDxe/SmbiosDxe.inf

DuetPkg/SmbiosGenDxe/SmbiosGen.inf

#DuetPkg/FvbRuntimeService/DUETFwh.inf

DuetPkg/EfiLdr/EfiLdr.inf {

<LibraryClasses>

DebugLib|MdePkg/Library/BaseDebugLibNull/BaseDebugLibNull.inf

NULL|IntelFrameworkModulePkg/Library/LzmaCustomDecompressLib/LzmaCustomDecompressLib.inf

}

IntelFrameworkModulePkg/Universal/BdsDxe/BdsDxe.inf {

<LibraryClasses>

PcdLib|MdePkg/Library/DxePcdLib/DxePcdLib.inf

}

MdeModulePkg/Universal/EbcDxe/EbcDxe.inf

UefiCpuPkg/CpuIo2Dxe/CpuIo2Dxe.inf

UefiCpuPkg/CpuDxe/CpuDxe.inf

PcAtChipsetPkg/8259InterruptControllerDxe/8259.inf

DuetPkg/AcpiResetDxe/Reset.inf

DuetPkg/LegacyMetronome/Metronome.inf

PcAtChipsetPkg/PcatRealTimeClockRuntimeDxe/PcatRealTimeClockRuntimeDxe.inf

PcAtChipsetPkg/8254TimerDxe/8254Timer.inf

DuetPkg/PciRootBridgeNoEnumerationDxe/PciRootBridgeNoEnumeration.inf

DuetPkg/PciBusNoEnumerationDxe/PciBusNoEnumeration.inf

IntelFrameworkModulePkg/Bus/Pci/VgaMiniPortDxe/VgaMiniPortDxe.inf

IntelFrameworkModulePkg/Universal/Console/VgaClassDxe/VgaClassDxe.inf

# IDE/AHCI Support

DuetPkg/SataControllerDxe/SataControllerDxe.inf

MdeModulePkg/Bus/Ata/AtaAtapiPassThru/AtaAtapiPassThru.inf

MdeModulePkg/Bus/Ata/AtaBusDxe/AtaBusDxe.inf

MdeModulePkg/Bus/Scsi/ScsiBusDxe/ScsiBusDxe.inf

MdeModulePkg/Bus/Scsi/ScsiDiskDxe/ScsiDiskDxe.inf

# Usb Support

MdeModulePkg/Bus/Pci/UhciDxe/UhciDxe.inf

MdeModulePkg/Bus/Pci/EhciDxe/EhciDxe.inf

MdeModulePkg/Bus/Usb/UsbBusDxe/UsbBusDxe.inf

MdeModulePkg/Bus/Usb/UsbKbDxe/UsbKbDxe.inf

MdeModulePkg/Bus/Usb/UsbMassStorageDxe/UsbMassStorageDxe.inf

# ISA Support

PcAtChipsetPkg/IsaAcpiDxe/IsaAcpi.inf

IntelFrameworkModulePkg/Bus/Isa/IsaBusDxe/IsaBusDxe.inf

IntelFrameworkModulePkg/Bus/Isa/IsaSerialDxe/IsaSerialDxe.inf

IntelFrameworkModulePkg/Bus/Isa/Ps2KeyboardDxe/Ps2keyboardDxe.inf

IntelFrameworkModulePkg/Bus/Isa/IsaFloppyDxe/IsaFloppyDxe.inf

MdeModulePkg/Universal/Disk/DiskIoDxe/DiskIoDxe.inf

MdeModulePkg/Universal/Disk/UnicodeCollation/EnglishDxe/EnglishDxe.inf

MdeModulePkg/Universal/Disk/PartitionDxe/PartitionDxe.inf

# Bios Thunk

DuetPkg/BiosVideoThunkDxe/BiosVideo.inf

# Sample Application

# MdeModulePkg/Application/HelloWorld/HelloWorld.inf

MyHelloWorld/MyHelloWorld.inf

###################################################################################################

# BuildOptions Section – Define the module specific tool chain flags that should be used as

# the default flags for a module. These flags are appended to any

# standard flags that are defined by the build process. They can be

# applied for any modules or only those modules with the specific

# module style (EDK or EDKII) specified in [Components] section.

###################################################################################################

[BuildOptions]

MSFT:*_*_*_CC_FLAGS = /FAsc /FR$(@R).SBR

Now I’ll go through a detailed step-by-step process description for the build.

I put the ‘C’ source code, MyHelloWorld.inf file and the modified DuetPkgX64.dsc file into a folder entitled MyHelloWorld within the MyWorkSpace folder.

Firstly, launch “Developer Command Prompt for VS2013”.

Navigate (using the “cd” change directory command) to the MyWorkSpace directory that contains all the build files.

Type in “edksetup”.

Type in “build –p MyHelloWorld/DuetPkgX64.dsc”.

The application builds perfectly and echoes the command line arguments out to the screen. For example, if you type:

MyHelloWorld.efi This is a test!

You see the “This is a test!” echoed back on the following line. Pretty cool.

A couple of interesting notes:

On the HDMI monitor I’ve hooked the Minnowboard to, I simply see the text “This is a test!” echoed to the screen. But on the CoolTerm application I’ve got hooked into the serial port, I see the following:

FS0:\> MyHelloWorld.efi This is a test!

InstallProtocolInterface: 5B1B31A1-9562-11D2-8E3F-00A0C969723B 762CBC00

PDB = c:\myworksspace2\Build\DuetPkgX64\DEBUG_VS2012x86\X64\MyHelloWorld5\MyHelloWorld\DEBUG\MyHelloWorld.pdb

Loading driver at 0x00077CD1000 EntryPoint=0x00077CD12C0 MyHelloWorld.efi

InstallProtocolInterface: BC62157E-3E33-4FEC-9920-2D3B36D750DF 762BAC58

InstallProtocolInterface: 752F3136-4E16-4FDC-A22A-E5F46812F4CA 78851848

This is a test!

Also, I’ve noted that the compiler rejects the following:

for (int i = 1; i > Argc; i++)

But, rather, it wants the variable declaration to be in a distinct statement:

int i;

for (i = 1; i > Argc; i++)

I don’t know why that is. Maybe I am using an older version of Visual Studio (VS2013)? That’s something to figure out for another day.

To summarize, in this episode I’ve graduated from creating a simple ‘C’ program that printed “Hello World” to the screen, to actually taking shell command parameters and echoing those out to the terminal. It may seem like a small step, but it really helped me understand how the ‘C’ source and build files interact with each other. This should enable me to write more sophisticated code going forward, and to understand how more complex programs, like drivers, are put together.

For others who might also like to take such a self-taught journey, a good debugger is indispensable. SourcePoint is probably the best UEFI hardware-assisted tool available; read more at the product website page SourcePoint for Intel Platforms.