EDK_II Module Writer_s Guide_0_7

This document is a guideline for new EDK II module developers, and provides detailed
instructions on how to develop and build a new module, and how to release with a
package. For information about developing new modules, start with this document.

Contents
1 The Basics of EDK II..........................................................................................1
1.1 Overview ..............................................................................................1
1.1.1 Module, Package and Platform.....................................................1
1.1.2 Module Customization ................................................................2
1.1.3 EDK II Development Lifecycle .....................................................2
1.1.4 Build Infrastructure ...................................................................4
1.2 Related References .................................................................................5
1.3 Terms...................................................................................................6
1.4 Target Audience .....................................................................................6
2 An EDK II Package ............................................................................................7
2.1 Introduction ..........................................................................................7
2.1.1 EDK II Packages .......................................................................7
2.1.2 The Package Directory ...............................................................7
2.1.3 Package Declaration File.............................................................8
2.1.4 Package DSC File ....................................................................10
2.2 Manage Package ..................................................................................11
2.2.1 Create Package .......................................................................11
2.2.2 Using a Package......................................................................12
2.2.3 Updating a Package .................................................................12
3 Module Development .......................................................................................16
3.1 What is an EDK II module? ....................................................................16
3.1.1 Module Type ...........................................................................17
3.2 Creating a Module ................................................................................18
3.2.1 Location.................................................................................18
3.2.2 Sample: Module Meta File - INF .................................................19
3.2.3 Adding a Package Dependency ..................................................21
3.2.4 Adding Source Files .................................................................21
3.2.5 Add Library Class References ....................................................22
3.2.6 Adding PCD References ............................................................23
3.2.7 Referencing a Protocol, PPI, or GUID ..........................................25
3.2.8 Adding a Dependency to a Module .............................................26
3.3 Additional Steps for Library Instances .....................................................26
3.3.1 Define Produced Library Class ...................................................26
3.3.2 Define a Library Constructor (Optional) ......................................27
3.3.3 Define a Library Destructor (Optional) ........................................27
3.4 Additional Steps for Driver.....................................................................28
3.4.1 Define a Driver Entry Point .......................................................28
3.5 EDK II Common Library Class ................................................................28
3.6 Module using HII ..................................................................................29
3.6.1 Forms....................................................................................29
3.6.2 Using Unicode Strings ..............................................................33
3.7 Building the module..............................................................................36
3.7.1 Add the module INF in package DSC ..........................................36
3.7.2 Select Library Instances ...........................................................37
iv
3.7.3 Configure PCDs .......................................................................39
3.7.4 Customize Build Options...........................................................42
3.7.5 Build module image .................................................................44
3.7.6 Build EFI Option Rom image .....................................................46
3.7.7 Common build module breaks ...................................................47
3.8 Debugging a Module .............................................................................48
3.8.1 Required steps for debugging a module ......................................48
3.8.2 Basic debugging methods .........................................................49
4 UEFI Applications ............................................................................................50
4.1 Begin with INF file ................................................................................50
4.2 Write UEFI Application Entry Point ..........................................................51
4.3 Get Service Tables................................................................................51
4.4 Communicating with a UEFI driver ..........................................................52
4.4.1 Protocol .................................................................................52
4.4.2 Variable .................................................................................52
5 UEFI Drivers ..................................................................................................53
5.1 Begin With INF File ...............................................................................53
5.2 Write the UEFI Driver entry point............................................................53
5.2.1 Example: APIs in UefiLib ..........................................................54
5.2.2 Example: Entry point to the Abc driver .......................................54
5.3 Get Service Tables................................................................................56
5.4 Communication between UEFI Drivers .....................................................57
5.4.1 Protocol .................................................................................57
5.4.2 Variable .................................................................................57
6 SEC Module....................................................................................................59
6.1 Beginning to Write the INF File ...............................................................59
6.2 Setup Pre-Memory Environment .............................................................59
6.3 Prepare for Data PEI Foundation .............................................................60
6.3.1 EFI_SEC_PEI_HAND_OFF * SecCoreData ....................................60
6.3.2 EFI_PEI_PPI_DESCRIPTOR *PpiList ............................................61
7 Pre-EFI Initialization Modules............................................................................63
7.1 Introduction ........................................................................................63
7.2 Beginning to Write a PEIM INF File ..........................................................63
7.3 Defining a PEIM’s entry point .................................................................63
7.4 Get Pei Services ...................................................................................64
7.5 Communicate between PEIM Modules ......................................................64
7.5.1 PPI........................................................................................64
7.5.2 HOB ......................................................................................65
7.5.3 PCD ......................................................................................66
7.6 Communicate with DXE Modules.............................................................66
7.6.1 HOB ......................................................................................66
7.6.2 Variable .................................................................................66
7.6.3 PCD ......................................................................................67
7.7 Boot Mode...........................................................................................67
7.8 Execution in Place PEIMs .......................................................................68
7.9 Dependency for PEIMs ..........................................................................68
8 DXE Drivers: non-UEFI drivers ..........................................................................70
 v
8.1 Beginning with INF File .........................................................................70
8.2 Write DXE Driver Entry Point..................................................................70
8.3 Obtaining Services Tables......................................................................71
8.4 Communication between DXE Drivers......................................................72
8.4.1 Protocol .................................................................................72
8.4.2 Variable .................................................................................74
8.4.3 Dynamic PCD..........................................................................75
8.5 Communication with PEIMs ....................................................................76
8.5.1 HOB ......................................................................................76
8.5.2 Variable .................................................................................78
8.5.3 Dynamic PCD..........................................................................78
8.6 Dependency Expressions .......................................................................78
8.7 Handler for EVT_SIGNAL_EXIT_BOOT_SERVICES ......................................79
8.8 DXE Runtime Driver..............................................................................80
8.8.1 INF File..................................................................................81
8.8.2 Handler for EVT_SIGNAL_VIRTUAL_ADDRESS_CHANGE ................81
8.9 DXE SAL Driver ....................................................................................82
8.9.1 INF File..................................................................................83
8.9.2 Entry Point .............................................................................83
8.10 DXE SMM Driver...................................................................................83
8.10.1 INF File..................................................................................84
8.10.2 Constraints.............................................................................84
Appendix A Dynamic PCD ....................................................................................................87
A.1.1 Class of Dynamic Type.....................................................................................87
A.1.2 When and how to use dynamic PCD ...................................................................88
Tables
Table 1 EDK II Module Types ............................................................................17
Table 2 Recommended name convention for module directory ...............................19
Table 3 EDK II supported file extensions ............................................................22
Table 4 INF PCD Section Name .........................................................................24
Table 5 PCD access functions............................................................................25
Table 6 Commonly use library classes ................................................................28
Table 7 Module Entry Point and Service Table Libraries .........................................29
Table 9 Protocols Used to Separate the Loading and Starting/Stopping of Drivers .....53
Table 10. Table Global Variables .......................................................................57
Table 11 Reference to Services Tables for DXE Drivers .........................................71
Figures
Figure 1 Conceptual workflow .............................................................................5
Figure 2 Firmware Volume................................................................................16
Figure 3 Temporary Memory Layout...................................................................60