Chapter 7
Configuration of Provisioned Material

Innovation distinguishes between a leader and a follower.

—Steve Jobs

Once material gets placed on a target system, one of the inevitable next steps would be the configuration of this material. Since much of the inherent configuration mechanisms that are available in the UEFI firmware environment are also supported in the UEFI Shell environment, this chapter’s material will touch on configuration capabilities available in both environments.

The BIOS has never been known for having a great user interface. The ROM sizes were too limited and the video interfaces too unpredictable to support high-end graphical interfaces.

Much of the design that the UEFI configuration infrastructure covers has been heavily studied and analyzed by modern operating systems. The results of these efforts are what have turned into the configuration infrastructure that first was documented in the UEFI 2.1 specification.

Initialization Timeline

During platform initialization, several distinct steps occur. To simplify the timeline, the illustration in Figure 7.1 simply covers four general phases of operation for the system. These phases are intended to illustrate when configuration of the platform is possible. Note that configuration services are available very early in platform initialization.

Figure 7.1: The Platform Initialization Timeline

Figure 7.1 gives a simplified view of the phase of operations for a platform:

Phase 1. During early initialization, the UEFI-compatible BIOS initializes some of the underlying components of the platform (such as CPU, chipset, and memory). This also includes establishing the UEFI infrastructure so that the common UEFI components (such as the UEFI configuration infrastructure) are available to be used by later phases of operation.

Phase 2. In the later phase, the BIOS starts to launch drivers (often located in add-in device option ROMs) that have configuration-related material associated with certain configurable devices. This configuration data is registered with the BIOS through something known as the Human Interface Infrastructure (HII) services. Between Phase 2 and 3 is usually when a local user would interact with the platform to configure it (picture a user at a BIOS setup menu).

Phase 3. The BIOS initialization is complete and the BIOS proceeds to launch the boot target (which is usually an operating system for most platforms).

Phase 4. The boot target is launched and running. For most platforms, this is the phase that the machine remains in for most of the time.

It should also be noted that a very common scenario for platform configuration is when a remote administrator interacts with a platform. This can be done with either the assistance of an operating system, as illustrated in Figure 7.2, or with a platform that contains an out-of-band management controller. Since the BIOS is often not interactive while the operating system is running, this poses some issues for updating BIOS-based configuration settings during the later phases of platform operation. Figure 7.2 shows a slightly modified example of the previous timeline, which now enables late configuration setting updates through a mechanism that applies the changes across a system reset, leveraging the underlying UEFI configuration infrastructure.

Figure 7.2: Timeline Illustrating How Late Requests for BIOS Setting Changes Can Be Accommodated

Step 1. The UEFI-compliant BIOS initializes like it normally does.

Step 2. The configuration step is usually based on some previously chosen settings that the user/administrator had previously applied to that device. These settings are stored in some nonvolatile location. During this step, the settings are typically read from the nonvolatile storage and the device is configured accordingly.

Step 3. The platform is running the operating system in this illustration and has some interaction with a remote administrator. The remote administrator requests some BIOS setting changes to occur on the platform and some agent proxies this request by a couple of methods:

Capsules. The UEFI infrastructure supports an UpdateCapsule() service, which allows for an OS-present agent to call into the BIOS and communicate some configuration request, which will typically be acted upon across a platform reset. This is a very flexible method of enabling an acrossreset update since it can potentially allow for updates of both on-motherboard devices as well as third-party devices (which often use their own proprietary local nonvolatile storage). Platform behavior changes typically do not occur until the platform has reset and the hardware has then been reconfigured based on the desired settings.

EFI Variable. The UEFI infrastructure provides abstractions to a platform nonvolatile storage service (that is, an EFI variable). This is primarily used by the motherboard devices and the setting requests can be directly established from the OS-present phase of operations. Platform behavior changes typically do not occur until the platform has reset and the hardware has then been reconfigured based on the desired settings.

Step 4. Once the remote configuration update request has been received and acted upon, the platform typically resets so that the boot timeline is restarted. It should be noted, though, that during this subsequent boot, the items that normally occur in Step 2 would still occur, but typically based on the aforementioned configuration updates in the current configuration settings.

Configuration Infrastructure Overview

