SetupDesignGuide.pdf - Firmware Encoding Index

Tiano 

Setup Design Guide 

Draft for Review 

September 15, 2002 

Version 0.31

THIS SPECIFICATION IS PROVIDED “AS IS” WITH NO 

WARRANTIES WHATSOEVER, INCLUDING ANY WARRANTY OF 

MERCHANTABILITY, NONINFRINGEMENT, FITNESS FOR ANY 

PARTICULAR PURPOSE, OR ANY WARRANTY OTHERWISE 

ARISING OUT OF ANY PROPOSAL, SPECIFICATION OR SAMPLE. 

A license is hereby granted to copy and reproduce this specification for 

internal use only. 

No other license, express or implied, by estoppel or otherwise, to any other 

intellectual property rights is granted herein. 

Intel disclaims all liability, including liability for infringement of any 

proprietary rights, relating to use of information in this specification. No 

license, express or implied, by estoppel or otherwise, to any intellectual 

property rights is granted herein. 

This specification is an intermediate draft for comment only and is subject to 

change without notice. Readers should not design products based on this 

document. 

† Third party brands and names are the property of their 

respective owners. 

Copyright © Intel Corporation, 2000. 

Intel order number xxxxxx-001


DRAFT 

Revision History 

Revision Revision History Date 

0.1 

Initial Draft 

02/11/ 2002 

Added bi-directional support 

02/14/2002 

(RIGHT_TO_LEFT flag) for the 

#strlang command. 

Lots of grammatical fixes 

Updated terms section 

02/21/2002 

0.11 

0. 12 

0. 30 

Updated 2.6.1 with reference to 

Hii.NewString and Hii.UpdateForm 

Added keyboard related package 

structure definitions as well as 

a chapter explaining the 

mechanics of describing a 

keyboard layout. 

Added GLYPH_NON_BREAKING 

Added the RemovePack function in 

the HII Protocol. 

Completed first round of reviews. 

Also added a RemovePack function 

to provide the ability to 

03/01/2002 

04/11/2002 

04/20/2002 

de-register information from HII. 

0. 31 

Added data to the 

EFI_FORM_CONFIGURATION_PROTOCOL 

section to enable the sending of 

mailbox events to the 

configuration browser. 

Changed the NV Steering protocol 

to a more general-purpose 

configuration callback protocol. 

05/02/2002 

iii

Table of Contents 

1 Introduction......................................................................................................... 7 

1.1 Scope .................................................................................................................... 7 

1.2 Target Audience .................................................................................................... 7 

1.3 Related Information ............................................................................................... 7 

1.4 Terms .................................................................................................................... 8 

1.5 Conventions Used in This Document .................................................................. 10 

1.5.1 1.5.2 Data Structure Descriptions..................................................................... 10 

Protocol Descriptions............................................................................... 10 

1.5.3 Procedure Descriptions ........................................................................... 10 

1.5.4 Pseudo-Code Conventions...................................................................... 11 

1.5.5 Typographic Conventions........................................................................ 11 

2 Setup Infrastructure Overview ........................................................................ 13 

2.1 Components of the Setup Infrastructure.............................................................. 13 

2.1.1 VFR/IFR................................................................................................... 13 

2.1.2 2.1.3 

Strings ..................................................................................................... 13 

Fonts........................................................................................................ 14 

2.1.4 EFI Driver (Containing Setup Data) ......................................................... 15 

2.1.5 HII Database............................................................................................ 16 

2.1.6 Configuration Driver................................................................................. 16 

2.2 

2.3 

2.4 

Composition of VFR and String data................................................................... 16 

How multiple language support is handled.......................................................... 17 

Storing Configuration Settings............................................................................. 18 

2.5 O/S Runtime Utilization ....................................................................................... 19 

2.6 How to get hardware information in setup........................................................... 20 

2.6.1 2.6.2 Single Iteration Hardware Interaction ...................................................... 20 

Multiple Iteration Hardware Interaction.................................................... 21 

2.7 Setup Infrastructure Overview Graphic ............................................................... 22 

3 

Setup Build Infrastructure ............................................................................... 24 

3.1 Setup Build Infrastructure Elements.................................................................... 24 

3.1.1 VFR Compiler .......................................................................................... 24 

3.1.2 NVRAM Mapping File .............................................................................. 24 

3.1.3 String Definitions...................................................................................... 25 

3.1.4 IFR Header Files...................................................................................... 25 

4 VFR Programming Language .......................................................................... 27 

4.1 BNF of VFR ......................................................................................................... 27 

4.2 VFR Programming Keywords.............................................................................. 29 

4.2.1 4.2.2 // (comment marker) ................................................................................ 29 

#define..................................................................................................... 29 

4.2.3 #include ................................................................................................... 29 

4.2.4 #strlang.................................................................................................... 29 

4.2.5 #strdef...................................................................................................... 29 

4.2.6 formset / endformset................................................................................ 30 

4.2.7 nvstorage................................................................................................. 30 

Version 0.92 1/19/00 iv

DRAFT 

4.3 

5 User Interface Design....................................................................................... 40 

5.1 Home Page ......................................................................................................... 40 

5.2 Subsequent Pages .............................................................................................. 40 

5.3 Key-based Navigation ......................................................................................... 40 

5.4 Mouse Navigation................................................................................................ 41 

5.5 Screen Format..................................................................................................... 41 

5.6 Colors .................................................................................................................. 42 

5.7 Pop-Ups .............................................................................................................. 43 

5.8 Partial Language Availability ............................................................................... 43 

6 

7 

4.2.8 form / endform ......................................................................................... 30 

4.2.9 subtitle ..................................................................................................... 31 

4.2.10 text........................................................................................................... 31 

4.2.11 oneof / endoneof...................................................................................... 31 

4.2.12 checkbox / endcheckbox ......................................................................... 32 

4.2.13 numeric.................................................................................................... 32 

4.2.14 date.......................................................................................................... 33 

4.2.15 time.......................................................................................................... 34 

4.2.16 string........................................................................................................ 35 

4.2.17 password ................................................................................................. 35 

4.2.18 goto.......................................................................................................... 36 

4.2.19 grayoutif................................................................................................... 36 

4.2.20 suppressif ................................................................................................ 36 

4.2.21 hidden...................................................................................................... 36 

4.2.22 inconsistentif............................................................................................ 36 

4.2.23 AND, OR, NOT ........................................................................................ 37 

4.2.24 graphics ................................................................................................... 37 

Reserved Keywords ............................................................................................ 37 

4.3.1 DEFAULT ................................................................................................ 37 

4.3.2 MANUFACTURING ................................................................................. 37 

4.3.3 DYNAMIC ................................................................................................ 37 

4.3.4 INTERACTIVE......................................................................................... 38 

Setup Driver Considerations ........................................................................... 44 

6.1 Pre-boot Operation versus Runtime Operation ................................................... 44 

6.2 How to allocate and steer data to NV storage..................................................... 44 

HII Database Interface ...................................................................................... 46 

7.1 EFI Human Interface Infrastructure Protocol....................................................... 46 

7.1.1 EFI_HII_PROTOCOL.NewPack()............................................................ 52 

7.1.2 EFI_HII_PROTOCOL.RemovePack()...................................................... 53 

7.1.3 EFI_HII_PROTOCOL.FindHandles()....................................................... 54 

7.1.4 EFI_HII_PROTOCOL.TestString()........................................................... 55 

7.1.5 EFI_HII_PROTOCOL.GetGlyph()............................................................ 56 

7.1.6 EFI_HII_PROTOCOL.NewString() .......................................................... 57 

7.1.7 EFI_HII_PROTOCOL.GetPrimaryLanguages() ....................................... 58 

7.1.8 EFI_HII_PROTOCOL.GetSecondaryLanguages() .................................. 59 

7.1.9 EFI_HII_PROTOCOL.GetString()............................................................ 60 

7.1.10 EFI_HII_PROTOCOL.GetLine() .............................................................. 62 

7.1.11 EFI_HII_PROTOCOL.GetForms() ........................................................... 64 

1.

DRAFT 

7.2 

7.3 

7.1.12 EFI_HII_PROTOCOL.UpdateForm() ....................................................... 65 

7.1.13 EFI_HII_PROTOCOL.GetKeyboardLayout() ........................................... 66 

EFI Form Configuration Protocol......................................................................... 67 

7.2.1 EFI_FORM_CONFIGURATION_PROTOCOL.SendForm() .................... 68 

7.2.2 EFI_FORM_CONFIGURATION_PROTOCOL.SendMessage().............. 70 

EFI Form Callback Protocol................................................................................. 72 

7.3.1 EFI_FORM_CALLBACK_PROTOCOL.NvRead() ................................... 73 

7.3.2 EFI_FORM_CALLBACK_PROTOCOL.NvWrite() ................................... 75 

7.3.3 EFI_FORM_CALLBACK_PROTOCOL.CallBack() .................................. 76 

8 Simple Input Modification................................................................................ 78 

8.1 Extending Simple Input ....................................................................................... 78 

9 HII Keyboard Support....................................................................................... 80 

9.1 Keyboard Mapping .............................................................................................. 80 

9.2 Modifier Key Definitions....................................................................................... 81 

9.3 Keyboard Layout Switching................................................................................. 83 

9.4 Dead Keys........................................................................................................... 83 

9.4.1 Bi-directional Input (Reserved for future implementation) ....................... 85 

1.

DRAFT 

1 

Introduction 

1.1 Scope 

This document describes the general goals and requirements associated with system configuration 

in EFI 2.0. It covers basic requirements for being able to present a user interface to a user during 

pre-boot, run-time, and remotely. Additionally, this specification describes a standard 

programming interface that an OEM can use for the registering of setup user interfaces, strings, and 

fonts. 

This document provides enough material to create infrastructure files for the user interface as well 

as the creation of a driver to export setup related information to the Human Interface Infrastructure 

programming interface. 

A full understanding of the EFI Specification is assumed throughout this document. 

1.2 Target Audience 

This document is intended for the following readers: 

• OEM’s that design and manufacture computers for an international audience using the EFI 

firmware implementation. 

• BIOS developers, either those who create general-purpose BIOS and other firmware products 

or those who modify these products for use in Intel architecture-based products. 

• Software developers who will be adapting their product suites (Manufacturing 

tools/Diagnostics/etc.) for an international audience to run on a platform with the Tiano 

firmware implementation. 

1.3 Related Information 

The following publications and sources of information may be useful to you or are referred to by 

this specification: 

• 

• 

• 

• 

• 

EFI Specification Version 1.02, Intel Corporation, 2000, 

http://developer.intel.com/technology/efi. 

ISO Standard 3166, Codes for representation of Country name, 

http://www.iso.ch/iso/en/ISOOnline.frontpage 

ISO Standard 639-2, Codes for representation of three-letter language abbreviations, 


ISO Standard 10646, Universal multiple-octet coded character set, 


ISO Standard 9995, Keyboard layouts for text and office systems, 


1.

DRAFT 

• 

• 

• 

IBM National Language Design Guide, Publication number SE09-8002-03, www.ibm.com 

The Unicode Standard 3.0, ISBN 0-201-61633-5, www.unicode.org 

Standardizing Out-of-Band Management Console Output and Terminal Emulation, 

http://www.microsoft.com/hwdev/headless/download/VT-UTF8andVT100+-v077.ZIP 

1.4 Terms 

The following terms are used throughout this document to describe varying aspects of input 

localization: 

Alt-GR Unicode: This represents the Unicode value of a key when the Alt-GR modifier key is 

being held down. This key (A2) in some keyboard layouts is defined as the right alternate key and 

serves the same function as the left alternate key, however in many other layouts it is a secondary 

modifier key similar to shift. For instance, key C1 is equated to an ‘a’ and it’s Unicode value in the 

typical U.K. keyboard is a non-shifted value of 0x0061, however when the Alt-GR key is held 

down in conjunction with the pressing of key C1 the value on the same keyboard often produces an 

‘á‘ which is a Unicode 0x00E1. 

BNF: BNF is an acronym for "Backus Naur Form". John Backus and Peter Naur introduced for 

the first time a formal notation to describe the syntax of a given language. 

Dead Key: This is typically an accent key that does not advance the cursor and is used to create 

special characters similar to ÄäĂăÊêŰűŨũ. This function is provided only on certain keyboard 

layouts. 

FONT: A font is a graphical representation corresponding to a character set, in this case Unicode. 

The following (A A A) are the same Latin letter in three fonts using the same size (14): 

GLYPH: The individual elements of a font corresponding to single characters. Single Width 

characters typically have a matrix of 8 width and 19 height. Wide characters are 16 width and 19 

height. 

HII: Human Interface Infrastructure. This generally refers to the database which contains string, 

font, and IFR information along with other pieces which use one of the database components. 

IFR: Internal Forms Representation. This is the binary encoding that is used for the representation 

of a user interface page(s). 

Keyboard Layout: The physical representation of a user’s keyboard. The usage of this is in 

conjunction to a structure that equates the physical key(s) and the associated action it represents. 

For instance, key C1 is equated to an ‘a’ and it’s Unicode value in the typical U.K. keyboard is a 

non-shifted value of 0x0061. 

PUSH MODE: A typing mode that is typically used by bi-directional languages, which toggles the 

ability to type in left-to-right and right-to-left. 

1.

DRAFT 

RTC: Real Time Clock. The piece of hardware often used to store a system’s date and time 

settings. 

Shifted Unicode: This represents the Unicode value of a key when the shift modifier key is being 

held down. For instance, key C1 is equated to an ‘a’ and it’s Unicode value in the typical U.K. 

keyboard is a non-shifted value of 0x0061, however when the shift key is held down in conjunction 

with the pressing of key C1 the value on the same keyboard often produces an ‘A’ which is a 

Unicode 0x0041.STRING: A null-terminated ordered list of 16-bit Unicode characters. 

TAG: A term used to refer to a directive. 

VFR: Visual Forms Representation. This is the source code format that is used by developers to 

create a user interface with varying pieces of data and/or questions. This would later be compiled 

into a binary encoding. 

1.

DRAFT 

1.5 Conventions Used in This Document 

This document uses typographic and illustrative conventions described below. 

1.5.1 Data Structure Descriptions 

The Intel Architecture processors of the IA-32 family are “little endian” machines. This means that 

the low-order byte of a multi-byte data item in memory is at the lowest address, while the highorder 

byte is at the highest address. Processors of the Itanium Processor Family (IPF) may be 

configured for both “little endian” and “big endian” operation. All implementations designed to 

conform to this specification will use “little endian” operation. 

In some memory layout descriptions, certain fields are marked reserved. Software must initialize 

such fields to zero, and ignore them when read. On an update operation, software must preserve 

any reserved field. 

1.5.2 Protocol Descriptions 

A protocol description generally has the following format: 

Protocol: 

Summary: 

GUID: 

Revision Number: 

Protocol Interface Struct 

Parameters: 

Related Definitions: 

Description: 

1.5.3 Procedure Descriptions 

The formal name of the protocol interface. 

A brief description of the protocol interface. 

The 128 bit unique identifier for the protocol interface. 

The revision of the protocol interface. 

A ‘C-style’ data structure definition containing the 

procedures and data fields produced by this protocol 

interface. 

