Link to Namespace Registry Entries Registry
Detailed Description of the Change and Special Instructions
1.1 Platform Configuration Namespace
The UEFI platform configuration infrastructure has been designed to facilitate the extraction of meaningful configuration data whether it is manually or via a programmatic (script-based) mechanism.
Associating meaning with a question
To achieve programmatic configuration each configuration-related IFR op-code must be capable of being associated with some kind of meaning (e.g. “Set iSCSI Initiator Name”).
Below is an illustration that depicts an EFI_IFR_QUESTION_HEADER. Each configuration-related IFR op-code is preceded with such a header, and the 3rd byte in the structure is highlighted because it becomes the lynchpin upon which meaning can be associated to the op-code.
Prompt Token and a new language
Given that for every configurable registered item in the HII Database (see EFI_HII_DATABASE_PROTOCOL) there will at least exist a set of IFR forms and a corresponding set of strings. Think of the IFR forms as a web page, each of which is represented by an IFR op-code. These pairs of op-codes and strings are sufficient to contain all the metadata required for a browser or a programmatic component (e.g. driver, script, etc.) to render a UI or configure a component in the platform.
Since another inherent feature of the UEFI configuration infrastructure is localization, each of the IFR op-codes make references to their related strings via a Token abstraction. This allows a reference to a string (e.g. Token #22) to be language agnostic.
Within the HII database, multiple sets of strings can be registered such that any given component might support one or more languages. These languages typically are associated with user-oriented translations such as Chinese, English, Spanish, etc. Given this inherent capability to associate op-codes with strings, it should also be mentioned that for a registered HII component (handle), each of the Prompt Token numbers are required to be unique if they are to be correctly managed or script-enabled. To be clear, this doesn’t mean that each Prompt Token must be globally unique across the entire HII database, it must be unique within the scope of the HII handle being referenced.
There is a concept introduced in 29.2.11.2 (Working with a UEFI Configuration Language) that speaks of a language that isn’t intended to be displayed or user visible. This is a key concept that allows data to be seamlessly introduced into the HII database content without perturbing the general flow or design of any existing IFR.
Below is an illustration which demonstrates the use of the x-UEFI-ns language. It is defined as the platform configuration language used by this specification and the keyword namespace further defined in this registry.
In the example, we have an English (as spoken in the US) string, a Spanish (as spoken in Mexico) string, and a UEFI platform configuration string. The latter string’s value is “iSCSIInitiatorName” and this keyword is an example of what would be the interoperability used to manage and extract meaning from the configuration metadata in the platform.
For example, a utility (or administrator) may query the platform to determine if a platform has exposed “iSCSIInitiatorName” within the configuration data. Normally, there would be no programmatic way of determining whether this platform contained this data object by simply examining the op-codes. However, with a namespace definition in place, a program can do the following to solve this issue:
1) Collect a list of all of the HII handles maintained by the HII database.
2) For each of the registered HII database entries, look to see if any strings are registered within the x-UEFI-ns language name.
a. If so, look for a string match of “iSCSIInitiatorName” in any of the strings for a particular HII handle
i. If none are found, go to the next HII handle and execute 2a again.
ii. If there are no more HII handles, then this platform doesn’t currently expose “iSCSIInitiatorName” as a programmatically manageable object.
3) If a match is found, then note the String Token value (e.g. 4).
4) Proceed to search through that HII handle’s registered IFR forms for a configuration op-code that has a matching Prompt Token value (e.g. 4).
5) Once discovered, the configuration op-code contains all of the information needed to understand where that iSCSI Initiator Name information is stored.
a. This allows a program to optionally extract the current settings as well as optionally set the current settings.
Even though the above steps are an illustration of what one might have to do to extract the information necessary to match a Keyword to its associated value, there are facilities defined in the EFI_HII_CONFIG_ROUTING_PROTOCOL, and more specifically the ExtractConfig() and RouteConfig() functions to facilitate the getting and setting of keyword values.
Software Layering
Below is an illustration which shows a common sample implementation’s interaction between agents within a UEFI-enabled platform. Some implementations may vary on the exact details.
1) Any application which wants to get or set any of the values abstracted by a keyword can interact with the API’s that are defined within the UEFI specification. It would be the responsibility of this application to construct and interpret keyword strings that are passed or returned from the API’s.
2) An agent within the system will expose the EFI_CONFIG_KEYWORD_HANDLER_PROTOCOL interface with its GetData() and SetData() functions. These services will interact both with the application that called it and the underlying routing routines within the system.
3) The EFI_HII_CONFIG_ROUTING_PROTOCOL is intended to act as a mechanism by configuration reading or writing directives are proxied to and from the appropriate underlying device(s) that have exposed configuration access abstractions.
4) Configurable items in the platform will expose an EFI_HII_CONFIG_ACCESS_PROTOCOL interface that allows the setting or retrieving of configuration data.
5) The component in the platform which has exposed configuration access abstractions.
Namespace Entries
This document establishes the UEFI Platform Configuration language as:
x-UEFI-ns
The keywords defined in this UEFI Configuration Namespace registry should all be discoverable within the platform configuration language of “x-UEFI-ns”.
Alternate Storage and Namespaces
Although this namespace registry deals solely with the keywords associated with the x-UEFI-ns platform configuration namespace, the underlying configuration infrastructure supports abstractions that encompass alternate x-UEFI-* namespace usages.
x-UEFI-CompanyName
If a company wanted to expose some additional keywords for their own private use, they must use one of the ID’s referenced in the PNP and ACPI ID Registry.
For example, if Intel wanted to expose some additional settings, they would use: x-UEFI-INTC.
Handling Multi-instance values
There are some keywords which may support multiple instances. This simply means that a given defined keyword may be exposed multiple times in the system. Since instance values are exposed as a “:#” (# is a placeholder for a one to four digit decimal number) suffix to the keyword, with the “#” holding the place of an instance value, we typically use that value as a means of directly addressing that keyword. However, if there are multiple agents in the system exposing a multi-instance keyword, one might see several copies of something like “iSCSIInitiatorName:1” exposed.
Under normal circumstances, an application would interact with the keyword handler protocol to retrieve the Keyword it desired via the GetData() function. What is retrieved would be any instances that match the keyword request.
For instance, when retrieving the iSCSIInitiatorName:1 keyword, the keyword protocol handler will search for any instances of the keyword and return to the caller what it found.
The illustration below shows an example of the returned keyword string fragments based on what the keyword protocol handler discovered.
In the case of iSCSIInitiatorName:1, the illustration shows how multiple controllers exposed the same keyword and even the same instance values. The response fragments below illustrate how the “PATH=” value would correspond to the device path for a given device and each of those device paths uniquely identify the controller responding to the request. This gives the caller sufficient information to uniquely adjust a keyword [via a SetData() call] by specifying the appropriate device path for the controller in the keyword string.
Keyword Rules
The creation of a keyword definition should comply with the following rules:
- All of the namespace strings must be alpha-numeric. No spaces or special characters are allowed, including “_”, “-” or “.”
- All prompt and option value strings must follow the CamelCase naming convention
- The first letter in the keyword and the first letter of each subsequent concatenated word are capitalized
- Exception!
- These keyword will remain as exceptions to the CamelCase naming convention.
- iSCSI, FCoE, UEFI, IPMI, SATA, FC
- These keyword will remain as exceptions to the CamelCase naming convention.
- Although Keywords are defined with upper and lower case, keyword retrieval is returned in a case insensitive manner. In other words, there is no difference between a keyword reference to BiosVendor and biosVendor.
- Max string length for a keyword is 40 characters
Click here to access the Namespace Registry Entries Registry.