The modern UEFI configuration infrastructure that was first described in the UEFI 2.1 specification is known as the Human Interface Infrastructure (HII). HII includes the following set of services:

Database Services. A series of UEFI protocols that are intended to be an inmemory repository of specialized databases. These database services are focused on differing types of information:

Database Repository. This is the interface that drivers interact with to manipulate configuration-related contents. It is most often used to register data and update keyboard layout-related information.

String Repository. This is the interface that drivers interact with to manipulate string-based data. It is most often used to extract strings associated with a given token value.

Font Repository. The interface to which drivers may contribute font-related information for the system to use. Otherwise, it is primarily used by the underlying firmware to extract the built-in fonts to render text to the local monitor. Note that since not all platforms have inherent support for rendering fonts locally (think headless platforms), general purpose UI designs should not presume this capability.

Image Repository. The interface to which drivers may contribute image-related information for the system to use. This is for purposes of referencing graphical items as a component of a user interface. Note that since not all platforms have inherent support for rendering images locally (think headless platforms), general purpose UI designs should not presume this capability.

Browser Services. The interface that is provided by the platform’s BIOS to interact with the built-in browser. This service’s look and feel is implementation-specific, which allows for platform differentiation.

Configuration Routing Services. The interface that manages the movement of configuration data from drivers to target configuration applications. It then serves as the single point to receive configuration information from configuration applications, routing the results to the appropriate drivers.

Configuration Access Services. The interface that is exposed by a driver’s configuration handler and is called by the configuration routing services. This service abstracts a driver’s configuration settings and also provides a means by which the platform can call the driver to initiate driver-specific operations.

Using the Configuration Infrastructure

The overview introduced the components of the UEFI configuration infrastructure. This section discusses with a bit more detail how one goes about using aspects of this infrastructure. The following steps are initiated by a driver that is concerned with using the configuration infrastructure:

Initialize hardware. The primary job of a device driver is typically to initialize the hardware that it owns. During this process of physically initializing the device, the driver is also responsible for establishing the proper configuration state information for that device. These typically include doing the following:

Installing required protocols. Protocols are interfaces that will be used to communicate with the driver. One of the more pertinent protocols associated with configuration would be the Configuration Access protocol. This is used by the system BIOS and agents in the BIOS to interact with the driver. This is also the mechanism by which a driver can provide an abstraction to a proprietary nonvolatile storage that under normal circumstances would not be usable by anyone other than the driver itself. This is how configuration data can be exposed for add-in devices and others can send configuration update requests without needing direct knowledge of that device.

Creating an EFI device path on an EFI handle. A device path is a binary description of the device and typically how it is attached to the system. This provides a unique name for the managed device and will be used by the system to refer to the device later.

Register Configuration Content. One of the latter parts of the driver initialization (once a device path has been established) is the registration of the configuration data with the underlying UEFI-compatible BIOS. The configuration data typically consists of sets of forms and strings that contain sufficient information for the platform to render pages for a user to interact with. It should also be noted that now that the configuration data is encapsulated in a binary format, what was previously an opaque meaningless set of data is now a well-known and exportable set of data that greatly expands the configurability of the device by both local and remote agents as well as BIOS and OS-present components.

Respond to Configuration Event. Once the initialization and registration functions have completed, the driver could potentially remain dormant until called upon. A driver would most often be called upon to act on a configuration event. A configuration event is an event that occurs when a BIOS component calls upon one of the interfaces that the driver exposed (such as the Configuration Access protocol) and sends the driver a directive. These directives typically would be something akin to “give me your current settings” or “adjust setting X’s value to a 5.”

Driver Model Interactions

The drivers that interact with the UEFI configuration infrastructure are often compliant with the UEFI driver model, as the examples shown in Figure 7.3 and Figure 7.4. Since driver model compliance is very common (and highly recommended) for device drivers, several examples are shown below that describe in detail how such a driver would most effectively leverage the configuration infrastructure.

Figure 7.3: A Single Driver that Is Registering Its Configuration Data and Establishing Its Environment in a Recommended Fashion

Step 1. During driver initialization, install services on the controller handle.

Step 2. During driver initialization, discover the managed device. Create a device handle and then install various services on it.

Step 3. During driver initialization, configuration data for the device is registered with the HII database (through the NewPackageList() API) using the device’s device handle. A unique HII handle is created during the registration event.

