---?image=assets/images/gitpitch-audience.jpg @title[EDK II Modules]

UEFI & EDK II Training

EDK II Modules: Libs, Drivers & Apps

tianocore.org Note: PITCHME.md for UEFI / EDK II Training EDK II Modules: Libs, Drivers & Apps Pres

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.

@title[Lesson Objective]

<p align="center"Lesson Objective

@fa[certificate gp-bullet-green]  What is a EDK II Module
@fa[certificate gp-bullet-cyan]  Use EDK II libraries to write UEFI apps/drivers
@fa[certificate gp-bullet-yellow]  How to Define a UEFI application
@fa[certificate gp-bullet-magenta]  Differences between UEFI App / Drivers INF file

---?image=assets/images/binary-strings-black2.jpg @title[Modules Overview Section]

EDK II Modules Overview

What are EDK II Modules

---?image=/assets/images/slides/Slide4.JPG @title[Modules]

Modules

@css[text-white fragment]( Smallest separate object compiled in EDK II)

@css[text-yellow fragment](@color[yellow](Compiles to)
@color[yellow](.EFI File))

@snap[east span-35] @css[ text-white fragment](UEFI/DXE Driver
@coloryellow
@color[orange](UEFI App.) or
@color#00ffff ) @snapend

@snap[south span-90 fragment] @box[bg-purple-pp-trans text-white rounded](Modules: Building Blocks of EDK II) @snapend

Note:

So the first thing we have in trying to break EDK II down is Modules:

A module is the smallest separate object compiled in the EDK II. A module is a single resultant .EFI file.
Module examples:
A UEFI/DXE driver
A PEIM
A UEFI application
A Library
All of these could be a module. A modules could be one entity

@title[Module Types]

Module Types

@snap[north span-60 fragment]

@box[bg-purple-pp text-white ](Most Used Module Types) @snapend

@snap[north-west span-100 fragment]

@color[#00b0f0](PEI_CORE)                  @color[yellow](UEFI_APPLICATION)                @color[orange](DXE_CORE)

@color[orange](BASE)                             @color[#00b0f0](DXE_RUNTIME_DRIVER)

@color[#87E2A9](PEIM)                             @color[yellow](UEFI_DRIVER)                         @color[#87E2A9](DXE_DRIVER)

@snapend

@snap[south span-100 fragment]

syntax:
<ModuleTypes> ::= <ModuleType> [<Space> <ModuleType>]

@snapend

@snap[north-west span-90 fragment]

@color[red](⤑)

@snapend

Note:

BASE
SEC
PEI_CORE
PEIM
DXE_CORE
DXE_DRIVER
DXE_RUNTIME_DRIVER
DXE_SAL_DRIVER
DXE_SMM_DRIVER
UEFI_DRIVER
UEFI_APPLICATION
BASE LIBRARY
SECURITY_CORE
PEI_CORE
COMBINED_PEIM_DRIVER
PIC_PEIM
RELOCATABLE_PEIM
BS_DRIVER
RT_DRIVER
SAL_RT_DRIVER
APPLICATION

There are many Module types. This also determines how the module code is compiled and how libraries are associated with each module.

the syntax is: as shown on the slide

First we will show the UEFI_APPLICATION type of module since it is the simplest and can be somewhat independent from the underlining hardware.

@title[Module Source - minimum files]

Module Source Contents - minimum files

MODULE_TYPE	Example Source files
UEFI_APPLICATION	@color[yellow](Foo.c, Foo.inf )
UEFI_DRIVER	@color[yellow](FooDriver.c, FooDriver.h, FooDriver.vfr, FooDriver.uni, FooDriver.inf )
DXE_DRIVER	@color[yellow](FooDxe.c, FooDxe.h, FooDxe.inf)
DXE, UEFI or PEIM Library	@color[yellow](FooLib.c, FooLib.h, FooLib.inf ) ( w/ LIBRARY_CLASS= )

@snap[south-west span-100] @box[bg-brick-trans text-white rounded fragment ](Complexity - Greater number of source files) @box[bg-lt-orange-trans text-white rounded fragment ](.INF file - One file is required per module) @box[bg-gold2-trans text-white rounded fragment ](.EFI file - Sources compiled to a single .EFI file) @snapend

Note:

Example of the naming and number of files associated with the modules types

the number of files is based on the Complexity of the UEFI / DXE driver and or UEFI application
There is a requirement that a module must have at least 1 .INF file
The resulting compilation will be a .EFI file

---?image=assets/images/binary-strings-black2.jpg @title[EDK II Library Modules Section]

EDK II Library Modules

@title[Library Class ]

Library Class

Syntax: ``` [LibraryClasses.common] |

DebugLib|MdePkg/Library/BaseDebugLibNull/BaseDebugLibNull.inf


@snap[west span-20]
@box[bg-royal text-white rounded fragment ](<span style="font-size:01.20em" ><b>Name</b></span>)
@snapend

@snap[west span-25 fragment]
<p align="right"><span style="font-size:02.50em" >@color[yellow](<b>&vert;</b>)</span></p>
@snapend

@snap[midpoint span-40 fragment]
@box[bg-purple-pp text-white rounded  ](<span style="font-size:01.20em" ><b>Implementation<sup>1</sup></b></span>)
@snapend

@snap[midpoint span-40 fragment]
@box[bg-green2 text-white rounded  ](<span style="font-size:01.20em" ><b>Implementation<sup>2</sup></b></span>)
@snapend

@snap[midpoint span-40 fragment]
@box[bg-brick text-white rounded  ](<span style="font-size:01.20em" ><b>Implementation<sup>3</sup></b></span>)
@snapend


@snap[south span-80 ]
@box[bg-green text-white rounded fragment ](<span style="font-size:01.20em" ><b>Consistent set of interfaces</b></span>)
<br>
<br>
<br>
@snapend

@snap[south span-100 ]
@box[bg-purple-pp text-white rounded fragment ](<span style="font-size:01.20em" ><b>Does not describe implementation of the interfaces</b></span>)
@snapend



Note:

#### Syntax for the .dsc file when mapping Libraries to modules

- [LibraryClasses.common]
-   <LibraryClassName>|<LibraryInstancePathToInf/Name.inf>
-   DebugLib|MdePkg/Library/BaseDebugLibNull/BaseDebugLibNull.inf

It has a library class name, a pipe symbol and then a library instance, which is identified by the path to the INF, then the INF itself. 

So for example, the “DebugLib”, class is identified by the MdePkg/Library/BaseDebugLibNull/BaseDebugLibNull.inf
The library instance, BaseDebugLibNull, has all the required interfaces for debug Lib.  And that’s the one that will be linked against the modules in this example.


- Consistent set of interfaces 
#### First, a basic library class definition: <br>
A library class is a set of interfaces; it does not have any implementation information

It is identified by one GUID. And usually contains
- some macros, 
- sometimes global variables, 
- some functions uniquely

 Each library class has one GUID, and there is a mapping of a library class to library instance. 
For example there may be three library instances for a given function and one library class that they would all represent. In this example, the DSC file is going to map library class to a library instance.


- Does not describe implementation of the interfaces
- The implementation is decided at the platform level
- DSC file maps class to instance

- library class

- At the top of the slide there is an example of [libraryclasses.common] for a DSC file.


---
@title[NULL Library Class]
<p align="right"><span class="gold" ><b>"NULL" Library Class</b></span></p>
<br>
<br>
<br>
<br>
<span style="font-size:0.85em">@color[yellow](<b>Syntax:</b>)</span>
```xml
    Pkg/MyModule/MyModule.inf {
    	 <LibraryClasses>
      	NULL|Pkg/Library/LibName/LibName.inf
      	NULL|Pkg/Library/LibName2/LibName2.inf
  	}

@color[yellow](UEFI Shell example:)

    ShellPkg/Application/Shell/Shell.inf {
     <LibraryClasses>
       NULL|ShellPkg/Library/UefiShellDriver1CommandsLib/UefiShellDriver1CommandsLib.inf
       NULL|ShellPkg/Library/UefiShellNetwork1CommandsLib/UefiShellNetwork1CommandsLib.inf
	  . . .
    }

@snap[north-west span-40]

@box[bg-royal text-white rounded fragment ](Constructors) @snapend

@snap[north-east span-40]

@box[bg-lt-orange text-white rounded fragment ](Special Cases) @snapend

@snap[north span-65]

@box[bg-navy text-white rounded fragment ](NOT "...LibNull" instance) @snapend

@snap[south-east span-40] @box[bg-purple-pp text-white rounded my-box-pad fragment ](

Open Source Example
DxeCrc32GuidedSectionExtractLib
ShellPkg as used with Profiles

)
@snapend

Note:

Not a named library
Not related to LibNull instances (DebugLibNull)
May not produce any interfaces
Does all work in constructors
Can be linked more than once
Used for special cases
DXE Core and DXE IPL section file interpreters
ShellPkg uses the NULL named library with its profiles, thus when compiling a version of the UEFI Shell application, all that is needed is to include the interface as shown in the example on this slide.

@title[Locating library classes]

Locating Library Classes

@snap[north-west span-100]

@box[bg-royal text-white rounded my-box-pad fragment](

                       Library based upon
       1. Industry specifications (UEFI, PCI, USB, etc.)
             @color[yellow](MdePkg/MdeModulePkg)
       2. Intel’s framework¹ specs
             @color[yellow](IntelFrameworkPkg/IntelFrameworkModulePkg)

) @box[bg-brick text-white rounded my-box-pad fragment](Use the package help files (.CHM) to find a library or function
Example: MdePkg.chm)
@box[bg-green text-white rounded fragment]( Search WorkSpace (.INF) "LIBRARY_CLASS" ) @snapend

@snap[south-west span-50] ¹Intel^® Platform Innovation Framework for UEFI @snapend

Note:

How do you find library classes?
The simple answer is ”you have to know what the library class is based on.”

For example, if it is based on industry standards like the UEFI, PI, SMBIOS, ACPI, etc…you are probably going to find it in the MDE package or maybe in the MDE module package.

---?image=/assets/images/slides/Slide11_1.JPG @title[Library Instance Hierarch]

Library Instance Hierarchy

@snap[north-west span-30]

@color[yellow](Form)
a hierarchy similar to UEFI drivers

@snapend

@snap[north-east span-30]

@color[yellow](Link)
your module to another

@snapend

@snap[north span-100]

@css[text-white fragment](

DebugLib

) @css[text-white fragment](

DebugLibSerialPort
(Instance)

) @css[text-white fragment](

SerialPort (Class)

) @css[text-white fragment](

MdePkg (Specs)

) @css[text-white fragment](

@color[red](Build error):Instance of Library class [Foo...Lib] is not found...
Consumed by module [My Module.inf]

)

@snapend

Note:

when the error Build : error 4000 : Instance of Library class [Foo…Lib] is not found in [WorkSpace/some module Lib.inf] consumed by module [WorkSpace/My Module.inf]
Library Instances (NOT Library Classes) form a hierarchy similar to UEFI drivers Some Library Instances will link your module to another Library DebugLib (Class)
DebugLibSerialPort (Instance)
SerialPort (Class)
Etc…

The build process handles this, as long as a Library Instance is listed somewhere in the module hierarchy in the .DSC file

Library instances, not library classes, form a hierarchy very similar to the way drivers work. One library instance you link to may link another library class without your awareness:

For example, If you linked the debug Lib and then someone doing the platform decides that they will use the debug Lib serial port for your debug Lib class, That debug serial port instance links against the serial Port library class which now links its own library instance.

Now the build will handle this all in the background. When it looks in your INF file it is going to see debug Lib, and when you look at the debug serial port it’s going to see serial port.

As long as there is at least one of each library instance in the workspace and in DSC file, it will be built behind the scenes. You won’t even realize that there is more than one dependency under your module, and behind the scenes is doing this for everything. Another NOTE: Most libraries are dependent on another library the same way that .c and .h files are dependent upon some other .c and .h files..

@title[Commonly Used Base Library Classes]

Commonly Used Base Library Classes

@snap[north-west span-100 fragment]

BaseLib DebugLib
UefiLib
UefiApplicationEntryPoint

@snapend

@snap[north-east span-100 fragment]

@color[yellow](UefiDriverEntryPoint)
UefiBootServicesTableLib
@color[yellow](DxeCoreEntryPoint)
DevicePathLib  IoLib
  PrintLib  @color[yellow](PeimEntryPoint)
UefiScsiLib @color[#87E2A9](BaseMemoryLib)

@snapend

@snap[north-west span-100 fragment]

CpuLib UefiUsbLib PciLib
@color[#87E2A9](MemoryAllocationLib)
@color[yellow](PeiCoreEntryPoint)
UefiRuntimeLib @color[#87E2A9](SmmMemLib)

@snapend

@snap[north-west span-100 fragment]

@color[#00b0f0](DxeSerivesLib)   @color[yellow](SynchronizationLib) PciExpressLib
DxePcdLib      @color[#00b0f0](UefiRuntimeServicesTableLib)
PciSegmentLibLib @color[yellow](PeiServicesLib)
PeiPcdLib  DxeHobLib   @color[#87E2A9](UefiFileHandleLib)

@snapend

@snap[south span-90] @box[bg-purple-pp text-white rounded my-box-pad fragment ](

@coloryellow Many Libraries in the EDK II code

) @snapend

Note: Key point is that this soon becomes an Eye chart of many - MANY Many Libraries in the EDK II code

---?image=/assets/images/slides/Slide48.JPG @title[MdePkg Library Doc. Location ]

MdePkg Library .CHM file Location

tianocore.org UDK2018 Documentation on

@fa[github gp-bullet-gold] Latest UDK Release

@fa[github gp-bullet-gold] UDK2018

---?image=/assets/images/slides/Slide51.JPG

@title[Library Navigation Demonstration]

Library Navigation Demonstration

Note:

Install a CHM Viewer for Ubuntu

bash$ sudo aptitude install kchmviewer

chm file unlock – right click –properties –check unblock

+++?image=/assets/images/slides/Slide42.JPG

@title[Library Navigation Demonstration video]

Library Navigation Demonstration

![video](https://www.youtube.com/embed/s8Zw1w1iQS4) Note:

Install a CHM Viewer for Ubuntu

bash$ sudo aptitude install kchmviewer

chm file unlock – right click –properties –check unblock

---?image=assets/images/binary-strings-black2.jpg @title[EDK II UEFI Applications Section]

EDK II UEFI Applications

---?image=/assets/images/slides/Slide54.JPG @title[Defining a UEFI Application]

Defining a UEFI Application

Characteristics of a UEFI Loadable Image

@ul[no-bullet] - @fa[certificate gp-bullet-white] Loaded by UEFI loader, just like drivers - @fa[certificate gp-bullet-white] Does not register protocols - @fa[certificate gp-bullet-white] Consumes protocols - @fa[certificate gp-bullet-white] Typically exits when completed (user driven ) - @fa[certificate gp-bullet-white] Same set of interfaces as drivers available @ulend

Note: @fa[certificate gp-bullet-green] What is a EDK II Module

UEFI Applications are just like UEFI drivers, they are loadable images.

Their difference lies in that they typically do not register protocols like a driver does. They typically consume protocols to do a user driven task.

The same set of UEFI or firmware interfaces are available to applications that drivers have. Thus they are useful for driver prototyping since they can be quickly loaded from the UEFI shell to test the usage of an interface and help you in driver development.

What do UEFI Applications do?
Extend firmware abstractly
Without hardware or OS dependence
Portable across platforms
IA32, IA64, Intel-64, XScale, Apple*, NT32 emulator, OVMF emulator
Enable rapid application development

---?image=/assets/images/slides/Slide56_1.JPG @title[Defining a UEFI Application -Usages]

Defining a UEFI Application

UEFI Loadable Image Usages

@ul[no-bullet] - @fa[certificate gp-bullet-white] Diagnostics: Platform / Factory - @fa[certificate gp-bullet-white] Utilities - @fa[certificate gp-bullet-white] Driver Prototyping - @fa[certificate gp-bullet-white] “Platform” Applications - @fa[certificate gp-bullet-white] Portable Across Platforms (IA32, X64, ARM, Itanium, etc.) @ulend

Note: Their usages include factory testing, platform diagnostics (no OS required), and other various pre-boot applications you can think of where the need to do some operation without an OS would be useful.

---?image=/assets/images/slides/Slide58.JPG

@title[Executing Applications]

Executing Applications

Note:

What are the Application Execution steps?

Applications written to the UEFI specification are loaded by the Boot Manager or by other UEFI applications. For Example, the shell is an application .

To load an application the firmware allocates enough memory to hold the image, copies the sections within the application to the allocated memory, and applies the relocation fix-ups needed. Once this is done, the allocated memory is set to be the proper type for code and data for the image. Control is then transferred to the application’s entry point. When the application returns from its entry point, or when it calls the Boot Service Exit(), the application is unloaded from memory and control is returned to the UEFI component that loaded the application.

+++?image=/assets/images/slides/Slide59.JPG

@title[Executing Applications 02]

Executing Applications

Note:

What are the Application Execution steps?

Applications written to the UEFI specification are loaded by the Boot Manager or by other UEFI applications. For Example, the shell is an application .

To load an application the firmware allocates enough memory to hold the image, copies the sections within the application to the allocated memory, and applies the relocation fix-ups needed. Once this is done, the allocated memory is set to be the proper type for code and data for the image. Control is then transferred to the application’s entry point. When the application returns from its entry point, or when it calls the Boot Service Exit(), the application is unloaded from memory and control is returned to the UEFI component that loaded the application.

+++?image=/assets/images/slides/Slide60.JPG

@title[Executing Applications 03]

Executing Applications

Note:

What are the Application Execution steps?

Applications written to the UEFI specification are loaded by the Boot Manager or by other UEFI applications. For Example, the shell is an application .

To load an application the firmware allocates enough memory to hold the image, copies the sections within the application to the allocated memory, and applies the relocation fix-ups needed. Once this is done, the allocated memory is set to be the proper type for code and data for the image. Control is then transferred to the application’s entry point. When the application returns from its entry point, or when it calls the Boot Service Exit(), the application is unloaded from memory and control is returned to the UEFI component that loaded the application.

+++?image=/assets/images/slides/Slide61.JPG

@title[Executing Applications 04]

Executing Applications

Note:

What are the Application Execution steps?

Applications written to the UEFI specification are loaded by the Boot Manager or by other UEFI applications. For Example, the shell is an application .

To load an application the firmware allocates enough memory to hold the image, copies the sections within the application to the allocated memory, and applies the relocation fix-ups needed. Once this is done, the allocated memory is set to be the proper type for code and data for the image. Control is then transferred to the application’s entry point. When the application returns from its entry point, or when it calls the Boot Service Exit(), the application is unloaded from memory and control is returned to the UEFI component that loaded the application.

+++?image=/assets/images/slides/Slide62.JPG

@title[Executing Applications 05]

Executing Applications

Note:

What are the Application Execution steps?

Applications written to the UEFI specification are loaded by the Boot Manager or by other UEFI applications. For Example, the shell is an application .

To load an application the firmware allocates enough memory to hold the image, copies the sections within the application to the allocated memory, and applies the relocation fix-ups needed. Once this is done, the allocated memory is set to be the proper type for code and data for the image. Control is then transferred to the application’s entry point. When the application returns from its entry point, or when it calls the Boot Service Exit(), the application is unloaded from memory and control is returned to the UEFI component that loaded the application.

---?image=/assets/images/slides/Slide65.JPG

@title[Executing OS Load App]

Executing Applications

Note: