Saturday, March 06, 2004
What is the Hive-based Registry and how to use it?
The hive-based registry is our answer to the difficult problem of persisting data on a device which does not power its RAM when turned off. In previous versions of the OS, registry save/restore meant dumping the entire registry to the OEM, a process which is slow and can be difficult to implement due to the unavailability of system calls in the OAL. The hive-based registry saves parts of the registry in files (hives) that can be stored on any file system. This frees the OEM up to easily store the registry on a disk, flash chip, or any other nonvolatile storage. The registry is broken into two parts: the system hive containing all data under HKEY_LOCAL_MACHINE, HKEY_CLASSES_ROOT, and HKEY_USERS; and the user hive containing all data under HKEY_CURRENT_USER. This enables user profile support because user hives can be swapped to keep users' data separate.
SETTING UP THE HIVE-BASED REGISTRY
---------------------------------------------------
The hive-based registry is currently only available for use on top of the FAT file system. In the final Talisker release it will be available for use with any file system.
1. Add the hive-based registry component (fsreghive) to your device configuration and make sure the object store-based registry component (fsreg) is not included. Make sure to do a clean build the first time after
changing your configuration.
2. (This step is necessary in our Beta1 release but will not be necessary in Beta2 or beyond.)
Set the IMGREGHIVE environment variable to 1. This causes registry hives to be generated when the image is made.
3. Check these settings in the platform.reg file:
[HKEY_LOCAL_MACHINE\init\BootVars]
"SYSTEMHIVE"=""
"PROFILEDIR"=""
"Start DevMgr"=dword:
"NoDefaultUser"=dword:
"SYSTEMHIVE" is the location and name of the system hive file. Do not include the name of the file system the file will be stored on; it will be inferred from other settings described below. Typically this will be a simple location such as "system.hv" or "Registry\\system.hv".
"PROFILEDIR" is the location of the root directory where user profiles are stored. Each user will be given a separate directory under the PROFILEDIR. Do not include the name of the file system the file will be stored on; it will be stored on the same file system as the system hive. Typically this will be blank "" or a directory such as "Documents and Settings".
"Start DevMgr" is a boolean indicating whether the device manager (device.exe) must be started to start the drivers necessary to reach the registry hives. A value of 1 will cause device manager to be started; 0
will not. The only case in which device manager should NOT be started is if the hives are to be stored in the object store, causing them to be lost on a cold boot. Typically the hives are stored outside RAM and so device manager is necessary.
"NoDefaultUser" is a boolean indicating whether a default user should be logged in on boot. The default user is typically used on single-user devices, to contain settings that would otherwise be specific to one user. To enable a multi-user environment, set this value to 1. In that case no user will be logged in on boot. See the Platform Builder documentation on user profiles for more information on how to log in other users.
4. Make sure the boot registry contains all information necessary to start the drivers and file systems needed to reach the system hive. The boot registry is an unchanging registry containing a minimum set of information necessary to boot up to the point that the persistent system registry can be reached. In your platform.reg file, for each driver and file system needed to boot:
a. Make sure its entries are wrapped in the comments
; HIVE BOOT SECTION
; END HIVE BOOT SECTION
These tags add the entries to the boot hive.
b. Set this flag bit:
[HKEY_LOCAL_MACHINE\Drivers\...]
"Flags"=dword:1000
The flags are a bitmask to OR with any existing settings. This flag tells device manager to load your driver with the boot registry and not to load it a second time with the system registry.
5. (This step is temporary until all file systems can be used with the hive-based registry.)
Set this registry value in common.reg or platform.reg:
[HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\FATFS]
"Flags"=dword:00020024.
6. Choose a flushing mechanism and implement it. The operating system does not perform any lazy flushing; it may flush some data in the background but cannot be relied on to flush all data reliably. To ensure that data is not lost, call RegFlushKey before the device is shutdown. That will flush any unsaved changes in the hive to the persistent file. The flush can occur during a shutdown sequence, or thread can be set up to do periodic flushes.
It will not damage anything to call RegFlushKey when no data has changed; in that case the file will not be touched. RegFlushKey should be called on both the system hive (HKEY_LOCAL_MACHINE) and the user hive
(HKEY_CURRENT_USER).
TROUBLESHOOTING
---------------------------
Possible problems include:
1. The build reports that the file default.fdf is missing. In this case a clean rebuild is necessary.
2. The build reports that default.hv, boot.hv, and user.hv are missing. Make sure you did step 2 of the setup instructions.
3. The build succeeds but it hangs soon after boot. Possible causes include:
- The device manager was never started. Set "Start DevMgr" = 1; see step 3 of the setup instructions.
- The device manager was started but the necessary file system was not. Make sure all registry entries for that file system, block driver, etc. are in the boot registry; see step 4a of the setup instructions. Also make sure the file system driver has the flag set to load it in the first boot phase; see step 4b.
- The necessary file system was started but didn't register as a "boot" file system. Make sure you did step 5 of the setup instructions.
- The configuration originally did not include the hive-based registry, and a full clean build was not done. Make sure to do a clean build after including the fsreghive component in your configuration.
4. The device boots but occasionally registry data is lost when the device is powered off. This can happen if changes are not flushed out to the persistent file. See step 6 of the setup instructions.
SETTING UP THE HIVE-BASED REGISTRY
---------------------------------------------------
The hive-based registry is currently only available for use on top of the FAT file system. In the final Talisker release it will be available for use with any file system.
1. Add the hive-based registry component (fsreghive) to your device configuration and make sure the object store-based registry component (fsreg) is not included. Make sure to do a clean build the first time after
changing your configuration.
2. (This step is necessary in our Beta1 release but will not be necessary in Beta2 or beyond.)
Set the IMGREGHIVE environment variable to 1. This causes registry hives to be generated when the image is made.
3. Check these settings in the platform.reg file:
[HKEY_LOCAL_MACHINE\init\BootVars]
"SYSTEMHIVE"=""
"PROFILEDIR"=""
"Start DevMgr"=dword:
"NoDefaultUser"=dword:
"SYSTEMHIVE" is the location and name of the system hive file. Do not include the name of the file system the file will be stored on; it will be inferred from other settings described below. Typically this will be a simple location such as "system.hv" or "Registry\\system.hv".
"PROFILEDIR" is the location of the root directory where user profiles are stored. Each user will be given a separate directory under the PROFILEDIR. Do not include the name of the file system the file will be stored on; it will be stored on the same file system as the system hive. Typically this will be blank "" or a directory such as "Documents and Settings".
"Start DevMgr" is a boolean indicating whether the device manager (device.exe) must be started to start the drivers necessary to reach the registry hives. A value of 1 will cause device manager to be started; 0
will not. The only case in which device manager should NOT be started is if the hives are to be stored in the object store, causing them to be lost on a cold boot. Typically the hives are stored outside RAM and so device manager is necessary.
"NoDefaultUser" is a boolean indicating whether a default user should be logged in on boot. The default user is typically used on single-user devices, to contain settings that would otherwise be specific to one user. To enable a multi-user environment, set this value to 1. In that case no user will be logged in on boot. See the Platform Builder documentation on user profiles for more information on how to log in other users.
4. Make sure the boot registry contains all information necessary to start the drivers and file systems needed to reach the system hive. The boot registry is an unchanging registry containing a minimum set of information necessary to boot up to the point that the persistent system registry can be reached. In your platform.reg file, for each driver and file system needed to boot:
a. Make sure its entries are wrapped in the comments
; HIVE BOOT SECTION
; END HIVE BOOT SECTION
These tags add the entries to the boot hive.
b. Set this flag bit:
[HKEY_LOCAL_MACHINE\Drivers\...]
"Flags"=dword:1000
The flags are a bitmask to OR with any existing settings. This flag tells device manager to load your driver with the boot registry and not to load it a second time with the system registry.
5. (This step is temporary until all file systems can be used with the hive-based registry.)
Set this registry value in common.reg or platform.reg:
[HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\FATFS]
"Flags"=dword:00020024.
6. Choose a flushing mechanism and implement it. The operating system does not perform any lazy flushing; it may flush some data in the background but cannot be relied on to flush all data reliably. To ensure that data is not lost, call RegFlushKey before the device is shutdown. That will flush any unsaved changes in the hive to the persistent file. The flush can occur during a shutdown sequence, or thread can be set up to do periodic flushes.
It will not damage anything to call RegFlushKey when no data has changed; in that case the file will not be touched. RegFlushKey should be called on both the system hive (HKEY_LOCAL_MACHINE) and the user hive
(HKEY_CURRENT_USER).
TROUBLESHOOTING
---------------------------
Possible problems include:
1. The build reports that the file default.fdf is missing. In this case a clean rebuild is necessary.
2. The build reports that default.hv, boot.hv, and user.hv are missing. Make sure you did step 2 of the setup instructions.
3. The build succeeds but it hangs soon after boot. Possible causes include:
- The device manager was never started. Set "Start DevMgr" = 1; see step 3 of the setup instructions.
- The device manager was started but the necessary file system was not. Make sure all registry entries for that file system, block driver, etc. are in the boot registry; see step 4a of the setup instructions. Also make sure the file system driver has the flag set to load it in the first boot phase; see step 4b.
- The necessary file system was started but didn't register as a "boot" file system. Make sure you did step 5 of the setup instructions.
- The configuration originally did not include the hive-based registry, and a full clean build was not done. Make sure to do a clean build after including the fsreghive component in your configuration.
4. The device boots but occasionally registry data is lost when the device is powered off. This can happen if changes are not flushed out to the persistent file. See step 6 of the setup instructions.