Step 4. During system operation, when a configuration event occurs, the system addresses (through the Configuration Access protocol) the configuration services associated with the device.

Figure 7.4: A Single Driver that Is Managing Multiple Devices, Registering Its Configuration Data, and Establishing Its Environment in a Recommended Fashion

Step 1. During driver initialization, install services on the controller handle.

Step 2. During driver initialization, discover the managed device(s). Create device handle(s) and then install various services on them.

Step 3. During driver initialization, configuration data for each device is registered with the HII database (through the NewPackageList() API) using each device’s device handle. A unique HII handle is created during the registration event.

Step 4. During system operation, when a configuration event occurs, the system addresses (through the Configuration Access protocol) the configuration services associated with the driver. In this example, the configuration services will be required to disambiguate references to each of its managed devices by the passedin HII handle.

Provisioning the Platform

Figure 7.5 is an illustration that builds on the previously introduced concepts and shows how the remote interaction would introduce the concept of bare-metal provisioning (putting content on a platform without the aid of a formal operating system). This kind of interaction could be used in the manufacturing environment to achieve the provisioning of the platform or in the after-market environment where one is remotely managing the platform and updating it.

Figure 7.5: Remote Interaction Occurs with a Target System; the System in Turn Accesses the Configuration Abstractions Associated with a Device or Set of Devices

Step 1. Remote administrator sends a query to a target workstation. This query could actually be a component of a broadcast by the administrator to all members of the network.

Step 2. Request received and an agent (possibly a shell-based one) proxies the request to the appropriate device.

Step 3. The agent responds based on interaction with the platform’s underlying configuration infrastructure.

Configuring through the UEFI Shell

One of the usage models associated with the UEFI Shell is for the running of programs or scripts within it so that it can automatically execute a variety of tasks and leverage the power of the overall BIOS environment. Some of the built-in commands associated with certain support levels of the UEFI Shell provide both basic and advanced features. These features expose the ability to configure the system as well as query the system for some rather complicated sets of data through scripts. Having this capability in scripting certainly does not preclude the ability for anyone to leverage the full extent of the UEFI BIOS’s capabilities through a binary program.

Basic Configuration

Some of the common commands that provide basic interaction with the configuration infrastructure include:

drvcfg. This command invokes the platform’s configuration infrastructure. This command is used primarily for the following purposes:

To invoke the system’s browser through a script so that it displays a given device’s setup pages.

To provide the ability to set a specific set of default behaviors for a given device.

To set a device’s configuration from a user-defined group of settings contained in a file.

drvdiag. This command invokes the Driver Diagnostics Protocol. This provides a script the ability to interact with the diagnostics services that a driver may expose in its list of services.

Command-line Usage for drvcfg

This section provides a set of examples of common usages for the drvcfg command, followed by the appropriate command-line syntax. The full command-line syntax is as follows:

drvcfg [-l XXX] [-c] [-f <Type>|-v|-s] [DriverHandle [DeviceHandle [ChildHandle]]] [-i filename] [-o filename]

To display the list of devices that are available for configuration:

Shell> drvcfg

To display the list of devices and child devices that are available for configuration:

Shell> drvcfg –c

To force defaults on all devices:

Shell> drvcfg –f 0

To force defaults on all devices that are managed by driver 0x17:

Shell> drvcfg –f 0 17

To force defaults on device 0x28 that is managed by driver 0x17:

Shell> drvcfg –f 0 17 28

To force defaults on all child devices of device 0x28 that are managed by driver 0x17:

Shell> drvcfg –f 0 17 28 –c

To force defaults on child device 0x30 of device 0x28 that is managed by driver 0x17:

Shell> drvcfg –f 0 17 28 30

To validate options on all devices:

Shell> drvcfg –v

To validate options on all devices that are managed by driver 0x17:

Shell> drvcfg –v 17

To validate options on device 0x28 that is managed by driver 0x17:

Shell> drvcfg –v 17 28

To validate options on all child devices of device 0x28 that are managed by driver 0x17:

Shell> drvcfg –v 17 28 –c

To validate options on child device 0x30 of device 0x28 that is managed by driver 0x17:

Shell> drvcfg –v 17 28 30

