Add rule lesson

Signed-off-by: Konstantin Aladyshev <aladyshev22@gmail.com>

1 files changed, 470 insertions, 0 deletions

diff --git a/Lessons_uncategorized/Lesson_FDF_FV_7/README.md b/Lessons_uncategorized/Lesson_FDF_FV_7/README.md
new file mode 100644
index 0000000..1bbd507
--- /dev/null
+++ b/Lessons_uncategorized/Lesson_FDF_FV_7/README.md
@@ -0,0 +1,470 @@
+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:
+```
+<SectionType> <SectionFileType> <File>
+```
+- `<SectionType>` - this is a standard section type that we've used
+- `<SectionFileType>` - this one is tricky, see explanation below
+- `<File>` - this is the file path for the section data
+
+`<SectionFileType>` is a parameter for the edk2 build system. Most often it is equal to the `<SectionType>`. 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 `<SectionType>`.
+
+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)
+