【UEFI实战】UEFI用户交互界面使用说明之UNI文件

- 日理万妓 2024-02-18 19:23 110阅读 0赞

## 综述 ##

UEFI用户交互界面的实现涉及到多种不同类型的文件，这里要讲的是UNI文件，它也是其中最简单的一种。本文主要参考自《edk-ii-uni-specification.pdf》（以下简称参考文档）。它可以在[EDK II Specifications · tianocore/tianocore.github.io Wiki · GitHub][EDK II Specifications _ tianocore_tianocore.github.io Wiki _ GitHub]下载到。文本的代码示例来自EDK2017，由于版本更新等原因，示例中的代码可能跟实际GIT库中的代码有一定的差异。

## 作用 ##

关于UNI文件的作用，在参考文档中做了如下的说明：

![20180405213219900][]

就是说，UNI提供了一系列的标记（Token）用来表示文本，这些文本可以有不同的实现（比如可以使用不同的语言，不同的编码格式），但是在代码调用中都可以使用统一的标记来表示。以之前在**[【UEFI实战】UEFI用户交互界面使用说明][UEFI_UEFI]**中的图示为例：

![20180405213659910][]

这里的Select Language就是一个在UNI文件中定义的标记（具体在FrontPageStrings.uni文件中）：

![20180405213927313][]

可以看到，这里实际上支持两种语言，一种是英语一种是法语，所以我们的Front Page中可以进行切换：

![20180405214046961][]

而在我们的代码中，实际上使用的是STR\_LANGUAGE\_SELECT这个标记：

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
        );

至于具体如何切换，这里暂不深入。

## 语法 ##

关于UNI文件中的语法，在参考文档中做了比较详细的说明（也有没说明白的地方）。但是因为使用了[BNF][]的表示方法（包括BNF的扩展方法），所以初看起来还是有一些吃力，这里做简要的介绍。关于BNF以及它的扩展版本，可以通过链接查看，或者在其它的地方找到具体的使用说明。

### 基本定义 ###

首先是一些需要了解的基本定义：

UNI文件中需要指明**LanguageCodes**，它是表示语言的标记，比如美式英语是en-US，法语是fr-FR，中文是zh-CN等等，它们在[rfc4646][]中定义。

UNI文件中使用的字符串可以包含EscChar，全称是Escape Character，中文翻译是转义字符，基本听到中文名懂编程的都知道是什么意思了。

UNI文件中使用的标记可以包含数组，英文大小写，下划线（\_）和折线（-）。UNI文件中可以包含其它的文件，使用include表达式。还有在UNI文件中会用到的基本表达式的BNF表示：

![20180405220529570][]

简单来说，::=左侧的是表达式，右侧是字符串定义。比如<US>这个表达式是最基本的，它就表示一个空格，它也会在::=的右侧用到，来组成更复杂的标记；比如<MS>，它的定义是<US>+，就表示多个空格；再比如<ME>，它的定义是<MS>\{<EOL>\}，<EOL>表示的是End Of Line，所以<ME>表达式实际上就是多个空格组成的一行。

以此类推，构成了UNI（其实也是其它一切用BNF或者它的扩展版本表示的）文件的语法基础，正是上述的基本语法阐述了一个UNI文件应该如何实现。

## 语法说明 ##

UNI文件的基本语法如下：

![20180405221351636][]

以一个实际的例子做对比：

![20180405222725355][]

这里就可以很明确的看到各个部分。不过上述例子中还有一部分没有包含进去，就是

/=#

它应该属于<Content>的一部分，称为ControlRefactor，不过目前不清楚它的作用，并且不是所有的UNI文件中都包含它，另外<LanguageDefs>也不是所有的UNI文件都包含，关于这些，在参考文档中并没有特别说明原因。

<CommentLine>和<LanguageDefs>两部分都比较简单，这里主要说明下<Content>，它的定义如下：

![20180405223307532][]

