写在前面

UEFI有自己的用户交互界面，它的实现基础被称为HII（Human Interface Infrastructure），本文是一系列介绍HII实现的第一篇。这里从开源EDK代码中的界面（称为Front Page）入手，介绍它的实现，并进一步说明整个HII。

之前已经写过一系列跟Setup相关的文档，内容有重复及补充。

入口说明

Front Page的实现代码可以在https://gitee.com/jiangwei0512/edk2-beni）找到，编译执行之后的结果大致如下：

它对应的是一个启动项程序UiApp，模块代码是MdeModulePkg\Application\UiApp\UiApp.inf，该模块的入口函数是InitializeUserInterface()（位于MdeModulePkg\Application\UiApp\FrontPage.c）。

初始化的大致流程如下：

上述流程中最主要的是两个部分，”初始化Front Page“和”显示Front Page“，对应到两个函数InitializeFrontPage()和CallFrontPage()，它们可以连起来看，主要做的事情就是两个：一个是准备素材，这里的素材指的是uni文件、vfr文件等表示的HII数据；另一个是显示这些素材，它通过一个EFI_FORM_BROWSER2_PROTOCOL来完成，这个Protocol提供两个接口，SendForm()用来显示配置好的HII，BrowserCallback()会被回调函数调用，用来获取和设置界面元素。

界面元素

在HII中构成一个界面的元素大致有四种，分别是字符串（Strings）、结构（Forms）、字体（Fonts）和图像（Images），如下图所示（最右边的Questions等是结构的组成部分，这里可以暂时不管，后续会介绍）：

字符串通过uni文件产生，结构通过vfr文件产生，字体暂不介绍，而图像则没有特别好介绍的。本例的Front Page中使用了结构、字符串和字体，图像则没有使用到。

元素更新

元素更新主要发生在InitializeFrontPage()函数中，对应的代码：

  ////Updata Front Page banner strings//UpdateFrontPageBannerStrings ();//// Update front page menus.//UpdateFrontPageForm();

• 前者UpdateFrontPageBannerStrings()主要是获取标记①（Token）对应的字符串的值并设置到对应的标记②中，它初始化Front Page的上半区静态部分：

以代码为例的话就像下面的那样：

    NewString = HiiGetString (gFrontPagePrivate.HiiHandle, STRING_TOKEN (STR_FRONT_PAGE_COMPUTER_MODEL), NULL);UiCustomizeFrontPageBanner (1, TRUE, &NewString);HiiSetString (gFrontPagePrivate.HiiHandle, STRING_TOKEN (STR_FRONT_PAGE_COMPUTER_MODEL), NewString, NULL);FreePool (NewString);

这里的标记STR_FRONT_PAGE_COMPUTER_MODEL出现了两次，虽然名字相同，但是是来自不同的文件，分别是uni文件中的：

#string STR_FRONT_PAGE_COMPUTER_MODEL  #language en-US  ""#language fr-FR  ""

和来自vfr文件中的：

    bannertitle = STRING_TOKEN(STR_FRONT_PAGE_COMPUTER_MODEL),line  1,align left;

标记①的操作通过HiiGetString()获取字符串，标记②的操作通过HiiSetString()设置字符串。不过两者本来就需要是一致的，所以也不需要特意去区分。

• 后者UpdateFrontPageForm()更新其它动态的部分，而动态的部分通过vfr文件查看可以看到它们位于两个操作码之间：

    label LABEL_FRANTPAGE_INFORMATION;//// This is where we will dynamically add a Action type op-code to show// the platform information.//label LABEL_END;

对应的代码：

