UEFI HII (Part 2)

This week, we will look at some of the key elements of the Human Interface Infrastructure portion of the UEFI 2.1 and later specifications. UEFI platform firmware provides two key facilities:

1. The HII Database. The database acts a repository for all sorts of configuration and user-interface resources, including forms, fonts, strings, images, animations, and keyboard layouts. The platform and individual drivers can install and remove these resources.
2. The HII Forms Browser. The browser is the platform-provided user interface where the forms are displayed and input from the user is taken in order to update configuration settings.

The platform firmware decides when the user interface should be displayed. This is different from legacy BIOS and UEFI 2.0, where individual option ROMs could put up their own user interface elements, provide their own boot hot keys for entering those utilities and delay the boot in order to display instructions and copyright information. Now, with UEFI 2.1 and beyond, the individual drivers provide user interface information to the platform and the platform presents it to the user.

In most implementations, the decision about when is controlled by the UEFI Boot Manager. The how might be part of the boot manager itself or a separate driver or application. Why? The boot manager is already responsible for hot keys for launching boot options and applications. The boot manager is also responsible for the UEFI driver health support and the UEFI user identification support, both of which can be user-interface intensive and are heavily involved with the boot process.

For drivers, the most important API is the EFI_HII_DATABASE_PROTOCOL. Normally, during driver initialization (if one page manages all driver-supported devices) or during Start(), the driver will install the forms and strings that it will use for configuration, driver health and user identification using NewPackageList().

The next important API for drivers is the EFI_HII_CONFIG_ACCESS_PROTOCOL, which is provided by the driver to handle configuration-related behaviors. This protocol provides three important functions:

1. ExtractConfig(). Return the current configuration settings.
2. RouteConfig() . Change the current configuration settings.
3. Callback(). Handle callbacks while the user is interacting with the forms.

That's it. The driver publishes forms and strings and provides a way to read and write configuration values and handle callbacks from the forms. Of course, there's a lot more in the nitty-gritty details and we'll dig into that soon.

But next, week we will spend a little time on how the resources are put together and delivered to the HII Database and even OS-present applications.

UEFI HII (Part 1)

Starting with version 2.1, the UEFI Specification began to describe a standardized way in which firmware could communicate with a user or application concerning firmware-related settings. Previously, the EFI 1.10 specification had the EFI_DRIVER_CONFIGURATION_PROTOCOL, which provided a means by which driver could take control of the console and throw up their own configuration screens. This mechanism provided a great deal of flexibility. The platform firmware could provide its own instance of this protocol for motherboard components and each of the 3rd party drivers, such as those on plug-in cards, could provide an instance also. A platform firmware application could list out these instances for a user to choose from. But this decentralized approach led to other problems. It meant that:

1. There was no consistent look-and-feel for a platform, since each driver got to pick its own color scheme, its own keyboard commands and its own screen layout.
2. Individual drivers had to make assumptions about the type of input and output devices available. For example, some platforms might have five buttons and a two line 25 character LCD display while others might have BitBlt graphics and input-method editors. 3rd party drivers would have to invest a lot to make their drivers work on a wide range of consoles.
3. There was no means of centralized platform configuration (for provisioning or remote management). For example, if I wanted to save the settings from one platform and use those to configure a brand-new bare-metal platform. How to get ahold of the settings and apply them in a uniform fashion?

In order to address these issues, the UEFI 2.1 specification introduced the Human Interface Infrastructure (HII), which was designed to give the platform firmware centralized control over how input, output and configuration were managed. HII includes everything from fonts, bitmaps, forms to the routing of configuration information between the system and drivers. There were several goals when we created HII. These included:

• Localization. Localization is the process by which a product is adapted to a local market. Most significantly for platform firmware, this includes display languages and input languages.
• Forms. Forms provide the abstraction by which drivers expose the configuration settings to the platform firmware.
• Remote and Off-Line and OS-Present Configuration. The configuration settings for a platform must be exposed in such a way that an implementation could support a variety of alternate ways to configure the platform. For example, remote scripting, remote interactive, semi-interactive (off-line but with forms) or OS application-driven configuration of the platform.
• Provide APIs which would allow drivers, including those on plug-in cards to have full access to the HII resources, including fonts, strings and forms, and be able to contribute additional resources.
• Support a wide-range of display devices.

This led to a fairly sophisicated and flexible infrastructure and a lot of confusion, because in many places the HII specification added abstractions between display, configuration and configuration storage that had never existed before in the firmware world. Next week, we'll look at some of the key design decisions and why they were made.

UEFI Shell: Profiles