A brief description of each field in the protocol interface 

structure. 

The type declarations and constants that are used in the 

protocol interface structure or any of its procedures. 

A description of the functionality provided by the 

protocol interface including any limitations and caveats 

the caller should be aware of. 

A procedure description generally has the following format: 

ProcedureName(): The formal name of the procedure. 

Summary: 

Prototype: 

Parameters: 

Related Definitions: 

A brief description of the procedure. 

A ‘C-style’ procedure header defining the calling 

sequence. 

The parameters defined in the template are described in 

further detail. 

The type declarations and constants that are only used by 

this procedure. 

1.

DRAFT 

Description: 

Status Codes Returned: 

A description of the functionality provided by the 

interface including any limitations and caveats the caller 

should be aware of. 

A description of the codes returned by the interface. 

1.5.4 Pseudo-Code Conventions 

Pseudo-code is presented to describe algorithms in a more concise form. None of the algorithms in 

this document are intended to be compiled directly. The code is presented at a level corresponding 

to the surrounding text. 

In describing variables, a list is an unordered collection of homogeneous objects. A queue is an 

ordered list of homogeneous objects. Unless otherwise noted, the ordering is assumed to be FIFO. 

Pseudo-code is presented in a C-like format, using C conventions where appropriate. The coding 

style, particularly the indentation style, is used for readability and does not necessarily comply with 

an implementation of the EFI Specification. 

1.5.5 Typographic Conventions 

The following typographic conventions are used in this document to illustrate programming 

concepts: 

Prototype 

This typeface is use to indicate prototype code. 

Argument 

Name 

register 

This typeface is used to indicate arguments. 

This typeface is used to indicate actual code or a programming construct. 

This typeface is used to indicate a processor register. 

1.


DRAFT 

2 

Setup Infrastructure Overview 

The intention of this chapter is to give a working overview to what this document will speak to at a 

higher level of detail. It is also intended to show how things work together and the advantages this 

provides to the user of this architecture. 

2.1 Components of the Setup Infrastructure 

2.1.1 VFR/IFR 

VFR (Visual Forms Representation) is the development language used to create IFR (Internal Forms 

Representation). IFR is the compiled version of the control language. This language controls what the 

contents of each displayed page consists of, where the changed data gets saved, how pages are linked, 

and much more. 

VFR 

source file 

VFR Compiler 

IFR 

in the form of 

a header file 

2.1.2 Strings 

VFR source files will include a Unicode file(s) which contains the string definitions for the particular 

application. The Unicode file will contain both the displayed strings as well as the translations for all 

the supported languages for the particular application. 

13


DRAFT 

VFR 

source file 

Strings 

Unicode file 

VFR Compiler 

IFR 


a header file 

String Tokens 


a header file 

2.1.3 Fonts 

Typically, the system firmware will carry a set of fonts to cover a common character set, however there 

might be times when a consumer of the setup infrastructure requires the printing of a character that the 

system does not have font data for. In this case, an EFI driver will carry this font data and submit it to 

the HII Database to be used later. A font can be submitted if there is not a font definition already for 

that particular Unicode character. 

14


DRAFT 

Human Interface Infrastructure 

Database 

Consists of IFR/String/Font 

Which has been submitted by varying EFI drivers 

EFI Driver 

Fonts in Database 

Fonts being submitted 

Unicode Value 

… 

0x0040 

0x0041 

0x0042 

… 

Font Defined 

TRUE 

TRUE 

FALSE 

Unicode Value 

… 

0x003F 

0x0041 

0x0042 

… 

Fonts in Database 

Unicode Value 

… 

0x003F 

0x0040 

0x0041 

0x0042 

… 

Font Defined 

TRUE 

TRUE 

TRUE 

TRUE 

2.1.4 EFI Driver (Containing Setup Data) 

The EFI Driver that contains setup information will be compiled with IFR, Strings, and Font data. 

IFR 


a header file 

String Tokens 


a header file 

EFI Driver 

source code 

‘C’ Compiler 

EFI Driver 

Fonts 


a header file 

15


DRAFT 

2.1.5 HII Database 

The Human Interface Infrastructure Database is the resource that serves as the repository of all the IFR, 

String, and Font data for the system. Drivers that contain information which is appropriate for the 

database will export this data to the HII Database. 

In a typical system, one might expect a driver which contains all the motherboard specific data 

(traditional F1-setup for the system). Additionally, there might be other add-in cards that contain their 

own drivers which have their own set of setup related data. All of the drivers that contain setup related 

data would export their information to the HII Database. 


Database 



EFI Driver 

EFI Driver 

EFI Driver 

2.1.6 Configuration Driver 

The EFI Configuration Driver is the program that reads the contents of the HII Database and interprets 

the data to present it to the user. This is also the program that takes the user input and provides for a 

mechanism to save the changes into an NVRAM location. 


Database 



EFI Driver 

EFI Driver 

EFI Driver 

EFI Configuration Driver 

Provides User Interface Support 

Callable by a Protocol Interface 

2.2 Composition of VFR and String data 

VFR has several keywords which determine the type of functions presented to the user. These 

keywords reference strings via tokens, which make them language agnostic. 

The strings are broken into language sections which have a one-to-one parallelism between each of the 

strings. For instance, if string token #3 is the equivalent of “I love bananas” in the English section, 

token #3 in any of the other language sections will contain strings that have the same meaning. 

16


DRAFT 

VFR Sample 

IFR Translation 

subtitle text = BANANA_STRING; Subtitle Op-Code, 3 

This example shows a sample of the type of encoding that happens between 

IFR and the string tokens. When a user chooses to display a particular language 

it has no effect on the IFR encoding. The infrastructure simply pulls the same 

token from a different string section. 

ENG 

Token 1 “Hello World” 

Token 2 “Goodbye World” 

Token 3 “I love bananas” 

SPA 

Token 1 “Hola Mundo” 

Token 2 “Adios Mundo” 

Token 3 “Yo amo plátanos” 

System is in 

Spanish mode. 

GER 

Token 1 “Hallo Welt” 

Token 2 “Auf Wiedersehen Welt” 

Token 3 “Ich liebe Bananen” 

Yo amo plátanos 

2.3 How multiple language support is handled 

When providing support for multiple setup programs, the varying language support for each program 

must be taken in consideration. For instance, if there are three drivers that have exported data to the HII 

database, each of them with different language string support, a “Home Page” will be created when the 

Configuration Driver is launched. This Configuration Driver will show as its initial page all the drivers 

which have exported configuration data and strings. 

The order of what is displayed on the initial page is determined by language priority. If a driver 

contains strings for the system’s default language setting (determined by the Lang global variable) the 

translated name of that driver will be shown at the top of the list. Immediately after that list will be a 

list of the drivers in their translated forms. The intention for this is to provide a simple mechanism for a 

user to scroll up and down a list of drivers and pick the appropriate driver for their use. Whichever 

language choice is made by the user, the language choice made at the initial page will carry forward to 

the rest of the pages and strings displayed under the initial page. 

17


DRAFT 


Database 



“Setup One” 

“Setup Two” 

“Setup Three” 

Setup One Supports: Setup Two Supports: Setup Three Supports: 

ENG ENG ENG 

SPA 

SPA 

FRA 




Setup One 

Setup Two 

Setup Three 

Setup Uno 

Setup Tres 

Setup Trois 

System is in 

English mode. 

2.4 Storing Configuration Settings 

There is an assumption of having some type of NVRAM available so that settings that are changed by 

the user are able to be saved. How one gets to the NVRAM is based on whether it is system NV 

storage one is accessing, or NV storage local to a specific card. Both are supported. 

With the exception of setting a system password, and system date and time, settings are not posted to 

NV storage until the user directs the infrastructure specifically to do so. As a rule of thumb, hardware 

configuration changes do not take place until a system reset has occurred. 

18


DRAFT 

When a system reset occurs, the architectural protocol BDS launches the drivers and loads the 

Configuration driver. Drivers that are enabled to take direction from an NV setting will read the 

updated settings during their initialization. 

System Reset 

BDS 


Database 



EFI Driver 

EFI Driver 

EFI Driver 




User 

Changes 

NVRAM 

2.5 O/S Runtime Utilization 

Due to the static nature of the data contained in the HII Database and the capacity to update NVRAM 

variables, the pre-boot configuration data can be used during O/S runtime. This allows the same 

configuration mechanisms to be used in pre-boot as well as in runtime. 

19


DRAFT 


Database 



Runtime 

Buffer 




Runtime Configuration 

Application 

Can act as a server to 

an HTML browser 

2.6 How to get hardware information in setup 

For the most part, the only hardware interaction that the Configuration Driver has is when it accesses 

NVRAM or saves information to an RTC. However, there are times when a developer needs to get 

hardware information presented to the user. 

In this infrastructure there are two classifications of hardware interaction, single and multiple iteration. 

Each of these interactions have varying procedures one must follow as well as varying ramifications. 

2.6.1 Single Iteration Hardware Interaction 

An EFI driver that uses the EFI setup infrastructure will typically carry both IFR and string data. In 

some cases, not all the information that is needed is included at build time. For example, a user might 

have a text string which shows what the CPU’s frequency is. In this case, the information is obviously 

not available at build time, so the information has to be retrieved. 

There are several ways one might go about this. One way might be that the driver that is about to 

export the setup data to the HII database calls the appropriate hardware services to determine what the 

CPU frequency is, fills in the appropriate string data, and then exports the data to the HII database. 

Another way might be that the driver that has exported data to the HII database needs to add 

information to the database could use the HII protocol calls for NewString or UpdateForm. Both 

of these functions are intended for post-export modification of database information. 

Another method, which is used for more complex situations, would be to label the op-code which 

required additional data with a DYNAMIC flag. When the data is exported to the HII database, it calls 

back to the driver to get the additional data. The driver will do the hardware interaction and return a 

packet of data to the database to fill in the appropriate string data. 

Once this single level of hardware interaction is complete, the presentation data stored in the database is 

static and the DYNAMIC flag is turned off. Due to the static nature of this data, it is able to be used 

pre-boot and be exported to an O/S runtime application and be used during that phase of operation. 

20


DRAFT 


Database 



EFI Driver 

VFR Sample 

text text = CPU_STRING, 

text = DERIVED_CPU_FREQUENCY, 

flags = DYNAMIC, 

key = CPU_FREQUENCY_KEY; 

This sample shows an example of the programming language used in the EFI Setup 

infrastructure. In this case, a DYNAMIC flag signifies that when this code is exported to 

the database a callback will be done for this operation to fill in the second text entry. 

The behavior and operands will vary based on which type of op-code is thus flagged. 

String Tokens – Prior to Callback 

ENG 

CPU_STRING 

“CPU Frequency” 

DERIVED_CPU_FREQUENCY “” 

SPA 

CPU_STRING 

“Frecuencia del CPU” 

DERIVED_CPU_FREQUENCY “” 

String Tokens – After Callback 

ENG 

CPU_STRING 

DERIVED_CPU_FREQUENCY 

SPA 

CPU_STRING 

DERIVED_CPU_FREQUENCY 

“CPU Frequency” 

“2.2 Ghz” 

“Frecuencia del CPU” 

“2.2 Ghz” 

2.6.2 Multiple Iteration Hardware Interaction 

An EFI driver that uses the EFI setup infrastructure will typically carry both IFR and string data. In 

some cases, not all the information that is needed is included at build time. For example, a user might 

need to add a boot option and to do this they need to select the file from a file system. In this case, the 

information is obviously not available at build time, so the information has to be retrieved. 

Unlike the previous section which had hardware interaction completed prior to the user ever having 

seen any data, this example requires hardware interaction at the user level. In the example of searching 

for a file, the driver will have the op-code labeled with a DYNAMIC and INTERACTIVE flag. When 

the data is exported to the EFI configuration driver, it calls back to the driver to get the additional data. 

21


DRAFT 

The driver will do the hardware interaction and return a packet of data to the database and it will fill in 

the appropriate string data. If the packet is returned successfully, the DYNAMIC flag is turned off. 

This string data would likely correlate to the initial list of file systems available on the system. This 

completes the first phase of interaction to acquire all the information the system needs to display data to 

the user. 

Additionally, when the user manually selects the file system they want to start searching, a callback to 

the exporting driver would occur and a packet would return the data requested. This would continue 

until the desired file was chosen. 

In the case where the driver which is exporting data bypasses the HII database and sends the data 

directly to the EFI configuration driver, the driver becomes responsible for the saving of the NVRAM 

data if any. Additionally, bypassing the HII database along with the multiple iteration callbacks are not 

compatible with runtime propagation. This use case would likely be used by pre-boot only utilities like 

the EFI Boot Maintenance Manager. 


Database 



EFI Driver/Utility 

Requiring Dynamic Hardware Interaction 




EFI Driver/Utility 


Pre-boot Only and Responsible 

for storing NVRAM changes 

Additionally, a driver which required multiple iteration support could use the HII database so that the 

data might have a presence in the O/S runtime. The practical situation for this might be a driver which 

has a large amount of questions and possibly only a very small set which require multiple iteration 

support. In this case, the developer needs to be conscious when designing the page contents of the VFR 

script so that if the O/S runtime version of the data is stripped of op-codes with the INTERACTIVE 

flag turned on the user experience will not be odd. For instance, if a driver contains a page dedicated to 

modem initialization and the op-codes associated with that page are all set to INTERACTIVE, it might 

look very odd if the O/S runtime user is presented with a blank page which inferred there should be 

more data. 

2.7 Setup Infrastructure Overview Graphic 

22


DRAFT 

BDS 

Policy Engine for EFI 

Responsible for launching drivers and boot options. 

typedef struct { 

EFI_HII_PACKET 



} EFI_IFR_PACKET; 

*IFRData; 

*FontData; 

*StringData; 


Database 

Consists of IFR/String/Font Data 


EFI Driver 

EFI Driver 

EFI Driver 

EFI Driver 


If UseDatabase == TRUE, Retrieve all DBHandles, Ignore Packet/DriverPointer 

If UseDatabase == FALSE, process the Packet and DriverPointer. 




typedef struct _EFI_CONFIGURATION_PROTOCOL { 

BOOLEAN 

UseDatabase; 

EFI_IFR_PACKET 

*Packet; OPTIONAL 

VOID 

*DriverPointer; OPTIONAL 

} EFI_CONFIGURATION_PROTOCOL 

23


DRAFT 

3 

Setup Build Infrastructure 

3.1 Setup Build Infrastructure Elements 

Many elements are involved in the building of a driver that uses the EFI Setup Infrastructure. No 

matter if the driver that is using EFI for configuration of a system board, a network device, or an 

embedded controller, they all will follow the same basic steps when assembling the components to 

leverage the EFI Setup Infrastructure. 

3.1.1 VFR Compiler 

Some of the things that the compiler is responsible for are the interpreting of the VFR keywords and 

converting them to IFR. The compiler is responsible for detecting situations in the VFR files that 

would otherwise cause an invalid binary format output. 

The command-line interface for the VFR compiler is: 

VFRCOMPILE [drive:][path]VfrSourceFile [drive:][path]StringFile 

The input to the compiler is the VFR source file and a Unicode string file. The VFR source file will 

contain VFR and likely make #include references to a separate global NVRAM mapping file. All of 

