Skip to content

Latest commit

 

History

History
1542 lines (1079 loc) · 39.1 KB

LabGuide.md

File metadata and controls

1542 lines (1079 loc) · 39.1 KB

Slide 1

UEFI & EDK II Training

How to Write a UEFI Application

with Windows Labs
tianocore.org

Slide 2 @title[Lesson Objective]

Lesson Objective

  • UEFI Application with PCDs
  • Simple UEFI Application
  • Add functionality to UEFI Application
  • Using EADK with UEFI Application

Slide 3 @title[UEFI Application w/ PCDs Section]

UEFI Application w/ PCDs

Slide 4 @title[EDK II PCD’s Purpose and Goals]


EDK II PCD’s Purpose and Goals - REVIEW

Documentaton : MdeModulePkg/Universal/PCD/Dxe/Pcd.inf

Purpose

  • Establishes platform common definitions
  • Build-time/Run-time aspects
  • Binary Editing Capabilities

Goals

  • Simplify porting
  • Easy to associate with a module or platform

Note:

Slide 5 @title[PCD Syntax review]

PCD Syntax - REVIEW

PCDs can be located anywhere within the Workspace even though a different package will use those PCDs for a given project

Note:

  • The Platform configuration database is generated by the build process parsing the build description files that define and specify PCD entries.

  • What we see on this slide is how the PCD data is being used in various levels of the build description files

  • First we have the DEC file – this Defines a list of PCD tokens that modules can use. It Defines the PCD entries that will exist under the GUID for that package, the PCD restriction, valid types for the PCD, and a default value for the PCD. There is a whole syntax and how to define a PCD in the DEC file.

  • Next we have PCB entries in the INF file- and this Defines the usage of PCD tokens by the module. It Defines what PCD entries are being used within the module, the PCD restriction (or DYNAMIC for none), and a Optional default value for the PCD within this module only.

  • Next is the DSC file – This is at the Platform level and describes the contents of the build for a specific platform. PCD entries are assigned values and types for the platform build. You would define a value here to be used by that platform. The value could be different when it is defined in the DEC file but the value in the DSC would be the final value . And They Cannot conflict with established restrictions.

  • Not on this slide but also there is the FDF build description File – and this file would have flash layout related values

Slide 6 @title[Lab 1: Writing UEFI Applications with PCDs]

Lab 1: Writing UEFI Applications with PCDs

In this lab, you’ll learn how to write UEFI applications with PCDs.

Note:

Slide 7 @title[EDK II HelloWorld App Lab ]

EDK II HelloWorld App Lab

First Setup for Building EDK II for Emulator, See Lab Setup for Emulator

Locate and Open
edk2/MdeModulePkg/Application/HelloWorld/HelloWorld.c

Notice the PCD values


Build Emulation
Then Run HelloWorld at the Shell command interface

Note:

  • So the steps for getting the source code, hopefully everyone did this prior to this training because it does take some time to download.

  • So here are the steps:

  • First create a directory, and for our example case we are using the directory “~src/Fw/edk2-ws” Linux or "C:\Fw\edk2-ws" Windows

Slide 8 @title[EDK II HelloWorld App Lab steps]

EDK II HelloWorld App Lab

Open a VS Command Prompt and type: cd C:\FW\edk2-ws then

  C:/FW/edk2-ws> Setenv.bat
  C:/FW/edk2-ws> cd edk2
  C:/FW/edk2-ws/edk2> edksetup.bat

Build the EmulatorPkg for Windows X64 (run WinHost.exe from Build/EmulatorX64/ . . ./X64 )

  C:/FW/edk2-ws/edk2> Build –D ADD_SHELL_STRING
  C:/FW/edk2-ws/edk2> RunEmulator.bat

At the UEFI Shell prompt

Shell> Helloworld
UEFI Hello World!
Shell>

How can we force the HelloWorld application to print out 3 times ?

Note: RunEmulator.bat will run WinHost.exe from Build/EmulatorX64/DEBUG_TAG/X64

Slide 9 @title[EDK II HelloWorld App Lab location]

EDK II HelloWorld App Lab

MdeModulePkg/Application/HelloWorld

Note:

First let's look at the source code for the HellowWorld Application

Slide 10 @title[EDK II HelloWorld App Lab code]

EDK II HelloWorld App Lab

Source: Helloworld.c

EFI_STATUS
EFIAPI
UefiMain (
  IN EFI_HANDLE        ImageHandle,
  IN EFI_SYSTEM_TABLE  *SystemTable
  )
{
	UINT32 Index;
	Index = 0;
  // Three PCD type (FeatureFlag, UINT32 
  // and String) are used as the sample.
  if (FeaturePcdGet (PcdHelloWorldPrintEnable)) {
  	for (Index = 0; Index < PcdGet32   (PcdHelloWorldPrintTimes); Index ++) {
  	  
  	  // Use UefiLib Print API to print
      // string to UEFI console
  	  
    	Print ((CHAR16*)PcdGetPtr (PcdHelloWorldPrintString));
    }
  }

  return EFI_SUCCESS;
}

