Let's look a the process how UEFI loads modues from flash. The Foundation checks its Firmware Volume (FV) and loads modules with specific types. For example, one of the module types for the DXE Foundation is `EFI_FV_FILETYPE_DRIVER=0x07` (DXE driver). After the module load, the DXE Foundation would transfer execution to the module section `EFI_SECTION_PE32=0x10` (PE32+ Executable image). As you might remember the section of this type is mandatory for such type of file by the specification. How we can add such files to our flash image? For example we can write something like this: ``` FILE DRIVER = 15c658f6-eb5c-4b8f-b232-d6bd7368a73e { SECTION PE32 = $(WORKDIR)/Build/UefiLessonsPkg/RELEASE_GCC5/X64/SimplestApp.efi } ``` To remove hardcoded paths we can use various build defines: ``` FILE DRIVER = 15c658f6-eb5c-4b8f-b232-d6bd7368a73e { SECTION PE32 = $(OUTPUT_DIRECTORY)/$(TARGET)_$(TOOL_CHAIN_TAG)/$(ARCH)/SimplestApp.efi } ``` But this also is not ideal, if our flash image would need a lot of modules, we would have a lot of this boilerplate code. Which is obviously not good. Also here we need to provide file type and file sections, and they should correspond to the actual module type. But to know the actual module type we need to consult the module itself. And if we change it one day, we would need to not forget to sync sections in FDF. This interdependency of code is not good. Finally here we need to provide file GUIDs. This information would pollute every FDF that would include the module. Luckily there is another method in edk2! Instead of working with the product of `*.inf` file build (i.e. its `*.efi` file), we can use the `*.inf` file itself: ``` [FV.SimpleVolume] FvAlignment = 16 INF UefiLessonsPkg/SimplestApp/SimplestApp.inf ``` This makes perfect sense since the `*.inf` file knows how to compile the module, the type of the module (`MODULE_TYPE`) and its file guid (`FILE_GUID`): ``` [Defines] INF_VERSION = 1.25 BASE_NAME = SimplestApp FILE_GUID = 4a298956-fbe0-47fb-ae3a-2d5a0a959a26 MODULE_TYPE = UEFI_APPLICATION VERSION_STRING = 1.0 ENTRY_POINT = UefiMain [Sources] SimplestApp.c [Packages] MdePkg/MdePkg.dec [LibraryClasses] UefiApplicationEntryPoint ``` If you try to build flash image with the FDF code we've written above you would get an error: ``` build.py... : error F003: Don't Find common rule RULE.COMMON.UEFI_APPLICATION for INF UefiLessonsPkg/SimplestApp/SimplestApp.inf ``` It is because edk2 uses `rule` system to construct FFS files from the module INF's. The error says that our FDF lack a rule for our module (which has a type `UEFI_APPLICATION`). Let's try to write such rule: ``` [Rule.Common.UEFI_APPLICATION] FILE APPLICATION = $(NAMED_GUID) { PE32 PE32 $(INF_OUTPUT)/$(MODULE_NAME).efi } ``` Here we say that for every included `*.inf` file with a `MODULE_TYPE = UEFI_APPLICATION` we add `FILE` of type `APPLICATION` to the FFS. This file would be added with a name `FILE_GUID` from the `*.inf` defines (this is what `$(NAMED_GUID)` means). The file would include one section `PE32` with a content `$(INF_OUTPUT)/$(MODULE_NAME).efi`, which is a product of a module build. `MODULE_NAME` is derived from the `BASE_NAME` defined in the `*inf` file and the `INF_OUTPUT` is derived from the build method that we use. In this case this would expand to: ``` Build/UefiLessonsPkg/RELEASE_GCC5/X64/UefiLessonsPkg/SimplestApp/SimplestApp/OUTPUT/SimplestApp.efi ``` The section syntax is similar to the way how we've defined sections in a file, except here we don't use the `SECTION` keyword and have written `PE32` two times. This syntax means: ``` ``` - `` - this is a standard section type that we've used - `` - this one is tricky, see explanation below - `` - this is the file path for the section data `` is a parameter for the edk2 build system. Most often it is equal to the ``. Except for the `RAW` section. In this case it can also be `BIN`, `ASL` or `ACPI`. We'll get back to this parameter when we would talk about binary modules. Right now just use the same value as you use for the ``. With the rule above the image would build and you can check the resulting `FV` with `VolInfo`: ``` $ VolInfo Build/UefiLessonsPkg/RELEASE_GCC5/FV/SIMPLEVOLUME.Fv -x Build/UefiLessonsPkg/RELEASE_GCC5/FV/Guid.xref VolInfo Version 1.0 Build Developer Build based on Revision: Unknown %36s %511s ParseGuidBaseNameFile: Build/UefiLessonsPkg/RELEASE_GCC5/FV/Guid.xref Signature: _FVH (4856465F) Attributes: 40800 EFI_FVB2_ERASE_POLARITY EFI_FVB2_ALIGNMENT_16 Header Length: 0x00000048 File System ID: 8c8ce578-8a3d-4f1c-9935-896185c32dd3 Revision: 0x0002 Number of Blocks: 0x00000428 Block Length: 0x00000001 Total Volume Size: 0x00000428 ============================================================ File Name: 4A298956-FBE0-47FB-AE3A-2D5A0A959A26 SimplestApp File Offset: 0x00000048 File Length: 0x000003DC File Attributes: 0x00 File State: 0xF8 EFI_FILE_DATA_VALID File Type: 0x09 EFI_FV_FILETYPE_APPLICATION ------------------------------------------------------------ Type: EFI_SECTION_PE32 Size: 0x000003C4 There are a total of 1 files in this FV ``` Everything is exactly as expected. If you want to include another `UEFI_APPLICATION` module, you just add another `*.inf` to the `FV`: ``` [FV.SimpleVolume] FvAlignment = 16 INF UefiLessonsPkg/SimplestApp/SimplestApp.inf INF UefiLessonsPkg/HelloWorld/HelloWorld.inf ``` If you check `VolInfo` for this configuration, you would see that now our FV has two files, and each of the files has one PE32 section. ``` $ VolInfo Build/UefiLessonsPkg/RELEASE_GCC5/FV/SIMPLEVOLUME.Fv -x Build/UefiLessonsPkg/RELEASE_GCC5/FV/Guid.xref VolInfo Version 1.0 Build Developer Build based on Revision: Unknown %36s %511s ParseGuidBaseNameFile: Build/UefiLessonsPkg/RELEASE_GCC5/FV/Guid.xref Signature: _FVH (4856465F) Attributes: 40800 EFI_FVB2_ERASE_POLARITY EFI_FVB2_ALIGNMENT_16 Header Length: 0x00000048 File System ID: 8c8ce578-8a3d-4f1c-9935-896185c32dd3 Revision: 0x0002 Number of Blocks: 0x00001B88 Block Length: 0x00000001 Total Volume Size: 0x00001B88 ============================================================ File Name: 4A298956-FBE0-47FB-AE3A-2D5A0A959A26 SimplestApp File Offset: 0x00000048 File Length: 0x000003DC File Attributes: 0x00 File State: 0xF8 EFI_FILE_DATA_VALID File Type: 0x09 EFI_FV_FILETYPE_APPLICATION ------------------------------------------------------------ Type: EFI_SECTION_PE32 Size: 0x000003C4 ============================================================ File Name: 2E55FA38-F148-42D3-AF90-1BE247323E30 HelloWorld File Offset: 0x00000428 File Length: 0x0000175C File Attributes: 0x00 File State: 0xF8 EFI_FILE_DATA_VALID File Type: 0x09 EFI_FV_FILETYPE_APPLICATION ------------------------------------------------------------ Type: EFI_SECTION_PE32 Size: 0x00001744 There are a total of 2 files in this FV ``` With the rule system we can easily add other sections to the resulting files. For example let's add `UI` section with a `MODULE_NAME` define content to each file resulting from the `UEFI_APPLICATION` module compilation. Here in the rule statements it is also possible to initialize `UI` section in-place as we've used to: ``` [Rule.Common.UEFI_APPLICATION] FILE APPLICATION = $(NAMED_GUID) { PE32 PE32 $(INF_OUTPUT)/$(MODULE_NAME).efi UI STRING="$(MODULE_NAME)" } ``` In the `VolInfo` output you can see how each of the files now have `EFI_SECTION_USER_INTERFACE` section initialized with the apropriate string: ``` $ VolInfo Build/UefiLessonsPkg/RELEASE_GCC5/FV/SIMPLEVOLUME.Fv -x Build/UefiLessonsPkg/RELEASE_GCC5/FV/Guid.xref VolInfo Version 1.0 Build Developer Build based on Revision: Unknown %36s %511s ParseGuidBaseNameFile: Build/UefiLessonsPkg/RELEASE_GCC5/FV/Guid.xref Signature: _FVH (4856465F) Attributes: 40800 EFI_FVB2_ERASE_POLARITY EFI_FVB2_ALIGNMENT_16 Header Length: 0x00000048 File System ID: 8c8ce578-8a3d-4f1c-9935-896185c32dd3 Revision: 0x0002 Number of Blocks: 0x00001BB8 Block Length: 0x00000001 Total Volume Size: 0x00001BB8 ============================================================ File Name: 4A298956-FBE0-47FB-AE3A-2D5A0A959A26 SimplestApp File Offset: 0x00000048 File Length: 0x000003F8 File Attributes: 0x00 File State: 0xF8 EFI_FILE_DATA_VALID File Type: 0x09 EFI_FV_FILETYPE_APPLICATION ------------------------------------------------------------ Type: EFI_SECTION_PE32 Size: 0x000003C4 ------------------------------------------------------------ Type: EFI_SECTION_USER_INTERFACE Size: 0x0000001C String: SimplestApp ============================================================ File Name: 2E55FA38-F148-42D3-AF90-1BE247323E30 HelloWorld File Offset: 0x00000440 File Length: 0x00001776 File Attributes: 0x00 File State: 0xF8 EFI_FILE_DATA_VALID File Type: 0x09 EFI_FV_FILETYPE_APPLICATION ------------------------------------------------------------ Type: EFI_SECTION_PE32 Size: 0x00001744 ------------------------------------------------------------ Type: EFI_SECTION_USER_INTERFACE Size: 0x0000001A String: HelloWorld There are a total of 2 files in this FV ``` Another commonly added section is `VERSION`, so let's add this one too: ``` [Rule.Common.UEFI_APPLICATION] FILE APPLICATION = $(NAMED_GUID) { PE32 PE32 $(INF_OUTPUT)/$(MODULE_NAME).efi UI STRING="$(MODULE_NAME)" VERSION STRING="$(INF_VERSION)" BUILD_NUM=$(BUILD_NUMBER) } ``` `VolInfo` output in this case: ``` $ VolInfo Build/UefiLessonsPkg/RELEASE_GCC5/FV/SIMPLEVOLUME.Fv -x Build/UefiLessonsPkg/RELEASE_GCC5/FV/Guid.xref VolInfo Version 1.0 Build Developer Build based on Revision: Unknown %36s %511s ParseGuidBaseNameFile: Build/UefiLessonsPkg/RELEASE_GCC5/FV/Guid.xref Signature: _FVH (4856465F) Attributes: 40800 EFI_FVB2_ERASE_POLARITY EFI_FVB2_ALIGNMENT_16 Header Length: 0x00000048 File System ID: 8c8ce578-8a3d-4f1c-9935-896185c32dd3 Revision: 0x0002 Number of Blocks: 0x00001BD8 Block Length: 0x00000001 Total Volume Size: 0x00001BD8 ============================================================ File Name: 4A298956-FBE0-47FB-AE3A-2D5A0A959A26 SimplestApp File Offset: 0x00000048 File Length: 0x00000406 File Attributes: 0x00 File State: 0xF8 EFI_FILE_DATA_VALID File Type: 0x09 EFI_FV_FILETYPE_APPLICATION ------------------------------------------------------------ Type: EFI_SECTION_PE32 Size: 0x000003C4 ------------------------------------------------------------ Type: EFI_SECTION_USER_INTERFACE Size: 0x0000001C String: SimplestApp ------------------------------------------------------------ Type: EFI_SECTION_VERSION Size: 0x0000000E Build Number: 0x0000 Version String: 1.0 ============================================================ File Name: 2E55FA38-F148-42D3-AF90-1BE247323E30 HelloWorld File Offset: 0x00000450 File Length: 0x00001786 File Attributes: 0x00 File State: 0xF8 EFI_FILE_DATA_VALID File Type: 0x09 EFI_FV_FILETYPE_APPLICATION ------------------------------------------------------------ Type: EFI_SECTION_PE32 Size: 0x00001744 ------------------------------------------------------------ Type: EFI_SECTION_USER_INTERFACE Size: 0x0000001A String: HelloWorld ------------------------------------------------------------ Type: EFI_SECTION_VERSION Size: 0x0000000E Build Number: 0x0000 Version String: 1.0 There are a total of 2 files in this FV ``` # Arch parameter in the rule section name We've defined our rule as ``` [Rule.Common.UEFI_APPLICATION] ``` The word after the first period means target architecture. In this case we defined it as `Common` which means any architecture. You can verify that our build would be fine with such rule: ``` [Rule.X64.UEFI_APPLICATION] ``` If you want to you could provide completely separate rule for `X32` architecture. # Overriding rules It is possible to override rules for particular modules. In this case you need to provide an overriden rule. If you remember earlier `SimplestApp.inf` and `HelloWorld.inf` modules have generated similarly constructed files. Let's provide overriden rule and use it for one of these modules: ``` [FV.SimpleVolume] FvAlignment = 16 INF RuleOverride=MyCompressed UefiLessonsPkg/SimplestApp/SimplestApp.inf INF UefiLessonsPkg/HelloWorld/HelloWorld.inf [Rule.Common.UEFI_APPLICATION] FILE APPLICATION = $(NAMED_GUID) { PE32 PE32 $(INF_OUTPUT)/$(MODULE_NAME).efi UI STRING="$(MODULE_NAME)" VERSION STRING="$(INF_VERSION)" BUILD_NUM=$(BUILD_NUMBER) } [Rule.Common.UEFI_APPLICATION.MyCompressed] FILE APPLICATION = $(NAMED_GUID) { GUIDED EE4E5898-3914-4259-9D6E-DC7BD79403CF { # LzmaCompress PE32 PE32 $(INF_OUTPUT)/$(MODULE_NAME).efi VERSION STRING="$(INF_VERSION)" BUILD_NUM=$(BUILD_NUMBER) } UI STRING="$(MODULE_NAME)" } ``` Now the modules generate differently structured files: ``` $ VolInfo Build/UefiLessonsPkg/RELEASE_GCC5/FV/SIMPLEVOLUME.Fv -x Build/UefiLessonsPkg/RELEASE_GCC5/FV/Guid.xref VolInfo Version 1.0 Build Developer Build based on Revision: Unknown %36s %511s ParseGuidBaseNameFile: Build/UefiLessonsPkg/RELEASE_GCC5/FV/Guid.xref Signature: _FVH (4856465F) Attributes: 40800 EFI_FVB2_ERASE_POLARITY EFI_FVB2_ALIGNMENT_16 Header Length: 0x00000048 File System ID: 8c8ce578-8a3d-4f1c-9935-896185c32dd3 Revision: 0x0002 Number of Blocks: 0x00001970 Block Length: 0x00000001 Total Volume Size: 0x00001970 ============================================================ File Name: 4A298956-FBE0-47FB-AE3A-2D5A0A959A26 SimplestApp File Offset: 0x00000048 File Length: 0x000001A0 File Attributes: 0x00 File State: 0xF8 EFI_FILE_DATA_VALID File Type: 0x09 EFI_FV_FILETYPE_APPLICATION ------------------------------------------------------------ Type: EFI_SECTION_GUID_DEFINED Size: 0x0000016B SectionDefinitionGuid: ee4e5898-3914-4259-9d6e-dc7bd79403cf DataOffset: 0x0018 Attributes: 0x0001 Decoding /------------ Encapsulation section start -----------------\ ------------------------------------------------------------ Type: EFI_SECTION_PE32 Size: 0x000003C4 ------------------------------------------------------------ Type: EFI_SECTION_VERSION Size: 0x0000000E Build Number: 0x0000 Version String: 1.0 \------------ Encapsulation section end -------------------/ ------------------------------------------------------------ Type: EFI_SECTION_USER_INTERFACE Size: 0x0000001C String: SimplestApp ============================================================ File Name: 2E55FA38-F148-42D3-AF90-1BE247323E30 HelloWorld File Offset: 0x000001E8 File Length: 0x00001786 File Attributes: 0x00 File State: 0xF8 EFI_FILE_DATA_VALID File Type: 0x09 EFI_FV_FILETYPE_APPLICATION ------------------------------------------------------------ Type: EFI_SECTION_PE32 Size: 0x00001744 ------------------------------------------------------------ Type: EFI_SECTION_USER_INTERFACE Size: 0x0000001A String: HelloWorld ------------------------------------------------------------ Type: EFI_SECTION_VERSION Size: 0x0000000E Build Number: 0x0000 Version String: 1.0 There are a total of 2 files in this FV ``` # APRIORI If you want to add some modules to the `a priori` file, you just add the module INFs to the `APRIORI` blocks: ``` APRIORI PEI { INF UefiLessonsPkg/MemoryInfo/MemoryInfo.inf } APRIORI DXE { INF UefiLessonsPkg/SimplestApp/SimplestApp.inf INF UefiLessonsPkg/HelloWorld/HelloWorld.inf } ``` `VolInfo`: ``` $ VolInfo Build/UefiLessonsPkg/RELEASE_GCC5/FV/SIMPLEVOLUME.Fv -x Build/UefiLessonsPkg/RELEASE_GCC5/FV/Guid.xref VolInfo Version 1.0 Build Developer Build based on Revision: Unknown %36s %511s ParseGuidBaseNameFile: Build/UefiLessonsPkg/RELEASE_GCC5/FV/Guid.xref Signature: _FVH (4856465F) Attributes: 40800 EFI_FVB2_ERASE_POLARITY EFI_FVB2_ALIGNMENT_16 Header Length: 0x00000048 File System ID: 8c8ce578-8a3d-4f1c-9935-896185c32dd3 Revision: 0x0002 Number of Blocks: 0x000000B8 Block Length: 0x00000001 Total Volume Size: 0x000000B8 ============================================================ File Name: 1B45CC0A-156A-428A-AF62-49864DA0E6E6 File Offset: 0x00000048 File Length: 0x0000002C File Attributes: 0x00 File State: 0xF8 EFI_FILE_DATA_VALID File Type: 0x02 EFI_FV_FILETYPE_FREEFORM ------------------------------------------------------------ Type: EFI_SECTION_RAW Size: 0x00000014 PEI APRIORI FILE: D2CE1D65-603E-4B48-B3E1-FE65D5D0BCA8 MemoryInfo ============================================================ File Name: FC510EE7-FFDC-11D4-BD41-0080C73C8881 File Offset: 0x00000078 File Length: 0x0000003C File Attributes: 0x00 File State: 0xF8 EFI_FILE_DATA_VALID File Type: 0x02 EFI_FV_FILETYPE_FREEFORM ------------------------------------------------------------ Type: EFI_SECTION_RAW Size: 0x00000024 DXE APRIORI FILE: 4A298956-FBE0-47FB-AE3A-2D5A0A959A26 SimplestApp 2E55FA38-F148-42D3-AF90-1BE247323E30 HelloWorld There are a total of 2 files in this FV ``` Here you can see, that as before, defining files inside the `APRIORI` blocks doesn't add the files itself to the FFS. Also this syntax doesn't even need any rules defined. But off course you'll need them when you would add the modules itself. # Links - [https://edk2-docs.gitbook.io/edk-ii-fdf-specification/3_edk_ii_fdf_file_format/39_-rule-_sections](https://edk2-docs.gitbook.io/edk-ii-fdf-specification/3_edk_ii_fdf_file_format/39_-rule-_sections)