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.
Contents1 The Basics of EDK II..........................................................................................11.1 Overview ..............................................................................................11.1.1 Module, Package and Platform.....................................................11.1.2 Module Customization ................................................................21.1.3 EDK II Development Lifecycle .....................................................21.1.4 Build Infrastructure ...................................................................41.2 Related References .................................................................................51.3 Terms...................................................................................................61.4 Target Audience .....................................................................................62 An EDK II Package ............................................................................................72.1 Introduction ..........................................................................................72.1.1 EDK II Packages .......................................................................72.1.2 The Package Directory ...............................................................72.1.3 Package Declaration File.............................................................82.1.4 Package DSC File ....................................................................102.2 Manage Package ..................................................................................112.2.1 Create Package .......................................................................112.2.2 Using a Package......................................................................122.2.3 Updating a Package .................................................................123 Module Development .......................................................................................163.1 What is an EDK II module? ....................................................................163.1.1 Module Type ...........................................................................173.2 Creating a Module ................................................................................183.2.1 Location.................................................................................183.2.2 Sample: Module Meta File - INF .................................................193.2.3 Adding a Package Dependency ..................................................213.2.4 Adding Source Files .................................................................213.2.5 Add Library Class References ....................................................223.2.6 Adding PCD References ............................................................233.2.7 Referencing a Protocol, PPI, or GUID ..........................................253.2.8 Adding a Dependency to a Module .............................................263.3 Additional Steps for Library Instances .....................................................263.3.1 Define Produced Library Class ...................................................263.3.2 Define a Library Constructor (Optional) ......................................273.3.3 Define a Library Destructor (Optional) ........................................273.4 Additional Steps for Driver.....................................................................283.4.1 Define a Driver Entry Point .......................................................283.5 EDK II Common Library Class ................................................................283.6 Module using HII ..................................................................................293.6.1 Forms....................................................................................293.6.2 Using Unicode Strings ..............................................................333.7 Building the module..............................................................................363.7.1 Add the module INF in package DSC ..........................................363.7.2 Select Library Instances ...........................................................37iv3.7.3 Configure PCDs .......................................................................393.7.4 Customize Build Options...........................................................423.7.5 Build module image .................................................................443.7.6 Build EFI Option Rom image .....................................................463.7.7 Common build module breaks ...................................................473.8 Debugging a Module .............................................................................483.8.1 Required steps for debugging a module ......................................483.8.2 Basic debugging methods .........................................................494 UEFI Applications ............................................................................................504.1 Begin with INF file ................................................................................504.2 Write UEFI Application Entry Point ..........................................................514.3 Get Service Tables................................................................................514.4 Communicating with a UEFI driver ..........................................................524.4.1 Protocol .................................................................................524.4.2 Variable .................................................................................525 UEFI Drivers ..................................................................................................535.1 Begin With INF File ...............................................................................535.2 Write the UEFI Driver entry point............................................................535.2.1 Example: APIs in UefiLib ..........................................................545.2.2 Example: Entry point to the Abc driver .......................................545.3 Get Service Tables................................................................................565.4 Communication between UEFI Drivers .....................................................575.4.1 Protocol .................................................................................575.4.2 Variable .................................................................................576 SEC Module....................................................................................................596.1 Beginning to Write the INF File ...............................................................596.2 Setup Pre-Memory Environment .............................................................596.3 Prepare for Data PEI Foundation .............................................................606.3.1 EFI_SEC_PEI_HAND_OFF * SecCoreData ....................................606.3.2 EFI_PEI_PPI_DESCRIPTOR *PpiList ............................................617 Pre-EFI Initialization Modules............................................................................637.1 Introduction ........................................................................................637.2 Beginning to Write a PEIM INF File ..........................................................637.3 Defining a PEIM’s entry point .................................................................637.4 Get Pei Services ...................................................................................647.5 Communicate between PEIM Modules ......................................................647.5.1 PPI........................................................................................647.5.2 HOB ......................................................................................657.5.3 PCD ......................................................................................667.6 Communicate with DXE Modules.............................................................667.6.1 HOB ......................................................................................667.6.2 Variable .................................................................................667.6.3 PCD ......................................................................................677.7 Boot Mode...........................................................................................677.8 Execution in Place PEIMs .......................................................................687.9 Dependency for PEIMs ..........................................................................688 DXE Drivers: non-UEFI drivers ..........................................................................70 v8.1 Beginning with INF File .........................................................................708.2 Write DXE Driver Entry Point..................................................................708.3 Obtaining Services Tables......................................................................718.4 Communication between DXE Drivers......................................................728.4.1 Protocol .................................................................................728.4.2 Variable .................................................................................748.4.3 Dynamic PCD..........................................................................758.5 Communication with PEIMs ....................................................................768.5.1 HOB ......................................................................................768.5.2 Variable .................................................................................788.5.3 Dynamic PCD..........................................................................788.6 Dependency Expressions .......................................................................788.7 Handler for EVT_SIGNAL_EXIT_BOOT_SERVICES ......................................798.8 DXE Runtime Driver..............................................................................808.8.1 INF File..................................................................................818.8.2 Handler for EVT_SIGNAL_VIRTUAL_ADDRESS_CHANGE ................818.9 DXE SAL Driver ....................................................................................828.9.1 INF File..................................................................................838.9.2 Entry Point .............................................................................838.10 DXE SMM Driver...................................................................................838.10.1 INF File..................................................................................848.10.2 Constraints.............................................................................84Appendix A Dynamic PCD ....................................................................................................87A.1.1 Class of Dynamic Type.....................................................................................87A.1.2 When and how to use dynamic PCD ...................................................................88TablesTable 1 EDK II Module Types ............................................................................17Table 2 Recommended name convention for module directory ...............................19Table 3 EDK II supported file extensions ............................................................22Table 4 INF PCD Section Name .........................................................................24Table 5 PCD access functions............................................................................25Table 6 Commonly use library classes ................................................................28Table 7 Module Entry Point and Service Table Libraries .........................................29Table 9 Protocols Used to Separate the Loading and Starting/Stopping of Drivers .....53Table 10. Table Global Variables .......................................................................57Table 11 Reference to Services Tables for DXE Drivers .........................................71FiguresFigure 1 Conceptual workflow .............................................................................5Figure 2 Firmware Volume................................................................................16Figure 3 Temporary Memory Layout...................................................................60