Note:

Source from Helloworld.c

Slide 11 @title[EDK II HelloWorld App Lab solution]

EDK II HelloWorld App Solution

Note:

  • look in file: C:\fw\edk2\MdeModulePkg\MdeModulePkg.Dec

  • This PCD defines the print string.

  • This PCD is a sample to explain String typed PCD usage.

  • gEfiMdeModulePkgTokenSpaceGuid.PcdHelloWorldPrintString|L"UEFI Hello World!\n"|VOID*|0x40000004

Solution:

  1. Edit the file C:/FW/edk2-ws/edk2/EmulatorPkg/EmulatorPkg.dsc
  • After the section [PcdsFixedAtBuild], add the new line :
  • [PcdsFixedAtBuild]
  • gEfiMdeModulePkgTokenSpaceGuid.PcdHelloWorldPrintTimes|3
  1. Re-Build – Cd to FW/edk2 dir
  • bash$ build -D ADD_SHELL_STRING

SLide 12 @title[EDK II HelloWorld App Lab solution 02]

EDK II HelloWorld App Solution

Note:

  1. RunEmulator.bat

  2. At the Shell prompt

 Shell> Helloworld
 UEFI Hello World!
 UEFI Hello World!
 UEFI Hello World!
 Shell>
  1. Exit with Reset at the shell
  • How can we change the string of the HelloWorld application?
  • Also see ~src/edk2/MdeModulePkg/MdeModulePkg.Dec

Slide 13 @title[Lab 2: Write a Simple UEFI Application]


Lab 2: Write a Simple UEFI Application


In this lab, you’ll learn how to write simple UEFI applications.

Slide 14 @title[Lab 2 - Write A Simple App]

LAB 2 - Writing a Simple UEFI Application

In this lab, you’ll learn how to write simple UEFI applications.

“C” file

EFI_STATUS
EFIAPI
UefiMain (
  IN EFI_HANDLE        ImageHandle,
  IN EFI_SYSTEM_TABLE *SystemTable
)
{ 
  return EFI_SUCCESS;
}
  • What goes into the Simplest “C”
  • Start with what should go into the Simplest .INF file

.inf file

[Defines]
  INF_VERSION    = 
  BASE_NAME      = 
  FILE_GUID      = 
  MODULE_TYPE    = 
  VERSION_STRING = 
  ENTRY_POINT    = 
 
[Sources]
 
[Packages]
 
[LibraryClasses]

Note:

  • Start with what should go into the Simplest .INF file
  • What goes into a Simplest “C”

Slide 15 @title[Lab 2: Application Lab –start with .c and .inf template]

Application Lab –start with .c and .inf template

Steps

  1. Copy the LabSampleCode/SampleApp directory to FW/edk2-ws/edk2
  2. Edit SampleApp.inf
  • Look in the INF for “XXXXXXXXXXX” sections that will need information
  • Create Name & GUID, and then fill in the MODULE_TYPE

Slide 16 @title[Lab 2: Sample Application INF file]

Lab 2: Sample Application INF file


 [Defines]
   INF_VERSION  = 0x00010005
   BASE_NAME    = XXXXXXXXXXX
   FILE_GUID    = XXXXXXXXXXX
   MODULE_TYPE  = XXXXXXXXXXX
   VERSION_STRING =   1.0            
   ENTRY_POINT  = UefiMain

 [Sources]
   XXXXXXXXX
 [Packages]
   #XXXXXXXX
  
 [LibraryClasses]
  #XXXXXXXXXXXXX
    
 [Guids]
  # . . .

Fill in with the following

 [Defines]
   INF_VERSION  = 0x00010005
   BASE_NAME    = SampleApp
   FILE_GUID    = NOTE: Get a GUID from Link below
   MODULE_TYPE  = UEFI_APPLICATION
   VERSION_STRING =   1.0            
   ENTRY_POINT  = UefiMain

 [Sources]
  SampleApp.c
 [Packages]
   #XXXXXXXX
  
 [LibraryClasses]
  #XXXXXXXXXXXXX
    
 [Guids]
  # . . .

Get a GUID: guidgerator.com

Note:

to get a Guid - http://www.guidgenerator.com/

  • Now here is a sample INF file
  • This is for an application called SampleApp
  • When the program starts is going to call the function called UefiMain inside the application.
  • The prototype for UefiMain is predetermined and you can see an example of a prototype by downloading a sample application.
  • So a couple of the things that the prototype will require are a pointer to the system table and a image handle parameter.

Slide 17 @title[Lab 2: Sample Application C file]

Lab 2: Sample Application ‘C’ file

/** @file
  This is a simple shell application
**/
 EFI_STATUS
 EFIAPI
 UefiMain (
   IN EFI_HANDLE        ImageHandle,
   IN EFI_SYSTEM_TABLE  *SystemTable
   )
 {
   return EFI_SUCCESS;
 }

Slide 18 @title[Lab 2: Will it compile now?]

Lab 2: Will it compile now?


Not yet . . .
  1. Need to add headers to the .C file
  2. Need to add a reference to INF from the platform DSC
  3. Need to add a few Package dependencies and libraries to the .INF

Note:

  • So the question is will it compile now?
  • And the answer is no it will not compile yet
  • First you need to add some headers to the.C. we need to be able to let some things.
  • We need to add a reference to the INF from the platform in DSC. Because If you build it now the build is going to say I don’t have a platform and so the build is going to break.
  • Then the next thing we need to add is a few package dependencies and libraries to the INF file because, for instance, features like the UEFI Application entry point will need to be added, because it doesn’t know how to do an entry point until you’ve added that.

SLide 19 @title[Lab 2: Application Lab – Update Files]

Lab 2: Application Lab – Update Files

  • 1.   `.DSC` (EmulatorPkg/EmulatorPkg.dsc)
    • `[Components . . .]`
    •   Add INF to components section, before build options
    •   Hint: add after comment "# Add new modules here "
      •        # Add new modules here
       SampleApp/SampleApp.inf
  • 2.   `.INF` file (SampleApp/SampleApp.inf)
    • Packages (all depend on MdePkg) and Library Classes 
      •      [Packages] 
        MdePkg/MdePkg.dec
     [LibraryClasses]  
       UefiApplicationEntryPoint
  • 3.   `.C` file - Header references File (SampleApp/SampleApp.c) 
    •  #include <Uefi.h>
 #include <Library/UefiApplicationEntryPoint.h>

Note:

  • So what are our steps for adding that
  • So first we need to add the MDE package to the INF file and you need to reference the file by the DEC file so under the [packages] section you Are going to add “MdePkg/MdePkg.dec”
  • Under the [LibraryClasses] section of the INF you’re going to add a reference to “UefiApplicationsEntryPoint” . And just as an interesting note is actually dependent on the “UefiBootServiecesTableLib”.
  • Next in the .C. file you are going to add some header references, the “Uefi.h” and “Library/UefiApplicationEntryPoint.h”
  • Then in the DSC file under the “[components]” section you’re going to add a reference to your new sample INF file.

SLide 20 @title[Lab 2: Lab cont. Solution ]

Lab 2: Lab cont. Solution

Note:

EmulatorPkg/EmulatorPkg.dsc in the components sectio of the file towards the botom

 SampleApp/SampleApp.inf

SampleApp/SampleApp.inf

     [Packages] 
        MdePkg/MdePkg.dec
     [LibraryClasses]  
       UefiApplicationEntryPoint

SampleApp/SampleApp.c - near the top of the file

#include <Uefi.h>
#include <Library/UefiApplicationEntryPoint.h>

Slide 21 @title[Lab 2: Will it compile now? ]

Lab 2 : Will it compile now?

Yes, At the VS Command Prompt 

  C:/FW/edk2-ws/edk2> Build –D ADD_SHELL_STRING 
  C:/FW/edk2-ws/edk2> RunEmulator.bat

Run the application from the shell

 Shell> SampleApp

Notice that the program will immediately unload because the main function is empty

Exit

 Shell> Reset

Note:

  • And the answer is yes.

  • It will compile and it will even run at this point but we haven’t really added any functionality to this sample code at this point and so since the main function is empty it will unload as soon as it is called.

  • So to test it after it has build successfully you then type RunEmulator.batin the EDK2 directory and to run your application type in the base name that you gave it in your INF file, type that name at the shell and it will run, but it won’t do anything because there is nothing for it to do.

  • another note: The program will immediately unload because the main function is empty

Slide 22 @title[Possible Build Errors ]

Possible Build Errors

Note: The FILE_GUID was invalid or not updated from “XXX…” to a proper formatted GUID

  • left is no FILE_GUID
  • right - left the "XXXX"

Slide 23 @title[Possible Build Errors 02 ]

Possible Build Errors

Note:

The [Packages] was invalid or did not specify MdePkg/MdePkg.dec properly

Slide 24 @title[Possible Build Errors 03]

Possible Build Errors

Note:

  • The #include <Library/UefiApplicationEntryPoint.h> has a typo (“Application” not “Applications”)

Slide 25 @title[Possible Build Errors 04 ]

Possible Build Errors

Note: The SampleApp.inf section [LibraryClasses] did not reference UefiApplicationEntryPoint

Slide 26 @title[Possible Build Errors 05]

Possible Build Errors

Note: Ensure the SampleApp.inf BaseName is SampleApp

SLide 27 @title[Lab 2.1: Build Switches]