To set options on device 0x28 that is managed by driver 0x17:

Shell> drvcfg –s 17 28

To set options on child device 0x30 of device 0x28 that is managed by driver 0x17:

Shell> drvcfg –s 17 28 30

To set options on device 0x28 that is managed by driver 0x17 in English:

Shell> drvcfg –s 17 28 –l eng

To set options on device 0x28 that is managed by driver 0x17 in Spanish:

Shell> drvcfg –s 17 28 –l spa

Command-line Usage for drvdiag

This section provides a set of examples of common usages for the drvdiag command, followed by the appropriate command-line syntax. The full command-line syntax is as follows:

To display the list of devices that are available for diagnostics:

Shell> drvdiag

To display the list of devices and child devices that are available for diagnostics:

Shell> drvdiag –c

To run diagnostics in standard mode on all devices:

Shell> drvdiag –s

To run diagnostics in standard mode on all devices in English:

Shell> drvdiag –s –l eng

To run diagnostics in standard mode on all devices in Spanish:

Shell> drvdiag –s –l spa

To run diagnostics in standard mode on all devices and child devices:

Shell> drvdiag –s –c

To run diagnostics in extended mode on all devices:

Shell> drvdiag –e

To run diagnostics in manufacturing mode on all devices:

Shell> drvdiag –m

To run diagnostics in standard mode on all devices managed by driver 0x17:

Shell> drvdiag –s 17

To run diagnostics in standard mode on device 0x28 managed by driver 0x17:

Shell> drvdiag –s 17 28

To run diagnostics in standard mode on all child devices of device 0x28 managed by driver 0x17:

Shell> drvdiag –s 17 28 –c

To run diagnostics in standard mode on child device 0x30 of device 0x28 managed by driver 0x17:

Shell> drvdiag –s 17 28 30

Advanced Configuration Abilities

Some of the common commands that provide basic interaction with the configuration infrastructure include:

memmap. This command displays the memory map associated with the UEFI environment.

dblk. This command allows a script to interact with the underlying block (storage) device so that it can display the contents of one or more of its blocks/ sectors.

dmem. This command displays the contents of system memory or device memory. If an address is not specified, then the contents of the EFI system table are displayed. Otherwise, memory starting at a particular address is displayed. This is especially useful for displaying the contents of certain memory ranges like a device’s PCI configuration space.

mm. This command allows the user to display or modify the I/O register, memory contents, or PCI configuration space.

Command-line Usage for memmap

This section provides an example of the memmap command. The full command-line syntax is as follows:

Command-line Usage for dblk

This section provides a set of examples of common usages for the dblk command, followed by the appropriate command-line syntax. The full command-line syntax is as follows:

dblk device [lba] [blocks] [-b]

To display one block of blk0, beginning from block 0:

Shell>dblk blk0

To display one block of fs0, beginning from block 0x2:

Shell>dblk fs0 2

To display 0x5 blocks of fs0, beginning from block 0x12:

Shell>dblk fs0 12 5

To display 0x10 blocks of fs0, beginning from block 0x12:

Shell>dblk fs0 12 10

The attempt to display more than 0x10 blocks will display only 0x10 blocks:

Shell>dblk fs0 12 20

To display one block of blk2, beginning from the first block (blk0):

fs1: mps1> dblk blk2 0 1

Command-line Usage for dmem

This section provides example usages of the dmem command. The full command-line syntax is as follows:

dmem [-b] [address] [size] [-MMIO]

To display the EFI system table pointer entries:

fs0:> dmem

To display memory contents from 1af3088 with size of 16 bytes:

To display memory mapped I/O contents from 1af3088 with size of 16 bytes:

Shell> dmem 1af3088 16 -MMIO

Command-line Usage for drvdiag

This section provides example usages of the drvdiag command. The full commandline syntax is as follows:

To display or modify memory:

To modify memory: Address 0x1b07288, width = 2 bytes:

To display I/O space: Address 80h, width = 4 bytes:

To modify I/O space using non-interactive mode:

To display PCI configuration space, ss=00, bb=00, dd=00, ff=00, rr=00:

To display PCIE configuration space, ss=00, bb=06, dd=00, ff=00, rrr=000:

..................Content has been hidden....................

You can't read the all page of ebook, please click here login for view all page.
Reset