Component Tales: First Boot Agent
[The following article is authored by one of the Windows Embedded MVPs (Most Valuable Professionals). Our MVPs have a heavy background in Embedded systems and are a great repository of information on Windows Embedded products. We’re providing this space on our team blog as a service to our readers by allowing MVPs to share some of their knowledge with the rest of the community.]
A Windows Embedded Standard image, freshly built from Target Designer, cannot be booted into directly. Instead it has to go through an additional process called First Boot Agent (FBA). The FBA process contains all the installation logic normally found in the setup application of XP Professional. It is implemented as several components to be found in the Software\System\System Services\Base node of the component catalog.
These components are added automatically to each image configuration by Target Designer.
In contrast to the desktop setup, during FBA no dialogs or agents are shown, because with the help of Target Designer all required settings are made on the component level when the image is configured. However, there are no dedicated settings for the FBA components. Settings that affect the FBA process need to be made in feature components.
The Boot Agent drives all tasks that are required to configure the embedded OS to the underlying target hardware including:
- plug-n-play enumeration
- security installation
- network configuration
- COM DLL and server registration
- user profile initialization
- optional component installation
- and more…
All these jobs need to run directly on the actual target because they require access to system and peripheral devices to accomplish the configuration. This is something which cannot be prepared during the image configuration in Target Designer on a development machine and therefore the separate FBA process is required.
FBA Phases
The execution of the collection of tasks during FBA is structured using phases, because several of the tasks rely on results from previous tasks. It all starts at phase 0 with the initial boot of the target system after copying the result of the Target Designer build process on a bootable partition of the device.
The First Boot Agent automatically takes over walking through all required tasks and creating the settings as specified for each component during the image configuration process in Target Designer (TD).
To do this, the required information is stored in the systems registry under the HKLM\SYSTEM\CurrentControlSet\Control\WindowsEmbedded\FBA registry key.
These settings are used only once during the FBA process.
Until phase 8500 the base operating system is built and then the system reboots. Between phase 8500 and 12000 optional and custom components are installed.
On completion, an image normally is sealed for cloning. FBA will start a second time for system cloning, if the system was sealed using the System Cloning Tool. These 12000+ phases take place on each individual target device to localize/personalize the system on its final destination hardware.
Here is an overview on the most important jobs that run in the first part of FBA execution (until phase 8500):
- Fba.exe – Performs runtime tasks
- Fbapnp.dll – Performs Plug-N-Play detection
- Fbanet.dll – Installs Net Protocols, domain SID & participation, Protocol binding
- Fbasec.dll – Configures system security database
- Fbacert.dll – Installs cryptographic support and system catalogs
- Fbareg.dll – Performs DLL registration. Processes RunOnce keys
- Fbaprof.dll – Initializes system profiles
- Fbaocm.dll – Integrates optional components in the setup process
Controlling FBA
At creation time each component allows you to add resource commands in Component Designer. This provides component developers the means to define if and how the component is treated during a specified FBA phase.
Basically there are four options that relate to FBA:
- Generic Command – Runs any executable at a given phase
- DLL/COM Registration – Registers a COM DLL or Server
- OC Mgr Request – Do not use - reserved by Microsoft
- RunOnce – Writes a run once entry
Dependent on the component requirements one is able to choose one or more of these commands. Requirements can be pretty clear if you want to register a COM DLL, but for Generic Command and RunOnce there are two options. Generic Command offers more control and even a certain level of error handling, while RunOnce just starts the process without any further interaction. The fourth option (OC Mgr Request) should not be applied. It is reserved for internal Microsoft use.
Troubleshooting FBA
Due to the fact that a successful completion of the FBA process is essential to the quality of the Windows Embedded Standard image, it is good to have a troubleshooting strategy at hand if errors occur. A good working approach is to:
- check the FBA log. - There is a FBA log file in \Windows\FBA called FBALog.txt
- check SetupAPI.log in Windows\. - A lot of components use this API for configuration.
- use Kernel Debugger and check the debug output on COM1
Common exit codes during FBA are:
- 0x4a020: The specified component has already
been installed - Error: 0x2: Cannot find the file specified – very frequent, if a component’s repository was not imported successfully
- Error: 0x7e: Specified module could not be found
- 0xe000020d: Invalid class installer
- 0xc0000005: Access Denied
It is not uncommon for FBA to reboot more than once after the initial reboot in phase 8500. This can be triggered e.g. by setup routines of optional or custom components.
However, if reboots are continuous and FBA does not proceed further, then either an old EWF partition is present from a previous installation or the image settings were set to a different partition than the actual one.
Sometimes blue screens show quite vividly that something is wrong. Common failures in this case have the codes Stop 6B pointing to a missing (FAT or NTFS) file system and Stop 7B pointing to a missing boot device, e.g. the PCI bus.If you experience different Stop error codes, it is a best practice to consult the Microsoft Support knowledgebase to get further information.
Alexander Wechsler
Wechsler Consulting
Technorati Tags: XPe,Standard 2009