From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received-SPF: Pass (sender SPF authorized) identity=mailfrom; client-ip=192.55.52.115; helo=mga14.intel.com; envelope-from=bob.c.feng@intel.com; receiver=edk2-devel@lists.01.org Received: from mga14.intel.com (mga14.intel.com [192.55.52.115]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by ml01.01.org (Postfix) with ESMTPS id 6B1B2211D56C4 for ; Wed, 6 Mar 2019 00:54:31 -0800 (PST) X-Amp-Result: SKIPPED(no attachment in message) X-Amp-File-Uploaded: False Received: from orsmga004.jf.intel.com ([10.7.209.38]) by fmsmga103.fm.intel.com with ESMTP/TLS/DHE-RSA-AES256-GCM-SHA384; 06 Mar 2019 00:54:31 -0800 X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="5.58,447,1544515200"; d="scan'208";a="280167972" Received: from shwdepsi1121.ccr.corp.intel.com ([10.239.158.47]) by orsmga004.jf.intel.com with ESMTP; 06 Mar 2019 00:54:28 -0800 From: "Feng, Bob C" To: edk2-devel@lists.01.org Cc: Bob Feng , Liming Gao , Jaben Carsey Date: Wed, 6 Mar 2019 16:54:21 +0800 Message-Id: <20190306085421.24960-2-bob.c.feng@intel.com> X-Mailer: git-send-email 2.20.1.windows.1 In-Reply-To: <20190306085421.24960-1-bob.c.feng@intel.com> References: <20190306085421.24960-1-bob.c.feng@intel.com> MIME-Version: 1.0 Subject: [Patch V2 1/1] Document: Update Inf spec to remove EDK and IPF related contents X-BeenThere: edk2-devel@lists.01.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: EDK II Development List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Wed, 06 Mar 2019 08:54:31 -0000 Content-Transfer-Encoding: 8bit BZ: https://bugzilla.tianocore.org/show_bug.cgi?id=1453 Remove EDK and IPF related contents Contributed-under: TianoCore Contribution Agreement 1.1 Signed-off-by: Bob Feng Cc: Liming Gao Cc: Jaben Carsey --- 1_introduction/11_overview.md | 4 ++-- 2_inf_overview/210_[ppis]_section.md | 3 +-- 2_inf_overview/211_[guids]_section.md | 3 +-- 2_inf_overview/212_[libraryclasses]_section.md | 3 +-- 2_inf_overview/213_[packages]_section.md | 3 +-- 2_inf_overview/214_pcd_sections.md | 16 +++++----------- 2_inf_overview/215_[depex]_section.md | 6 +----- 2_inf_overview/21_processing_overview.md | 21 +++++---------------- 2_inf_overview/22_information_file_general_rules.md | 32 +++++++++++--------------------- 2_inf_overview/24_[defines]_section.md | 6 +++--- 2_inf_overview/25_[sources]_section.md | 6 +----- 2_inf_overview/26_[buildoptions]_section.md | 11 ++--------- 2_inf_overview/27_[binaries]_section.md | 7 +------ 2_inf_overview/29_[protocols]_section.md | 3 +-- 2_inf_overview/README.md | 13 +------------ 3_edk_ii_inf_file_format/314_[depex]_sections.md | 8 +++----- 3_edk_ii_inf_file_format/315_[binaries]_section.md | 7 +------ 3_edk_ii_inf_file_format/32_component_inf_definition.md | 6 +++--- 3_edk_ii_inf_file_format/34_[defines]_section.md | 8 ++------ 3_edk_ii_inf_file_format/35_[buildoptions]_sections.md | 7 +++---- 3_edk_ii_inf_file_format/39_[sources]_sections.md | 9 ++------- 3_edk_ii_inf_file_format/README.md | 6 +----- README.md | 3 ++- SUMMARY.md | 37 +++++++++++++++++-------------------- appendix_b_build_changes_and_customizations.md => appendix_a_build_changes_and_customizations.md | 10 +++++----- appendix_a_edk_inf_file_specification/README.md | 40 ---------------------------------------- appendix_a_edk_inf_file_specification/a1_design_discussion.md | 317 ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- appendix_a_edk_inf_file_specification/a2_edk_file_specification.md | 461 ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- appendix_c_symbols.md => appendix_b_symbols.md | 4 ++-- appendix_d_sample_driver_inf_files.md => appendix_c_sample_driver_inf_files.md | 8 ++++---- appendix_e_sample_library_inf_files.md => appendix_d_sample_library_inf_files.md | 10 +++++----- appendix_f_sample_binary_inf_files.md => appendix_e_sample_binary_inf_files.md | 8 ++++---- appendix_g_module_types.md => appendix_f_module_types.md | 4 ++-- 33 files changed, 93 insertions(+), 997 deletions(-) diff --git a/1_introduction/11_overview.md b/1_introduction/11_overview.md index 9239080..2dcf02f 100644 --- a/1_introduction/11_overview.md +++ b/1_introduction/11_overview.md @@ -1,9 +1,9 @@ ## 2.14 PCD Sections -These sections are used for specifying PCD information and are valid for EDK -II modules only. The entries for these sections are looked up from the package -declaration files (DEC) for generating the `AutoGen.c` and `AutoGen.h` files. +These sections are used for specifying PCD information. The entries for these +sections are looked up from the packagedeclaration files (DEC) for generating +the `AutoGen.c` and `AutoGen.h` files. The PCD's Name (`PcdName`) is defined as PCD Token Space GUID C name and the PCD C name - separated by a period "." character. Unique PCDs are identified using the following format to identify the named PCD: @@ -43,11 +43,11 @@ using the following format to identify the named PCD: PCDs listed in architectural sections must not be listed in common architectural sections. It is not possible for a PCD to be valid for only IA32 and also valid for any architecture. -A PCD may be valid for IA32 and X64 and invalid for EBC and IPF usage, so +A PCD may be valid for IA32 and X64 and invalid for EBC usage, so mixing of specific architectural modifiers is permitted. This section defines how a module has been coded to access a PCD. A PCD can only be accessed using the function defined by the UEFI specification for a single type, therefore, mixing PCD section types is not permitted. @@ -90,11 +90,10 @@ one of the following section definitions: ```ini [(PcdType)] [(PcdType).common] [(PcdType).IA32] [(PcdType).X64] -[(PcdType).IPF] [(PcdType).EBC] ``` The required entries for this section are the PCD Token Space Guid C Name's for the PCD that will be looked up by tools from the DEC files, and the PCD's C @@ -141,11 +140,10 @@ definitions: ```ini [FixedPcd] [FixedPcd.common] [FixedPcd.IA32] [FixedPcd.X64] -[FixedPcd.IPF] [FixedPcd.EBC] ``` The following is an example of the `PCD FIXED_AT_BUILD` type: @@ -167,11 +165,10 @@ character. This section uses one of the following section definitions: ```ini [PatchPcd] [PatchPcd.IA32] [PatchPcd.X64] -[PatchPcd.IPF] [PatchPcd.EBC] [PatchPcd.common] ``` The following is an example of the `PCD FIXED_AT_BUILD` type: @@ -193,11 +190,10 @@ binary only module. This section uses one of the following section definitions: ```ini [FeaturePcd] [FeaturePcd.common] [FeaturePcd.IA32] [FeaturePcd.X64] -[FeaturePcd.IPF] [FeaturePcd.EBC] ``` The following is an example of the PCD `FEATURE_FLAG` type: @@ -221,11 +217,10 @@ following section definitions: ```ini [Pcd] [Pcd.common] [Pcd.IA32] [Pcd.X64] -[Pcd.IPF] [Pcd.EBC] ``` The following is an example of the PCD `DYNAMIC` type: @@ -247,11 +242,10 @@ format. This section uses one of the following section definitions: ```ini [PcdEx] [PcdEx.common] [PcdEx.IA32] [PcdEx.X64] -[PcdEx.IPF] [PcdEx.EBC] ``` The following is an example of the PCD `DYNAMIC_EX` type: diff --git a/2_inf_overview/215_[depex]_section.md b/2_inf_overview/215_[depex]_section.md index 5c1f110..912228f 100644 --- a/2_inf_overview/215_[depex]_section.md +++ b/2_inf_overview/215_[depex]_section.md @@ -1,9 +1,9 @@ ## 2.15 [Depex] Section -The EDK II `[Depex]` section is a replacement for the `DPX_SOURCE` file using -in EDK (the file is specified in the nmake section of an EDK INF file.) - This section is used for specifying a `Depex` expression, not a binary file. In the "As Built" INF files, this section contains a comment that lists the full dependency expression, including `Depex` statements AND'd from library instances linked against a module. @@ -87,11 +84,10 @@ The Depex section headers start with one of the following: ```ini [Depex] [Depex.IA32] [Depex.X64] -[Depex.IPF] [Depex.EBC] [Depex.common] ``` When generating the "As Built" binary INF during a build, the complete diff --git a/2_inf_overview/21_processing_overview.md b/2_inf_overview/21_processing_overview.md index 440d5d9..7eb68eb 100644 --- a/2_inf_overview/21_processing_overview.md +++ b/2_inf_overview/21_processing_overview.md @@ -1,9 +1,9 @@ ## 2.2 Information File General Rules -This section covers the format for the EDK II module INF files. While the EDK -code base and tools treated libraries completely separate from modules, the EDK -II code base and tools process modules, with libraries being considered a +This section covers the format for the EDK II module INF files. The EDK +II code base and tools process modules, with libraries is considered a module that produces a library class. ### 2.2.1 Section Entries -To simplify parsing, the EDK II meta-data files continue using the INI format. -This style was introduced for EDK meta-data files, when only the Windows tool -chains were supported. It was decided that for compatibility purposes, that INI -format would continue to be used. EDK II formats differ from the defacto format -in that the semicolon ";" character cannot be used to indicate a comment. +The EDK II meta-data files use the INI format. The semicolon ";" character cannot +be used to indicate a comment in the EDK II format. Leading and trailing space/tab characters must be ignored. Duplicate section names must be merged by tools. @@ -52,11 +48,11 @@ This description file consists of sections delineated by section tags enclosed within square `[]` brackets. Section tag entries are case-insensitive. The different sections and their usage are described below. The text of a given section can be used for multiple section names by separating the section names with a comma. For example: -`[Sources.X64, Sources.IPF]` +`[Sources.X64, Sources.IA32]` The content below each section heading is processed by the parsing utilities in the order that they occur in the file. The precedence for processing these architecture section tags is from right to left, with sections defining an architecture having a higher precedence than a section which uses common (or no @@ -184,14 +180,13 @@ case sensitive because of multiple environment support. * All files (except those listed in the Packages sections) must reside in the directory containing the INF file or in sub-directories of the directory containing the INF file. * Additionally, all EDK II directories that are architecturally dependent must - use a name with only the first character capitalized. Ia32, Ipf, X64 and Ebc - are valid architectural directory names. IA32, IPF and EBC are not acceptable - directory names, and may cause build breaks. From a build tools perspective, - IA32 is not equivalent to Ia32 or ia32. + use a name with only the first character capitalized. Ia32 is valid architectural + directory names. IA32 is not acceptable directory names, and may cause build + breaks. From a build tools perspective, IA32 is not equivalent to Ia32 or ia32. * Absolute paths are not permitted in EDK II INF files. All paths specified are relative to an EDK II package directory (defined as a directory containing a DEC file) or relative to the directory containing the INF file. @@ -207,14 +202,14 @@ places that permit the use of space characters in a directory path. The EDK II Coding Style specification covers naming conventions for use within C Code files, and as well as specifying the rules for directory and file names. This section is meant to highlight those rules as they apply to the content of the INF files. -Architecture keywords (`IA32`, `IPF`, `X64` and `EBC`) are used by build tools +Architecture keywords (`IA32`, `X64`, and `EBC`) are used by build tools and in metadata files for describing alternate threads for processing of files. These keywords must not be used for describing directory paths. Additionally, -directory names with architectural names (Ia32, Ipf, X64 and Ebc) do not +directory names with architectural names (Ia32, X64 and Ebc) do not automatically cause the build tools or meta-data files to follow these alternate paths. Directories and Architectural Keywords are similar in name only. All directory paths within EDK II INF files must use the forward slash "/" @@ -313,15 +308,10 @@ evaluated, during the parsing of the file. [LibraryClasses.X64.PEIM] # Can use $(MDE) and $(PERF) DEFINE MDEMEM = $(MDE)/PeiMemoryAllocationLib MemoryAllocationLib|$(MDEMEM)/PeiMemoryAllocationLib.inf -[LibraryClasses.IPF] - # Cannot use $(PERF) or $(MDEMEM) - # Can use $(MDE) from the common section - PalLib|$(MDE)/UefiPalLib/UefiPalLib.inf - TimerLib|$(MDE)/BaseTimerLibNullTemplate/BaseTimerLibNullTemplate.inf ``` In the previous example, the directory and filename for a library instance is the recommended instance and may not be the actual library linked to the module, as the platform integrator may choose a different library instance to diff --git a/2_inf_overview/24_[defines]_section.md b/2_inf_overview/24_[defines]_section.md index 8e5706c..54fa829 100644 --- a/2_inf_overview/24_[defines]_section.md +++ b/2_inf_overview/24_[defines]_section.md @@ -1,9 +1,9 @@ -# Appendix B Build Changes and Customizations +# Appendix A Build Changes and Customizations -## B.1 Customizing EDK Compilation for a Component +## A.1 Customizing EDK Compilation for a Component There are several mechanisms for customizing the build for a firmware component. These include: * Creating a new component INF file that specifies `BUILD_TYPE=xxx`, and then @@ -53,22 +53,22 @@ component. These include: * Another option is to define a variable in the component INF file, passing it to the component makefile via the DSC `[makefile.common]` section, and then using `!IFDEF` statements in the `[build.$(PROCESSOR).$(COMPONENT_TYPE)]` section to perform custom steps. -## B.2 Changing Files in an EDK Library +## A.2 Changing Files in an EDK Library Library INF files are shared among different platforms. However, not all platforms require all the same source files. To customize the library INF files for different platforms, simply define `$(PLATFORM)`, either on the command line, or in the DSC file, and then make customizations in the `[sources.$(PROCESSOR).$(PLATFORM)]` section of the library INF file. An alternative to this method is to simply create a new INF file for the library, and then use it in place of the existing library INF file -## B.3 Customizing EDK II Compilation for a Module Common Definitions +## A.3 Customizing EDK II Compilation for a Module Common Definitions The preferred method for customizing a build is to copy the source module directory to a new directory and modifying the INF file and module sources. This method is preferred over the EDK methods as build reproducibility is more easily accomplished. diff --git a/appendix_a_edk_inf_file_specification/README.md b/appendix_a_edk_inf_file_specification/README.md deleted file mode 100644 index a0af502..0000000 --- a/appendix_a_edk_inf_file_specification/README.md +++ /dev/null @@ -1,40 +0,0 @@ - - -# Appendix A EDK INF File Specification - -This appendix covers the format of the original EDK INF files. However, the -format of comments in the EDK INF may vary from this specification, as the -original EDK parsing tool, ProcessDSC, only looked for a specific set of -tokens. Due the extensive use of MACRO statements in the EDK components and -libraries INF files, EDK INF files cannot be processed by tools to create a -distribution that complies with the UEFI Platform Initialization Distribution -Package Specification. diff --git a/appendix_a_edk_inf_file_specification/a1_design_discussion.md b/appendix_a_edk_inf_file_specification/a1_design_discussion.md deleted file mode 100644 index 6c64df3..0000000 --- a/appendix_a_edk_inf_file_specification/a1_design_discussion.md +++ /dev/null @@ -1,317 +0,0 @@ - - -## A.1 Design Discussion - -Directive statements are permitted within the EDK INF files. - -### A.1.1 [defines] Section - -The `[defines]` section of an EDK INF file is used to define variable -assignments that can be used in later build steps. The EDK parsing utilities -process local symbol assignments made in this section. Note that the sections -are processed in the order listed here, and later assignments of these local -symbols do not override previous assignments. - -This section will typically use one of the following section definitions: - -```ini -[define] -[defines] -[defines.IA32] -[defines.X64] -[defines.IPF] -[defines.EBC] -``` - -********** -**Note:** The `[define]` section tag is only valid for EDK INF files. EDK II INF -files must use the 'defines' keyword. -********** - -The format for entries in this section is: - -`Name = Value` - -The following is an example of this section. - -```ini -[defines] - BASE_NAME = DiskIo - FILE_GUID = CA261A26-7718-4b9b-8A07-5178B1AE3A02 - COMPONENT_TYPE = BS_DRIVER -``` - -The following table lists the possible content of this section. - -###### Table 6 EDK [defines] Section Elements - -| Tag | Required | Value | Notes | -| --------------------------- | ------------------------------------------------------------------ | --------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `BASE_NAME` | Yes | A single word | This is a single word identifier that will be used for the component name. | -| `COMPONENT_TYPE` | Yes | One of the EDK I Component Types | See Table EDK I Component (module) Types for possible values | -| `FILE_GUID` | No--Optional for Libraries, Required for all other component types | Guid Value | Registry (8-4-4-4-12) Format GUID | -| `EDK_RELEASE_VERSION` | No--Optional | Hex Value | A Hex version number, 0x00020000 | -| `EFI_SPECIFICATION_VERSION` | No--Optional | HexValue | A Hex version number, 0x00020000 | -| `MAKEFILE_NAME` | No--Optional | Filename.ext | The name of the Makefile to be generated for this component | -| `CUSTOM_MAKEFILE` | No--Optional | Filename.ext | This specifies the name of a custom makefile that should be used, instead of a generated makefile. **NOTE**: EDK INF components specifying a custom EDK style makefile cannot be used in an EDK II build. | -| `BUILD_NUMBER` | No--Optional | Set this four digit value in the generated Makefile | Normally not used in INF files. | -| `C_FLAGS` | No--Optional | Microsoft C Flags to use with for a cl commands for this module | Normally not used in INF files. Typically, an EDK INF file will provide a separate nmake section to specify different build parameters. | -| `FFS_EXT` | No--Optional | File Extension | The FFS extension to use for this component, refer to the table _EDK I Component (module) Types for the default FFS extension. This value is used to create a component PKG file. | -| `FV_EXT` | No--Optional | File Extension | The FV extension to use for this component, refer to the table _EDK I Component (module) Types for the default FV extension. | -| `SOURCE_FV` | No--Optional | Word | If present, the variable is set at the beginning of the generated makefile | -| `VERSION` | No--Optional | Four digit integer | If present, this value will be used for the VERSION section of the FFS. | -| `VERSION_STRING` | No--Optional | String | If present, this value will be used to generate the UNICODE file for the VERSION section of the FFS. | - -The following table lists the available `COMPONENT_TYPE` values supported by -EDK INF files. - -###### Table 7 EDK Component (module) Output File Extensions - -| COMPONENT_TYPE | EDK II Extension | EDK File, FFS or FV Extension | Description | -| ----------------------- | ---------------------- | ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `LIBRARY` | .lib | .lib | Library component linked as part of the build with other components. | -| `FILE` | From file name or .FFS | From file name or .FFS | Raw file copied directly to FV | -| `Apriori` | .bin | .SEC | This EDK INF component is not supported in the EDK II build - it is created from content in other EDK II build meta-data files. | -| `EFI Binary Executable` | .efi | .pe32 | PE32/PE32+/Coff binary executable. The extension of the file has changed for EDK II builds which generate processed (GenFw) images. | -| `AcpiTable` | .acpi | .SEC | An ACPI Table. | -| `Legacy16` | .bin | .SEC | The MODULE_TYPE for a Legacy16 when migrating to EDK II should be specified as USER_DEFIND. The .rom or .bin file should be included under a [binaries] section. In EDK, the COMPONENT_TYPE of Legacy16 was mostly used to specify PCI Option ROMs. | -| `BINARY` | .bin | .FFS | | -| `CONFIG` | .bin | .SEC | | -| `LOGO` | .bin | .SEC | The MODULE_TYPE for a LOGO when migrating to EDK II should be specified as USER_DEFINED. The .bmp file should be include under a [binaries] section. In EDK, the COMPONENT_TYPE of LOGO was used to specify a .bmp file. | -| `RAWFILE` | .raw | .RAW | | -| `FVIMAGEFILE` | .fv | .FVI | | -| `SECURITY_CORE` | .efi | .SEC | Modules of this type are designed to start execution at the reset vector of a CPU. They are responsible for preparing the platform for the PEI Phase. Since there are no standard services defined for SEC, modules of this type follow the same rules as modules of type Base and typically include some amount of CPU specific assembly code to establish temporary memory for a stack. Modules of this type may optionally produce services that are passed to the PEI Phase in HOBs and those services must be compliant with the PEI CIS. | -| `PEI_CORE` | .efi | .PEI | This module type is used by PEI Core implementations that are complaint with the PEI CIS. | -| `COMBINED_PEIM_DRIVER` | .efi | .PEI | | -| `PIC_PEIM` | .efi | .PEI | | -| `RELOCATABLE_PEIM` | .efi | .PEI | When migrating to EDK II, this type of module should use the register for shadow PPI, and set the [defines] entry: `SHADOW = TRUE` | -| `PE32_PEIM` | .efi | .PEI | This module type is used by PEIMs that are compliant with the PEI CIS | -| `BS_DRIVER` | .efi | .DXE | This module type is either the DXE Core or DXE Drivers that are complaint with the DXE CIS. These modules only execute in the boot services environment and are destroyed when ExitBootServices() is called. | -| `RT_DRIVER` | .efi | .DXE | This module type is used by DXE Drivers that are complaint with the DXE CIS. These modules execute in both boot services and runtime services environments. This means the services that these modules produce are available after ExitBootServices() is called. If SetVirtualAddressMap() is called, then modules of this type are relocated according to virtual address map provided by the operating system. | -| `SAL_RT_DRIVER` | .efi | .DXE | This module type is used by DXE Drivers that can be called in physical mode before SetVirtualAddressMap() is called and either physical mode or virtual mode after SetVirtualAddressMap() is called. This module type is only available to IPF CPUs. This means the services that these modules produce are available after ExitBootServices(). | -| `BS_DRIVER` | .efi | .SMM | This module type is used by DXE Drivers that are loaded into SMRAM. As a result, this module type is only available for IA-32 and x64 CPUs. These modules only execute in physical mode, and are never destroyed. This means the services that these modules produce are available after ExitBootServices(). | -| `APPLICATION` | .efi | .APP | This module type is used by UEFI Applications that are compliant with the EFI 1.10 Specification or the UEFI 2.0 Specification. UEFI Applications are always unloaded when they exit. | -| `EFI USER INTERFACE` | .ui | .ui | | -| `EFI VERSION` | .ver | .ver | | -| `EFI DEPENDENCY` | .dpx | .dpx | | - -### A.1.2 [sources] Section - -The `[sources]` section is used to specify the files that make up the -component. Directories names are required for files existing in subdirectories -of the component. All directory names are relative to the location of the INF -file. Macros are allowed in the source file path. For EDK builds, each file is -added to the macro of `$(INC_DEPS)`, which can be used in a makefile dependency -expression. - -This section will typically use one of the following section definitions: - -```ini -[sources] -[sources.common] -[sources.IA32] -[sources.X64] -[sources.IPF] -[sources.EBC] -``` - -The following example demonstrates entries in this section. - -```ini -[sources.common] - DxeIpl.dxs - DxeIpl.h - DxeLoad.c - -[sources.Ia32] - Ia32/VirtualMemory.h - Ia32/VirtualMemory.c - Ia32/DxeLoadFunc.c - Ia32/ImageRead.c - -[sources.X64] - X64/DxeLoadFunc.c - -[sources.IPF] - Ipf/DxeLoadFunc.c - Ipf/ImageRead.c -``` - -Binary file types - EDK does not have the flexibility of EDK II, but does -provide a method for specifying binary files in the `[sources]` section. The -following lists the mapping of EDK specific binary file types to EFI sections. - -**_SEC_GUID_** - -The binary file is an `EFI_SECTION_FREEFORM_SUBTYPE_GUID` section. - -**_SEC_PE32_** - -This binary is an `EFI_SECTION_PE32` section. - -**_SEC_PIC_** - -This binary is an `EFI_SECTION_PIC` section. - -**_SEC_PEI_DEPEX_** - -This binary is an `EFI_SECTION_PEI_DEPEX` section. - -**_SEC_DXE_DEPEX_** - -This binary is an `EFI_SECTION_DXE_DEPEX` section. - -**_SEC_TE_** - -This binary is an `EFI_SECTION_TE` section. - -**_SEC_VER_** - -This binary is an `EFI_SECTION_VERSION` section. - -**_SEC_UI_** - -This binary is an `EFI_SECTION_USER_INTERFACE` section. - -**_SEC_BIN_** - -The binary is an `EFI_SECTION_RAW` section. - -**_SEC_COMPAT16_** - -This binary is an `EFI_SECTION_COMPATIBILTY16` section. - -### A.1.3 [libraries] Section - -The `[libraries]` section of the EDK INF is used to list the names of the -libraries that will be linked into the EDK component. The library names do not -include the directory locations or the extension name of the file. For each -library, `{LibName}`, found, the `{LibName}` is added to the LIBS definition in -the output makefile: - -`LIBS = $(LIBS) $(LIB_DIR)\{LibName}` - -This section will typically use one of the following section definitions: - -```ini -[libraries.common] -[libraries.IA32] -[libraries.X64] -[libraries.IPF] -[libraries.EBC] -``` - -The formats for entries in this section is: - -`LibraryName` - -The following is an example of a libraries section. - -```ini -[libraries.common] - EfiProtocolLib - EfiDriverLib -``` - -### A.1.4 [includes] Section - -The `[includes]` section of the EDK INF file is a list of directories to be -included on the compile command line. These are included in a section of the -Makefile generated by the parsing utilities. For each include path specified, -the following line is written to the component's makefile. - -`INC = $(INC) -I $(SOURCE_DIR)\{path}` - -The path must be absolute, however the use of the global variable, EDK_SOURCE -is recommended to construct the path. - -This section will typically use one of the following section definitions: - -```ini -[includes.common] -[includes.IA32] -[includes.X64] -[includes.IPF] -[includes.Nt32] -[include.common] -[include.IA32] -[include.X64] -[include.IPF] -``` - -The formats for entries in this section is: - -`$(EDK_SOURCE)/path/to/header/files` - -The following is an example of the [includes] section. - -```ini -[includes.common] - $(EDK_SOURCE)FoundationEfi - $(EDK_SOURCE)Foundation - $(EDK_SOURCE)FoundationFramework - . - $(EDK_SOURCE)FoundationInclude - $(EDK_SOURCE)FoundationEfiInclude - $(EDK_SOURCE)FoundationFrameworkInclude - $(EDK_SOURCE)FoundationIncludeIndustryStandard - $(EDK_SOURCE)FoundationCoreDxe - $(EDK_SOURCE)FoundationLibraryDxeInclude -``` - -### A.1.5 [nmake] Section - -The optional EDK `[nmake]` section may also include a ".ProcessorName" to -restrict processing based on the processor name. The section data is simply -copied directly to the component makefile, before the build commands are -emitted. - -This section will typically use one of the following section definitions: - -```ini -[nmake] -[nmake.common] -[nmake.IA32] -[nmake.X64] -[nmake.IPF] -[nmake.EBC] -``` - -The format for entries in this section is any valid Makefile syntax. Refer to -make command reference for your tool chains. - -The following is an example of the EDK `[nmake]` section. - -```ini -[nmake.common] - IMAGE_ENTRY_POINT = DiskIoDriverEntryPoint -``` diff --git a/appendix_a_edk_inf_file_specification/a2_edk_file_specification.md b/appendix_a_edk_inf_file_specification/a2_edk_file_specification.md deleted file mode 100644 index defbbc2..0000000 --- a/appendix_a_edk_inf_file_specification/a2_edk_file_specification.md +++ /dev/null @@ -1,461 +0,0 @@ - - -## A.2 EDK File Specification - -The general rules for all EDK INI style documents follow. - -********** -**Note:** Path and Filename elements within the INF are case-sensitive in order -to support building on UNIX style operating systems. -********** - -A section terminates with either another section definition or the end of the -file. - -#### Summary - -Component EDK INF description - -#### Prototype - -```c - ::= [
] - - - [] - [] - [] -``` - -### A.2.1 Header Section - -#### Summary - -This section contains Copyright and License notices for the INF file in -comments that start the file. This section is optional using a format of: - - -```ini -#/*++ -# -# Copyright -# License -# -# Module Name: -# EdkFrameworkProtocolLib.inf -# -# Abstract: -# -# Component description file. -# -#--*/ -``` - -This information a developer creating a new EDK component or library -information (INF) file. - -This is an optional section. - -#### Prototype - -```c -
::= ["#"] "/*++" - [] - [] - [] - [] - ["#"] "--*/" - ::= ["#"] "Abstract:" - [["#"] ]* - ["#"] - ::= ["#"] "Module Name:" - [["#"] + ]+ - ["#"] - ::= [["#"] "Copyright (c) "," ]+ ["#"] - - ::= [["#"] ]+ - ["#"] -``` - -#### Example - -``` -#/*++ -# -# Copyright (c) 2004, Intel Corporation -# All rights reserved. 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. -# -# Module Name: -# -# EdkFrameworkProtocolLib.inf -# -# Abstract: -# -# Component description file. -# -#--*/ -``` - -### A.2.2 [defines] Section - -#### Summary - -This describes the required `[define]` tag, which is required in all EDK INF -files. This file is created by the developer and is an input to the new build -tool parsing utilities. Elements may appear in any order within this section. - -This is a required section. - -The define sections defines symbols that describe the component. Some items are -emitted to the output makefile. - -The `FILE_GUID` is required for all EDK components that are not libraries. This -guid is used to build the FW volume file list used by build tools to generate -the final firmware volume, as well as processed in some SMM, PEI or DXE DEPEX -statements. - -********** -**Note:** Possible values for `COMPONENT_TYPE`, and their descriptions, are -listed in the table, "Component (module) Types." For each component, the -`BASE_NAME` and `COMPONENT_TYPE` are required. The `COMPONENT_TYPE` definition -is case sensitive. The default FV extension can be overridden by defining the -symbol `FV_EXT`. -********** - -Section `[defines.$(PROCESSOR).$(PLATFORM)]` is used with EDK components only. -The section is processed in order by the parsing utilities. Assignments of -variables in other sections do not override previous assignments. - -Platform integrators that will be using EDK components that require a static -FlashMap.h (and/or FlashMap.inc) must code them by hand and maintain the state -of the static FlashMap files with the EDK II DSC and FDF files. - -#### Prototype - -```c - ::= "[defines" [] "]" + - ::= ["," "defines" ]* - ::= "." ["." ] - ::= {"IA32"} {"X64"} {"IPF"} {"EBC"} {"common"} - ::= {} {"$(PLATFORM)") {"platform"} - ::= "BASE_NAME" "=" - ["COMPONENT_TYPE" "=" ] - ["FILE_GUID" "=" ] - ["EDK_RELEASE_VERSION" "=" "0x00020000" ] - ["MAKEFILE_NAME" "=" ] - ["CUSTOM_MAKEFILE" "=" ] - ["BUILD_NUMBER" "=" {1,4} ] - ["BUILD_TYPE" "=" ] - ["FFS_EXT" "=" ] - ["FV_EXT" "=" ] - ["SOURCE_FV" "=" ] - ["PACKAGE" "=" "CompressPEIM" ] - ["VERSION_NUMBER" "=" {1,4} ] - ["VERSION_STRING" "=" ] - ["GENERIC_CAPSULE_FILE_PATH" "=" ] - ["MICROCODE_ALIGNMENT" "=" ] - ["MICROCODE_FILE_PATH" "=" ] - ["PLATFORM_BDS_FILE_PATH" "=" ] - ["RESTRICTED_BDS_FILE_PATH" "=" ] - ::= [] ["." ] - ::= - ::= {"MAKEFILE"} {"CUSTOM_MAKEFILE"} {} - ::= [ "\"] - ::= [{ "\"} {"..\"}]+ - ::= {"$(" ")"} - {"$(EFI_SOURCE)"} {"$(EDK_SOURCE)"} - ::= {} - {"$(EFI_APRIORI_GUID)"} - {"$(EFI_ACPI_TABLE_STORAGE_GUID)"} - {"$(EFI_DEFAULT_BMP_LOGO_GUID)"} - {"$(EFI_PEI_APRIORI_FILE_NAME_GUID)"} - ::= {"APPLICATION"} {"AcpiTable"} {"APRIORI"} - {"BINARY"} {"BS_DRIVER"} {"CONFIG"} {"FILE"} - {"FVIMAGEFILE"} {"LIBRARY"} {"LOGO"} {"LEGACY16"} - {"MICROCODE"} {"PE32_PEIM"} {"PEI_CORE"} - {"RAWFILE"} {"RT_DRIVER"} {"SAL_RT_DRIVER"} - {"SECURITY_CORE"} {"COMBINED_PEIM_DRIVER"} {"PIC_PEIM"} - {"RELOCATABLE_PEIM"} - ::= -``` - -#### Example (EDK Driver) - -```ini -[Defines] - BASE_NAME = DiskIo - FILE_GUID = CA261A26-7718-4b9b-8A07-5178B1AE3A02 - COMPONENT_TYPE = BS_DRIVER -``` - -#### Example (EDK Library) - -```ini -[Defines] - BASE_NAME = WinNtLib - COMPONENT_TYPE = LIBRARY -``` - -### A.2.3 [includes] Section - -#### Summary - -Defines the optional "includes paths" for EDK INF files only. These sections -should never be used in EDK II INF files. These sections are used to define the -include paths for compiling the component source files. Valid sections for EDK -include the `[includes.$(PROCESSOR).$(PLATFORM)]`, `[includes.$(PROCESSOR)]`, -and `[includes.common]` sections. - -********** -**NOTE**: EDK uses both "include" and "includes" section header types. These -sections are processed if present. These paths are used to define the `$(INC)` -macro and is written to the component's makefile. -********** - -This is an optional section. - -The standard Macro Definitions are not permitted within this section. - -For EDK modules, the path must include either the `$(EFI_SOURCE)` or -`$(EDK_SOURCE)` environment variable. - -This section also allows for specifying individual header files that will be -added to the `$(INC)` macro using the `/FI` (Microsoft) or `-include` (GCC) -switch. This is an optional section. - -#### Prototype - -```c - ::= "[include" ["s"] [] ']" - + - ::= ["," "include" ["s"]? ]* - ::= [] [] [] - ::= "." - ::= {"IA32"} {"X64"} {"IPF"} {"EBC"} {"common"} {} - ::= "." {"$(PROCESSOR)"} {"$(" ")"} - ::= "." {"Platform") {"nt32"} {"$(PLATFORM)"} - ::= {} {} - ::= ["\" ]+ - ::= {"$(EDK_SOURCE)"} {"$(EFI_SOURCE)"} {"$(BUILD_DIR)"} - {"$(SOURCE_DIR)"} - ::= ["..\"]+ {".."} {} -``` - -#### Example - -```ini -[Includes.common] - $(EDK_SOURCE)FoundationEfi - $(EDK_SOURCE)Foundation - $(EDK_SOURCE)FoundationFramework - . - $(EDK_SOURCE)FoundationInclude - $(EDK_SOURCE)FoundationEfiInclude - $(EDK_SOURCE)FoundationFrameworkInclude - $(EDK_SOURCE)FoundationIncludeIndustryStandard - $(EDK_SOURCE)FoundationCoreDxe - $(EDK_SOURCE)FoundationLibraryDxeInclude -``` - -### A.2.4 [libraries] Section - -#### Summary - -Defines the optional `[libraries]` section tag for EDK INF files. The -`[libraries]` section is used to define a `$(LIBS)` macro in the EDK component's -makefile. All libraries listed in the `[libraries.common]`, -`[libraries.$(PROCESSOR)]`, and `[libraries.$(PROCESSOR).$(PLATFORM)]` sections -are added to the LIBS definition as either `$(LIB_DIR)\LibName` or -`$(PROCESSOR)\LibName`. The libraries are specified without path information. - -The standard Macro Definitions are not permitted in this section. - -This is an optional section. - -#### Prototype - -```c - ::= "[libraries" [] ']" + - ::= "." ["." ] - ::= ["," ["." ]] - ["," "libraries." ]* - ::= {"IA32"} {"X64"} {"IPF"} {"EBC"} {"common"} - {"platform"} {"nt32"} {"$(PROCESSOR)"} - ::= {"platform"} {"$(PLATFORM)"} {} - ::= -``` - -#### Example - -```ini -[Libraries.common] - EfiProtocolLib - EfiDriverLib -``` - -### A.2.5 [nmake] Section - -#### Summary - -Defines the [nmake] section tag for EDK INF files. These sections are used to -make a direct addition to the component's output makefile. EFI section -`[nmake.$(PROCESSOR).$(PLATFORM)]`, `[nmake.$(PROCESSOR)]`, and `[nmake.common]` -are processed if present. The section data is simply copied directly to the -component makefile, before the build commands are emitted. Filenames specified -in this section are relative to the EDK INF file or the EDK DSC file. - -This is an optional section. - -This section is not permitted in EDK II modules. Note that the `C_STD_INCLUDE` -line is usually used to clear any flags that might have been set by the -Microsoft tool chain setup scripts, therefore no `` are printed, and -the line in the Example is the most common usage. - -The standard Macro Definitions are not permitted in this section. - -#### Prototype - -```c - ::= "[nmake" [] ']" - + - ::= [] ["," "nmake" ]* - ::= "." - ::= "." - ::= {"IA32"} {"X64"} {"IPF"} {"EBC"} {"common"} - ::= [] [] [] [] [] [] [] [] - ::= "IMAGE_ENTRY_POINT" "=" - ::= "DPX_SOURCE" "=" - ::= "C_STD_INCLUDE" "=" [] - ::= "C_PROJ_FLAGS" "=" - ::= "ASM_PROJ_FLAGS" "=" - ::= "LIB_STD_FLAGS" "=" - ::= ["EBC_C_STD_FLAGS" "=" ] - ["EBC_LIB_STD_FLAGS" "=" ] - ::= "=" {} {} - ::= Valid NMAKE Makefile syntax. -``` - -#### Parameters - -**_CFlags_** - -This content must be valid compiler flags for the Microsoft C compiler, cl.exe. - -**_AFlags_** - -This content must be valid flags for the Microsoft Assembler, ml.exe. - -**_LFlags_** - -This content must be valid flags for the Microsoft Linker, lib.exe. - -#### Example - -```ini -[nmake.common] - C_STD_INCLUDE = - IMAGE_ENTRY_POINT=WatchdogTimerDriverInitialize - DPX_SOURCE=WatchDogTimer.dxs - -[nmake.common] - C_FLAGS = $(C_FLAGS) /D EDKII_GLUE_LIBRARY_IMPLEMENTATION - LIB_STD_FLAGS = $(LIB_STD_FLAGS) /IGNORE:4006 /IGNORE:4221 - -[nmake.ia32] - C_FLAGS = $(C_FLAGS) /D MDE_CPU_IA32 - -[nmake.x64] - C_FLAGS = $(C_FLAGS) /D MDE_CPU_X64 - -[nmake.ipf] - C_FLAGS = $(C_FLAGS) /D MDE_CPU_IPF - -[nmake.ebc] - EBC_C_STD_FLAGS = $(EBC_C_STD_FLAGS) /D EDKII_GLUE_LIBRARY_IMPLEMENTATION - EBC_LIB_STD_FLAGS = $(EBC_LIB_STD_FLAGS) /IGNORE:4006 /IGNORE:4221 - EBC_C_STD_FLAGS = $(EBC_C_STD_FLAGS) /D MDE_CPU_EBC -``` - -### A.2.6 [sources] Section - -#### Summary - -Defines the `[sources]` section tag is required for EDK INF files. NOTE: EDK -uses both "source" and "sources" in the section header. - -There can be multiple sources sections, depending on the target processor. -Example sources sections are listed below. The parsing utility creates a -directory path for each file (`$(DEST_DIR)...\MyFile.c`), and looks up the -makefile template for the `COMPONENT_TYPE` (EDK) to emit. - -It is not permissible to mix EDK and EDK II style files within a module. - -The macro, TABLE_NAME may be used in existing EDK INF files that point to ACPI -tables, this value wil be ignored by EDK II build tools. - -#### Prototype - -```c - ::= "[source" ["s"] [] "]" - []* []+ - ::= ["," "sources" ]* - ::= if (COMPONENT_TYPE defined in defines): - "." [] else: - "." - ::= if (COMPONENT_TYPE defined in defines): ["," - ]* else: - ["|" ]* - ::= {"IA32"} {"X64"} {"IPF"} {"Common"} - ::= "." {"$(PLATFORM)"} {"$(PROCESSOR)"} {} - ::= ["DEFINE" "=" [] ]* - ["TABLE_NAME" "=" ] - ::= ["|" ] - ::= {"MSFT"} {"GCC"} {"INTEL"} {"*"} - ::= "." - ::= [ {"\"} {"/"}] [ {"\"} {"/"}]+ -``` - -#### Examples - -```ini -[sources.common] - BsDataHubStatusCode.c - BsDataHubStatusCode.h -``` diff --git a/appendix_c_symbols.md b/appendix_b_symbols.md similarity index 98% rename from appendix_c_symbols.md rename to appendix_b_symbols.md index ed1254f..330c755 100644 --- a/appendix_c_symbols.md +++ b/appendix_b_symbols.md @@ -1,9 +1,9 @@ -# Appendix C Symbols +# Appendix B Symbols One of the core concepts of this utility is the notion of symbols. Use of symbols follows the makefile convention of enclosing within `$()`, for example `$(EDK_SOURCE)`. As the utility processes files during execution, it will often perform parsing of variable assignments. These variables can then be referenced diff --git a/appendix_d_sample_driver_inf_files.md b/appendix_c_sample_driver_inf_files.md similarity index 94% rename from appendix_d_sample_driver_inf_files.md rename to appendix_c_sample_driver_inf_files.md index 0efcb63..e0875a7 100644 --- a/appendix_d_sample_driver_inf_files.md +++ b/appendix_c_sample_driver_inf_files.md @@ -1,9 +1,9 @@ -# Appendix D Sample Driver INF Files +# Appendix C Sample Driver INF Files The following INF file example are from EDK II `MdeModulePkg/Universal/Disk/DiskIoDxe/DiskIoDxe.inf` and `IntelFrameworkModulePkg/Universal/StatusCode/RuntimeDxe/StatusCodeRuntimeDxe.inf` driver modules. -## D.1 DiskIoDxe INF file +## C.1 DiskIoDxe INF file ```ini ## @file # Module that lays Disk I/O protocol on every Block I/O protocol. # @@ -101,11 +101,11 @@ driver modules. [Protocols] gEfiDiskIoProtocolGuid ## BY_START gEfiBlockIoProtocolGuid ## TO_START ``` -## D.2 StatusCodeRuntimeDxe INF file +## C.2 StatusCodeRuntimeDxe INF file ```ini ## @file # Status Code Runtime Dxe driver produces Status Code Runtime Protocol. # diff --git a/appendix_e_sample_library_inf_files.md b/appendix_d_sample_library_inf_files.md similarity index 94% rename from appendix_e_sample_library_inf_files.md rename to appendix_d_sample_library_inf_files.md index bf4a6fd..1b03f0f 100644 --- a/appendix_e_sample_library_inf_files.md +++ b/appendix_d_sample_library_inf_files.md @@ -1,9 +1,9 @@ -# Appendix E Sample Library INF Files +# Appendix D Sample Library INF Files The following INF file are examples of INF files for the EDK II MdePkg library, PeiServicesTablePointerLib and the MdeModulePkg libraries, DxeCoreMemoryAllocationLib.inf and SmmCorePerformanceLib.inf. -## E.1 PeiServicesTablePointerLib.inf +## D.1 PeiServicesTablePointerLib.inf ```ini ## @file # Instance of PEI Services Table Pointer Library using global variable for the table pointer. # @@ -80,11 +80,11 @@ DxeCoreMemoryAllocationLib.inf and SmmCorePerformanceLib.inf. [LibraryClasses] DebugLib ``` -## E.2 DxeCoreMemoryAllocationLib.inf +## D.2 DxeCoreMemoryAllocationLib.inf ```ini ## @file # Memory Allocation Library instance dedicated to DXE Core. # @@ -133,11 +133,11 @@ DxeCoreMemoryAllocationLib.inf and SmmCorePerformanceLib.inf. [LibraryClasses] DebugLib BaseMemoryLib ``` -## E.3 SmmCorePerformanceLib.inf +## D.3 SmmCorePerformanceLib.inf ```ini ## @file # Performance library instance used by SMM Core. # diff --git a/appendix_f_sample_binary_inf_files.md b/appendix_e_sample_binary_inf_files.md similarity index 94% rename from appendix_f_sample_binary_inf_files.md rename to appendix_e_sample_binary_inf_files.md index e6d06d7..0180b52 100644 --- a/appendix_f_sample_binary_inf_files.md +++ b/appendix_e_sample_binary_inf_files.md @@ -1,9 +1,9 @@ -# Appendix F Sample Binary INF Files +# Appendix E Sample Binary INF Files The following are example INF files for the binary modules, EnhancedFatDxe, in the FatBinPkg. The second example is a generated binary INF file for the RuntimeDxe driver in the MdeModulePkg. -## F.1 FatBinPkg/EnhancedFatDxe/Fat.inf +## E.1 FatBinPkg/EnhancedFatDxe/Fat.inf ```ini ## @file # # Binary FAT32 EFI Driver for IA32, X64, IPF and EBC arch. @@ -87,11 +87,11 @@ RuntimeDxe driver in the MdeModulePkg. [Binaries.ARM] PE32|Arm/Fat.efi|* ``` -## F.2 MdeModulePkg/Core/RuntimeDxe.inf +## E.2 MdeModulePkg/Core/RuntimeDxe.inf ```ini ## @file # Module that produces EFI runtime virtual switch over services. # diff --git a/appendix_g_module_types.md b/appendix_f_module_types.md similarity index 99% rename from appendix_g_module_types.md rename to appendix_f_module_types.md index 4cada25..334d4b7 100644 --- a/appendix_g_module_types.md +++ b/appendix_f_module_types.md @@ -1,9 +1,9 @@ -# Appendix G Module Types +# Appendix F Module Types ###### Table 9 EDK II Module Types | FILE TYPE | MODULE_TYPE | EDK II Extension | Description | | -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -- 2.20.1.windows.1