Lab 2.1: Build Switches

In this lab, you’ll change the build switch to be always TRUE

Note:

Slide 28 @title[Lab 2.1: Build MACRO Switches ]

Build MACRO Switches

The build for EmulatorPkg is using build MACRO Switch:
-D ADD_SHELL_STRING – used to change a string in the UEFI Shell application, only used for EDK II Training (requires ShellPkg be re-built on a change of this switch)

edit EmulatorPkg.dsc Notepad

# For UEFI / EDK II Training 
# This flag is to enable a different ver string for building of the ShellPkg
# These can be changed on the command line.
  DEFINE ADD_SHELL_STRING      = FALSE

1. First delete directory Build/EmulatorX64/DEBUG_tag/X64/ShellPkg

Slide 29 @title[Lab 2.1: Compiling w/ Build Switch ]

Lab 2.1: Compiling w/out Build Switch

At the VS Command Prompt, Build without the -D Switch

  C:/FW/edk2-ws/edk2> Build
  C:/FW/edk2-ws/edk2> RunEmulator.bat

Check the Shell Version with the “Ver” command Build with the -D ADD_SHELL_STRING switch

  C:/FW/edk2-ws/edk2> Build -D  ADD_SHELL_STRING
  C:/FW/edk2-ws/edk2> RunEmulator.bat

Check the Shell Version with the “Ver” command

Note:

You will need to Delete directory: Build/EmulatorX64/DEBUG_tag/X64/ShellPkg

Between each build

Slide 30 @title[Lab 2.1: Compiling w/out Build Switch 02]

Lab 2.1: Compiling w/out Build Switch

Edit the file C:/FW/edk2-ws/edk2/EmulatorPkg/EmulatorPkg.dsc

Change the ADD_SHELL_STRING = FALSE to TRUE

Re-build - CD to C:\FW\edk2-ws\edk2

   C:/FW/edk2-ws/edk2> Build
   C:/FW/edk2-ws/edk2> RunEmulator.bat

Check the Shell Version with the “Ver” command

Note: Will need to Delete dir: %WORKSPACE%/Build/EmulatorX64/DEBUG_tag/X64/ShellPkg Between each build

Slide 31@title[Lab 2: What we learned from LAB 2]