VOID
UpdateFrontPageForm (VOID)
{VOID                        *StartOpCodeHandle;VOID                        *EndOpCodeHandle;EFI_IFR_GUID_LABEL          *StartGuidLabel;EFI_IFR_GUID_LABEL          *EndGuidLabel;//// Allocate space for creation of UpdateData Buffer//StartOpCodeHandle = HiiAllocateOpCodeHandle ();ASSERT (StartOpCodeHandle != NULL);EndOpCodeHandle = HiiAllocateOpCodeHandle ();ASSERT (EndOpCodeHandle != NULL);//// Create Hii Extend Label OpCode as the start opcode//StartGuidLabel = (EFI_IFR_GUID_LABEL *) HiiCreateGuidOpCode (StartOpCodeHandle, &gEfiIfrTianoGuid, NULL, sizeof (EFI_IFR_GUID_LABEL));StartGuidLabel->ExtendOpCode = EFI_IFR_EXTEND_OP_LABEL;StartGuidLabel->Number       = LABEL_FRANTPAGE_INFORMATION;  // 对应vfr中的LABEL_FRANTPAGE_INFORMATION//// Create Hii Extend Label OpCode as the end opcode//EndGuidLabel = (EFI_IFR_GUID_LABEL *) HiiCreateGuidOpCode (EndOpCodeHandle, &gEfiIfrTianoGuid, NULL, sizeof (EFI_IFR_GUID_LABEL));EndGuidLabel->ExtendOpCode = EFI_IFR_EXTEND_OP_LABEL;EndGuidLabel->Number       = LABEL_END;	// 对应vfr中的LABEL_END////Updata Front Page form//UiCustomizeFrontPage (gFrontPagePrivate.HiiHandle,StartOpCodeHandle);HiiUpdateForm (gFrontPagePrivate.HiiHandle,&mFrontPageGuid,FRONT_PAGE_FORM_ID,StartOpCodeHandle,EndOpCodeHandle);HiiFreeOpCodeHandle (StartOpCodeHandle);HiiFreeOpCodeHandle (EndOpCodeHandle);
}

这里的两个部分（StartOpCodeHandle和EndOpCodeHandle）组合构成了Front Page剩余的部分，其过程如下：

1. 通过函数HiiAllocateOpCodeHandle()创建两个OpCodeHandle，它们对应的是同一个结构体：

typedef struct {UINT8  *Buffer;UINTN  BufferSize;UINTN  Position;
} HII_LIB_OPCODE_BUFFER;

创建好之后的结构体中Buffer是一个大小为0x200字节的空间；BufferSize就是0x200；Position初始化为0，它相当于存放其它操作码的容器。

2. 创建两个OpCode，会使用到前面创建的OpCodeHandle：

StartGuidLabel = (EFI_IFR_GUID_LABEL *) HiiCreateGuidOpCode (StartOpCodeHandle, &gEfiIfrTianoGuid, NULL, sizeof (EFI_IFR_GUID_LABEL));
StartGuidLabel->ExtendOpCode = EFI_IFR_EXTEND_OP_LABEL;
StartGuidLabel->Number       = LABEL_FRANTPAGE_INFORMATION;

HiiCreateGuidOpCode()的第一个参数就是OpCodeHandle；第二个参数是一个GUID；第三个参数是可选的，可以是NULL；第四个参数是组件元素结构体的大小。本例创建了两个EFI_IFR_GUID_LABEL结构体（跟vfr文件中的label对应），它也是HiiCreateGuidOpCode()的返回值，其结构如下：

///
/// Label opcode.
///
typedef struct _EFI_IFR_GUID_LABEL {EFI_IFR_OP_HEADER   Header;////// EFI_IFR_TIANO_GUID.///EFI_GUID            Guid;////// EFI_IFR_EXTEND_OP_LABEL.///UINT8               ExtendOpCode;////// Label Number.///UINT16              Number;
} EFI_IFR_GUID_LABEL;

后面的两句代码用来初始化EFI_IFR_GUID_LABEL结构体的后两个参数，其中Number就对应到vfr文件中的label名，本例中分别是LABEL_FRANTPAGE_INFORMATION和LABEL_END。

3. 对OpCode的自定义，其实就是在StartOpCodeHandle和EndOpCodeHandle之间创建自定义的元素。
4. 更新Front Page结构，更新的部分就是前面代码中增加的自定义元素。
5. 释放资源。

这里最重要的是第3步，对应如下的函数：

VOID
UiCustomizeFrontPage (IN EFI_HII_HANDLE  HiiHandle,IN VOID            *StartOpCodeHandle)
{//// Create "Select Language" menu with Oneof opcode.//UiCreateLanguageMenu (HiiHandle, StartOpCodeHandle);//// Create empty line.//UiCreateEmptyLine(HiiHandle, StartOpCodeHandle);//// Find third party drivers which need to be shown in the front page.//UiListThirdPartyDrivers (HiiHandle, &gEfiIfrFrontPageGuid, NULL, StartOpCodeHandle);//// Create empty line.//UiCreateEmptyLine(HiiHandle, StartOpCodeHandle);//// Create "Continue" menu.//UiCreateContinueMenu(HiiHandle, StartOpCodeHandle);//// Create reset menu.//UiCreateResetMenu(HiiHandle, StartOpCodeHandle);
}

基本上图中显示的部分都有对应的函数，但是底部黑色部分并没有，它们是根据特定情况而产生的，比如<Enter>= Select Entry是因为UiCreateLanguageMenu()而显示的，而↑↓=Move Highlight只要有创建上述的元素就会有显示。动作显示的组件有一个包含的关系，如下图所示：