Last time, I discussed how the UEFI Shell can come in four basic flavors, called support levels. Level 0 was the most basic, supporting almost all of the API, but none of the scripting language and no user interface. Level 1 added basic scripting. Level 2 added file manipulation scripting. Level 3 added user-interface related scripting. Ok. So now we have a robust shell. But it can't do very much. In a manufacturing environment, it is important that software developers, including those who write provisioning and management scripts for systems, be able to depend on other types of commands, such as those which connect to the network stack or those which provide debug capabilities. If my script depends on these commands being present, how can I detect or even automatically correct such a situation? Enter Shell Command Profiles. A Shell Command Profile is a group of related commands that have a name. Names are made up of numbers, letters and the underscore ('_') character. Profile names that start with a '_' are reserved for usage by 3rd parties. Profile names that start with a letter or number are reserved for use by the UEFI Shell specification. The names of all profiles are stored in the environment variable "profiles" and are separated by the semicolon (';') character. This environment variable is initialized based on (a) the profiles that are built into the shell executable itself and (b) a file named "profiles.txt" that exists in the same directory as the shell executable. A script can determine which profiles are installed by searching this environment variable for the name of a specific profile. For example: if not Profile("Network1") then echo Required script command profile "Network1" not found. exit /b 1 endif The Profile() operator searches the "profiles" environment variable for the one specified and returns 1 if it is found or o if it is not. The UEFI 2.0 Shell Specification supports four standard profiles:

• Driver1. Standard set of driver-related commands. This includes connect, devices, devtree, dh, disconnect, drivers, drvcfg, drvdiag, reconnect and unload.
• Debug1. Standard set of debug commands. This includes the following commands: bcfg, comp, dblk, dmem, dmpstore, edit, eficompress, efidecompress, guid, hexedit, loadpcirom, mem, memmap,mm, mode, pci, sermod, setsize and smbiosview.
• Network1. Standard set of networking-related commands. This includes ifconfig, ipconfig, and ping.
• Install1. Standard set of commands to aid installation. This includes only bcfg.

Shell profiles provide an extensible method for creating standard groups of commands that can be relied up by 3rd party applications. Next Time: The UEFI Shell API.

UEFI Shell: Levels of Support

The UEFI shell comes in four flavors, called levels of support. These "levels" (from 0 to 3) allows for compliant implementations of the shell that range from light-weight, bare-bones to a full-featured versions. At the same time, the user of the shell can determine, at run-time, whether the necessary features are available for it to run correctly. Why offer different levels of support?

1. Size. While the rest of the universe expands storage capacity exponentially, the firmware world still lives with relatively expensive flash devices. Suffice it to say that the types of flash and trends in flash which are driving down the cost for devices such as the iPod are a little slower in dropping the average price of motherboard flash. Flash size can significantly impact the cost of a motherboard. So there is constant pressure to keep the "required" elements of the firmware as small as possible. NOTE: One additional trend is that silicon vendors such as Intel are gobbling up room on the flash devices as well, both with their own firmware modules and with support for on-board micro controllers such as the ME (Management Engine). In some systems, 2/3 of the flash space is consumed by support for these devices. So the shell in the firmware must be small.
2. Video & Keyboard Support. When most of us think of a "shell" we usually think of some sort of command-prompt console at which a user can type in commands, execute scripts, etc. However, in many of the systems, the shell is used primarily for execution of scripts or applications that do not require a console at all.

So the UEFI shell can provide any of 4 standard support levels:

• 0 (Minimal). This is the most basic support. The APIs are fully supported, but there is no support for scripting, aliases or a console. Normal shell applications will execute.
• 1 (Scripting). This level adds support for scripts and the script control commands, but none of the other commands that do anything (such as write text to the screen or manipulate files). This allows scripts to be launched, but all of the script commands must be executables (.efi files) on a mapped drive.
• 2 (Basic). This level adds file script commands, such as rm, ls and mkdir. At this level, there is still no console support. As a result, those commands which would normally output to the console do not do so at this support level. Notice that, up to this point, an application could use the APIs to read and write files, but not execute scripts which used the common file manipulation commands.
• 3 (Interactive). This level adds console input and output, as well as those script commands which depend on the console, such as echo, type and cls.

The support level provided by the UEFI shell can be checked by any script or application by examining the environment variable shellsupport which contains the text "0" for Level 0, "1" for Level 1 and so on. Next week we'll look at how support provided by the shell can further be augmented in a standard way using "profiles". Tim

UEFI Updates Specification Roadmap.

Hey, just noticed that UEFI has officially updated their roadmap here. For me, the big questions revolve around SCT support for ARM, HII and the user identification and security parts of 2.2 and 2.3. These additions are hefty (clocking in at over 300 pages).