these are compiled into an output header file. 

The outputs of the compiler are header files that will be used by the driver which will export the data. 

3.1.2 NVRAM Mapping File 

Many of the op-codes associated with IFR are intended to save the user’s choice to some NV data 

location. To enable this feature, a map file must be created so that the EFI setup infrastructure knows 

where in an NVRAM variable the data must be stored. This map is also used by hardware specific 

drivers that might have configuration data stored in the NVRAM variable. For instance, when a driver 

has interest in the state of the SerialPortEnable setting, it will need to include this NVRAM 

mapping file to know at what offset this data is located. 

struct { 

UINT16 

SystemPassword[20]; 

UINT16 

ModemInitializationString[60]; 

UINT8 

SerialPortEnable; 

UINT16 

SamplePieceOfData; 

UINT32 

MyFavoriteNumber; 

} SystemNvRamMap; 

Note that the SystemNvRamMap is the name of the structure name that is used to reference data both 

for the drivers that are interested in their content and the VFR language itself. For instance, if a 

command to display the ModemInitializationString setting was to be written in VFR it might 

be done as follows: 

text 

text = SystemNvRamMap.ModemInitializationString; 

24


DRAFT 

3.1.3 String Definitions 

One of the primary aspects of a user interface is the list of strings associated with it. When an EFI 

driver which exports setup information is compiled, the strings are located in a Unicode file. This file 

uses the #strdef command to signify the beginning of a string definition. On that same line is an 

ISO 639-2 language code, a programmatic name of the string, and lastly the string itself. 

#strdef ENG STR_TITLE "My English setup engine" 

#strdef ENG STR_PAGE1 "My First Setup Page" 

#strdef ENG STR_PAGE2 "My Second Setup Page" 

#strdef ENG STR_PAGE3 "My Third Setup Page" 

3.1.3.1 Multiple Language Support 

The EFI Setup Infrastructure supports multiple languages in the string definitions. The #strlang 

command defines what string to associate with the ISO 639-2 language code. Each string is treated as a 

token, so it can be noticed that the programmatic name for each string has a corresponding string in 

each language. For instance, the STR_TITLE shows up in the English, Spanish, and French set of 

strings. 

When writing VFR, no concern really needs to be given to which language to use or reference since the 

EFI Configuration Driver will determine which language’s string token will be used. For more on this 

see section 2.3. 

#strlang ENG "English" 

#strlang FRA "Français" 

#strlang GER "Deutsche" 

#strdef ENG STR_TITLE "My English setup engine" 

#strdef ENG STR_PAGE1 "My First Setup Page" 

#strdef ENG STR_PAGE2 "My Second Setup Page" 

#strdef ENG STR_PAGE3 "My Third Setup Page" 

#strdef FRA STR_TITLE "Mon moteur de setup Français" 

#strdef FRA STR_PAGE1 "Ma Première Page D'Installation" 

#strdef FRA STR_PAGE2 "Ma Deuxième Page D'Installation" 

#strdef FRA STR_PAGE3 "Ma Troisième Page D'Installation" 

#strdef GER STR_TITLE "Meine Deutsche aufstellung maschine" 

#strdef GER STR_PAGE1 "Meine Erste InstallationsSeite" 

#strdef GER STR_PAGE2 "Meine Zweite InstallationsSeite" 

#strdef GER STR_PAGE3 "Meine Dritte InstallationsSeite" 

3.1.4 IFR Header Files 

The VFR compiler takes all the previously mentioned input files and converts them into a form that is 

usable by the EFI setup compatible driver. Since it is highly likely this driver will use a ‘C’ compiler to 

be built, the form of the VFR output files are in ‘C’ type header files. The header files should not ever 

need to be manipulated, but there are often comments associated with the byte encodings in the header 

files. The byte encoding of the header file is generally organized in the order of IFR followed by String 

Tokens and then Font data. A portion of a header file might look as follows: 

25


DRAFT 

#define IFR_BEGINNING_OFFSET 

#define STRING_BEGINNING_OFFSET 

#define FONT_BEGINNING_OFFSET 

0x0000 

0x01c3 

0x09de 