后面的小节介绍如何创建图中的动态显示部分。

创建菜单

UiCreateLanguageMenu()的具体的代码：

VOID
UiCreateLanguageMenu (IN EFI_HII_HANDLE              HiiHandle,IN VOID                        *StartOpCodeHandle)
{CHAR8                       *LangCode;CHAR8                       *Lang;UINTN                       LangSize;CHAR8                       *CurrentLang;UINTN                       OptionCount;CHAR16                      *StringBuffer;VOID                        *OptionsOpCodeHandle;UINTN                       StringSize;EFI_STATUS                  Status;EFI_HII_STRING_PROTOCOL     *HiiString;Lang         = NULL;StringBuffer = NULL;//// Init OpCode Handle and Allocate space for creation of UpdateData Buffer//OptionsOpCodeHandle = HiiAllocateOpCodeHandle ();ASSERT (OptionsOpCodeHandle != NULL);GetEfiGlobalVariable2 (L"PlatformLang", (VOID**)&CurrentLang, NULL);//// Get Support language list from variable.//GetEfiGlobalVariable2 (L"PlatformLangCodes", (VOID**)&gLanguageString, NULL);if (gLanguageString == NULL) {gLanguageString = AllocateCopyPool (AsciiStrSize ((CHAR8 *) PcdGetPtr (PcdUefiVariableDefaultPlatformLangCodes)),(CHAR8 *) PcdGetPtr (PcdUefiVariableDefaultPlatformLangCodes));ASSERT (gLanguageString != NULL);}if (gLanguageToken == NULL) {//// Count the language list number.//LangCode = gLanguageString;Lang = AllocatePool (AsciiStrSize (gLanguageString));ASSERT (Lang != NULL);OptionCount = 0;while (*LangCode != 0) {GetNextLanguage (&LangCode, Lang);OptionCount ++;}//// Allocate extra 1 as the end tag.//gLanguageToken = AllocateZeroPool ((OptionCount + 1) * sizeof (EFI_STRING_ID));ASSERT (gLanguageToken != NULL);Status = gBS->LocateProtocol (&gEfiHiiStringProtocolGuid, NULL, (VOID **) &HiiString);ASSERT_EFI_ERROR (Status);LangCode     = gLanguageString;OptionCount  = 0;while (*LangCode != 0) {GetNextLanguage (&LangCode, Lang);StringSize = 0;Status = HiiString->GetString (HiiString, Lang, HiiHandle, PRINTABLE_LANGUAGE_NAME_STRING_ID, StringBuffer, &StringSize, NULL);if (Status == EFI_BUFFER_TOO_SMALL) {StringBuffer = AllocateZeroPool (StringSize);ASSERT (StringBuffer != NULL);Status = HiiString->GetString (HiiString, Lang, HiiHandle, PRINTABLE_LANGUAGE_NAME_STRING_ID, StringBuffer, &StringSize, NULL);ASSERT_EFI_ERROR (Status);}if (EFI_ERROR (Status)) {LangSize = AsciiStrSize (Lang);StringBuffer = AllocatePool (LangSize * sizeof (CHAR16));ASSERT (StringBuffer != NULL);AsciiStrToUnicodeStrS (Lang, StringBuffer, LangSize);}ASSERT (StringBuffer != NULL);gLanguageToken[OptionCount] = HiiSetString (HiiHandle, 0, StringBuffer, NULL);FreePool (StringBuffer);OptionCount++;}}ASSERT (gLanguageToken != NULL);LangCode = gLanguageString;OptionCount = 0;if (Lang == NULL) {Lang = AllocatePool (AsciiStrSize (gLanguageString));ASSERT (Lang != NULL);}while (*LangCode != 0) {GetNextLanguage (&LangCode, Lang);if (CurrentLang != NULL && AsciiStrCmp (Lang, CurrentLang) == 0) {HiiCreateOneOfOptionOpCode (OptionsOpCodeHandle,gLanguageToken[OptionCount],EFI_IFR_OPTION_DEFAULT,EFI_IFR_NUMERIC_SIZE_1,(UINT8) OptionCount);gCurrentLanguageIndex = (UINT8) OptionCount;} else {HiiCreateOneOfOptionOpCode (OptionsOpCodeHandle,gLanguageToken[OptionCount],0,EFI_IFR_NUMERIC_SIZE_1,(UINT8) OptionCount);}OptionCount++;}if (CurrentLang != NULL) {FreePool (CurrentLang);}FreePool (Lang);HiiCreateOneOfOpCode (StartOpCodeHandle,FRONT_PAGE_KEY_LANGUAGE,0,0,STRING_TOKEN (STR_LANGUAGE_SELECT),STRING_TOKEN (STR_LANGUAGE_SELECT_HELP),EFI_IFR_FLAG_CALLBACK,EFI_IFR_NUMERIC_SIZE_1,OptionsOpCodeHandle,NULL);
}

