Add draft for the UEFI config language lesson

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

1 files changed, 283 insertions, 0 deletions

diff --git a/Lessons_uncategorized/Lesson_Configuration_Language_1/README.md b/Lessons_uncategorized/Lesson_Configuration_Language_1/README.md
new file mode 100644
index 0000000..ff037ae
--- /dev/null
+++ b/Lessons_uncategorized/Lesson_Configuration_Language_1/README.md
@@ -0,0 +1,283 @@
+The communication between the `FormBrowser` application and the HII subsystem is based on a special interface language defined in the UEFI specification: `UEFI Configuration Language`.
+
+In a way it is similar to how a real internet browser uses HTTP GET/POST requests "language" to accesses a web server.
+
+And as you might know in case of the HTTP you could use something like `curl` to issue requests directly from CLI instead of using a window browser application.
+There is no predefined command in the UEFI shell that would allow you to issue `UEFI Configuration Language` requests directly without launching a form browser, so let's create such application.
+
+In other words our application would use this `UEFI Configuration Language` to talk with the HII subsystem directly. Our goal is to read and write HII form elements directly from the UEFI Shell CLI.
+
+The protocol that is used for communication with the HII subsystem is `EFI_HII_CONFIG_ROUTING_PROTOCOL`:
+```
+EFI_HII_CONFIG_ROUTING_PROTOCOL
+
+Summary:
+The EFI HII Configuration Routing Protocol manages the movement of configuration data from drivers to configuration applications. It then serves as the single point to receive configuration information from configuration applications, routing the results to the appropriate drivers.
+
+
+GUID:
+
+#define EFI_HII_CONFIG_ROUTING_PROTOCOL_GUID \
+ { 0x587e72d7, 0xcc50, 0x4f79,\
+ { 0x82, 0x09, 0xca, 0x29, 0x1f, 0xc1, 0xa1, 0x0f }}
+
+
+Protocol Interface Structure:
+
+typedef struct {
+ EFI_HII_EXTRACT_CONFIG ExtractConfig;
+ EFI_HII_EXPORT_CONFIG ExportConfig
+ EFI_HII_ROUTE_CONFIG RouteConfig;
+ EFI_HII_BLOCK_TO_CONFIG BlockToConfig;
+ EFI_HII_CONFIG_TO_BLOCK ConfigToBlock;
+ EFI_HII_GET_ALT_CFG GetAltConfig;
+} EFI_HII_CONFIG_ROUTING_PROTOCOL;
+
+Description:
+This protocol defines the configuration routing interfaces between external applications and the HII. There may only be one instance of this protocol in the system.
+```
+
+# `HIIConfig.efi dump`
+
+First let's try to use the protocol `ExportConfig` function to dump the current HII configuration in the `UEFI Configuration Language` format:
+```
+EFI_HII_CONFIG_ROUTING_PROTOCOL.ExportConfig()
+
+Summary:
+This function allows the caller to request the current configuration for the entirety of the current HII database and returns the data in a null-terminated string.
+
+Prototype:
+
+typedef
+EFI_STATUS
+ (EFIAPI * EFI_HII_EXPORT_CONFIG ) (
+ IN CONST EFI_HII_CONFIG_ROUTING_PROTOCOL *This,
+ OUT EFI_STRING *Results
+ );
+
+Parameters:
+This		Points to the EFI_HII_CONFIG_ROUTING_PROTOCOL instance
+Results		A null-terminated string in <MultiConfigAltResp> format which has all values filled in for the entirety of the current HII database
+
+Description:
+This function allows the caller to request the current configuration for all of the current HII database. The results include both the current and alternate configurations
+```
+
+Create a Shell application `HIIConfig`. In the INF file add the `gEfiHiiConfigRoutingProtocolGuid` to the application protocols `UefiLessonsPkg/HIIConfig/HIIConfig.inf`:
+```
+[Defines]
+  INF_VERSION                    = 1.25
+  BASE_NAME                      = HIIConfig
+  FILE_GUID                      = 417bf8bf-05b6-4cb5-b6e1-ed41c1fc971d
+  MODULE_TYPE                    = UEFI_APPLICATION
+  VERSION_STRING                 = 1.0
+  ENTRY_POINT                    = ShellCEntryLib
+
+[Sources]
+  HIIConfig.c
+
+[Packages]
+  MdePkg/MdePkg.dec
+  MdeModulePkg/MdeModulePkg.dec
+
+[LibraryClasses]
+  ShellCEntryLib
+  UefiLib
+
+[Protocols]
+  gEfiHiiConfigRoutingProtocolGuid
+```
+
+In the `UefiLessonsPkg/HIIConfig/HIIConfig.c` locate this protocol and use its `ExportConfig` function if the application is called with a `dump` argument:
+```cpp
+#include <Library/UefiBootServicesTableLib.h>
+#include <Library/UefiLib.h>
+#include <Library/MemoryAllocationLib.h>
+#include <Protocol/HiiConfigRouting.h>
+
+
+VOID Usage()
+{
+  Print(L"Usage:\n");
+  Print(L"HIIConfig.efi dump\n");
+}
+
+INTN
+EFIAPI
+ShellAppMain (
+  IN UINTN Argc,
+  IN CHAR16 **Argv
+  )
+{
+  EFI_HII_CONFIG_ROUTING_PROTOCOL  *gHiiConfigRouting = NULL;
+  EFI_STATUS Status = gBS->LocateProtocol(&gEfiHiiConfigRoutingProtocolGuid,
+                                          NULL,
+                                          (VOID **)&gHiiConfigRouting);
+  if (EFI_ERROR(Status)) {
+    Print(L"Error! Can't locate gEfiHiiConfigRoutingProtocolGuid: %r", Status);
+    return Status;
+  }
+
+  if (Argc == 1) {
+    Usage();
+    return EFI_SUCCESS;
+  }
+
+  EFI_STRING Result;
+  if (!StrCmp(Argv[1], L"dump")) {
+    Status = gHiiConfigRouting->ExportConfig(gHiiConfigRouting, &Result);
+    Print(L"Full configuration for the HII Database (Size = %d):\n", StrLen(Result));
+    Print(L"%s\n", Result);
+    FreePool(Result);
+  }
+  return EFI_SUCCESS;
+}
+```
+As the `Result` string data is allocated on heap, we need to use `FreePool` to free this memory afterwards.
+
+Let's build and test this application:
+```
+FS0:\> HIIConfig.efi dump
+Full configuration for the HII Database (Size = 42018):
+GUID=1cc53572800cab4c87ac3b084a6304b1&NAME=004d00610069006e0046006f0072006d00530074006100740065&PATH=01041400dfc5dcd907405e4390988970935504b27fff0400&OFFSET=0000&WIDTH=0020&VALUE=00000000000000000000000000000000000000000000007400650073006e0055&OFFSET=0020&WIDTH=0004&VALUE=00000000&GUID=1cc53572800cab4c87ac3b084a6304b1&
+```
+Here is you first peak to the `UEFI Configuration language`.
+
+But something is wrong, can you see what?
+
+The string lenght of the response above is 42018, but the actual printed string is a way shorter than that. If you'll try to measure it, you'll see that it has exactly 320 symbols. Why is that?
+
+This is happening because the maximum printable number of characters in the `Print()` statement is limited by the `gEfiMdePkgTokenSpaceGuid.PcdUefiLibMaxPrintBufferSize` PCD. Check its definition in the [https://github.com/tianocore/edk2/blob/master/MdePkg/MdePkg.dec](https://github.com/tianocore/edk2/blob/master/MdePkg/MdePkg.dec):
+```
+  ## The maximum printable number of characters. UefLib functions: AsciiPrint(), AsciiErrorPrint(),
+  #  PrintXY(), AsciiPrintXY(), Print(), ErrorPrint() base on this PCD value to print characters.
+  # @Prompt Maximum Printable Number of Characters.
+  gEfiMdePkgTokenSpaceGuid.PcdUefiLibMaxPrintBufferSize|320|UINT32|0x101
+```
+If you want to see how it is used, check the `InternalPrint` function implementation in the [https://github.com/tianocore/edk2/blob/master/MdePkg/Library/UefiLib/UefiLibPrint.c](https://github.com/tianocore/edk2/blob/master/MdePkg/Library/UefiLib/UefiLibPrint.c).
+
+Anyway, to bypass this limit we can use the `gST->ConOut->OutputString` function directly like this:
+```
+  Print(L"Full configuration for the HII Database (Size = %d):\n", StrLen(Result));
+- Print(L"%s\n", Result);
++ gST->ConOut->OutputString(gST->ConOut, Results);
+```
+
+Now you can see the full output. Here I've truncated the bunch of zeros in part in the middle of the output. But even with this the output is very long:
+```
+Full configuration for the HII Database (Size = 42018):
+GUID=1cc53572800cab4c87ac3b084a6304b1&NAME=004d00610069006e0046006f0072006d00530074006100740065&PATH=01041400dfc5dcd907405e4390988970935504b27fff0400&OFFSET=0
+000&WIDTH=0020&VALUE=00000000000000000000000000000000000000000000007400650073006e0055&OFFSET=0020&WIDTH=0004&VALUE=00000000&GUID=1cc53572800cab4c87ac3b084a630
+4b1&NAME=004d00610069006e0046006f0072006d00530074006100740065&PATH=01041400dfc5dcd907405e4390988970935504b27fff0400&ALTCFG=0000&OFFSET=0020&WIDTH=0004&VALUE=0
+0000000&GUID=1cc53572800cab4c87ac3b084a6304b1&NAME=004d00610069006e0046006f0072006d00530074006100740065&PATH=01041400dfc5dcd907405e4390988970935504b27fff0400&
+ALTCFG=0001&OFFSET=0020&WIDTH=0004&VALUE=00000000&GUID=16d6474bd6a852459d44ccad2e0f4cf9&NAME=00490053004300530049005f0043004f004e004600490047005f0049004600520
+05f004e00560044004100540041&PATH=0104140016d6474bd6a852459d44ccad2e0f4cf97fff0400&OFFSET=0&WIDTH=000000000000453c&VALUE=00000000000000000000000000000000000000
+...
+... ton of zeros
+...
+000000000000000000&GUID=16d6474bd6a852459d44ccad2e0f4cf9&NAME=00490053004300530049005f0043004f004e004600490047005f004900460052005f004e00560044004100540041&PAT
+H=0104140016d6474bd6a852459d44ccad2e0f4cf97fff0400&ALTCFG=0000&OFFSET=01d8&WIDTH=0001&VALUE=00&OFFSET=01d9&WIDTH=0001&VALUE=00&OFFSET=01da&WIDTH=0001&VALUE=00
+&OFFSET=01dc&WIDTH=0002&VALUE=03e8&OFFSET=01de&WIDTH=0001&VALUE=00&OFFSET=01df&WIDTH=0001&VALUE=00&OFFSET=05fe&WIDTH=0002&VALUE=0000&OFFSET=062a&WIDTH=0001&VA
+LUE=00&OFFSET=062b&WIDTH=0001&VALUE=01&OFFSET=0fd4&WIDTH=0001&VALUE=00&OFFSET=0fd5&WIDTH=0001&VALUE=00&OFFSET=0fd6&WIDTH=0001&VALUE=00&OFFSET=0fd7&WIDTH=0001&
+VALUE=00&OFFSET=0fd8&WIDTH=0001&VALUE=00&OFFSET=0fd9&WIDTH=0001&VALUE=00&OFFSET=0fda&WIDTH=0001&VALUE=00&OFFSET=0fdb&WIDTH=0001&VALUE=00&OFFSET=0fdc&WIDTH=000
+1&VALUE=00&OFFSET=0fdd&WIDTH=0001&VALUE=00&OFFSET=0fde&WIDTH=0001&VALUE=00&OFFSET=0fdf&WIDTH=0001&VALUE=00&OFFSET=0fe0&WIDTH=0001&VALUE=00&OFFSET=0fe1&WIDTH=0
+001&VALUE=00&OFFSET=0fe2&WIDTH=0001&VALUE=00&OFFSET=0fe3&WIDTH=0001&VALUE=00&OFFSET=0fe4&WIDTH=0001&VALUE=00&OFFSET=0fe5&WIDTH=0001&VALUE=00&OFFSET=0fe6&WIDTH
+=0001&VALUE=00&OFFSET=0fe7&WIDTH=0001&VALUE=00&OFFSET=0fe8&WIDTH=0001&VALUE=00&OFFSET=0fe9&WIDTH=0001&VALUE=00&OFFSET=0fea&WIDTH=0001&VALUE=00&OFFSET=0feb&WID
+TH=0001&VALUE=00&OFFSET=0fec&WIDTH=0002&VALUE=0064&OFFSET=0fee&WIDTH=0002&VALUE=0064&OFFSET=0ff0&WIDTH=0002&VALUE=0064&OFFSET=0ff2&WIDTH=0002&VALUE=0064&OFFSE
+T=0ff4&WIDTH=0002&VALUE=0064&OFFSET=0ff6&WIDTH=0002&VALUE=0064&OFFSET=0ff8&WIDTH=0002&VALUE=0064&OFFSET=0ffa&WIDTH=0002&VALUE=0064&OFFSET=0ffc&WIDTH=0001&VALU
+E=00&OFFSET=0ffd&WIDTH=0001&VALUE=00&OFFSET=0ffe&WIDTH=0001&VALUE=00&OFFSET=0fff&WIDTH=0001&VALUE=00&OFFSET=1000&WIDTH=0001&VALUE=00&OFFSET=1001&WIDTH=0001&VA
+LUE=00&OFFSET=1002&WIDTH=0001&VALUE=00&OFFSET=1003&WIDTH=0001&VALUE=00&OFFSET=1004&WIDTH=0001&VALUE=00&OFFSET=1005&WIDTH=0001&VALUE=00&OFFSET=1006&WIDTH=0001&
+VALUE=00&OFFSET=1007&WIDTH=0001&VALUE=00&OFFSET=1008&WIDTH=0001&VALUE=00&OFFSET=1009&WIDTH=0001&VALUE=00&OFFSET=100a&WIDTH=0001&VALUE=00&OFFSET=100b&WIDTH=000
+1&VALUE=00&OFFSET=100c&WIDTH=0002&VALUE=0000&OFFSET=100e&WIDTH=0002&VALUE=0000&OFFSET=1010&WIDTH=0002&VALUE=0000&OFFSET=1012&WIDTH=0002&VALUE=0000&OFFSET=1014
+&WIDTH=0002&VALUE=0000&OFFSET=1016&WIDTH=0002&VALUE=0000&OFFSET=1018&WIDTH=0002&VALUE=0000&OFFSET=101a&WIDTH=0002&VALUE=0000&OFFSET=101c&WIDTH=0001&VALUE=00&O
+FFSET=101d&WIDTH=0001&VALUE=00&OFFSET=101e&WIDTH=0001&VALUE=00&OFFSET=101f&WIDTH=0001&VALUE=00&OFFSET=1020&WIDTH=0001&VALUE=00&OFFSET=1021&WIDTH=0001&VALUE=00
+&OFFSET=1022&WIDTH=0001&VALUE=00&OFFSET=1023&WIDTH=0001&VALUE=00&OFFSET=1024&WIDTH=0001&VALUE=00&OFFSET=1025&WIDTH=0001&VALUE=00&OFFSET=1026&WIDTH=0001&VALUE=
+00&OFFSET=1027&WIDTH=0001&VALUE=00&OFFSET=1028&WIDTH=0001&VALUE=00&OFFSET=1029&WIDTH=0001&VALUE=00&OFFSET=102a&WIDTH=0001&VALUE=00&OFFSET=102b&WIDTH=0001&VALU
+E=00&GUID=16d6474bd6a852459d44ccad2e0f4cf9&NAME=00490053004300530049005f0043004f004e004600490047005f004900460052005f004e00560044004100540041&PATH=0104140016d6
+474bd6a852459d44ccad2e0f4cf97fff0400&ALTCFG=0001&OFFSET=01d8&WIDTH=0001&VALUE=00&OFFSET=01d9&WIDTH=0001&VALUE=00&OFFSET=01da&WIDTH=0001&VALUE=00&OFFSET=01dc&W
+IDTH=0002&VALUE=03e8&OFFSET=01de&WIDTH=0001&VALUE=00&OFFSET=01df&WIDTH=0001&VALUE=00&OFFSET=05fe&WIDTH=0002&VALUE=0000&OFFSET=062a&WIDTH=0001&VALUE=00&OFFSET=
+062b&WIDTH=0001&VALUE=01&OFFSET=0fd4&WIDTH=0001&VALUE=00&OFFSET=0fd5&WIDTH=0001&VALUE=00&OFFSET=0fd6&WIDTH=0001&VALUE=00&OFFSET=0fd7&WIDTH=0001&VALUE=00&OFFSE
+T=0fd8&WIDTH=0001&VALUE=00&OFFSET=0fd9&WIDTH=0001&VALUE=00&OFFSET=0fda&WIDTH=0001&VALUE=00&OFFSET=0fdb&WIDTH=0001&VALUE=00&OFFSET=0fdc&WIDTH=0001&VALUE=00&OFF
+SET=0fdd&WIDTH=0001&VALUE=00&OFFSET=0fde&WIDTH=0001&VALUE=00&OFFSET=0fdf&WIDTH=0001&VALUE=00&OFFSET=0fe0&WIDTH=0001&VALUE=00&OFFSET=0fe1&WIDTH=0001&VALUE=00&O
+FFSET=0fe2&WIDTH=0001&VALUE=00&OFFSET=0fe3&WIDTH=0001&VALUE=00&OFFSET=0fe4&WIDTH=0001&VALUE=00&OFFSET=0fe5&WIDTH=0001&VALUE=00&OFFSET=0fe6&WIDTH=0001&VALUE=00
+&OFFSET=0fe7&WIDTH=0001&VALUE=00&OFFSET=0fe8&WIDTH=0001&VALUE=00&OFFSET=0fe9&WIDTH=0001&VALUE=00&OFFSET=0fea&WIDTH=0001&VALUE=00&OFFSET=0feb&WIDTH=0001&VALUE=
+00&OFFSET=0fec&WIDTH=0002&VALUE=0064&OFFSET=0fee&WIDTH=0002&VALUE=0064&OFFSET=0ff0&WIDTH=0002&VALUE=0064&OFFSET=0ff2&WIDTH=0002&VALUE=0064&OFFSET=0ff4&WIDTH=0
+002&VALUE=0064&OFFSET=0ff6&WIDTH=0002&VALUE=0064&OFFSET=0ff8&WIDTH=0002&VALUE=0064&OFFSET=0ffa&WIDTH=0002&VALUE=0064&OFFSET=0ffc&WIDTH=0001&VALUE=00&OFFSET=0f
+fd&WIDTH=0001&VALUE=00&OFFSET=0ffe&WIDTH=0001&VALUE=00&OFFSET=0fff&WIDTH=0001&VALUE=00&OFFSET=1000&WIDTH=0001&VALUE=00&OFFSET=1001&WIDTH=0001&VALUE=00&OFFSET=
+1002&WIDTH=0001&VALUE=00&OFFSET=1003&WIDTH=0001&VALUE=00&OFFSET=1004&WIDTH=0001&VALUE=00&OFFSET=1005&WIDTH=0001&VALUE=00&OFFSET=1006&WIDTH=0001&VALUE=00&OFFSE
+T=1007&WIDTH=0001&VALUE=00&OFFSET=1008&WIDTH=0001&VALUE=00&OFFSET=1009&WIDTH=0001&VALUE=00&OFFSET=100a&WIDTH=0001&VALUE=00&OFFSET=100b&WIDTH=0001&VALUE=00&OFF
+SET=100c&WIDTH=0002&VALUE=0000&OFFSET=100e&WIDTH=0002&VALUE=0000&OFFSET=1010&WIDTH=0002&VALUE=0000&OFFSET=1012&WIDTH=0002&VALUE=0000&OFFSET=1014&WIDTH=0002&VA
+LUE=0000&OFFSET=1016&WIDTH=0002&VALUE=0000&OFFSET=1018&WIDTH=0002&VALUE=0000&OFFSET=101a&WIDTH=0002&VALUE=0000&OFFSET=101c&WIDTH=0001&VALUE=00&OFFSET=101d&WID
+TH=0001&VALUE=00&OFFSET=101e&WIDTH=0001&VALUE=00&OFFSET=101f&WIDTH=0001&VALUE=00&OFFSET=1020&WIDTH=0001&VALUE=00&OFFSET=1021&WIDTH=0001&VALUE=00&OFFSET=1022&W
+IDTH=0001&VALUE=00&OFFSET=1023&WIDTH=0001&VALUE=00&OFFSET=1024&WIDTH=0001&VALUE=00&OFFSET=1025&WIDTH=0001&VALUE=00&OFFSET=1026&WIDTH=0001&VALUE=00&OFFSET=1027
+&WIDTH=0001&VALUE=00&OFFSET=1028&WIDTH=0001&VALUE=00&OFFSET=1029&WIDTH=0001&VALUE=00&OFFSET=102a&WIDTH=0001&VALUE=00&OFFSET=102b&WIDTH=0001&VALUE=00
+```
+
+It is almost impossible to find something in such output, so let's prettify it. For this we will write custom function `PrintConfigString`:
+```
+- gST->ConOut->OutputString(gST->ConOut, Result);
++ PrintConfigString(Result);
+```
+
+Before writing this function let's investigate the output above. As you can see the resulting string consists of pairs `<key>=<data>` delimited by the `&` character. And there only 6 keys in the whole output. Here are their meaning:
+```
+GUID   - guid of the FormSet
+NAME   - name of the variable storage inside the FormSet
+PATH   - device path
+ALTCFG - alternative configurations
+OFFSET - offset of the variable inside the storage
+WIDTH  - size of the variable inside the storage
+VALUE  - value of the variable inside the storage
+```
+
+They are combined like this:
+- The combination `GUID=<...>&NAME=<...>&PATH=<...>` is like a header for some storage configuration
+- Sometimes the header above can include `ALTCFG` at the end: `GUID=<...>&NAME=<...>&PATH=<...>&ALTCFG=<...>`
+- After the storage configuration header there are configuration elements. Every element is encoded via the `OFFSET=<...>&WIDTH=<...>&VALUE=<...>` configuration
+
+
+Now back to our pretty print task. In our `PrintConfigString` function we would split the configuration string by the keyword separator `&` and use another `PrintConfigSubString` function to print each `<key>=<data>` pair:
+```
+VOID PrintConfigString(
+  IN EFI_STRING ConfigString
+  )
+{
+  UINTN StartIndex=0;
+  for (UINTN i=0; ConfigString[i] != 0; i++) {
+    if (ConfigString[i] == L'&') {
+      ConfigString[i] = 0;
+      PrintConfigSubString(&ConfigString[StartIndex]);
+      StartIndex = i+1;
+    }
+  }
+  PrintConfigSubString(&ConfigString[StartIndex]);
+}
+```
+
+Here is how our `PrintConfigSubString` function would look like:
+```
+VOID PrintConfigSubString(
+  IN EFI_STRING ConfigString
+  )
+{
+  EFI_STATUS Status;
+  if (StrStr(ConfigString, L"GUID=")) {
+    <...>						// display the full string and actual guid
+  } else if (StrStr(ConfigString, L"NAME=")) {
+    <...>                                               // display the full string and actual name
+  } else if (StrStr(ConfigString, L"PATH=")) {
+    <...>
+  } else if (StrStr(ConfigString, L"VALUE=")) {
+    <...>                                               // display the full string and actual value
+  } else if (StrStr(ConfigString, L"OFFSET=") || StrStr(ConfigString, L"WIDTH=")) {
+    Print(L"%s  ", ConfigString);                       // don't print '\n', so we could see the "OFFSET=<...>  WIDTH=<...>  VALUE=<...>" on the same string
+  } else {
+    Print(L"%s\n", ConfigString);
+  }
+}
+```
+
+If the string starts with a `GUID=`/`NAME=`/`PATH=` we will parse the data and display actual GUID/Name/DevicePath in a readable standard format. If the string starts with `VALUE=` we would display its data as a hex buffer similar to hexdump.
+
+
+