UINT8 ByteEncoding[] = { 

/*O*/ 0x11, 

// offset = 0x0000 

/*L*/ 0x14, 

/*G*/ 0x00, 0x00, 0x00, 0x00, 0x0C, 0xF3, 

0xD3, 0x4E, 0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 

0x06, 0x07, 

/*S*/ 0x01, 0x00, 

/*O*/ 0x01, 

/*L*/ 0x06, 0x01, 0x00, 

/*S*/ 0x02, 0x00, 

/*O*/ 0x02, 

/*L*/ 0x04, 

/*S*/ 0x05, 0x00, 

/*O*/ 0x95, 

/*L*/ 0x13, 0xA9, 0x00, 0xA9, 0x00, 0x00, 

/*S*/ 0x10, 0x00, 

/*S*/ 0x13, 0x00, 0x93, 0x07, 0x35, 0x08, 0x01, 0x00, 0xAC, 0x07, 

… 

// offset = 0x1c3 

0xDE, 0x10, 0x00, 0x00, // Length for this language list of strings 

0x45, 0x4E, 0x47, 0x00, // Language = ENG 

0x94, 0x00, 0x00, 0x00, // printable-name 

0x00, 0x00, 0x00, 0x00, // attributes 

0x94, 0x00, 0x00, 0x00, // offset to string 0 

0xA4, 0x00, 0x00, 0x00, // offset to string 1 

0xD4, 0x00, 0x00, 0x00, // offset to string 2 

0xFC, 0x00, 0x00, 0x00, // offset to string 3 


0x4E, 0x01, 0x00, 0x00, // offset to string 5 


… 

26


DRAFT 

4 

VFR Programming Language 

4.1 BNF of VFR 

Character sequences that are in bold are key words. Keywords are case insensitive. The same 

extensions to BNF used to describe VFR are used here. Where elements are on separate lines in the 

BNF, those elements are required. VFR comments start with ‘//’ and end at the end of the line. 

The following ‘meta’-language elements are allowed on any line. 

::= 

::= 

::= 

define | define 

redefine | redefine 

include file-path 

Note: No comments are allowed on a file path line. The entire line from the first non-blank character 

following the include is taken as the file name. 

::= 

* 

endformset 

formset guid= title= nvstore= 

Note: is the current placeholder for the variable path. 

::= 

* 

endform 

form formid= title= 

::= | | | | | | 

| | | | | 

::= 

::= 

subtitle text= 

text text= 

::= varid= prompt= help= 

[location=,] 

, ::= 

Note: It is expected that the compiler will automatically allocate the location information in most cases. 

27


DRAFT 

::= oneof 

* 

endoneof 

::= option text= value= [default][] 

::= checkbox [default][] 

Note: The default flag being activated for a checkbox defines the initial behavior to be active. 

::= numeric min= max= [default=] 

[step=] 

, , , all ::= 

Note: The default initial value is the value. The default step value is 1. 

::= password minsize= maxsize= encoding= 

::= supressif 

::= grayoutif 

::= inconsistentif text= 

::= goto prompt= formid= 

::= hidden id= value= 

::= image string= graphic= 

::= background graphic= 

, ::= 

::= []* 

::= a | b | c | … | z | _ 

::= | 0 | 1 | … | 9 

::= 

::= 

::= UINT8-constant 

::= | 

| 

| 

 

, , ::= UINT8-constant 

::= | | 

::= 

::= 

::= []n..n 

::= 

, , ::= UINT8-constant 

28


DRAFT 

4.2 VFR Programming Keywords 

The keywords described in the following section compose the working set of commands for the VFR 

language. Each description is followed by an example to better help the programmer understand what a 

sample line of VFR code would look like using that particular keyword. 

4.2.1 // (comment marker) 

Allows a programmer to leave comments in the VFR file and has no effect on the IFR binary that is 

generated. 

Example: // This is a typical comment marker 

4.2.2 #define 

Used to assign a meaningful name to a constant. Very similar in function to the ‘C’ style #define 

keyword. 

Example: #define FORMSET_GUID “CAED85D9-F30C-4ed3-B7A6-83EE32A1C604” 

#define GUID FORMSET_GUID 

4.2.3 #include 

This command tells the VFR compiler to use the contents of a file as part of the source to compile. 

Example: #include “C:\Source\SourceFile.ifr” 

4.2.4 #strlang 

This command is used to assign the ISO-639-2 three letter language abbreviation to its corresponding 

printable language name. 

This command will be used in an included header file which has a Unicode format. It will be an error 

condition which will be detected by the compiler if this is used in a non-Unicode formatted file. 

Example: #strlang SPA “Español”; 

#strlang FRA “Français”; 

#strlang ENG “English”; 

#strlang HEB ‏”עברית“‏ RIGHT_TO_LEFT; 

Notice how the 4 th example shows a RIGHT_TO_LEFT flag is turned on. This information will be 

passed on to the attributes for strings that are defined under the HEB (Hebrew) language. Strings that 

normally were left-justified in the default situation would now be right justified with this flag turned on. 

Additionally, user input will move from right to left. Instead of the column location of the cursor 

incrementing as a user types, it will decrement. 

4.2.5 #strdef 

This command is used to define a string and which language it belongs to. 

This command will be used in a separate Unicode header file. It will be an error condition which will 

be detected by the compiler if this is used in a non-Unicode formatted file. 

Example: #strdef ENG STR_SUBTITLE_TEXT “My subtitle text” 

#strdef FRA STR_SUBTITLE_TEXT “Mon texte de sous-titre” 

29


DRAFT 

#strdef 

SPA STR_SUBTITLE_TEXT “Mi texto del subtítulo” 

4.2.6 formset / endformset 

This command is used to define the beginning and end of a set of forms. 

If any of the keywords used in the VFR file have a DYNAMIC or an INTERACTIVE flag turned on, 

then calls to the HII must pass in the pointer to the driver’s callback interface and the 

drivercallback should be set to TRUE. The drivercallback field will be filled into the 

byte-stream by the compiler, and is an optional field for the user to input. When this data is exported to 

the HII database, a FALSE will be replaced with a zero, and a TRUE will be replaced with the value of 

the driver’s callback interface pointer. 

Example: formset guid = FORMSET_GUID, 

title = STR_FORMSET_TITLE, 

[drivercallback = TRUE,] 

version = 2, 

endformset; 

4.2.7 nvstorage 

This command is used to define the location of the non-volatile storage used for the choices made by 

the user. If the NV storage will not be located in the system NV (e.g. Add-in card NV storage) then 

access to the add-in card’s NV must be exposed via the EFI_FORM_CALLBACK_PROTOCOL 

protocol. For more information on the EFI_FORM_CALLBACK_PROTOCOL protocol see section 

7.3.The handle that contains the interface will be communicated via the nvstorage setting. The first 

example shows how one might define an NV storage descriptor for the system variables. 

Example: nvstorage handle = NULL, 

devicepath = NULL, 

key = NULL; 

In the second example, the handle and devicepath are defined to be non-NULL to signify that 

when this data is exported, there will be a callback done to fill in the two variables. The key value will 

be retrieved from a VFR_NV_KEY() macro. It is intended to be a uniquely identified value so that the 

callback to the driver will correctly identify the purpose of the callback and hand back the correct 

information. 

Example: nvstorage handle = 1, 

devicepath = 1, 

For more information about NV steering see section 6.2. 

4.2.8 form / endform 

key = RaidControllerMapDefine; 

This command is used to define the beginning and end of a page of user interface data. 

Example: form formid = PAGE_ONE, 

title = STR_FORM_TITLE, 

endform; 

30


DRAFT 

4.2.9 subtitle 

Subtitle strings are intended to be used by authors to separate sections of questions into semantic 

groups. 

Example: subtitle text = STR_SUBTITLE_TEXT; 

4.2.10 text 

Unlike HTML, text is simply another tag. This enables IFR to be more easily localized. The first 

example shows a simple usage case where a static string is being printed. The second example shows a 

use case which is more complex and allows for a one-time callback to acquire the secondary text data. 

The second case is described in more detail in section 4.3.3. 

Example: text text = STR_MISCELLANEOUS_TEXT; 

Example: text text = STR_MISCELLANEOUS_TEXT; 

4.2.11 oneof / endoneof 

text = STR_CPU_DERIVED_TEXT, 



This command provides the ability to choose from multiple choices. Each of the choices is defined by 

an option statement. To support the ability to reset the user choices to a specific set of defaults, the 

flags settings contains a bit-mask which defines which option is defined as a system default and/or a 

manufacturing setting. 

Note that the flags setting is used to determine which choice is a system default. In the case of 

option 3 the flags setting is set for a manufacturing default setting. It is an error condition if more 

than one option has the DEFAULT or MANUFACTURING flag turned on. 

Also notice that this is the first keyword example that the results of the user’s choice can be reflected 

into a NVRAM storage location. See 6.2 to learn more about NVRAM configuration and to better 

understand how this works programmatically. 

It is also reasonable that a particular option can have both the default and manufacturing bits set. In this 

case it would be specified with a flags = DEFAULT | MANUFACTURING. 

Example: oneof 

varid = NvRamMap.SerialPortQuestion1, 

prompt = STR_ONE_OF_PROMPT, 

help = STR_ONE_OF_HELP, 

option text = STR_SERIAL_PORT1, value=0, flags=NULL; 

option text = STR_SERIAL_PORT2, value=1, flags=DEFAULT; 

option text = STR_SERIAL_PORT3, value=2, flags=MANUFACTURING; 

endoneof; 

A second example shows how one would create a oneof command which required dynamic 

interaction with a hardware driver. Note from the first example that the key and flags settings are 

optional for this command. This example is not compatible with exporting data to runtime, and thus 

31


DRAFT 

should only be used in cases where the calling application is intended to be a pre-boot only utility. For 

further information on the DYNAMIC and INTERACTIVE flags, see sections 4.3.3 and 4.3.4. 

Example: oneof 

varid = NULL.BootOptionSelection, 

prompt = STR_BOOT_OPTION_SELECTION, 

help = STR_BOOT_OPTION_HELP, 

key = BOOT_OPTION_KEY, 

flags = DYNAMIC | INTERACTIVE, 

// There are no options defined in this case. The initial set of options are 

// not known since they are system specific. For instance – when looking up 

// a file, one cannot know how many file systems will be found on available 

// media. 

endoneof; 

More information about interacting with hardware is contained in section 2.6. 

4.2.12 checkbox / endcheckbox 

The result returned by Checkbox is zero if the box is not checked and one if it is. If the default value 

needs to be one, set the flags parameter to turn on the DEFAULT flag bit. 

Notice that this is an example that the results of the user’s choice can be reflected into a NVRAM 

storage location. See 6.2 to learn more about NVRAM configuration and to better understand how this 

works programmatically. 

Example: checkbox 

4.2.13 numeric 

endcheckbox; 

varid = NvRamMap.SerialPortQuestion2, 

prompt = STR_CHECK_BOX, 

help = STR_CHECK_BOX_HELP, 

flags = DEFAULT, 

This command allows for numeric entry by selecting from numeric choices. The step portion of the 

numeric command allows for the defining of at what rate the value increments when selection the next 

or previous entry. If the step is set to zero, the user will be prompted for manual input of the numeric 

value. 

Notice that this is an example that the results of the user’s choice can be reflected into a NVRAM 



Example: numeric 

varid = NvRamMap.SystemTimeoutValue, 

prompt = STR_NUMERIC, 

help = STR_NUMERIC_HELP, 

min = 0, 

max = 35, 

32


DRAFT 

4.2.14 date 

endnumeric; 

step = 1, 

default = 8, 

This command allows for the entry of date information. 

Notice that this is an example that the results of the user’s choice can be reflected into an NVRAM 



Also notice that date and time are the two functions that are likely to be included in a system for 

user input, yet not stored in a traditional NVRAM storage location. In this case, the destination is likely 

an RTC. This example shows the storage location as being NULL. Date and time are special cases 

where the storage location being NULL is translated into a call to the RTC (if available). In all other 

cases, a NULL parent will force the data the user inputs to be thrown away. 

Example: date year varid = NULL.Year, 

prompt = STR_DATE, 

help = STR_DATE_YEAR_HELP, 

min = 1939, 

max = 2076, 

step = 1, 

default = 2002; 

month varid = NULL.Month, 


help = STR_DATE_MONTH_HELP, 

min = 1, 

max = 12, 

step = 1, 

default = 1; 

day varid = NULL.Day, 


help = STR_DATE_DAY_HELP, 

min = 1, 

max = 31, 

step = 1, 

default = 1; 

33


DRAFT 

4.2.15 time 

enddate; 

This command allows for the entry of time information. 

Notice that this is an example that the results of the user’s choice can be reflected into an NVRAM 



Also notice that date and time are the two functions that are likely to be included in a system for 

user input, yet not stored in a traditional NVRAM storage location. In this case, the destination is likely 

an RTC. This example shows the storage location as being NULL. Date and time are special cases 

where the storage location being NULL is translated into a call to the RTC (if available). In all other 

cases, a NULL parent will force the data the user inputs to be thrown away. 

Example: time hour varid = NULL.Hour, 

prompt = STR_TIME, 

help = STR_TIME_HOUR_HELP, 

min = 0, 

max = 23, 

step = 1, 

default = 0; 

minute varid = NULL.Minute, 


help = STR_TIME_MINUTE_HELP, 

min = 0, 

max = 59, 

step = 1, 

default = 0; 

second varid = NULL.Second, 


help = STR_TIME_SECOND_HELP, 

min = 0, 

max = 59, 

step = 1, 

default = 0; 

endtime; 

34


DRAFT 

4.2.16 string 

This command allows for the typing of a text string. This could take the form of a modem initialization 

string, or any other piece of informational human-readable data. 

Example: string 

endstring; 

varid = NvRamMap.MyStringData, 

prompt = STR_MY_STRING_PROMPT, 

help = STR_MY_STRING_HELP, 

minsize = 6, 

maxsize = 60, 

A second example shows how one would create a string command which required interaction with a 

hardware driver. Note from the first example that the key and flags settings are optional for this 

command. This example is not compatible with exporting data to runtime, and thus should only be 

used in cases where the calling application is intended to be a pre-boot only utility. For further 

information on the DYNAMIC and INTERACTIVE flags, see sections 4.3.3 and 4.3.4. 


endstring; 

varid = NULL.ModemString, 

prompt = STR_MODEM_STRING_PROMPT, 

help = STR_MODEM_STRING_HELP, 

minsize = 1, 

maxsize = 60, 

flags = INTERACTIVE, 

key = MODEM_STRING_KEY, 


4.2.17 password 

This command allows for the entry of a system password. It does not dictate system policy; the actual 

prompting for a power-on password is not done from the setup infrastructure. However, if a password 

is already set, the user will be prompted for the original password prior to allowing the user to change 

the password. 

Additionally, the storage format of the password is defined both by the VFR password encoding 

setting and the infrastructure itself. If the encoding is set to a zero value, the password will be stored 

in it’s Unicode format without encryption. The reference implementation provides a very rudimentary 

sample of an encryption mechanism which would be enabled by setting the encoding flag to one. 

Example: password 

varid = NvRamMap.Password, 

prompt = STR_PASSWORD_PROMPT, 

help = STR_PASSWORD_HELP, 

35


DRAFT 

4.2.18 goto 

endpassword; 

minsize = 6, 

maxsize = 20, 

encoding = 1, 

This command allows the user to jump to a new page. In terms of HTML operations, this behaves 

exactly like a hyper-link. The target for a goto command is going to be a form. 

Example: goto formid PAGE_ONE, 

4.2.19 grayoutif 

prompt = STR_GOTO_PAGE_ONE; 

The grayoutif tag causes the following tag to be displayed in a special display form used for 

inaccessible options if the Boolean expression evaluates to true. Those writing IFR should realize that 

different browsers will support this option to varying degrees. In particular, HTML has no similar 

construct so may not support this facility. 

Example: grayoutif NvRamMap.MagicNumber == 3; 

4.2.20 suppressif 

The suppressif tag causes the following tag to be hidden from the user if the Boolean expression 

evaluates to true. As with grayoutif, the quality of support may vary from browser to browser. 

HTML does not itself have a mechanism to provide this functionality. 

Example: suppressif NvRamMap.SerialPortCount == 0; 

4.2.21 hidden 

Hidden input allows for communication of things like revision data between the creator of the VFR and 

the consumer. The user should not generally see hidden tags. Hidden tags can be used inside VFR 

along with the grayoutif and suppressif tags to control display of optional data. 

Example: hidden 

4.2.22 inconsistentif 

varid = NULL.CurrentIfrVersion, 

value = 2; 

This tag uses a Boolean expression to allow the creator of the IFR to check options in a richer manner 

than provided by the question tags themselves. This tag may be used to e.g. validate that two options 

aren’t using the same address or that numbers entered align to some pattern (like leap years and 

February in date input). The tag provides a string to be used in a “pop-up” display to alert the user to 

the issue. Inconsistency tags may be evaluated when the user traverses from tag to tag or only upon 

submission. The user should not be allowed to submit the results of a form inconsistencies. 

Example: inconsistentif 

endif; 

prompt = STR_ERROR_POPUP, 

ideqval NvRamMap.TestValue == 2, 

36


DRAFT 

inconsistentif 

endif; 


ideqvallist NvRamMap.TestValue length = 4, 

inconsistentif 

endif; 

ideqid 

4.2.23 AND, OR, NOT 

values == 1 2 3 4, 


NvRamMap.TestValue == NvRamMap.TestOtherValue, 

These tags are used in conjunction with inconsistentif expressions. Much like their ‘C’ 

counterparts, these tags are defined as logical and, or, and not operations. 

Example: inconsistentif 

endif; 

4.2.24 graphics 

TBD 

prompt = STR_ERROR_CALENDAR, 

ideqval NULL.Day == 29, 

AND, 

ideqval NULL.Month == 2, 

AND, 

NOT, 

4.3 Reserved Keywords 

ideqvallist NULL.Year length = 7, 

values == 2004 2008 2012 2016 2020 2024 2028 

The reserved keywords are generally the equivalent of ‘C’ type #define operations that are reserved 

by the compiler and not usable as user-defined variables. It is illegal to attempt to change the values for 

these keywords and the compiler will fail to build the VFR if this is attempted. 

4.3.1 DEFAULT 

This keyword is used primarily when defining flags settings for certain operations. This keyword will 

primarily be used when a user wants to revert to default settings. 

4.3.2 MANUFACTURING 


primarily be used by a special utility to revert to the system settings to their manufacturing values. 

4.3.3 DYNAMIC 

**Limit to one-of, text, and string – any reason for other op-codes to be of this class?** 

37


DRAFT 


primarily be used if a particular operation requires additional information from a hardware specific 

interface. The intention is that once the data is retrieved successfully, the bit will internally be turned 

off and a callback will not be done again. When doing a callback, a key will be passed to the driver 

who exported this data. The driver interprets the key and returns the appropriate data in an appropriate 

form. The compiler will ensure the key value specified is unique across the entire formset. 

A common scenario where this might be used is when a text op-code which prints CPU information is 

used and needs to print information like the CPU frequency. This obviously could not have been 

determined during the building of the VFR file. 

Example: text text = STR_CPU_FREQUENCY_TEXT, 

text = STR_CPU_DERIVED_TEXT, 




4.3.4 INTERACTIVE 

**Limit to one-of, text, and string, and numeric – any reason for other op-codes to be of this 

class?** 


primarily be used if a particular operation requires additional information from a hardware specific 

interface. The intention is that once the initial data is retrieved successfully, the DYNAMIC bit will 

internally be disabled. This assumes that the infrastructure now has sufficient data to display initial 

data to the screen. 

The INTERACTIVE flag is not compatible with exporting data to runtime since it assumes callbacks to 

a driver which may not exist in the O/S runtime space. The use of this flag should be relegated to preboot 

only utilities. 

Once a user makes a selection on a tag that is interactive, a callback will be made to retrieve the data 

from a driver. A common use for this flag might be the entering of a modem configuration string, and 

returning data based on the resulting status from the modem. 


endstring; 

varid = NULL.ModemString, 

prompt = STR_MODEM_STRING_PROMPT, 

help = STR_MODEM_STRING_HELP, 

minsize = 1, 

maxsize = 60, 

flags = INTERACTIVE, 

key = MODEM_STRING_KEY, 

In the above example, a user would select the modem string prompt. After typing in the modem string 

to send to the modem (i.e. ATE1M0), a callback to the driver would send this packet of data to the 

modem. The modem will give some return code to the called driver. The driver will return back to the 

38


DRAFT 

setup infrastructure with a particular return code and return packet. This packet (based on the keyword 

it is responding to) will contain some string data to print out. In the case of the above example, one 

might get returned a string stating “Modem Configured Without Errors”. The infrastructure will print 

that message, and return the user to the menu which contained the modem string prompt. 


39


DRAFT 

5 

User Interface Design 

The Setup described here is targeted at the following design goals 

1. Walk up and use interface – the user should not have to have training to use the user interface to 

successfully navigate the application. The user may or may not understand the actual fields 

presented. 

2. The driver should work in the firmware, with no reliance on rotating media or an operating system. 

It should use the fonts, strings, and forms as defined in the HII specification. Part of this 

development is to ensure that this support is sufficient. 

5.1 Home Page 

The root of the menu hierarchy (“the home page”) is the only page with no associated IFR. The page 

must be generated on the fly by the configuration driver. The page is the first presented to the user and 

has the following functions. 

1. Enables the user to choose an application to run. If three drivers exported data to the HII database, 

three different hyperlinks should be presented to choose from. Each of these hyperlinks may have 

several language versions to choose from. 

2. Allow the user by virtue of their choice of hyperlinks to pick a language to use. 

3. Allows the user to exit with or without updating the configuration. 

5.2 Subsequent Pages 

The format of subsequent pages is derived from the IFR representation of the corresponding form. The 

first form appearing in a form set is taken to be the root of the hierarchy represented by that form set. 

5.3 Key-based Navigation 

Setup is navigated by a series of keys. The bottom line of the screen is devoted to indicating the active 

keys at any time. In the UI lingo, this is known as ‘keys help’. The keys are used for navigation around 

the menus, and for modification of the configuration. The keys selected below are chosen because they 

do not change definition based on language and because they conform to several standards. The US 

English names of the keys are used for description. 

The keys used in Setup are: 

- Up Arrow, Down Arrow – move the highlight between fields on a menu. (Also Tab and 

Shift-Tab) The page is scrolled as necessary to display the next / previous prompt and 

option text. 

- PgUp, PgDn – scroll text. It is possible (although not likely) for string items (text, prompts, 

etc.) with no questions to fill the entire screen. PgUp and PgDn enable scrolling of the forms. 

If the currently selected option is not displayed on the page due to use of PgUp and PgDn, 

40


DRAFT 

input of either up or down arrow will cause the currently selected prompt and option to be 

displayed. The highlight will not move in this case. 

- Left Arrow, Right Arrow – Cycle through selections for one-of items. 

- Spacebar – selects or de-selects checkbox items. 

- 0, 1, …, 9 – Numeric entry 

- F1 – Scroll help. 

- F2 – Back (as in an internet browser. Path may be limited to an arbitrary number (e.g. 10) items or may 

be limited to reaching the main menu. 

- Esc – Return to parent menu discarding changes. If changes were made, a pop-up should require 

confirmation. Note that changes are not fully accepted until the user exits Setup or otherwise commits 

the changes.. 

- Visible Keys – Passwords 

- Enter – Accept hyperlink or begin entering data on a question 

Per the walkup and use requirement, there is no help key because all help is presented to the user 

without request. 

5.4 Mouse Navigation 

A mouse may be used for navigation. Only the left mouse button is defined and only single clicks are 

supported. 

Where clicked 

Upper left corner (over 

F2=Back) 

Numeric, One-of, 

Password fields 

← and → to the left and 

right of one-of fields 

Check box 

5.5 Screen Format 

Action 

Return to previous (parent) menu 

Highlight field. 

Scroll through options 

Toggle check in box (X then space then X then space…) 

The screen is character oriented and divided vertically and horizontally into regions. Rows range from 

1 (the top line) to C max (the bottom line). Columns range from 1 (left-most) to R max (right most). 

Row 1 is the title line. The title is presented as centered on the line. On the first page, the title line is 

passed to the driver when it is invoked. On the remaining pages the title is derived from the Title IFR 

operand. Left and right arrows are displayed as the left most two character of all but the root title pages 

(for use with mouse navigation). They are used equivalently with the browser left and right arrows. 

Two options are also on the top line: “F2=Back” is flush left while “F3=Exit” is presented flush right 

(in positions similar to those on a browser). 

Row R max is used for keys help. The text for the keys help is carried by the Setup driver. 

41


DRAFT 

The area between the title screen and the keys help is known as the page body. 

The page body is divided into thirds. The leftmost block is known as the prompt block, the middle is 

the option block, and the rightmost column is the help block. The right two blocks (prompt block and 

option block) are collectively known as the question block. 

The question block is used to present subtitles and text. If they fit, question prompts reside in the 

prompt block. The currently selected option resides in the option block. The option column is 

separated from the help column by a scroll bar. If the IFR page is longer vertically than the page body, 

the appropriate arrows and block appear on the scroll bar. 

The currently selected input field is highlighted. 

Example (with fewer than normal rows): 

F2=Back 

Ersatz© 2003 Mega-SCSI 

▲ 

Help: 

Interrupt . . . . . . . . . . . . . . ←PIRQ A→ │ SCAM (SCSI Configured 

Mode . . . . . . . . . . . . . . . . . ←Fast and Wide→ │ Automagically) will 

SCAM . . . . . . . . . . . . . . . . [X] ▒ automatically assign addresses 

← → toggles check box , ↑↓ moves highlight, F1 scrolls help 

│ 

│ 

▼ 

to SCSI peripherals. Some 

old devices don’t work with 

SCAM. 

Note that the blank space between the prompt and the options is filled with dot+space pairs to provide 

horizontal visual reference. The dots do not necessarily align vertically. At least one space must appear 

after the prompt and before the option. 

5.6 Colors 

Colors are configurable via an optional protocol. If the optional protocol does not exist, a default 

palette is selected. The following areas are selectable 

Part of Screen 

Title background 

Default Color 

Dark Blue 

Title text 

Keys help background 

Keys help text 

Help Text 

Field background 

Field text (input prompt text, option 

White 

Black 

Light gray 

Dark Blue 

Light gray 

Black 

42


DRAFT 

text, text) 

Subtitle text 

Grayed-out text 

Suppressed text 

Highlight background 

Highlight text 

Inconsistency background 

Inconsistency text 

Black 

Dark Gray 

Not displayed 

White 

Black 

Yellow 

Black 

5.7 Pop-Ups 

Warnings (February cannot have 30 days) are displayed as pop-ups. The pop-ups are surrounded above 

and below by a blank field of the inconsistancy color and the message displayed 

5.8 Partial Language Availability 

It is quite possible that the language selected may only be available for a portion of the forms. If the 

currently selected language is not available for a given form, the default language shall be used. 

43


DRAFT 

6 

Setup Driver Considerations 

6.1 Pre-boot Operation versus Runtime Operation 

Due to the static nature of the data contained in the HII Database and the capacity to update NVRAM 

variables, the pre-boot configuration data can be effectively used during O/S runtime. This allows the 

same configuration mechanisms to be used in pre-boot as well as in runtime. 

Some thought needs to be given when designing the overall requirements associated with a setup 

application with regards to the type of data that is needed and it’s hardware interaction requirements. 

For additional information about hardware interaction see section 2.6. If some of the questions 

associated with a setup environment require a high level of hardware interaction, it might make sense to 

design the user interface flow in the VFR such that these types of questions are isolated. The reason for 

this is that when this data is exported to a runtime presence, it may not make any sense in that 

environment. For instance if there were a page which contained some diagnostic type of interactions 

which are not reasonable in a runtime environment the user experience of that page may not be 

desirable. 

6.2 How to allocate and steer data to NV storage 

The file which contains the global data primarily consists of a series of #define values and the definition 

of the NV mapping descriptors. This file is intended to be used as an include file both for VFR 

purposes as well as a ‘C’ syntax include file for drivers that are built to support the EFI setup 

infrastructure. 

There NV mapping descriptors take the form of structure declarations in this definition file. Each piece 

of data that can be changed in the configuration needs to be saved. For each of these data items, there 

will be a structure member. 

To support the ability to store data in multiple physical locations, one needs to be able to specify which 

data items will reside in which NV storage location. A common scenario would be that a developer 

might have the results of many questions reside in the systemboard NVRAM, yet some of the questions 

might reside in another NV storage location. To differentiate between which is the system store and 

which is the alternate store the VFR_NV_KEY macro is used in the structure definition. 

The VFR compiler will read the structure that has the macro with a 0 input as the system store 

descriptor. All structures with non-zero macro inputs are going to be considered to be non-system 

storage descriptors. 

A sample VFR entry which declares a system NV store descriptor might look like the following entry: 

nvstorage 

handle = NULL, 

devicepath = NULL, 

key = NvRamMapKey; 

A sample VFR entry which declares a non-system NV store descriptor might look like the following 

entry: 

nvstorage handle = 1, 

44


DRAFT 

devicepath = 1, 

key = RaidControllerNvDataKey; 

For additional information on the nvstorage command see section 4.2.7. 

The following snapshot is from the definition file containing the #define values as well as the NV 

structure definitions. This example shows a structure NvRamMap with the VFR_NV_KEY macro. 

The macro uses an NvRamMapKey which has a definition of 0. This then defines a system NV store 

structure. Followed immediately after it is a RaidControllerNvData structure definition with the same 

macro and the RaidControllerNvDataKey. Since the macro input evaluates to a non-zero value, it by 

definition is defining a non-system NV store structure. 

#define NvRamMapKey 0 

#define RaidControllerNvDataKey 1 

struct { 

UINT16 

SystemPassword[20]; 

UINT16 

ModemInitializationString[60]; 

UINT8 

SerialPortEnable; 

UINT16 


UINT32 


} NvRamMap VFR_NV_KEY(NvRamMapKey); 

struct { 

UINT16 


UINT32 


} RaidControllerNvData VFR_NV_KEY(RaidControllerNvDataKey); 

45


DRAFT 

7 

HII Database Interface 

7.1 EFI Human Interface Infrastructure Protocol 

Summary 

The EFI_HII_PROTOCOL manages the HII database, a repository for data having to do with fonts, 

strings, forms, keyboards, and other future human interface items. 

GUID 

#define EFI_HII_PROTOCOL_GUID \ 

{ 0xb5f16136, 0x1144, 0x4d6a, 0xbb, 0xbb, 0x41, 0xf2, \ 

0xff, 0x1e, 0x1d, 0x4 } 

Protocol Interface Structure 

typedef struct _EFI_HII_PROTOCOL { 

EFI_HII_NEW_PACK 

NewPack; 

EFI_HII_REMOVE_PACK 

RemovePack; 

EFI_HII_FIND_HANDLES 

FindHandles; 

EFI_HII_GET_GLYPH 

EFI_HII_GET_PRI_LANGUAGES 

EFI_HII_GET_SEC_LANGUAGES 

EFI_HII_NEW_STRING 

EFI_HII_GET_STRING 

EFI_HII_TEST_STRING 

EFI_HII_GET_LINE 

EFI_HII_GET_FORMS 

EFI_HII_UPDATE_FORM 

EFI_HII_GET_KEYBOARD_LAYOUT 

GetGlyph; 

GetPrimaryLanguages; 

GetSecondaryLanguages; 

NewString; 

GetString; 

TestString; 

GetLine; 

GetForms; 

UpdateForm; 

GetKeyboardLayout; 

} EFI_HII_PROTOCOL; 

Parameters 

NewPack 

RemovePack 

FindHandles 

Extracts the various packs from a package list. The descriptions of 

how each type of pack is processed are described in subsequent 

sections. 

Removes the package from the HII Database. 

Determines the handles that are currently active in the database. 

46


DRAFT 

GetGlyph 

GetPrimaryLanguages 

GetSecondaryLanguages 

NewString 

GetString 

TestString 

GetLine 

GetForms 

UpdateForm 

GetKeyboard 

Translates a Unicode character into the corresponding font glyph. 

This function allows a program to determine which primary 

languages are supported on a given handle. 

This function allows a program to determine which secondary 

languages are supported on a given handle for a given primary 

language. 

This function allows a new String to be added to an already existing 

String Package. 

This function extracts a string from a package already registered with 

the HII database. 

Test if all of the characters in a string have corresponding font 

characters. 

This function allows a program to extract a part of a string of not 

more than a given width. 

This function allows a program to extract a form or form package 

that has previously been registered with the EFI HII database. 

This function allows the caller to update a form or form package that 

has previously been registered with the EFI HII database. 

This function provides the caller with the current keyboard layout 

definitions that is registered with the HII Database. 

Description 

Extracts the various packs from a package list. The descriptions of how each type of pack is processed 

are described in subsequent sections. 

47


DRAFT 

Related Definitions 

typedef UINT16 RELOFST 

typedef UINT16 STRING_REF 

RELOFST is a 16-bit word offset relative to the start of the encompassing String Pack structure, thus 

providing position independence for the entire structure. 

STRING_REF is a variable that can contain a STRING_TOKEN. When used in programs, string 

tokens are fundamentally constants. 

typedef UINTN EFI_HII_HANDLE; 

typedef CHAR16 * EFI_STRING; 

typedef UINT16 EFI_FORM_ID; 

typedef UINT16 EFI_FORM_LABEL; 

// 

// The following types are currently defined: 

// 

#define EFI_HII_FONT 1 

#define EFI_HII_STRING 2 

#define EFI_HII_IFR 3 

#define EFI_HII_KEYBOARD 4 


UINT32 Length; 

UINT16 Type; 

} EFI_HII_PACK_HEADER; 

// 

// A string package is used to localize strings to a particular 

// language. The package is associated with a particular driver 

// or set of drivers. Tools are used to associate tokens with 

// string references in forms and in programs. These tokens are 

// language agnostic. When paired with a language pack (directly 

// or indirectly), the string token resolves into an actual 

// UNICODE string. 

// 

// 

// LanguageNameString The string containing one or more ISO 639-2 

// three character designator of the language or languages whose 

// translations are contained in this language pack. The first 

// designator indicates the primary language while the others are 

// secondary languages. 

// 

// PrintableLanguageName Contains the offset into this structure 

48


DRAFT 

// of a printable name of the language for use when prompting the 

// user. The language printed is to be the primary language. 

// 

// 

// String attributes 

// 

#define LANG_RIGHT_TO_LEFT 0x00000001 

LANG_RIGHT_TO_LEFT: If on, the language is intended to be printed right to left. The default (off) 

is to print left to right. 

// 

// StringPointers Are relative offsets from the beginning of the 

// package to each corresponding string. This 

// list of pointers will be null-terminated. 

// 


EFI_HII_PACK_HEADER Header; 

RELOFST LanguageNameString; 

RELOFST PrintableLanguageName; 

UINT32 Attributes; 

RELOFST StringsPointers[1]; 

STRING Strings[1]; 

} EFI_HII_STRING_PACK; 