1. 它也可以包含<CommentLine>，事实上注释可以出现在任何的位置，关于注释的表达式，在之前的基本定义中已经说明过，就是以//开头的行；

2. 空白行也随时可以出现；

3. <UnicodeLines>是以\#string开头的一个字符串（中间可以换行），它算是<Content>中最重要的部分，包含了真正用来定义并在其它文件中使用的标记；

4. <ControlRefactor>在前面的红色字体中已有说明，含义不明；

5. <LanguageDefs>也可以出现在<Content>中；

6. <SecurityLines>同样含义不明；

7. <IncludeLines>也在之前提到过，就是用来包含其它UNI文件的，像下面那样：

#include "MiscBaseBoardManufacturer.uni"
    #include "MiscBiosVendor.uni"
    #include "MiscChassisManufacturer.uni"
    #include "MiscOemString.uni"
    #include "MiscPortInternalConnectorDesignator.uni"
    #include "MiscSystemLanguageString.uni"
    #include "MiscSystemManufacturer.uni"
    #include "MiscSystemOptionString.uni"
    #include "MiscSystemSlotDesignation.uni"

上述<Content>的定义中，除了两个标红的不知道作用，最重要的就是<UnicodeLines>了，它的定义如下：

![20180405234904239][]

下面是一个具体的例子：

![20180405235253807][]

对于<FontId>没有找到具体的例子。这里说明下它的定义：

![2018040523563026][]

然后定义的Identifier就会被用在<UnicodeLines>中。

## UNI文件的使用 ##

本文的最后介绍下UNI文件的使用。

首先在C代码中要使用UNI文件，对应模块的INF文件中需要包含该文件，以Front Page对应的UiApp.inf为例：

![20180405235940516][]

在模块编译的过程中，编译工具（其实是Python脚本）将它们转换成对应的Unicode字节，放到AutoGen.c文件中的某个数组中。然后在C代码中要使用的话，需要先包含该UNI，使用的函数如下：

/**
      Registers a list of packages in the HII Database and returns the HII Handle
      associated with that registration.  If an HII Handle has already been registered
      with the same PackageListGuid and DeviceHandle, then NULL is returned.  If there
      are not enough resources to perform the registration, then NULL is returned.
      If an empty list of packages is passed in, then NULL is returned.  If the size of
      the list of package is 0, then NULL is returned.
    
      The variable arguments are pointers which point to package header that defined 
      by UEFI VFR compiler and StringGather tool.
    
      #pragma pack (push, 1)
      typedef struct {
        UINT32                  BinaryLength;
        EFI_HII_PACKAGE_HEADER  PackageHeader;
      } EDKII_AUTOGEN_PACKAGES_HEADER;
      #pragma pack (pop)
      
      @param[in]  PackageListGuid  The GUID of the package list.
      @param[in]  DeviceHandle     If not NULL, the Device Handle on which 
                                   an instance of DEVICE_PATH_PROTOCOL is installed.
                                   This Device Handle uniquely defines the device that 
                                   the added packages are associated with.
      @param[in]  ...              The variable argument list that contains pointers 
                                   to packages terminated by a NULL.
    
      @retval NULL   A HII Handle has already been registered in the HII Database with
                     the same PackageListGuid and DeviceHandle.
      @retval NULL   The HII Handle could not be created.
      @retval NULL   An empty list of packages was passed in.
      @retval NULL   All packages are empty.
      @retval Other  The HII Handle associated with the newly registered package list.
    
    **/
    EFI_HII_HANDLE
    EFIAPI
    HiiAddPackages (
      IN CONST EFI_GUID    *PackageListGuid,
      IN       EFI_HANDLE  DeviceHandle  OPTIONAL,
      ...
      )

该函数将UNI文件提供的字符串最终放到HII数据库中，该HII数据库中还包含图像，窗体（Form），字体等内容。下面是一个具体的例子：

