The `ExportConfig` function dumps configuration for the entirety of the current HII database. We've prettified that output, but it is still cumbersome to use it if we just want to check a single configuration value. For this task we can utilize the `EFI_HII_CONFIG_ROUTING_PROTOCOL.ExtractConfig()` function: ``` EFI_HII_CONFIG_ROUTING_PROTOCOL.ExtractConfig() Summary: This function allows a caller to extract the current configuration for one or more named elements from one or more drivers. Prototype: typedef EFI_STATUS (EFIAPI * EFI_HII_EXTRACT_CONFIG ) ( IN CONST EFI_HII_CONFIG_ROUTING_PROTOCOL *This, IN CONST EFI_STRING Request, OUT EFI_STRING *Progress, OUT EFI_STRING *Results ); Parameters: This Points to the EFI_HII_CONFIG_ROUTING_PROTOCOL instance Request A null-terminated string in format Progress On return, points to a character in the Request string. Points to the string’s null terminator if request was successful Points to the most recent ‘&’ before the first failing name / value pair (or the beginning of the string if the failure is in the first name / value pair) if the request was not successful Results A null-terminated string in format which has all values filled in for the names in the Request string Description: This function allows the caller to request the current configuration for one or more named elements from one or more drivers. The resulting string is in the standard HII configuration string format. ``` Our goal in this lesson is to add 3 methods to get a configuration setting: - by providing a full config request string - by providing config header values (GUID/NAME/PATH) in a readable format to get all settings for the corresponding storage - by providing config header values (GUID/NAME/PATH) in a readable format and OFFSET and WIDTH data to get some individual setting from the corresponding storage So our help message in this lesson would be updated to this: ```cpp VOID Usage() { Print(L"Usage:\n"); Print(L"HIIConfig.efi dump\n"); Print(L"HIIConfig.efi extract \n"); Print(L"HIIConfig.efi extract \n"); Print(L"HIIConfig.efi extract \n"); } ``` # `HIIConfig.efi extract ` Let's stars with the `HIIConfig.efi extract ` handler. It can be implemented like this: ```cpp EFI_STRING Request; EFI_STRING Progress; EFI_STRING Result; if (!StrCmp(Argv[1], L"dump")) { <...> } else if (!StrCmp(Argv[1], L"extract")) { if (Argc == 3) { // <--- HIIConfig.efi extract Request = Argv[2]; } else { Print(L"Error! Wrong arguments\n"); Usage(); return EFI_INVALID_PARAMETER; } Status = gHiiConfigRouting->ExtractConfig(gHiiConfigRouting, Request, &Progress, &Result); if (StrCmp(Progress, L'\0')) { Print(L"Part of string was unparsed %s\n", Progress); } if (EFI_ERROR(Status)) { Print(L"Error! ExtractConfig returned %r\n", Status); return Status; } Print(L"Response: "); PrintLongString(Result); Print(L"\n\n"); PrintConfigString(Result); FreePool(Result); } ``` The `ExtractConfig` function parses incoming request string sequentially, that is why there is a real possibility, that only the part of the string would be parsed. This is why we need to check the `Progress` data after the call. If some part of string wouldn't be parsed, this part would be returned in the `Progress`. The result is encoded in the configuration string, so we first print it as a long string via our `PrintLongString` function and then parse the output via our `PrintConfigString` function. In the end we need to free `Result` string as it was allocated on heap by the `ExtractConfig` call. We don't need to free the `Progress` string as it is just a pointer to the data in the `Result` string. For the test let's constuct a requst string from the data in the output of the `dump` command. If you remember at the beginning it displays `MainFormState` configuration: ``` FS0:\> HIIConfig.efi dump Full configuration for the HII Database (Size = 42018): GUID=1cc53572800cab4c87ac3b084a6304b1 (7235C51C-0C80-4CAB-87AC-3B084A6304B1) NAME=004d00610069006e0046006f0072006d00530074006100740065 (MainFormState) PATH=01041400dfc5dcd907405e4390988970935504b27fff0400 (VenHw(D9DCC5DF-4007-435E-9098-8970935504B2)) OFFSET=0000 WIDTH=0020 VALUE=00000000000000000000000000000000000000000000007400650073006e0055 55 00 6E 00 73 00 65 00 74 00 00 00 00 00 00 00 | U.n.s.e.t....... 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 | ................ OFFSET=0020 WIDTH=0004 VALUE=00000000 00 00 00 00 | .... GUID=1cc53572800cab4c87ac3b084a6304b1 (7235C51C-0C80-4CAB-87AC-3B084A6304B1) NAME=004d00610069006e0046006f0072006d00530074006100740065 (MainFormState) PATH=01041400dfc5dcd907405e4390988970935504b27fff0400 (VenHw(D9DCC5DF-4007-435E-9098-8970935504B2)) ALTCFG=0000 OFFSET=0020 WIDTH=0004 VALUE=00000000 00 00 00 00 | .... GUID=1cc53572800cab4c87ac3b084a6304b1 (7235C51C-0C80-4CAB-87AC-3B084A6304B1) NAME=004d00610069006e0046006f0072006d00530074006100740065 (MainFormState) PATH=01041400dfc5dcd907405e4390988970935504b27fff0400 (VenHw(D9DCC5DF-4007-435E-9098-8970935504B2)) ALTCFG=0001 OFFSET=0020 WIDTH=0004 VALUE=00000000 00 00 00 00 | .... <...> ``` So let's use the data from the output to construct our request string: ``` FS0:\> HIIConfig.efi extract GUID=1cc53572800cab4c87ac3b084a6304b1&NAME=004d00610069006e0046006f0072006d00530074006100740065&PATH=01041400dfc5dcd907405e4390988970935504b27fff0400 Response: GUID=1cc53572800cab4c87ac3b084a6304b1&NAME=004d00610069006e0046006f0072006d00530074006100740065&PATH=01041400dfc5dcd907405e4390988970935504b27fff0400&OFFSET=0000&WIDTH=0020&VALUE=00000000000000000000000000000000000000000000007400650073006e0055&OFFSET=0020&WIDTH=0004&VALUE=00000000&GUID=1cc53572800cab4c87ac3b084a6<...> GUID=1cc53572800cab4c87ac3b084a6304b1 (7235C51C-0C80-4CAB-87AC-3B084A6304B1) NAME=004d00610069006e0046006f0072006d00530074006100740065 (MainFormState) PATH=01041400dfc5dcd907405e4390988970935504b27fff0400 (VenHw(D9DCC5DF-4007-435E-9098-8970935504B2)) OFFSET=0000 WIDTH=0020 VALUE=00000000000000000000000000000000000000000000007400650073006e0055 55 00 6E 00 73 00 65 00 74 00 00 00 00 00 00 00 | U.n.s.e.t....... 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 | ................ OFFSET=0020 WIDTH=0004 VALUE=00000000 00 00 00 00 | .... GUID=1cc53572800cab4c87ac3b084a6304b1 (7235C51C-0C80-4CAB-87AC-3B084A6304B1) NAME=004d00610069006e0046006f0072006d00530074006100740065 (MainFormState) PATH=01041400dfc5dcd907405e4390988970935504b27fff0400 (VenHw(D9DCC5DF-4007-435E-9098-8970935504B2)) ALTCFG=0000 OFFSET=0020 WIDTH=0004 VALUE=00000000 00 00 00 00 | .... FS0:\> c53572800cab4c87ac3b084a6304b1 (7235C51C-0C80-4CAB-87AC-3B084A6304B1) NAME=004d00610069006e0046006f0072006d00530074006100740065 (MainFormState) PATH=01041400dfc5dcd907405e4390988970935504b27fff0400 (VenHw(D9DCC5DF-4007-435E-9098-8970935504B2)) ALTCFG=0001 OFFSET=0020 WIDTH=0004 VALUE=00000000 00 00 00 00 | .... ``` Here you can see that the `MainFormState` output is the same that was in the case of a `dump` command, but now the output string contains ONLY the `MainFormState` output. Before diving into the various configuration requests let's add more methods to call our program that would simplify our life. # `HIIConfig.efi extract ` Usually you know `Guid`/`Name`/`DevicePath` values in their standard format, and it is not easy to convert them to their respective configuration string format. So let's write a code that would do it programmatically. This would allow us to call our program with something like this: ``` FS0:\> HIIConfig.efi extract 7235C51C-0C80-4CAB-87AC-3B084A6304B1 MainFormState VenHw(D9DCC5DF-4007-435E-9098-8970935504B2) ``` Let's update our application to support such call. Here I've marked places that were updated: ```cpp EFI_STRING Request; EFI_STRING Progress; EFI_STRING Result; if (!StrCmp(Argv[1], L"dump")) { <...> } else if (!StrCmp(Argv[1], L"extract")) { if (Argc == 3) { Request = Argv[2]; } else if (Argc == 5) { // <--- HIIConfig.efi extract Status = CreateCfgHeader(Argv[2], Argv[3], Argv[4], &Request); if (EFI_ERROR(Status)) { return Status; } Print(L"Request: %s\n", Request); } else { Print(L"Error! Wrong arguments\n"); Usage(); return EFI_INVALID_PARAMETER; } Status = gHiiConfigRouting->ExtractConfig(gHiiConfigRouting, Request, &Progress, &Result); if (StrCmp(Progress, L'\0')) { Print(L"Part of string was unparsed %s\n", Progress); } if (Argc == 5) // <--- if Request string was allocated on heap we need to free it FreePool(Request); if (EFI_ERROR(Status)) { Print(L"Error! ExtractConfig returned %r\n", Status); return Status; } Print(L"Response: "); PrintLongString(Result); Print(L"\n\n"); PrintConfigString(Result); FreePool(Result); } ``` Here we use the custom `CreateCfgHeader` function to create `GUID=&NAME=&PATH=` request. To do it our function would utilize `HiiConstructConfigHdr` function from the `HiiLib` [https://github.com/tianocore/edk2/blob/master/MdeModulePkg/Library/UefiHiiLib/HiiLib.c](https://github.com/tianocore/edk2/blob/master/MdeModulePkg/Library/UefiHiiLib/HiiLib.c): ```cpp /** Allocates and returns a Null-terminated Unicode string using routing information that includes a GUID, an optional Unicode string name, and a device path. The string returned is allocated with AllocatePool(). The caller is responsible for freeing the allocated string with FreePool(). The format of a is as follows: GUID=32&NAME=NameLength&PATH=DevicePathSize @param[in] Guid Pointer to an EFI_GUID that is the routing information GUID. Each of the 16 bytes in Guid is converted to a 2 Unicode character hexadecimal string. This is an optional parameter that may be NULL. @param[in] Name Pointer to a Null-terminated Unicode string that is the routing information NAME. This is an optional parameter that may be NULL. Each 16-bit Unicode character in Name is converted to a 4 character Unicode hexadecimal string. @param[in] DriverHandle The driver handle which supports a Device Path Protocol that is the routing information PATH. Each byte of the Device Path associated with DriverHandle is converted to a 2 Unicode character hexadecimal string. @retval NULL DriverHandle does not support the Device Path Protocol. @retval Other A pointer to the Null-terminate Unicode string **/ EFI_STRING EFIAPI HiiConstructConfigHdr ( IN CONST EFI_GUID *Guid OPTIONAL, IN CONST CHAR16 *Name OPTIONAL, IN EFI_HANDLE DriverHandle ) ``` As we would use HII library, don't forget to add `HiiLib` to the `[LibraryClasses]` in the `UefiLessonsPkg/HIIConfig/HIIConfig.inf` file and add the `#include ` statement to the `UefiLessonsPkg/HIIConfig/HIIConfig.c` file. To call the `HiiConstructConfigHdr` function we need to have 3 parameters: GUID, Name and a DriverHandle. Here is how we get them: - to get `Guid` we can utilize `StrToGuid` converter function, - we can get `Name` as-is from the `Argv`, - to get `DriverHandle` we construct `EFI_DEVICE_PATH_PROTOCOL` structure from the argumat via the `ConvertTextToDevicePath` function and than use this device path in the `LocateDevicePath` boot service: ``` EFI_BOOT_SERVICES.LocateDevicePath() Summary: Locates the handle to a device on the device path that supports the specified protocol. Prototype: typedef EFI_STATUS (EFIAPI *EFI_LOCATE_DEVICE_PATH) ( IN EFI_GUID *Protocol, IN OUT EFI_DEVICE_PATH_PROTOCOL **DevicePath, OUT EFI_HANDLE *Device ); Parameters: Protocol The protocol to search for DevicePath On input, a pointer to a pointer to the device path. On output, the device path pointer is modified to point to the remaining part of the device path—that is, when the function finds the closest handle, it splits the device path into two parts, stripping off the front part, and returning the remaining portion Device A pointer to the returned device handle Description: The LocateDevicePath() function locates all devices on DevicePath that support Protocol and returns the handle to the device that is closest to DevicePath. DevicePath is advanced over the device path nodes that were matched. ``` The complete code for the `CreateCfgHeader` looks like this: ```cpp EFI_STATUS CreateCfgHeader(EFI_STRING GuidStr, EFI_STRING NameStr, EFI_STRING DevicePathStr, EFI_STRING* Request) { EFI_STATUS Status; EFI_GUID FormsetGuid; Status = StrToGuid(GuidStr, &FormsetGuid); if (Status != RETURN_SUCCESS) { Print(L"Error! Can't convert argument to GUID\n"); return EFI_INVALID_PARAMETER; } EFI_HANDLE DriverHandle = NULL; EFI_DEVICE_PATH_PROTOCOL* DevicePath = ConvertTextToDevicePath(DevicePathStr); Status = gBS->LocateDevicePath(&gEfiDevicePathProtocolGuid, &DevicePath, &DriverHandle ); FreePool(DevicePath); if (EFI_ERROR(Status) || (DriverHandle == NULL)) { Print(L"Error! Can't get DriverHandle\n"); return EFI_INVALID_PARAMETER; } *Request = HiiConstructConfigHdr(&FormsetGuid, NameStr, DriverHandle); return EFI_SUCCESS; } ``` Build and test the new command: ``` FS0:\> HIIConfig.efi extract 7235C51C-0C80-4CAB-87AC-3B084A6304B1 MainFormState VenHw(D9DCC5DF-4007-435E-9098-8970935504B2) Request: GUID=1cc53572800cab4c87ac3b084a6304b1&NAME=004d00610069006e0046006f0072006d00530074006100740065&PATH=01041400dfc5dcd907405e4390988970935504b27fff0400 Response: GUID=1cc53572800cab4c87ac3b084a6304b1&NAME=004d00610069006e0046006f0072006d00530074006100740065&PATH=01041400dfc5dcd907405e4390988970935504b27fff0400&OFFSET=0000&WIDTH=0020&VALUE=00000000000000000000000000000000000000000000007400650073006e0055&OFFSET=0020&WIDTH=0004&VALUE=00000000&GUID=1cc53572800cab4c87ac3b084a6<...> GUID=1cc53572800cab4c87ac3b084a6304b1 (7235C51C-0C80-4CAB-87AC-3B084A6304B1) NAME=004d00610069006e0046006f0072006d00530074006100740065 (MainFormState) PATH=01041400dfc5dcd907405e4390988970935504b27fff0400 (VenHw(D9DCC5DF-4007-435E-9098-8970935504B2)) OFFSET=0000 WIDTH=0020 VALUE=00000000000000000000000000000000000000000000007400650073006e0055 55 00 6E 00 73 00 65 00 74 00 00 00 00 00 00 00 | U.n.s.e.t....... 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 | ................ OFFSET=0020 WIDTH=0004 VALUE=00000000 00 00 00 00 | .... GUID=1cc53572800cab4c87ac3b084a6304b1 (7235C51C-0C80-4CAB-87AC-3B084A6304B1) NAME=004d00610069006e0046006f0072006d00530074006100740065 (MainFormState) PATH=01041400dfc5dcd907405e4390988970935504b27fff0400 (VenHw(D9DCC5DF-4007-435E-9098-8970935504B2)) ALTCFG=0000 OFFSET=0020 WIDTH=0004 VALUE=00000000 00 00 00 00 | .... GUID=1cc53572800cab4c87ac3b084a6304b1 (7235C51C-0C80-4CAB-87AC-3B084A6304B1) NAME=004d00610069006e0046006f0072006d00530074006100740065 (MainFormState) PATH=01041400dfc5dcd907405e4390988970935504b27fff0400 (VenHw(D9DCC5DF-4007-435E-9098-8970935504B2)) ALTCFG=0001 OFFSET=0020 WIDTH=0004 VALUE=00000000 00 00 00 00 | .... ``` The output is the same as before, so our code works correctly. # `HIIConfig.efi extract ` It is possible to limit the configuration response to specific part of the storage if you supply `...&OFFSET=&WIDTH=` in the request. For example: ``` FS0:\> HIIConfig.efi extract GUID=1cc53572800cab4c87ac3b084a6304b1&NAME=004d00610069006e0046006f0072006d00530074006100740065&PATH=01041400dfc5dcd907405e4390988970935504b27fff0400&OFFSET=0000&WIDTH=0020 Response: GUID=1cc53572800cab4c87ac3b084a6304b1&NAME=004d00610069006e0046006f0072006d00530074006100740065&PATH=01041400dfc5dcd907405e4390988970935504b27fff0400&OFFSET=0000&WIDTH=0020&VALUE=00000000000000000000000000000000000000000000007400650073006e0055 GUID=1cc53572800cab4c87ac3b084a6304b1 (7235C51C-0C80-4CAB-87AC-3B084A6304B1) NAME=004d00610069006e0046006f0072006d00530074006100740065 (MainFormState) PATH=01041400dfc5dcd907405e4390988970935504b27fff0400 (VenHw(D9DCC5DF-4007-435E-9098-8970935504B2)) OFFSET=0000 WIDTH=0020 VALUE=00000000000000000000000000000000000000000000007400650073006e0055 55 00 6E 00 73 00 65 00 74 00 00 00 00 00 00 00 | U.n.s.e.t....... 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 | ................ ``` Once again it is kinda hard to create configuration string if you know Guid/Name/DevicePath in their usual format. So let's create one more `extract` command call option in our program: ``` HIIConfig.efi extract ``` To simplify things we wouldn't perform any processing on the `` and `` arguments, so you need to provide them exactly as they would go to the request. So to mimic request above you should write arguments like this: ``` HIIConfig.efi extract 7235C51C-0C80-4CAB-87AC-3B084A6304B1 MainFormState VenHw(D9DCC5DF-4007-435E-9098-8970935504B2) 0000 0020 ``` But in case of the UEFI configuration language the leading zeros are not mandatory, so you can use something like this: ``` HIIConfig.efi extract 7235C51C-0C80-4CAB-87AC-3B084A6304B1 MainFormState VenHw(D9DCC5DF-4007-435E-9098-8970935504B2) 0 20 ``` In other way you should provide `` and `` arguments in hex without leading `0x` letters. To handle our new command we update our code like this: ```cpp EFI_STRING Request; EFI_STRING Progress; EFI_STRING Result; if (!StrCmp(Argv[1], L"dump")) { <...> } else if (!StrCmp(Argv[1], L"extract")) { if (Argc == 3) { Request = Argv[2]; } else if ((Argc == 5) || (Argc == 7)) { <---- create CfgHeader Status = CreateCfgHeader(Argv[2], Argv[3], Argv[4], &Request); if (EFI_ERROR(Status)) { return Status; } if (Argc == 7) { <---- append it with `&OFFSET=&WIDTH=` string EFI_STRING OffsetStr = Argv[5]; EFI_STRING WidthStr = Argv[6]; UINTN Size = (StrLen(Request) + StrLen(L"&OFFSET=") + StrLen(OffsetStr) + StrLen(L"&WIDTH=") + StrLen(WidthStr) + 1) * sizeof(CHAR16); EFI_STRING TempRequest = AllocateZeroPool(Size); UnicodeSPrint(TempRequest, Size, L"%s&OFFSET=%s&WIDTH=%s", Request, OffsetStr, WidthStr); FreePool(Request); Request = TempRequest; } Print(L"Request: %s\n", Request); } else { Print(L"Error! Wrong arguments\n"); Usage(); return EFI_INVALID_PARAMETER; } Status = gHiiConfigRouting->ExtractConfig(gHiiConfigRouting, Request, &Progress, &Result); if (StrCmp(Progress, L'\0')) { Print(L"Part of string was unparsed %s\n", Progress); } if (Argc >= 5) <---- don't forget to free dynamically allocated request string FreePool(Request); if (EFI_ERROR(Status)) { Print(L"Error! ExtractConfig returned %r\n", Status); return Status; } Print(L"Response: "); PrintLongString(Result); Print(L"\n\n"); PrintConfigString(Result); FreePool(Result); } ``` Let's build our application and test new functionality: ``` FS0:\> HIIConfig.efi extract 7235C51C-0C80-4CAB-87AC-3B084A6304B1 MainFormState VenHw(D9DCC5DF-4007-435E-9098-8970935504B2) 0 20 Request: GUID=1cc53572800cab4c87ac3b084a6304b1&NAME=004d00610069006e0046006f0072006d00530074006100740065&PATH=01041400dfc5dcd907405e4390988970935504b27fff0400&OFFSET=0&WIDTH=20 Response: GUID=1cc53572800cab4c87ac3b084a6304b1&NAME=004d00610069006e0046006f0072006d00530074006100740065&PATH=01041400dfc5dcd907405e4390988970935504b27fff0400&OFFSET=0&WIDTH=20&VALUE=00000000000000000000000000000000000000000000007400650073006e0055 GUID=1cc53572800cab4c87ac3b084a6304b1 (7235C51C-0C80-4CAB-87AC-3B084A6304B1) NAME=004d00610069006e0046006f0072006d00530074006100740065 (MainFormState) PATH=01041400dfc5dcd907405e4390988970935504b27fff0400 (VenHw(D9DCC5DF-4007-435E-9098-8970935504B2)) OFFSET=0 WIDTH=20 VALUE=00000000000000000000000000000000000000000000007400650073006e0055 55 00 6E 00 73 00 65 00 74 00 00 00 00 00 00 00 | U.n.s.e.t....... 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 | ................ ``` As you see everything works exactly as with the manual configuration string.