// 

// Glyph Attributes 

// 

#define GLYPH_NON_SPACING 1 

#define GLYPH_NON_BREAKING 2 

Unicode defines several non-spacing characters which are generally used to implement uncommon 

accents, etc (as in Vietnamese). The idea is to ‘or’ the non-spacing character over the succeeding 

character. 


CHAR16 

UnicodeWeight; 

UINT8 

Attributes; 

UINT8 

GlyphCol1[19]; 

} EFI_NARROW_GLYPH; 


CHAR16 UnicodeWeight; 

UINT8 

Attributes; 

UINT8 

GlyphCol1[19], GlyphCol2[19]; 

UINT8 

Pad[3]; 

} EFI_WIDE_GLYPH; 

49


DRAFT 

// 

// A font list consists of a font header followed by a series 

// of glyph structures. Note that fonts are not language specific. 

// 



UINT16 

NumberOfNarrowGlyphs; 

UINT16 

NumberOfWideGlyphs; 

EFI_NARROW_GLYPH NarrowGlyphs[1]; 

EFI_WIDE_GLYPH WideGlyphs[1]; 

} EFI_HII_FONT_PACK; 

// 

// A form list consists of a large variety of structure 

// possibilities so to represent the binary blob of data 

// associated with a package of forms, we will assume a 

// pointer to a self-describing data buffer. 

// 



VOID 

*IfrData; 

} EFI_HII_IFR_PACK; 

typedef enum { 

EfiKeyLCtrl, EfiKeyA0, EfiKeyLAlt, EfiKeySpaceBar, 

EfiKeyA2, EfiKeyA3, EfiKeyA4, EfiKeyRCtrl, EfiKeyLeftArrow, 

EfiKeyDownArrow, EfiKeyRightArrow, EfiKeyZero, 

EfiKeyPeriod, EfiKeyEnter, EfiKeyLShift, EfiKeyB0, 

EfiKeyB1, EfiKeyB2, EfiKeyB3, EfiKeyB4, EfiKeyB5, EfiKeyB6, 

EfiKeyB7, EfiKeyB8, EfiKeyB9, EfiKeyB10, EfiKeyRshift, 

EfiKeyUpArrow, EfiKeyOne, EfiKeyTwo, EfiKeyThree, 

EfiKeyCapsLock, EfiKeyC1, EfiKeyC2, EfiKeyC3, EfiKeyC4, 

EfiKeyC5, EfiKeyC6, EfiKeyC7, EfiKeyC8, EfiKeyC9, 

EfiKeyC10, EfiKeyC11, EfiKeyC12, EfiKeyFour, EfiKeyFive, 

EfiKeySix, EfiKeyPlus, EfiKeyTab, EfiKeyD1, EfiKeyD2, 

EfiKeyD3, EfiKeyD4, EfiKeyD5, EfiKeyD6, EfiKeyD7, EfiKeyD8, 

EfiKeyD9, EfiKeyD10, EfiKeyD11, EfiKeyD12, EfiKeyD13, 

EfiKeyDel, EfiKeyEnd, EfiKeyPgDn, EfiKeySeven, EfiKeyEight, 

EfiKeyNine, EfiKeyE0, EfiKeyE1, EfiKeyE2, EfiKeyE3, 

EfiKeyE4, EfiKeyE5, EfiKeyE6, EfiKeyE7, EfiKeyE8, EfiKeyE9, 

EfiKeyE10, EfiKeyE11, EfiKeyE12, EfiKeyBackSpace, 

EfiKeyIns, EfiKeyHome, EfiKeyPgUp, EfiKeyNLck, EfiKeySlash, 

EfiKeyAsterisk, EfiKeyMinus, EfiKeyEsc, EfiKeyF1, EfiKeyF2, 

EfiKeyF3, EfiKeyF4, EfiKeyF5, EfiKeyF6, EfiKeyF7, EfiKeyF8, 

EfiKeyF9, EfiKeyF10, EfiKeyF11, EfiKeyF12, EfiKeyPrint, 

EfiKeySLck, EfiKeyPause 

50


DRAFT 

} EFI_KEY; 

Figure 1 


EFI_KEY 

CHAR16 

CHAR16 

CHAR16 

CHAR16 

UINT16 

} EFI_KEY_DESCRIPTOR; 

Key; 

Unicode; 

ShiftedUnicode; 

AltGrUnicode; 

ShiftedAltGrUnicode; 

Modifier; 

// 

// This structure allows a sparse set of keys to be redefined 

// or a complete redefinition of the keyboard layout. Most 

// keyboards have a lot of commonality in their layouts, therefore 

// only defining those keys that need to change from the default 

// minimizes the passed in information. 

// 

// Additionally, when an update occurs, the active keyboard layout 

// will be switched to the newly updated keyboard layout. This 

// allows for situations that when a keyboard layout driver is 

// loaded as part of system initialization, the system will default 

// the keyboard behavior to the new layout. 

// 

// Each call to update the keyboard mapping should contain the 

// complete set of key descriptors to be updated, since every 

// call to the HII which contains an EFI_HII_KEYBOARD_PACK will 

// wipe the previous set of overrides. A call to 

// 



EFI_KEY_DESCRIPTOR *Descriptor; 

UINTN 

DescriptorCount; 

} EFI_HII_KEYBOARD_PACK; 

typedef union { 

EFI_HII_IFR_PACK 

EFI_HII_FONT_PACK 

EFI_HII_STRING_PACK 

EFI_HII_KEYBOARD_PACK 

} EFI_HII_PACK_LIST; 

*IfrPack; 

*FontPack; 

*StringPack; 

*KeyboardPack; 

51


DRAFT 

7.1.1 EFI_HII_PROTOCOL.NewPack() 

Summary 

Extracts the various packs from a package list. 

Prototype 

EFI_STATUS 

(EFIAPI *EFI_HII_NEW_PACK) ( 

IN EFI_HII_PROTOCOL 

IN EFI_HII_PACK_LIST 

OUT EFI_HII_HANDLE 

); 

*This, 

*Package, 

*Handle 

Parameters 

This 

PackageList 

Handle 

A pointer to the EFI_HII_PROTOCOL instance. 

A pointer to an EFI_HII_PACK_LIST package instance. 