//
      // Publish our HII data
      //
      gFrontPagePrivate.HiiHandle = HiiAddPackages (
                                      &mFrontPageGuid,
                                      gFrontPagePrivate.DriverHandle,
                                      FrontPageVfrBin,
                                      UiAppStrings,
                                      NULL
                                      );

这里的UiAppStrings参数对应的就是UiApp.uni，对应关系是“BASE\_NAME”+Strings对应到字符数组，这里的BASE\_NAME的值来自inf。同时xxxStrings也是AutoGen.c中转换后得到的数组变量名。以上述的UiAppStrings为例（这里截取部分代码）：

//
    //Unicode String Pack Definition
    //
    unsigned char UiAppStrings[] = {
    
    // STRGATHER_OUTPUT_HEADER
      0xB2,  0x03,  0x00,  0x00,
    
    // PACKAGE HEADER
    
      0x7B,  0x01,  0x00,  0x04,  0x34,  0x00,  0x00,  0x00,  0x34,  0x00,  0x00,  0x00,  0x00,  0x00,  0x00,  0x00,  
      0x00,  0x00,  0x00,  0x00,  0x00,  0x00,  0x00,  0x00,  0x00,  0x00,  0x00,  0x00,  0x00,  0x00,  0x00,  0x00,  
      0x00,  0x00,  0x00,  0x00,  0x00,  0x00,  0x00,  0x00,  0x00,  0x00,  0x00,  0x00,  0x01,  0x00,  0x65,  0x6E,  
      0x2D,  0x55,  0x53,  0x00,
    
    // PACKAGE DATA
    
    // 0x0001: $PRINTABLE_LANGUAGE_NAME:0x0001
      0x14,  0x45,  0x00,  0x6E,  0x00,  0x67,  0x00,  0x6C,  0x00,  0x69,  0x00,  0x73,  0x00,  0x68,  0x00,  0x00,  
      0x00,

在UiApp.uni中定义的第一个标记是：

![20180406001700926][]

在上述的字节中（PACKAGE DATA部分），第一个0x14有其它的含义（见EFI\_HII\_SIBT\_STRING\_UCS2），后面的每两个字节就表示一个Unicode字符的英文或者法文（上图是英文，法文在数组的后面，这里没有列出），可以看到0x0045表示的是Unicode的E，0x006E表示的是Unicode的n（具体的转换可以看[这里][Link 1]），以此类推。

之后就可以通过对应的GUID使用到定义在UNI中的标记了，使用的方式是

STRING_TOKEN (标记)

这里的标记最终会被定义成一个宏，放到跟AutoGen.c同一层目录下的xxxStrDefs.h文件中，这里的xxx就是模块的名称。这个STRING\_TOKEN(标记)会被当成一个宏，对应到一个整数，通过这个整数可以找到上述数组中对应Unicode字符串的位置。这个宏最终会被EFI\_HII\_STRING\_PROTOCOL中的GetString()函数使用并解析成字符串：

/**
      This function retrieves the string specified by StringId which is associated
      with the specified PackageList in the language Language and copies it into
      the buffer specified by String.
    
      @param  This                   A pointer to the EFI_HII_STRING_PROTOCOL instance.
      @param  Language               Points to the language for the retrieved string.
      @param  PackageList            The package list in the HII database to search for
                                     the  specified string.
      @param  StringId               The string's id, which is unique within
                                     PackageList.
      @param  String                 Points to the new null-terminated string.
      @param  StringSize             On entry, points to the size of the buffer pointed
                                     to by  String, in bytes. On return, points to the
                                     length of the string, in bytes.
      @param  StringFontInfo         If not NULL, points to the string's font
                                     information.  It's caller's responsibility to free
                                     this buffer.
    
      @retval EFI_SUCCESS            The string was returned successfully.
      @retval EFI_NOT_FOUND          The string specified by StringId is not available.
                                     The specified PackageList is not in the database.
      @retval EFI_INVALID_LANGUAGE    The string specified by StringId is available but 
                                      not in the specified language.
      @retval EFI_BUFFER_TOO_SMALL   The buffer specified by StringSize is too small to
                                     hold the string.
      @retval EFI_INVALID_PARAMETER   The Language or StringSize was NULL.
      @retval EFI_INVALID_PARAMETER   The value referenced by StringSize was not zero and
                                      String was NULL.
      @retval EFI_OUT_OF_RESOURCES    There were insufficient resources to complete the
                                      request.
    
    **/
    typedef
    EFI_STATUS
    (EFIAPI *EFI_HII_GET_STRING)(
      IN CONST  EFI_HII_STRING_PROTOCOL *This,
      IN CONST  CHAR8                   *Language,
      IN        EFI_HII_HANDLE          PackageList,
      IN        EFI_STRING_ID           StringId,
      OUT       EFI_STRING              String,
      IN OUT    UINTN                   *StringSize,
      OUT       EFI_FONT_INFO           **StringFontInfo OPTIONAL
    );

该Protocol在《UEFI Spec》中也有定义。它的初始化位于HiiDatabaseDxe.inf模块中，具体的实现不在这里深入了。

以上就是UNI文件说明的全部内容。

[EDK II Specifications _ tianocore_tianocore.github.io Wiki _ GitHub]: https://github.com/tianocore/tianocore.github.io/wiki/EDK-II-Specifications
[20180405213219900]: https://image.dandelioncloud.cn/pgy_files/images/2024/01/29/614d31a9ac65421290559e4f43039cf4.png
[UEFI_UEFI]: https://blog.csdn.net/jiangwei0512/article/details/79764763
[20180405213659910]: https://image.dandelioncloud.cn/pgy_files/images/2024/01/29/f56b7610bf0341438b0d5d51bfc21e13.png
[20180405213927313]: https://image.dandelioncloud.cn/pgy_files/images/2024/01/29/f01ad961e18b41af8e291e904af27f07.png
[20180405214046961]: https://image.dandelioncloud.cn/pgy_files/images/2024/01/29/c89dc9c5e4ff45459c7bb9dc4c1f3594.png
[BNF]: https://baike.baidu.com/item/BNF/7328753?fr=aladdin
[rfc4646]: http://www.faqs.org/rfcs/rfc4646.html
[20180405220529570]: https://image.dandelioncloud.cn/pgy_files/images/2024/01/29/9e716efaf9fa4e599d9ac0717b99d10d.png
[20180405221351636]: https://image.dandelioncloud.cn/pgy_files/images/2024/01/29/d7f5f5654e4349158bbb4f755f50c277.png
[20180405222725355]: https://image.dandelioncloud.cn/pgy_files/images/2024/01/29/1257634d89f344c2b3073ac4450ef64a.png
[20180405223307532]: https://image.dandelioncloud.cn/pgy_files/images/2024/01/29/fc95a2dd058d4c959395084f1a114108.png
[20180405234904239]: https://image.dandelioncloud.cn/pgy_files/images/2024/01/29/9d82e5efb2be4754b6c8df99b689e69f.png
[20180405235253807]: https://image.dandelioncloud.cn/pgy_files/images/2024/01/29/309204063cfe44a5b4799306e1f0cecc.png
[2018040523563026]: https://image.dandelioncloud.cn/pgy_files/images/2024/01/29/b595a8a9618849949edb981c9f0eee03.png
[20180405235940516]: https://image.dandelioncloud.cn/pgy_files/images/2024/01/29/85c143a8316e4ecd82362ae7222314c3.png
[20180406001700926]: https://image.dandelioncloud.cn/pgy_files/images/2024/01/29/aa1ea85e7f4c4d159cfd28709e51d572.png
[Link 1]: https://baike.baidu.com/item/Unicode%E5%AD%97%E7%AC%A6%E5%88%97%E8%A1%A8/12022016