这里的大部分代码只是创建选项时需要使用的数据，可以不同特别关注，这里的重要步骤起始只有两个：

1. 创建一个新的HII_LIB_OPCODE_BUFFER，用来存放单选项，单选项通过HiiCreateOneOfOptionOpCode()函数放到HII_LIB_OPCODE_BUFFER中；
2. 将存放了单选项的HII_LIB_OPCODE_BUFFER，构建成一个单选框，存放到上一层的HII_LIB_OPCODE_BUFFER中。

创建空行

空行对应到这里的是一个EFI_IFR_SUBTITLE_OP（Subtitle statement），对应的结构体：

typedef struct _EFI_IFR_SUBTITLE {EFI_IFR_OP_HEADER        Header;EFI_IFR_STATEMENT_HEADER Statement;UINT8                    Flags;
} EFI_IFR_SUBTITLE;

但是没有实际的数据，就变成了一个空行，注意创建时的参数都是0：

VOID
UiCreateEmptyLine (IN EFI_HII_HANDLE              HiiHandle,IN VOID                        *StartOpCodeHandle)
{HiiCreateSubTitleOpCode (StartOpCodeHandle, STRING_TOKEN (STR_NULL_STRING), 0, 0, 0);
}

创建第三方驱动使用的界面

执行流程：

最终的操作也是创建操作码：

    HiiCreateGotoExOpCode (StartOpCodeHandle,0,gHiiDriverList[Index].PromptId,gHiiDriverList[Index].HelpId,0,(EFI_QUESTION_ID) (Index + FRONT_PAGE_KEY_DRIVER),0,&gHiiDriverList[Index].FormSetGuid,gHiiDriverList[Index].DevicePathId);

对应的操作码可能是EFI_IFR_REF_OP、EFI_IFR_REF2_OP、EFI_IFR_REF3_OP和EFI_IFR_REF4_OP，这依赖于传入的参数值。

创建Continue/reset菜单

两者对应的都是EFI_IFR_ACTION_OP操作码，对应的实现：

/**Create continue menu in the front page.@param[in]    HiiHandle           The hii handle for the Uiapp driver.@param[in]    StartOpCodeHandle   The opcode handle to save the new opcode.**/
VOID
UiCreateContinueMenu (IN EFI_HII_HANDLE              HiiHandle,IN VOID                        *StartOpCodeHandle)
{HiiCreateActionOpCode (StartOpCodeHandle,FRONT_PAGE_KEY_CONTINUE,STRING_TOKEN (STR_CONTINUE_PROMPT),STRING_TOKEN (STR_CONTINUE_PROMPT),EFI_IFR_FLAG_CALLBACK,0);
}/**Create Reset menu in the front page.@param[in]    HiiHandle           The hii handle for the Uiapp driver.@param[in]    StartOpCodeHandle   The opcode handle to save the new opcode.**/
VOID
UiCreateResetMenu (IN EFI_HII_HANDLE              HiiHandle,IN VOID                        *StartOpCodeHandle)
{HiiCreateActionOpCode (StartOpCodeHandle,FRONT_PAGE_KEY_RESET,STRING_TOKEN (STR_RESET_STRING),STRING_TOKEN (STR_RESET_STRING),EFI_IFR_FLAG_CALLBACK,0);
}

从代码中可以看到，差别只在显示和QuestionId，后者在回调函数中判断其值并执行不同的操作，其代码在UiSupportLibCallbackHandler()，部分代码如下：

    switch (QuestionId) {case FRONT_PAGE_KEY_CONTINUE://// This is the continue - clear the screen and return an error to get out of FrontPage loop//*ActionRequest = EFI_BROWSER_ACTION_REQUEST_EXIT;break;case FRONT_PAGE_KEY_LANGUAGE:*Status = LanguageChangeHandler(Value);break;case FRONT_PAGE_KEY_RESET://// Reset//gRT->ResetSystem (EfiResetCold, EFI_SUCCESS, 0, NULL);*Status = EFI_UNSUPPORTED;default:break;}