A pointer to the EFI_HII_HANDLE instance. 

Description 

With the exception of font and keyboard data, this function adds the contents of the package list to the 

database and returns a handle back to the data. Font and keyboard data is kept in a common pool and 

will have a NULL handle associated with them. In the case where a PackageList contains both 

pooled data and database data, a valid handle will be returned upon the addition of the appropriate data 

into the database. 

Status Codes Returned 

EFI_SUCCESS 

EFI_INVALID_PARAMETER 

Data was extracted from the Package, Database was updated with 

the data, and Handle returned successfully. 

The content of the Package was invalid. 

52


DRAFT 

7.1.2 EFI_HII_PROTOCOL.RemovePack() 

Summary 

Remove a package from the HII Database. 

Prototype 

EFI_STATUS 

(EFIAPI *EFI_HII_REMOVE_PACK) ( 


IN EFI_HII_HANDLE 

); 

*This, 

Handle 

Parameters 

This 

Handle 


The handle that was registered to the data that is being requested to 

be removed. 

Description 

This function removes the string and/or form data associated with a handle from the HII database. This 

function has no effect on keyboard or font data that may have been registered with the NewPack 

function. 


EFI_SUCCESS 


The data associated with the Handle was removed from the HII 

Database. 

The Handle was not valid. 

53


DRAFT 

7.1.3 EFI_HII_PROTOCOL.FindHandles() 

Summary 

Determines the handles that are currently active in the database. 

Prototype 

EFI_STATUS 

(EFIAPI *EFI_HII_FIND_HANDLES) ( 

IN EFI_HII_PROTOCOL *This, 

IN OUT UINT16 

*HandleBufferLength, 

OUT EFI_HII_HANDLE *Handle 

); 

Parameters 

This 

HandleBufferLength 

Handle 


A pointer to the length of the handle buffer on input. On output the 

actual number of handles. 

An array of EFI_HII_HANDLE instances returned. 

Description 

Determines the handles that are currently active in the database. As an example of use, a program 

wishing to create a Setup-like configuration utility would use this call to determine the handles 

available. It would then use calls defined in the forms section below to extract forms and then interpret 

them. 


EFI_SUCCESS 

EFI_BUFFER_TOO_SMALL 

Handles[] updated successfully. 

The HandleBufferLength parameter indicates that Handle[] is too 

small to support the number of handles. HandleBufferLength is 

updated with a value that will enable the data to fit. 

54


DRAFT 

7.1.4 EFI_HII_PROTOCOL.TestString() 

Summary 

Test if all of the characters in a string have corresponding font characters. 

Prototype 

EFI_STATUS 

(EFIAPI *EFI_HII_TEST_STRING) ( 


IN CHAR16 *StringToTest, 

IN OUT UINT32 

*FirstMissing, 

OUT UINT32 *GlyphBufferSize 

); 

Parameters 

This 

StringToTest 

FirstMissing 

GlyphBufferSize 


A pointer to a Unicode string. 

A pointer to an index into the string. On input, the index of the first 

character in the StringToTest to examine. On exit, the index of 

the first character encountered for which a glyph is unavailable. If all 

glyphs in the string are available, the index is the index of the 

terminator of the string. 

A pointer to a value. On output, if the function returns 

EFI_SUCCESS, this contains the amount of memory required to 

store the string’s glyph equivalent. 

Description 

This function may be repeatedly called to determine subsequent missing characters. Note that the index 

pointed to by FirstMissing must be incremented between calls. Line separator characters are 

ignored. 


EFI_SUCCESS 

EFI_NOT_FOUND 

All glyphs are available. (Note that an empty string always returns 

this value.) 

A glyph was not found for a character. 

55


DRAFT 

7.1.5 EFI_HII_PROTOCOL.GetGlyph() 

Summary 

Translates a Unicode character into the corresponding font glyph. 

Prototype 

EFI_STATUS 

(EFIAPI *EFI_HII_GET_GLYPH) ( 


IN CHAR16 *Source, 

IN OUT UINT16 

*Index, 

OUT UINT8 *GlyphBuffer, 

OUT UINT16 *BitWidth, 

IN OUT UINT32 

*InternalStatus 

); 

Parameters 

This 

Source 

Index 

GlyphBuffer 

BitWidth 

InternalStatus 


A pointer to a Unicode string. 

On input, the offset into the string to fetch the character from. On 

successful completion, the index is updated to the first character past 

the character(s) making up the just extracted glyph. 

Pointer to an array where the glyphs corresponding to the characters 

in the Source may be stored. GlyphBuffer is assumed to be wide 

enough to accept a wide glyph character. 

If EFI_SUCCESS was returned, the UINT16 pointed to by this 

value is filled with the length of the glyph in pixels. Unchanged if 

the call was unsuccessful. 

To save the time required to read the string from the beginning on 

each glyph extraction (to ensure that e.g. the narrow versus wide 

glyph mode is correct), this value is updated each time the function is 

called with status local to the call. The cell pointed to by this 

parameter must be initialized to 0 prior to invoking the call the first 

time for any string. 

Description 

The data returned is the format required for input to the UGA BLT routines. 


EFI_SUCCESS 

It worked. 

EFI_NOT_FOUND 

A glyph for a character was not found. 

56


DRAFT 

7.1.6 EFI_HII_PROTOCOL.NewString() 

Summary 

This function allows a new String to be added to an already existing String Package. 

Prototype 

EFI_STATUS 

(EFIAPI *EFI_HII_NEW_STRING) ( 


IN CHAR16 

*Language, 

IN EFI_HII_HANDLE Handle, 

IN STRING_REF 

*Reference, 

IN CHAR16 

*NewString 

); 

Parameters 

This 

Language 

Handle 


Pointer to a NULL-terminated string containing a single ISO-639-2 

language identifier, indicating the language the string is translated 

in. A string consisting of all spaces indicates that the string is 

applicable to all languages. 

The handle of the language pack to which the string is to be added. 

Reference The identifier of the string to be added. If the reference value is 0, 

then the string will be assigned a new identifier on that handle for 

the Language specified. Otherwise, the string will be updated with 

the NewString Value. 

NewString 

Description 

The string to be added. 

This routine adds a new string to a string package already submitted via NewPack. This string 

effectively overwrites existing strings. 


EFI_SUCCESS 


String effectively registered. 

Unknown handle. 

57


DRAFT 

7.1.7 EFI_HII_PROTOCOL.GetPrimaryLanguages() 

Summary 

This function allows a program to determine what the primary languages that are supported on a given 

handle. 

Prototype 

EFI_STATUS 

(EFIAPI *EFI_HII_GET_PRI_LANGUAGES) ( 


*This, 


Handle, 

OUT EFI_STRING 

*LanguageString 

); 

Parameters 

This 

Handle 

LanguageString 


Handle on which the strings reside. 

A string allocated by GetPrimaryLanguages containing a list of 

all primary languages registered on the handle. The routine will not 

return the 3-spaces language identifier used in other functions to 

indicate non-language-specific strings. 

Description 

This routine is intended to be used by drivers to query the interface database for supported languages. 

This routine returns a string of concatenated 3 byte language identifiers one per string package 

associated with the handle. 


EFI_SUCCESS 


Correctly returned the LanguageString. 


58


DRAFT 

7.1.8 EFI_HII_PROTOCOL.GetSecondaryLanguages() 

Summary 

This function allows a program to determine which secondary languages are supported on a given 

handle for a given primary language. 

Prototype 

EFI_STATUS 

(EFIAPI *EFI_HII_GET_SEC_LANGUAGES) ( 


*This, 


Handle, 

IN CHAR16 

*PrimaryLanguage, 

OUT EFI_STRING 

*LanguageString 

); 

Parameters 

This 

Handle 

PrimaryLanguage 



Handle on which the strings reside. 


language identifier, indicating the primary language. 

A string allocated by GetSecondaryLanguages containing a 

list of all secondary languages registered on the handle. The routine 

will not return the 3-spaces language identifier used in other 

functions to indicate non-language-specific strings, nor will it return 

the primary language. This function succeeds but returns a NULL 

LanguageString if there are no secondary languages associated 

with the input Handle and PrimaryLanguage pair. 

Description 

Each string package has associated with it a single primary language and zero or more secondary 

languages. This routine returns the secondary languages associated with a string package. The string 

package is identified by the package list handle and the (currently three character ISO-639-2 primary 

language identifier. 


EFI_SUCCESS 


Correctly returned the LanguageString. 


59


DRAFT 

7.1.9 EFI_HII_PROTOCOL.GetString() 

Summary 

This function extracts a string from a package already registered with the EFI HII database. 

Prototype 

EFI_STATUS 

(EFIAPI *EFI_HII_GET_STRING) ( 



IN STRING_REF Token, 

IN BOOLEAN Raw, 

IN CHAR16 *LanguageString, 

IN OUT UINT16 

*BufferLength, 

OUT EFI_STRING *StringBuffer 

); 

Parameters 

This 

Handle 

Token 

Raw 


BufferLength 

StringBuffer 


Handle on which the string resides. 

The string token assigned to the string. 

If true, the string is returned unedited in the internal storage format 

described above. If false, the string returned is edited by replacing 

with and by removing special characters such as the 

prefix. 


language identifier, indicating the language to print. If the 

LanguageString is empty (starts with a NULL) the default system 

language will be used to determine the language. 

Length of the StringBuffer. If the status reports that the buffer 

width is too small, this parameter is filled with the length of the 

buffer needed. 

The buffer designed to receive the characters in the string. 

Description 

This routine extracts a string from the package database. The string may be extracted in internal or 

external formats. 


EFI_SUCCESS 



StringBuffer is filled with a null-terminated string. 

Unknown handle or string token. 

The buffer provided was not large enough to allow the 

60


DRAFT 

entire string to be stored. 

61


DRAFT 

7.1.10 EFI_HII_PROTOCOL.GetLine() 

Summary 

This function allows a program to extract a part of a string of not more than a given width. With 

repeated calls, this allows a calling program to extract “lines” of text that fit inside columns. The effort 

of measuring the fit of strings inside columns is localized to this call. 

Prototype 

EFI_STATUS 

(EFIAPI *EFI_HII_GET_LINE) ( 



IN STRING_REF Token, 

IN OUT UINT16 

*Index, 

IN UINT16 LineWidth, 

IN CHAR16 *LanguageString, 

IN OUT UINT16 


OUT EFI_STRING *StringBuffer 

); 

Parameters 

This 

Handle 

Token 

Index 

LineWidth 


BufferLength 

StringBuffer 


Handle on which the string resides. 

The string token assigned to the string. 

On input, the offset into the string where the line is to start. On 

output, the index is updated to point to beyond the last character 

returned in the call. The interface is designed so that repeated calls 

will fill the buffer with subsequent parameters. 

The maximum width of the line in units of narrow glyphs. Specific 

line breaks (as in the case of two carriage returns) are still honored 

resulting in separate lines. The buffer is padded to the length in 

narrow spaces. 


language identifier, indicating the language to print. If the 

LanguageString is empty (starts with a NULL) the default system 

language will be used to determine the language. 

Pointer to the Length of the StringBuffer. If the status reports 

that the buffer width is too small, this parameter is filled with the 

length of the buffer needed. 

The buffer designed to receive the characters in the string. 

Description 

62


DRAFT 

This function is used to extract parts of a string so that those parts of strings fit inside a column of a 

defined width. This is commonly used in menuing applications. 


EFI_SUCCESS 

EFI_NOT_FOUND 


StringBuffer filled with characters that will fit on the 

line. 

The font glyph for at least one of the characters in the 

string is not in the font database. 


entire string to be stored. Note that the BufferWidth 

may need to be larger than the LineWidth due to e.g. 

non-spacing characters. 

63


DRAFT 

7.1.11 EFI_HII_PROTOCOL.GetForms() 

Summary 

This function allows a program to extract a form or form package that has previously been registered 

with the EFI HII database. 

Prototype 

EFI_STATUS 

(EFIAPI *EFI_HII_GET_FORMS) ( 



IN EFI_FORM_ID FormId, 

IN OUT UINT16 


OUT UINT8 *Buffer 

); 

Parameters 

This 

Handle 

FormId 

BufferLength 

Buffer 


Handle on which the form resides. 

The id of the form to return. If the id is zero, the entire form package 

is returned. 

On input, the length of the Buffer. On output, the length of the 

returned buffer, if the length was sufficient and, if it was not, the 

length that is required to fit the requested form(s). 

The buffer designed to receive the form(s). 

Description 

This function is used to extract a form or forms 


EFI_SUCCESS 


EFI_NOT_FOUND 


Buffer filled with the requested forms. 

BufferLength updated. 


A form on the requested handle cannot be found with the 

requested FormId. 


form to be stored. 

64


DRAFT 

7.1.12 EFI_HII_PROTOCOL.UpdateForm() 

Summary 

This function allows the caller to update a form or form package that has previously been registered 


Prototype 

EFI_STATUS 

(EFIAPI *EFI_HII_UPDATE_FORM) { 



IN EFI_FORM_LABEL Label, 

IN UINT16 

BufferLength, 

IN UINT8 

*Buffer 

}; 

Parameters 

This 

Handle 

Label 

BufferLength 

Buffer 


Handle of the package where the form to be updated resides. 

The label inside the form package where the update is to take place. 

The length of the Buffer. 

The buffer containing the new tags to insert before Label. 

Description 

This function allows a program to update a form at runtime. The form must have been built expecting 

the update, as a labÄel tag is required. The tags in Buffer are inserted into the form just prior to the 

label tag. 


EFI_SUCCESS 


EFI_NOT_FOUND 

The Form was updated with the new tags. 

The buffer for the buffer length does not contain an integral 

number of tags. 

The Handle, Label, or FormId was not found. 

65


DRAFT 

7.1.13 EFI_HII_PROTOCOL.GetKeyboardLayout() 

Summary 

This function allows a program to retrieve the keyboard layout data that has previously been registered 


Prototype 

EFI_STATUS 

(EFIAPI *EFI_HII_GET_KEYBOARD_LAYOUT) ( 


IN OUT UINT16 

DescriptorCount, 

OUT EFI_KEY_DESCRIPTOR *Descriptor 

); 

Parameters 

This 

DescriptorCount 

Descriptor 


On input, the number of Descriptor entries the buffer can hold. 

On output, the number of entries of the returned buffer, if the length 

was sufficient and, if it was not, the number of entries that is required 

to fit the requested keyboard layout data. 

The pointer to the buffer designed to receive the keyboard layout 

data. 

Description 

This function is used to extract the keyboard layout. The returned buffer will contain the current default 

system descriptor data merged with any override keyboard data. For example, if the firmware default 

keyboard is the U.S. keyboard and a driver added via NewPack a keyboard descriptor set for a 

Germany keyboard, the layout which is retrieved will reflect the U.S. keyboard with the Germany 

overrides. 

If a program needed to acquire the base keyboard layout, it could do the following: Issue a 

GetKeyboardLayout and cache the results. Issue a NewPack with a keyboard descriptor count of 

zero to wipe out the keyboard overrides. Issue a GetKeyboardLayout to get the base keyboard 

layout, and update via NewPack the original overrides. 


EFI_SUCCESS 


KeyDescriptor filled with the requested keyboard 

layout. KeyDescriptorCount updated. 


form to be stored. 

66


DRAFT 

7.2 EFI Form Configuration Protocol 

Summary 

The EFI_FORM_CONFIGURATION_PROTOCOL is the interface to the EFI Configuration Driver. 

This will allow the caller to direct the configuration driver to use either the HII database or use the 

passed in packet of data. This will also allow the caller to post messages into the configuration drivers 

internal mailbox. 

GUID 

#define EFI_FORM_CONFIGURATION_PROTOCOL_GUID \ 

{ 0xe5a1333e, 0xe1b4, 0x4d55, 0xce, 0xeb, 0x35, 0xc3, \ 

0xef, 0x13, 0x34, 0x43 } 


typedef struct _EFI_FORM_CONFIGURATION_PROTOCOL { 

EFI_SEND_FORM 

SendForm; 

EFI_SEND_MESSAGE 

SendMessage; 

} EFI_FORM_CONFIGURATION_PROTOCOL; 

Parameters 

SendForm 

SendMessage 

This function provides direction to the configuration driver whether 

to use the HII database or to use a passed-in set of data. This also 

establishes a pointer to the calling driver’s callback interface. 

This function allows the caller to put data into the configuration 

driver’s internal mailbox. This has the effect of allowing data to be 

posted as a key/value pair and have information be updated as an 

out-of-band transaction. 

Description 

This is the interface to call for drivers to leverage the EFI Configuration Driver interface. 


67


DRAFT 

7.2.1 EFI_FORM_CONFIGURATION_PROTOCOL.SendForm() 

Summary 

This function provides direction to the configuration driver whether to use the HII database or to use a 

passed-in set of data. This also establishes a pointer to the calling driver’s callback interface. 

Prototype 

EFI_STATUS 

(EFIAPI *EFI_SEND_FORM) ( 

IN EFI_FORM_CONFIGURATION_PROTOCOL *This, 

IN BOOLEAN 

UseDatabase, 

IN EFI_IFR_PACKET 

*Packet, 

IN EFI_HANDLE 

CallbackHandle 

); 

Parameters 

This 

UseDatabase 

Packet 

CallbackHandle 

A pointer to the EFI_FORM_CONFIGURATION_PROTOCOL 

instance. 

Determine whether or not the HII database is to be used to gather 

information. If the value is FALSE then the configuration driver 

will get the information provided in the passed in Packet or 

Message parameters. 

A pointer to a set of data containing pointers to IFR, and/or String 

data. 

The handle to the calling driver’s callback interface. 


#define EFI_HII_FONT 1 

#define EFI_HII_STRING 2 

#define EFI_HII_IFR 3 

#define EFI_HII_KEYBOARD 4 

typedef struct _EFI_HII_PACKET { 

UINT32 

Length; 

UINT16 

Type; 

} EFI_HII_PACKET; 




} EFI_IFR_PACKET; 