What we learned from LAB 2


  1. How to write a simple native UEFI Application
  2. Each module requires a .inf file with a unique GUID (use http://www.guidgenerator.com/ )
  3. The module created will be the base name defined in the .inf file
  4. The module’s .inf file is required to be included in the platform .dsc file
  5. The [Packages] section is required at minimum to include MdePkg/dePkg.dec
  6. When using a Build Switch (-D) on the command line it overrides the value in the .DSC file

Slide 32 @title[Lab 2: If there are Build Errors ]

Lab 2: If there are build errors …


See class files for the solution
  • . . .FW/LabSampleCode/LessonB.2
  • Copy the .inf and .c files to C:/FW/edk2-ws/edk2/SampleApp
  • Search sample DSC for reference to SampleApp.inf and add this line to your workspace DSC file:
    C:/FW/edk2-ws/edk2/EmulatorPkg/EmulatorPkg.dsc
   SampleApp/SampleApp.inf

Invoke “ build” again and check the solution

Note:

Slide 33 @title[Add more Functionality Section]

Add Functionality

        Add Functionality to the Simple UEFI Application :

Next 3 Labs

  •     Lab 3:  Print the UEFI System Table
  •     Lab 4:  Wait for an Event
  •     Lab 5:  Create a Simple Typewriter function


Solutions in .../FW/LabSampleCode/LabSolutions/LessonB.n

Slide 34 @title[Lab 3: Print the UEFI System Table]


Lab 3: Print the UEFI System Table


Add code to print the hex address of the EFI System Table pointer to the console.

Slide 35 @title[Lab 3 : Add System Table Code]

Lab 3 : Add System Table Code

Add code to print to the console the hex address of the system table pointer

  • Where is the “print” function? (hint: use the MdePkg Document With Libraries.chm file in Lab_Material_FW/FW/Documentation to search for it)
  • Where does the app get the pointer value?(compared to mem command on pdf slide 35)

pic of uefi shell mem command followed by updated sampleapp

Note:

  • So let’s extend this and give it something useful to do
  • so for this example we are going to have our sample application print out the system table pointer
  • So how do we do that. Well remember to find a function we want we can use the help documentation or CHM file.so what we will find if we do this is that the print function is part of the UefiLib. So in order to add the print functionality we would need to add the UefiLib to our list of library classes in our INF file
  • To see this example look in the files in our sample lab code .c and .inf.
  • So also as an exercise you can look at the file in the sample lab code Min.dsc, this is a platform description file without a platform or any packages that go with it, and this demonstrates the minimal contents for a DSC file that can build this application. So it will build a single application orientated toward the one we just created except nothing else. So unlike the Emulator platform description file, if you were to look at it, There are huge amounts of other components, library classes, and all of that, this Min.dsc only does the minimum requirements.

Slide 36 @title[Locating the “Print” Function ]

Lab 3 : Locating the Print() Function

  1. Search the MdePkg Document With Libraries.chm and find that the Print function by clicking on the “Index” tab
  2. Type “Print” and double click
  3. Scroll to the top in the right window to see that the print function is in the UefiLib.h file

Note:

  • "MdePkg Document With Libraries.chm" located in ... Lab_Material_FW/FW/Documentation
  1. Search the MdePkg.chm and find that the Print function by clicking on the “Index” tab
  2. Type “Print” and double click
  3. Scroll to the top in the right window to see that the print function is in the UefiLib.h file
    • NOTE -: Install a CHM Viewer for Ubuntu
  • bash$ sudo aptitude install kchmviewer

Slide 37 @title[Modifying .C & .INF Files ]

Lab 3 : Modifying .C & .INF Files

  • SampleApp.c
#include <Uefi.h>
#include <Library/UefiApplicationEntryPoint.h>
#include <Library/UefiLib.h>

EFI_STATUS
EFIAPI
UefiMain (
  IN EFI_HANDLE        ImageHandle,
  IN EFI_SYSTEM_TABLE  *SystemTable
  )
{
// Lab 3
  Print(L"System Table: 0x%p\n", SystemTable); 
  return EFI_SUCCESS;
}
  • SampleApp.inf
 [LibraryClasses]
  UefiApplicationEntryPoint
# Lab 3
  UefiLib

Note:

  • c code and inf file

Slide 38 @title[Build and Test SampleApp]

Lab 3 : Build and Test SampleApp

At the VS Command Prompt

  C:/FW/edk2-ws/edk2> Build
  C:/FW/edk2-ws/edk2> RunEmulator.bat

Run the application from the shell

 Shell> SampleApp
 System Table: 0x07E34018
 Shell>

Verify by using the Shell “mem” command Exit

 Shell> Reset

Note:

End of LAB 3

Slide 39 @title[Lab 4: Waiting for an Event]


Lab 4: Waiting for an Event


In this lab, you’ll learn how to locate code and .chm files to help write EFI code for waiting for an event

Note:

Sldie 40 @title[Lab 4 : Add Wait for Event ]

Lab 4 : Add Wait for Event


Add code to make your application wait for a key press event (WaitForEvent / WaitForKey)

  • Where are these functions located?
  • What else can you do with the key press?

Note:

  • Add code to make your application wait for an event (WaitForEvent) and use the (WaitForKey) as the event

  • Hint: use the MdePkg.chm to find where the “WaitForEvent” and the “WaitForKey” functions are located

  • Another Hint: The system table is passed in as a parameter to your sample application

  • Search the EDK II code for “WaitForEvent”

  • Test by running your application in the Shell

Slide 41 @title[Lab 4 : How to locate functions? ]

Lab 4 : HOW?

Locate Functions:
WaitForEvent / WaitForKey

  • Search MdePkg.chm - Note: "MdePkg Document With Libraries.chm" located in ... Lab_Material_FW/FW/Documentation

    • Locate WaitForEvent in Boot Services
    • Locate WaitForKey and find ( EFI_SIMPLE_TEXT_INPUT_PROTOCOL will be part of ConIn )

  • Check the UEFI Spec for parameters needed: - WaitForEvent is referenced via Boot Services pointer, which is referenced via EFI System Table

    • WaitForKey can be referenced through the EFI System Table passed into the application

  • OR
    Search the working space for WaitForEvent for an example

Note:

  1. Search the MdePkg.chm and find where the “WaitForEvent” is located. It is part of the “Boot Services”.
  2. Search the MdePkg.chm and find where the “WaitForKey” is located. It is part of the “EFI_SIMPLE_TEXT_INPUT_PROTOCOL as part of ConIn.
  3. The WaitForEvent can be referenced through the Boot Services pointer which can be referenced through the System Table
  4. The WaitForKey can be referenced through the System Table passed into our Sample application
  5. Check the UEFI Spec for the parameters needed
  6. An example can be found in MdePkg\Library\UefiLib\Console.c :
  • gBS->WaitForEvent (1, &gST->ConIn->WaitForKey, &EventIndex);

Slide 42 @title[Lab 4 :Update the C File for WaitForKey ]

Lab 4 : Update the C File for WaitForKey

Search the work space and find the following MdePkg/Library/UefiLib/Console.c ~ ln 563:

Add the following following comment "// Lab 4"

EFI_STATUS
EFIAPI
UefiMain (
  IN EFI_HANDLE        ImageHandle,
  IN EFI_SYSTEM_TABLE  *SystemTable
  )
{
// Lab 4
 UINTN                      EventIndex; 

// Lab 3
 Print(L"System Table: 0x%p",SystemTable); 

 // Lab 4
 Print(L"\nPress any Key to continue : \n");
 gBS->WaitForEvent (1, &gST->ConIn->WaitForKey, &EventIndex);

Slide 43 @title[Lab 4 :Test Compile ]

Lab 4 :Test Compile


However, this won’t compile … gBS and gST are not defined.

Search the MdePkg.chm for “gBS” and “gST” – they are located in UefiBootServicesTableLib.h

Add the boot services lib to SampleApp.c . . .

#include <Library/UefiBootServicesTableLib.h>

(hint: Lesson B.4 has the solution)

Note:

  • However, this won’t compile … gBS and gST are not defined.

  • Search the MdePkg.chm for “gBS” and “gST” – they are located in UefiBootServicesTableLib.h

    • Add the boot services lib to SampleApp.c …
    • #include <Library/UefiBootServicesTableLib.h>

  • (hint: Lesson B.4 has the solution)

Slide 44 @title[Lab 4 : Update SampleApp.c for gBS & gST ]

Lab 4 : Update for gBS & gST


Note:

  • add:
  • #include <Library/UefiBootServicesTableLib.h>
#include <Uefi.h>
#include <Library/UefiApplicationEntryPoint.h>
#include <Library/UefiLib.h>
// Lab 4
#include <Library/UefiBootServicesTableLib.h>

EFI_STATUS
EFIAPI
UefiMain (
  IN EFI_HANDLE        ImageHandle,
  IN EFI_SYSTEM_TABLE  *SystemTable
  )
{
// Lab 4
  UINTN          EventIndex;
  
// Lab 3
 Print(L"System Table: 0x%08x\n",SystemTable); 

//Lab 4
 Print( L"\nPress any Key to continue : \n\n");
 gBS->WaitForEvent (1, &gST->ConIn->WaitForKey,    	&EventIndex);
 return EFI_SUCCESS;
}

// End of lab

Note:

Slide 45

Lab 4: Build and Test SampleApp

At the VS Command Prompt

  C:/FW/edk2-ws/edk2> Build
  C:/FW/edk2-ws/edk2> RunEmulator.bat

Run the application from the shell

 Shell> SampleApp
 System Table: 0x07E34018
 Press any key to continue:
 Shell>

Notice that the SampleApp will wait until a key press to continue.

Exit

 Shell> Reset

Note:

End of Lab 4

Slide 46 @title[Lab 5: Creating a Simple Typewriter Function]


Lab 5: Creating a Simple Typewriter Function


In this lab, you'll learn how to create a simple typewriter function that retrieves the keys you type and subsequently prints each one back to the console

Note:

Slide 47 @title[Lab 5 :Create a Simple Typewriter Function]

Lab 5 : Typewriter Function


Create a Simple Typewriter Function using the SampleApp from Lab 4
Requirements:

  • Retrieve keys entered from keyboard (Like Lab 4)
  • Print back each key entered to the console
  • To exit, press “.” (DOT) and then <Enter> key

Slide 48 @title[Lab 5 :Create a Simple Typewriter Function How]

Lab 5 : Typewriter Function


Create a Simple Typewriter Function using the SampleApp from Lab 4

How:

  1. Add a Loop using WaitForEvent with WaitForKey
  2. Use the ReadKeyStroke function from ConIn
  3. Print back each key to console
  4. Exit when DOT “.” character is followed by an <Enter> key

Slide 49 @title[Lab 5 : How Hints]

Lab 5 : How Process (Hints)

	Status = gST->ConIn->ReadKeyStroke (gST->ConIn, Key);
  • ReadKeyStroke uses buffer called EFI_INPUT_KEY ~ ln 393
		 OUT EFI_INPUT_KEY  *Key,
  • TIP: Good Idea to zero out a buffer in your function –
    • Use MdePkg.chm to find ZeroMem function
    • Use ZeroMem on your variable buffer “Key” of type EFI_INPUT_KEY
  • Use Boolean flag “ExitLoop” to exit your loop once the user enters a DOT “.” character.

Slide 50 @title[Lab 5 :Typewriter Function Solution]

Lab 5 : Solution


Copy and paste from the following sub slide

Slide 51 @title[Lab 5 :Typewriter Function Solution]

Lab 5 : Solution

SampleApp.c Should have the following for Lab 5:

#include <Uefi.h>
#include <Library/UefiApplicationEntryPoint.h>
#include <Library/UefiLib.h>
#include <Library/UefiBootServicesTableLib.h>
// Lab 5
#include <Library/BaseMemoryLib.h>
#define CHAR_DOT  0x002E    // '.' in Unicode

EFI_STATUS
EFIAPI
UefiMain (
  IN EFI_HANDLE        ImageHandle,
  IN EFI_SYSTEM_TABLE  *SystemTable
  )
{
  UINTN          EventIndex;
// Lab 5
  BOOLEAN        ExitLoop;
  EFI_INPUT_KEY  Key;
  
// Lab 3
 Print(L"System Table: 0x%p\n",SystemTable); 

//Lab 4
 Print( L"\nPress any Key to continue : \n\n");
 gBS->WaitForEvent (1, &gST->ConIn->WaitForKey,    	&EventIndex);

// Lab 5
 Print(L"Enter text. Include a dot ('.') in a sentence then <Enter> to exit:\n "); //
 ZeroMem (&Key, sizeof (EFI_INPUT_KEY));
 gST->ConIn->ReadKeyStroke (gST->ConIn, &Key);
 ExitLoop = FALSE;
 do {    // Do loop until "DOT" and "enter" 
	 gBS->WaitForEvent (1, &gST->ConIn->WaitForKey,&EventIndex);
	 gST->ConIn->ReadKeyStroke (gST->ConIn, &Key);
	 Print(L"%c", Key.UnicodeChar);
	 if (Key.UnicodeChar == CHAR_DOT){
		ExitLoop = TRUE;
    	 }
    } while (!(Key.UnicodeChar == CHAR_LINEFEED  ||  
	    Key.UnicodeChar == CHAR_CARRIAGE_RETURN) || 
       !(ExitLoop) );

 Print(L"\n");
 return EFI_SUCCESS;
}

// End of lab

Slide 52 @title[Lab 5 :Build and Test SampleApp ]

Lab 5 :Build and Test SampleApp

At the VS Command Prompt

  C:/FW/edk2-ws/edk2> Build
  C:/FW/edk2-ws/edk2> RunEmulator.bat

Run the application from the shell

 Shell> SampleApp

Exit

 Shell> Reset

Note:

End of Lab 5

Slide 53 @title[Bonus Lab :Open Protocol example]

Bonus Exercise: Open Protocol Example

Write an Application using argv, argc parameters

  • Captures command line parameters using Open Protocol
  • Need to open SHELL_INTERFACE_PROTOCOL
  • Note: Requires ShellPkg

Build SampleApp

$> Build 
$> RunEmulator.bat

Run the application form the shell

Shell> SampleApp  test1 test2

(hint: ~FW/LabSampleCode/ShellAppSample has the solution)

Note:

Slide 54 @title[Write a EADK Application Section]


Using EADK with UEFI Application

Labs 6-7 are Optional

Slide 55 @title[Lab 6: Writing UEFI Applications with EADK]

Optional

Lab 6: Writing UEFI Applications with EADK

In this lab, you’ll write an application with the same functionality as SampleApp.c using LibC from the EDK II Application Development Kit (EADK)

Note:

Slide 56 @title[Lab 6: With EDK II EADK]

Optional

Lab 6: With EDK II EADK


Write the same application with the same functionality as SampleApp.c using the LibC from the EADK

  • What libraries are needed
  • What differences are there using the LibC

Slide 57 @title[Lab 6: EDK II using EADK]

Optional

Lab 6: EDK II using EADK


Start with the packages for EADK

  • /edk2-libc - AppPkg - has directory Applications
  • /edk2-libc - StdLib - contains the LibC libraries

Copy and paste directory

..\FW\LabSampleCode\SampleCApp to 
       C:\FW\edk2-ws\edk2-libc\AppPkg\Applications\SampleCApp

Slide 58 @title[Lab 6: EDK II using EADK 02]

Optional

Lab 6: EDK II using EADK


  • EDK II using EADK
  • Check out AppPkg/Applications/SampleCApp

SampleCApp.c and SampleCApp.inf

“C” file

#include <stdio.h>
   // . . .
int
main (
   IN int Argc,
   IN char **Argv
 )
 {
      return 0;
 }

.inf file

[Defines]
  INF_VERSION    = 1.25
  BASE_NAME      = SampleCApp
  FILE_GUID      = 54321…
  MODULE_TYPE    = UEFI_APPLICATION
  VERSION_STRING = 0.1
  ENTRY_POINT    = ShellCEntryLib

[Sources]
  SampleCApp.c

[Packages]
  StdLib/StdLib.dec
  MdePkg/MdePkg.dec
  ShellPkg/ShellPkg.dec

[LibraryClasses]
  LibC
  LibStdio

Slide 59 @title[Lab 6 : Update AppPkg.dsc ]

Optional

Lab 6 : Update AppPkg.dsc

Edit the AppPkg/AppPkg.dsc and add SampleCApp.inf at the end of the components section

  • (hint: search for "#### Sample Applications")
  • AppPkg/Applications/SampleCApp/SampleCApp.inf

[Components]

  #### Sample Applications.
  AppPkg/Applications/Hello/Hello.inf        # No LibC includes or functions.
  AppPkg/Applications/Main/Main.inf          # Simple invocation. No other LibC functions.
  AppPkg/Applications/Enquire/Enquire.inf    #
  AppPkg/Applications/ArithChk/ArithChk.inf  #
  
  AppPkg/Applications/SampleCApp/SampleCApp.inf #  LAB 6

Slide 60 @title[Lab 6 :Build and Test SampleCApp ]

Optional

Lab 6 :Build and Test SampleCApp

Build AppPkg at the VS Command prompt

  C:/FW/edk2-ws/edk2> build -p AppPkg/AppPkg.dsc –m AppPkg/Applications/SampleCApp/SampleCApp.inf -a X64

Copy the built application to the Emulator runtime directory (note VS Tool)

  C:/FW/edk2-ws/edk2>copy  ..\Build\AppPkg\DEBUG_VS2015x86\X64\SampleCApp.efi  ..\Build\EmulatorX64\DEBUG_VS2015x86\X64

Run the Emulation

  C:/FW/edk2-ws/edk2> RunEmulator.bat

Run the application SampleCapp from the shell

 Shell> SampleCApp
 Shell>

Notice that the program will immediately unload because the main function is empty

Slide 61 @title[Lab 7: Adding Functionality to SampleCApp]

Optional

Lab 7: Adding Functionality to SampleCApp


In this lab, you’ll add functionality to SampleCApp the same as in Lab 5. This lab will use EADK libraries so the coding style is similar to standard C.

Slide 62 @title[Lab 7: With EDK II EADK]

Optional

Lab 7: Add the same functionally from Lab 5


See slide 66 for solution

Slide 63 @title[Lab 7: With EDK II EADK]

Lab 7: Add the same functionally from Lab 5


See slide 66 for solution

Slide 64 @title[Lab 7: With EDK II EADK]

Lab 7: Add the same functionally from Lab 5


See slide 66 for solution

Slide 65 @title[Lab 7: With EDK II EADK]

Lab 7: Add the same functionally from Lab 5


See slide 66 for solution

Slide 66 @title[Lab 7: With EDK II EADK solution]

Optional

Lab 7: Solution

SampleCApp.c and SampleCApp.inf

“C” file

#include <stdio.h>
#include <Library/UefiBootServicesTableLib.h>
int
main (
  IN int Argc,
  IN char **Argv
  )
{
   char c;
// Lab 3
   printf("System Table: %p \n", gST) ; 
// Lab 4
   puts("Press any Key and then <Enter> to continue :  ");
   c=(char)getchar();
 
// Lab 5
   puts ("Enter text. Include a dot ('.') in a sentence then <Enter> to exit:");
   do {
      c=(char)getchar();
     } while (c != '.');
   puts ("\n");
   return 0;
}

.inf file

[Defines]
  INF_VERSION    = 1.25
  BASE_NAME      = SampleCApp
  FILE_GUID      = 54321…
  MODULE_TYPE    = UEFI_APPLICATION
  VERSION_STRING = 0.1
  ENTRY_POINT    = ShellCEntryLib

[Sources]
  SampleCApp.c

[Packages]
  StdLib/StdLib.dec
  MdePkg/MdePkg.dec
  ShellPkg/ShellPkg.dec

[LibraryClasses]
  LibC
  LibStdio
  UefiBootServicesTableLib

Note:

Notice that in the C file the loop is now only one line of code using the POSIX C getcahr() function.

After compile notice the size of the final .EFI file is about 2K larger than the native UEFI application.

Slide 67 @title[Lab 7 :Build and Test SampleCApp ]

Optional

Lab 7 :Build and Test SampleCApp

Build AppPkg at the VS Command prompt

  C:/FW/edk2-ws/edk2> build -p AppPkg\AppPkg.dsc –m AppPkg\Applications\SampleCApp\SampleCApp.inf -a X64

Copy the built application to the Emulator runtime directory (note VS Tool)

  C:/FW/edk2-ws/edk2>copy  ..\Build\AppPkg\DEBUG_VS2015x86\X64\SampleCApp.efi  ..\Build\EmulatorX64\DEBUG_VS2015x86\X64

Run the Emulation

  C:/FW/edk2-ws/edk2> RunEmulator.bat

Run the application SampleCapp from the shell

 Shell> SampleCApp
 Press any Key and then <Enter> to Continue :

 Enter text. Include a dot (‘.’) in a sentence then <Enter> to exit:
 Some text here, then a DOT. 
 Shell>

Slide 68 @title[Summary]


Summary

  • UEFI Application with PCDs
  • Simple UEFI Application
  • Add functionality to UEFI Application
  • Using EADK with UEFI Application

SLide 69 @title[Questions]


Slide 70

Return to Training Table of contents for next presentation link: https://github.com/tianocore-training/Tianocore_Training_Contents/wiki

Slide 71 @title[Logo Slide]




SLide 72 @title[Acknowledgements]

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.
**/