*IfrData; 

*StringData; 

68


DRAFT 


EFI_SUCCESS 

EFI_NOT_FOUND 



EFI_DEVICE_ERROR 

The function completed successfully 

The variable was not found. 

The DataSize is too small for the result. DataSize has 

been updated with the size needed to complete the 

request. 

One of the parameters has an invalid value. 

The variable could not be saved due to a hardware failure. 

69


DRAFT 

7.2.2 EFI_FORM_CONFIGURATION_PROTOCOL.SendMessage() 

Summary 

This function allows the caller to put data into the configuration driver’s internal mailbox. This has the 

effect of allowing data to be posted as a key/value pair and have information be updated as an out-ofband 

transaction. 

Prototype 

EFI_STATUS 

(EFIAPI *EFI_SEND_MESSAGE) ( 

IN EFI_FORM_CONFIGURATION_PROTOCOL *This, 

IN UINT16 

MessageKey, 

IN VOID 

*MessageData, 

IN UINTN 

MessageDataLength 

); 

Parameters 

This 

MessageKey 

MessageData 

MessageDataLength 

A pointer to the EFI_FORM_CONFIGURATION_PROTOCOL 

instance. 

A unique value which will have be associated with a particular opcode. 

The messaging services are typically to be used in an 

Interactive or Dynamic mode situation where a periodic event may 

occur that requires certain pieces of data to be updated. For 

instance, temperature sensor data might get dynamically updated 

based on events from the calling driver. 

A pointer to the data associated with the MessageKey. 

The length of the data in MessageData. 


The MessageData format will be based on the op-code type that the 

MessageKey references. 

If OneOf command: 

An array of option encodings. 

Each encoding is as follows: 

typedef struct _EFI_IFR_OP_HEADER { 

UINT8 

OpCode; 

UINT8 

Length; 

} EFI_IFR_OP_HEADER; 


EFI_IFR_OP_HEADER 

Header; 

70


DRAFT 

STRING_REF Option; // The string token describing the option 

UINT16 Value; // The value associated with this option that is stored in 

// the NVRAM if chosen 

UINT8 Flags; // For now, if non-zero, means that it is the default 

// option, - further definition likely above 

UINT16 Key; // Value to be passed to caller to identify this particular 

// op-code 

} EFI_IFR_ONE_OF_OPTION; 

If Text command: 

An update for the second text parameter 


CHAR16 

*UpdateString 

If StringOp command: 



CHAR16 *UpdateString; // String to print as a status (May be NULL) 

BOOLEAN PopUp; // Create a PopUp box for the UpdateString 

} EFI_IFR_STRING_MESSAGE; 

If NumericOp command: 


UINT16 

NumericValue; 


EFI_SUCCESS 

EFI_NOT_FOUND 








request. 



• 

71


DRAFT 

7.3 EFI Form Callback Protocol 

Summary 

The EFI_FORM_CALLBACK_PROTOCOL is the defined interface for access to custom NV storage 

devices as well as communication of user selections in a more interactive environment. This protocol 

should be published by hardware specific drivers which want to export access to custom hardware 

storage or publish IFR which has a requirement to call back the original driver. 

GUID 

#define EFI_FORM_CALLBACK_PROTOCOL_GUID \ 

{ 0xf3e4543d, 0xcf35, 0x6cef, 0x35, 0xc4, 0x4f, 0xe6, \ 

0x34, 0x4d, 0xfc, 0x54 } 


typedef struct _EFI_FORM_CALLBACK_PROTOCOL { 

EFI_NV_READ 

NvRead; 

EFI_NV_WRITE 

NvWrite; 

EFI_FORM_CALLBACK 

Callback; 

} EFI_FORM_CALLBACK_PROTOCOL; 

Parameters 

Read 

Write 

Callback 

This is the read operation to access the NV data serviced by a 

hardware specific driver. 

This is the write operation to access the NV data serviced by a 

hardware specific driver. 

This is the function that is called from the configuration browser to 

communicate key value pairs. 

Description 

This is the interface that is provided by hardware specific drivers that control access to non-system NV 

storage and support callbacks from the browser or HII. 

72


DRAFT 

7.3.1 EFI_FORM_CALLBACK_PROTOCOL.NvRead() 

Summary 

Returns the value of a variable. 

Prototype 

EFI_STATUS 

(EFIAPI *EFI_NV_READ) ( 

IN EFI_FORM_CALLBACK_PROTOCOL *This, 

IN CHAR16 

*VariableName, 

IN EFI_GUID 

*VendorGuid, 

OUT UINT32 

*Attributes OPTIONAL, 

IN OUT UINTN 

*DataSize, 

OUT VOID 

*Buffer 

); 

Parameters 

This 

VariableName 

VendorGuid 

Attributes 

DataSize 

Buffer 

A pointer to the EFI_FORM_CALLBACK_PROTOCOL instance. 

A Null-terminated Unicode string that is the name of the vendor’s 

variable. 

A unique identifier for the vendor. 

If not NULL, a pointer to the memory location to return the attributes 

bit-mask for the variable. See “Related Definitions”. 

The size in bytes of the Buffer. A size of zero causes the variable 

to be deleted. 

The buffer to return the contents of the variable. 


//********************************************************* 

// Variable Attributes 

//********************************************************* 

#define EFI_VARIABLE_NON_VOLATILE 

0x0000000000000001 

#define EFI_VARIABLE_BOOTSERVICE_ACCESS 0x0000000000000002 

#define EFI_VARIABLE_RUNTIME_ACCESS 

0x0000000000000004 

Description 

Each vendor may create and manage its own variables with the risk of name conflicts by using a unique 

VendorGuid. When a variable is set its Attributes are supplied to indicate how the data variable 

should be stored and maintained by the system. Any attempts to access a variable that does not have 

the attribute set for runtime access will yield the EFI_NOT_FOUND error. 


73


DRAFT 

EFI_SUCCESS 

EFI_NOT_FOUND 








request. 



74


DRAFT 

7.3.2 EFI_FORM_CALLBACK_PROTOCOL.NvWrite() 

Summary 

Sets the value of a variable. 

Prototype 

EFI_STATUS 

(EFIAPI *EFI_NV_WRITE) ( 


IN CHAR16 

*VariableName, 

IN EFI_GUID 

*VendorGuid, 

OUT UINT32 

*Attributes OPTIONAL, 

IN OUT UINTN 

*DataSize, 

OUT VOID 

*Buffer 

); 

Parameters 

This 

VariableName 

VendorGuid 

A pointer to the EFI_FORM_CALLBACK_PROTOCOL instance. 

A Null-terminated Unicode string that is the name of the vendor’s 

variable. Each VariableName is unique for each VendorGuid. 

A unique identifier for the vendor. 

Attributes Attributes bitmask to set for the variable. See section 7.3.1 

DataSize 

Buffer 

Description 

The size in bytes of the Buffer. A size of zero causes the variable 

to be deleted. 

The buffer to return the contents of the variable. 

Variables are stored by the firmware and may maintain their values across power cycles. Each vendor 

may create and manage its own variables without the risk of name conflicts by using a unique 

VendorGuid. 


EFI_SUCCESS 


EFI_OUT_OF_RESOURCES 


The firmware has successfully stored the variable and its 

data as defined by the Attributes. 

An invalid combination of Attribute bits was supplied, or 

the DataSize exceeds the maximum allowed. 

Not enough storage is available to hold the variable and its 

data. 


75


DRAFT 

7.3.3 EFI_FORM_CALLBACK_PROTOCOL.CallBack() 

Summary 

This is the function that is called to provide results data to the driver. This data consists of a unique key 

which is used to identify what data is either being passed back or being asked for. 

Prototype 

EFI_STATUS 

(EFIAPI *EFI_FORM_CALLBACK) ( 


IN UINT16 

KeyValue, 

IN VOID 

*Data 

); 

Parameters 

This 

KeyValue 

Data 

A pointer to the EFI_NV_ACCESS_PROTOCOL instance. 

A unique value which is sent to the original exporting driver so that 

it can identify the type of data to expect. The format of the data 

tends to vary based on the op-code that generated the callback. 

A pointer to the data being sent to the original exporting driver. 


The Data format will be based on the op-code type that the KeyValue 

references. 

If OneOf op-code the following is being passed in the Data pointer: 

UINT16 

Value 

If Text op-code there is no user initiated data to be sent other 

than the KeyValue. There should be a reasonable expectation that a 

response to this callback will be that a message gets posted with a 

particular key value and string. This would be done in the 

EFI_FORM_CONFIGURATION_PROTOCOL. 

NULL 

If String op-code the following is being passed in the Data pointer: 

CHAR16 

*String 

If Numeric op-code the following is being passed in the Data 

pointer: 

UINT16 

Value 

76


DRAFT 


EFI_SUCCESS 


EFI_OUT_OF_RESOURCES 


The firmware has successfully stored the variable and its 

data as defined by the Attributes. 

An invalid combination of Attribute bits was supplied, or 

the DataSize exceeds the maximum allowed. 

Not enough storage is available to hold the variable and its 

data. 


77


DRAFT 

8 

Simple Input Modification 

Modifications have been made in the SIMPLE_INPUT protocol to support additional keys. 

8.1 Extending Simple Input 

The SIMPLE_INPUT protocol has some extensions that are being added. The following is a modified 

version of the Control Characters and EFI Scan Codes for the SIMPLE_INPUT protocol. 

The SIMPLE_INPUT protocol defines an input stream that contains Unicode characters and required 

EFI scan codes. Only the control characters defined in Table 3-1 have meaning in the Unicode input or 

output streams. The input stream does not support any software flow control. 

Table 3-1. 

Supported Unicode Control Characters 

Mnemonic Unicode Description 

Null U+0000 Null character ignored when received. 

BS U+0008 Backspace. Moves cursor left one column. If the cursor is at the left 

margin, no action is taken. 

TAB U+0x0009 Tab. 

LF U+000A Linefeed. Moves cursor to the next line. 

CR U+000D Carriage Return. Moves cursor to left margin of the current line. 

The input stream supports Scan Codes in addition to Unicode characters. If the Scan Code is set to 

0x00 then the Unicode character is valid and should be used. If the Scan Code is set to a non-0x00 

value it represents a special key as defined by Table 3-2. 

Table 3-2. 

EFI Scan Codes for SIMPLE_INPUT_INTERFACE 

EFI Scan Code 

0x0000 

0x0001 

0x0002 

0x0003 

0x0004 

0x0005 

0x0006 

0x0007 

0x0008 

0x0009 

0x000a 

Description 

Null scan code. 

Move cursor up 1 row. 

Move cursor down 1 row. 

Move cursor right 1 column. 

Move cursor left 1 column. 

Home. 

End. 

Insert. 

Delete. 

Page Up. 

Page Down. 

78


DRAFT 

Table 3-2. EFI Scan Codes for SIMPLE_INPUT_INTERFACE (continued) 

EFI Scan Code Description 

0x000b Function 1. 

0x000c Function 2. 

0x000d Function 3. 

0x000e Function 4. 

0x000f Function 5. 

0x0010 Function 6. 





0x0015 Function 11. (Newly Proposed) 

0x0016 Function 12. (Newly Proposed) 

0x0017 Escape. 

Table 3- 3 Additional EFI Scan Codes for SIMPLE_INPUT_INTERFACE 

0x2000 Shift. (Newly Proposed) 

0x4000 Control. (Newly Proposed) 

0x8000 Alternate. (Newly Proposed) 

The following example shows the new definitions for the EFI Scan Codes, and provides the facility to 

export varying modifier states on non-printing characters. 

#define SCAN_F11 

#define SCAN_F12 

0x0015 

0x0016 

// 

// Bit 13 on = Shift 

// Bit 14 on = Control 

// Bit 15 on = Alt 

// 

// This allows for interpretation of Shift F10 for 

// the scan code by seeing a scan code of 0x2014 

// As it allows a Shift-Alt-F10 yielding a scan code of 0xA014 

// 

// Additionally, a Shift-Tab would be interpreted by reading 

// the EFI Scan code as a 0x2000, and a Unicode value of 0x0009. 

// 

#define SCAN_SHIFT 

0x2000 

#define SCAN_CONTROL 

0x4000 

#define SCAN_ALT 

0x8000 

79


DRAFT 

9 

HII Keyboard Support 

9.1 Keyboard Mapping 

The keyboard mapping that is defined in EFI is loosely based on ISO 9995. The naming mechanism is 

illustrated in Figure 2. The keys that are highlighted in red are the keys that almost all keyboard layouts 

use for customizations. That does not necessarily mean that all the keys are different. In fact, most of 

the keys are likely to be the same, however when modifying the mapping one can normally reference 

the keys in red as the likely candidates to create modifications for. 

Instead of referencing keys in hardware specific ways such as scan codes or HID entries, EFI now 

defines an EFI_KEY enumeration that allows for a simple way to reference this hardware abstraction. 

It also provides a way to update the keyboard layout with a great deal of flexibility. Any of the keys 

can be mapped to any Unicode value or control code value. 

Esc F1 F2 F3 F4 F5 F6 F7 F8 F9 F10 F11 F12 

Print SLck 

Pause 

E0 E1 E2 E3 E4 E5 E6 E7 E8 E9 E10 E11 E12 

Backspace 

Ins 

Home PgUp 

NLck / * 

- 

Tab D1 D2 D3 D4 D5 D6 D7 D8 D9 D10 D11 D12 D13* 

CapsLock C1 C2 C3 C4 C5 C6 C7 C8 C9 C10 C11 C12* Enter 

Del End PgDn 

7 8 9 

4 5 6 

+ 

LShift B0* B1 B2 B3 B4 B5 B6 B7 B8 B9 B10 RShift 

LCtrl A0 LAlt Space Bar A2 A3 A4 RCtrl 

1 2 3 

0 . 

Enter 

Figure 2 

When defining the values for a particular key, there are five elements that are pertinent to the key. 

Key Name: 

Unicode Value: 

The EFI_KEY enumeration (see Figure 1) defines the names of the above 

keys. 

This defines the Unicode value (if any) of the named key. 

Shifted Unicode Value: This defines the Unicode value (if any) of the named key while the shift 

modifier key is being pressed 

Alt-GR Unicode Value: This defines the Unicode value (if any) of the named key while the 

modifier key (if any) is being pressed. 

Alt-GR 

Shifted Alt-GR Unicode Value: This defines the Unicode value (if any) of the named key while the 

Shift and Alt-GR modifier key (if any) is being pressed. 

80


DRAFT 

Modifier Key Value: 

This defines the non-printable special function this key has assigned to it. 

Under normal circumstances, a key that has any Unicode definitions generally has a Control key value 

of SCAN_NULL. This means the key has no special function other than the printing of a character. If 

any of the Unicode values have a value of 0xFFFF this is the exception to the rule. Though rarely used, 

this is the one case which a key might have both a printable character and an active Control key value. 

An example of this would be the numeric keypad’s insert key. The definition for this key on a standard 

US keyboard is as follows: 

Key Name = ZERO_KEY 

Unicode Value = 0x0030 (basically a ‘0’) 

Shifted Unicode Value = 0xFFFF (the exception to the rule) 

Alt-GR Unicode Value = 0x0000 

Shifted Alt-GR Unicode Value = 0x0000 

Modifier Key Value = SCAN_INSERT 

This is one of the few keys that under normal circumstances prints something out, but also has a special 

function. These are generally limited to the numeric keypad, however this does not prevent someone 

from having the flexibility to define these types of variations. 

(Assuming for the implementation that the state of CapsLock and NumLock, etc will correctly handle 

the shift states since they do it already……just wanted to mention it and it was thought about) 

9.2 Modifier Key Definitions 

Modifier keys are defined to allow for special functionality that is not necessarily accomplished by a 

printable character. Many of these modifier keys are flags to toggle certain state bits on and off inside 

of a keyboard driver. An example is CAPS_LOCK_MODIFIER. This state being active could alter 

what the typing of a particular key produces. Other control keys affect the position of the cursor like 

LEFT_ARROW_MODIFIER, END_MODIFIER, etc. One modifier key is likely unfamiliar to most 

people who exclusively use US keyboards, and that key is the ALT_GR_MODIFIER key. This key’s 

primary purpose is to activate a secondary type of shift modifier that exposes additional printable 

characters on certain keys. In some keyboard layouts this key does not exist and is normally the 

RIGHT_ALT_MODIFIER key. None of the other modifier key functions should be a mystery to 

someone familiar with the usage of a standard computer keyboard. 

An example of a few descriptor entries would be as follows: 

Layout = { 

EfiKeyLCtrl,0,0,0,0,LEFT_CONTROL_MODIFIER, //(Left control key) 

EfiKeyA0,0,0,0,0,NULL_MODIFIER, 

//(Not defined windows key) 

EfiKeySpaceBar,0x0020,0x0020,0x0020,0x0020,NULL_MODIFIER //(Space Bar) 

} 

// 

// Define the Control modifier value information 

81


DRAFT 

// 

#define NULL_MODIFIER 

#define LEFT_CONTROL_MODIFIER 

#define RIGHT_CONTROL_MODIFIER 

#define LEFT_ALT_MODIFIER 

#define RIGHT_ALT_MODIFIER 

#define ALT_GR_MODIFIER 

#define INSERT_MODIFIER 

#define DELETE_MODIFIER 

#define PAGE_DOWN_MODIFIER 

#define PAGE_UP_MODIFIER 

#define HOME_MODIFIER 

#define END_MODIFIER 

#define LEFT_SHIFT_MODIFIER 

#define RIGHT_SHIFT_MODIFIER 

#define CAPS_LOCK_MODIFIER 

#define SHIFT_LOCK_MODIFIER 

#define NUM_LOCK _MODIFIER 

#define LEFT_ARROW_MODIFIER 

#define RIGHT_ARROW_MODIFIER 

#define DOWN_ARROW_MODIFIER 

#define UP_ARROW_MODIFIER 

0x0000 

0x0001 

0x0002 

0x0003 

0x0004 

0x0005 

0x0006 

0x0007 

0x0008 

0x0009 

0x000A 

0x000B 

0x000C 

0x000D 

0x000E 

0x000F 

0x0010 

0x0011 

0x0012 

0x0013 

0X0014 

// 

// For further explanations on Dead Keys see section 9.4 

// 

#define DEAD_KEY_MODIFIER 

0x0015 

#define DEAD_KEY_DEPENDENCY_MODIFIER 0x0016 

#define FUNCTION_KEY_ONE_MODIFIER 0x0017 

#define FUNCTION_KEY_TWO_MODIFIER 0x0018 

#define FUNCTION_KEY_THREE_MODIFIER 0x0019 

#define FUNCTION_KEY_FOUR_MODIFIER 0x001A 

#define FUNCTION_KEY_FIVE_MODIFIER 0x001B 

#define FUNCTION_KEY_SIX_MODIFIER 0x001C 

#define FUNCTION_KEY_SEVEN_MODIFIER 0x001D 

#define FUNCTION_KEY_EIGHT_MODIFIER 0x001E 

#define FUNCTION_KEY_NINE_MODIFIER 0x001F 

#define FUNCTION_KEY_TEN_MODIFIER 0x0020 

#define FUNCTION_KEY_ELEVEN_MODIFIER 0x0021 

#define FUNCTION_KEY_TWELVE_MODIFIER 0x0022 

// 

// Keys which have multiple Control functions based on modifier 

// settings are handled in the keyboard driver implementation. 

// For instance PRINT_KEY might have a modifier held down and 

// is still a non-printing character, but might have an alternate 

82


DRAFT 

// control function like SYSREQUEST 

// 

#define PRINT_MODIFIER 

#define SYS_REQUEST_MODIFIER 

#define SCROLL_LOCK_MODIFIER 

#define PAUSE_MODIFIER 

#define BREAK_MODIFIER 

0x0023 

0x0024 

0x0025 

0x0026 

0x0027 

9.3 Keyboard Layout Switching 

The need for switching from one keyboard layout to another is a very common implementation. A 

typical example would be for a user who needed to type in a language that did not have certain keys 

exposed (e.g. Typical Hebrew layout has no Latin characters). For these types of configurations, it 

would be common for the system to be aware of two completely different keyboard layouts and allow a 

hot key to switch between the default and the alternate layout. 

The way this would work in our given implementation would be that the firmware has some built-in 

keyboard layout. A driver installs the Hebrew layout. The user needs to switch modes and hits a hot 

key that forces the keyboard driver to switch from the Hebrew layout to the firmware’s Default layout. 

Hit the hot key again and the user mode switches again and the keyboard driver is now pointing to the 

Hebrew layout. 

// 

// To enable the ability to define what key combinations 

// designate a special function one could do some of the 

// following to allow for this flexibility. 

// 

// 

// This assumes that the driver implementation will not 

// assign a key definition if one of the following modifier 

// values is presented. 

// 

#define LAYOUT_SWITCH_MODIFIER 

0x0028 

#define LAYOUT_SWITCH_DEPENDENCY_MODIFIER 0x0029 

Layout = { 

EfiKeyLCtrl, 0, 0, 0, 0, LAYOUT_SWITCH_MODIFIER, 

EfiKeyLShift, 0, 0, 0, 0, LAYOUT_SWITCH_DEPENDENCY_MODIFIER 

} 

9.4 Dead Keys 

Dead keys are a concept that provides the ability to OR together an accent key and another printable 

character. Dead keys would be defined as a special type of Modifier character. They are typically 

83


DRAFT 

accent keys that do not advance the cursor and in essence are a type of modifier key in that they 

maintain some level of state. 

The way a person uses a dead key is that the dead key that maybe has the function of overlaying an 

umlaut (two dots) onto whatever the next character might be. The user presses the umlaut dead key and 

follows it with a capital A. This yields a “Ä” 

// 

// If it’s a dead key, we need to pass a list of physical key 

// names… each with a unicode, shifted, altgr, shiftedaltgr 

// value. Each key name will have a Modifier value of 

// DEAD_KEY_MODIFIER for first entry, and then the list of 

// DEAD_KEY_DEPENDENCY_MODIFIER physical key descriptions. 

// This eventually will lead to the next normal non-dead-key 

// definition. 

// 

// This requires defining an additional Modifier value of 

// DEAD_KEY_DEPENDENCY_MODIFIER to signify DEAD_KEY_MODIFIER 

// children definitions. 

// 

// The keyboard driver (consumer of the layouts) will know that 

// any key definitions with the DEAD_KEY_DEPENDENCY_MODIFIER 

// modifier do not redefine the value of the specified EFI_KEY. 

// They are simply used as a special case augmentation to the 

// original DEAD_KEY_MODIFIER. 

// 

// It is an error condition to define a DEAD_KEY_MODIFIER 

// without having all the DEAD_KEY_DEPENDENCY_MODIFIER 

// keys defined serially. 

// 

Layout = { 

EfiKeyE0, 0, 0, 0, 0, DEAD_KEY_MODIFIER, 

EfiKeyC1, 0x00E2, 0x00C2, 0, 0, DEAD_KEY_DEPENDENCY_MODIFIER, 

EfiKeyD3, 0x00EA, 0x00CA, 0, 0, DEAD_KEY_DEPENDENCY_MODIFIER, 

EfiKeyD8, 0x00EC, 0x00CC, 0, 0, DEAD_KEY_DEPENDENCY_MODIFIER, 

EfiKeyD9, 0x00F4, 0x00D4, 0, 0, DEAD_KEY_DEPENDENCY_MODIFIER, 

EfiKeyD7, 0x00FB, 0x00CB, 0, 0, DEAD_KEY_DEPENDENCY_MODIFIER, 

} 

In the above example, a key located at E0 is designated as a Dead Key. Using a common German 

keyboard layout as the example, at the E0 location a circumflex accent “^” is defined as a dead key. 

The valid keys that can be pressed after the dead key which will produce valid printable characters are 

the A, E, I, O, and U characters. These are located at C1, D3, D8, D9, and D7 respectively. 

The results of the Layout definition provided above would allow for the production of the following 

characters: âÂêÊîÎôÔûÛ. 

84


DRAFT 

9.4.1 Bi-directional Input (Reserved for future implementation) 

Many languages have left-to-right orientation, however some use right-to-left orientation for keyboard 

input. This requires the ability to handle both types of input. There are several issues to deal with 

when it comes to bi-directional input. 

There are some issues when it comes to the ability to type things in one orientation and in the middle of 

a set of words change directionality. This is common when typing in a right-to-left oriented language 

such as Hebrew and a word only makes sense to be typed in a non-right-to-left language. 

For instance, to type, “I love Intel too” one might type in Hebrew, גמ כן"‏ Intel אחוב ‏."אני To provide the 

ability to do switch orientation like this one needs to focus on some of the elements of bi-directional 

typing. 

9.4.1.1 Bi-directional segments 

Bi-directional text may consist of a main part that has one orientation (e.g. Hebrew text written from 

right-to-left), and portions that have opposite orientation (e.g. English text written left-to-right). The 

portion of text with different orientation is called a segment. Bi-directional text may have a body of 

right-to-left text with embedded left-to-right segments. 

There are two methods which support global orientation switching. One method requires manual 

intervention to switch between right-to-left and left-to-right, and the other automatically handles rightto-left 

orientation for characters that require them (e.g. Hebrew, Arabic, etc) and switch modes 

automatically for characters that require left-to-right handling (e.g. Arabic Numbers, English letters, 

etc.) 

For the EFI implementation, we will only support a manual method of orientation switching. 

9.4.1.2 Orientation Hot Keys 

For the EFI implementation, a hot key would be created to enable switching of keyboard orientation. 

When switching orientation this is called going into “Push” mode. 

The switching of orientation modes affects input direction. However we need to give some thought to 

the saving of text information in such a way as to allow for the appropriate readability when loaded in 

at a later time. One proposal might be that when typing from right to left, the data being saved is 

orientation agnostic. Meaning, that if I typed one through 4 and it displayed “4321” when that 

information is saved or redirected to a file it is stored as it is typed, not as it was displayed. 

The ability to switch orientations should be an easy task that allows for the minimum of effort. A 

simple two-key combination of two untranslatable keys would be the appropriate methodology. The 

suggested hot key combination would be holding down the EfiKeyRCtrl and the EfiKeyRShift 

to enable the orientation toggle. 

9.4.1.2.1 Push Mode 

When the orientation hot key is pressed the user enters push mode. Push mode is a keyboard input 

mode in which characters are “pushed” in the direction opposite to the base direction of the segment. 

The cursor does not move. When the orientation hot key is pressed again, the user enters into the 

previous bi-directional mode. 

אחוב“‏ was typed the user would have typed ‏”אני אחוב Intel גמ כן“‏ An example of this is when the phrase 

then they would have pressed the orientation hot key to enable push mode. This would have ‏”אני 

85


DRAFT 

proceeded to “push” the characters already typed to the right keeping the cursor in the same relative 

position to the originally typed phrase. The user would then press the orientation hot key again to 

enable left-to-right mode and then type Intel. This would yield the “Intel אחוב ‏”אני with the cursor 

between the word “Intel” and the phrase אחוב“‏ ‏.”אני The user would then press the orientation hot key 

again to switch off the push mode and likely hit the END key to go to the end of the line (in right-to-left 

‏.”אני אחוב Intel גמ כן“‏ orientation) and proceed to complete typing the complete phrase of 

86

SetupDesignGuide.pdf - Firmware Encoding Index

You also want an ePaper? Increase the reach of your titles

Delete template?

Save as template?