Fortunately, Intel does provide the source to plat_api.c, the one file Intel recommends for modification. In order to implement IPSM, it is also necessary to modify several registry keys and a few OEM files.

This article explains how to integrate PSM for use on an Intel XScale SA-1110 processor-based board equipped with Intel StrataFlash flash memory. The process of integrating IPSM -- and making it work -- was somewhat challenging, due to the fact that the required information was not available in a single location. Instead, it was necessary to search through numerous sources for the relevant details. Thus, the main objective of this article is to make it easier for others to implement IPSM on their platforms.

The article is presented in two parts: the steps required to integrate IPSM from scratch; and, discussion of several key issues that related to the process.

---

Part I -- Integrating IPSM

---

The steps required to integrate IPSM are:

A. Setting up the PSM directory

1. Get the IPSM from Intel. It unzips into a folder called PSM.
   
2. Copy the PSM folder to the $(_TARGETPLATROOT)\drivers directory. $(_TARGETPLATROOT) is C:\WINCE400\PLATFORM\econtest1 in my setup.

B. Changing the HAL code

1. Make the following changes in $(_TARGETPLATROOT)\kernel\hal\OEMIOCTL.c:
   • Add this line,if not present: #include pkfuncs.h>
     
   • Add these at the top of initialization:
     extern PSMHAL_IOCtl(DWORD, LPVOID, LPVOID);
#define IOCTL_PSM_FLASH_CMD CTL_CODE(FILE_DEVICE_HAL,4066, METHOD_BUFFERED,FILE_ANY_ACCESS)
     
   • Add this to the OEMIoControl( ) function switch statement:
     case IOCTL_PSM_FLASH_CMD:
retval = PSMHAL_IOCtl(nInBufSize, lpInBuf, lpOutBuf);
break;
2. Make the following changes in $(_TARGETPLATROOT)\kernel\hal\sources
   SOURCELIBS=$(_TARGETPLATROOT)\drivers\PSM\SA11X0\WCE.NET\BIN\PSMHal.lib \
$(_TARGETPLATROOT)\drivers\PSM\SA11X0\WCE.NET\BIN\Registry.lib

3. Look into $(_TARGETPLATROOT)\Inc\SA11X0BD.INC or \Platform\myPlatform\Kernel\Hal\ARM\MAP1100.H and check whether the memory is mapped and to what address it is mapped.

C. Making the PSM FileSystem Settings

1. Change the PSM_OEMInfo structure in the PLAT_API.c to suit your platform. The contents and an example is given below.
   /* PhysicalReadStartAddress */ (VOID_PTR)0x08000000,
/* PhysicalWriteStartAddress */ (VOID_PTR)0x08000000,
/* PhysicalBurstReadStartAddress */ (VOID_PTR)0x08000000,
/* VirtualReadStartAddress */ (VOID_PTR)0xa1000000,
/* VirtualWriteStartAddress */ (VOID_PTR)0xa1000000,
/* VirtualBurstReadStartAddress */ (VOID_PTR)0xa1000000,
/* MaximumArrayLength */ 0x01000000,
/* MaximumRegistrySize */ 0x00000000,
/* ManagedAreaStart */ 0x00000000,
/* ManagedAreaLength */ 0x01000000,
/* ReadBusWidth */ 16,
/* WriteBusWidth */ 16,
/* BurstReadBusWidth */ 16
   
   The Readstartaddress, WriteStartAddress and BurstReadStartAddress (both physical and virtual) are the start addresses of the flash array.
   MaximumArrayLength is the maximum length of the flash array and MaximumRegistrySize is the size of the registry backup to be used. ManagedAreaStart is the start of the PSM area and ManagedAreaLength is the length of the PSM file storage and registry storage put together. The Bus width entries are the width of the bus connected to the flash.

D. Building the Driver

1. Start the Platform Builder Environment.
   
2. In the platform created make sure you have selected the hive-based REGISTRY.
   
3. Open the build release directory (from the build menu).
   
4. Change directory to $(_TARGETPLATROOT)\drivers\PSM\SA11X0\WCE.NET.
   
5. Run buildpsm.bat from there.

You will end up with psmfsd.dll in the $(_TARGETPLATROOT)\drivers\PSM\SA11X0\WCE.NET\bin directory.

E. Making the registry settings (the tricky part . . .)

The registry key changes for Windows CE 4.0 and 4.2 have minor differences, as shown below.

1. ; HIVE BOOT SECTION
[HKEY_LOCAL_MACHINE\System\StorageManager\Profiles\PSMFSD]
Name="IPSM"
Folder="e-conSystems"
; END HIVE BOOT SECTION


2. ; HIVE BOOT SECTION
[HKEY_LOCAL_MACHINE\Drivers\BuiltIn\FlshDrv]
"FolderName" = "MYIPSM" ; Folder name of your choice


3. [HKEY_LOCAL_MACHINE\System\StorageManager\AutoLoad\psmfsd]
"Dll"="psmfsd.dll"
"Paging"=dword:1
"MountFlags"=dword:2

"Loadflags"=dword:1 ; REQUIRED ONLY FOR WINCE 4.2 (only difference )


4. ; HIVE BOOT SECTION
[HKEY_LOCAL_MACHINE\init\BootVars]
"SYSTEMHIVE"="system.hv"
"PROFILEDIR"="Profiles"
"Start DevMgr"=dword:1
"DefaultUser"="e-conSystems"
; END HIVE BOOT SECTION


5. Include . . .
   
   "Flags"=dword:1000
   
   . . . in the driver keys that get loaded in the boot hive section.

F. Final build

After the above modifications, you will need to do a clean rebuild. You need to verify whether psmfsd.dll and flshdrv.dll are present in the image. Otherwise, you may have to copy them from some subdirectory of $(_TARGETPLATROOT)\drivers\PSM to the release directory, and make it part of the image.

With this NK.bin you should be able to get the PSM file storage and the registry backup working fine.

---

Part II -- Discussion of key issues

---

What exactly IPSM does, and how the filesystem works, is hidden within Intel's Intellectual Property. But, from the information available and the changes made, we can trace an outline of the IPSM.

Intel's psm driver contains a file manager that comes in the form of two libraries. Specifically, psmfsd.lib and psmhal.lib. psmfsd.lib get linked along with plat_api.c to create psmfsd.dll; and psmhal.lib gets linked with plat_api.c, which become part of the Hardware Adaptation layer / Board Support Package code.

Once the correct settings are made in plat_api.c and in the HAL files, the PSM file storage will start working. The registry backup is a tricky part.

In the RAM-based registry, the registry is in RAM and vanishes as soon as the power is switched off. To provide persistent storage to a RAM-based registry we need to allocate registry backup space in the Plat_Oem structure. Also, we (OEMs) have to implement the WriteRegistryToOEM() and ReadRegistryFromOEM() functions. These functions do a low-level write of the registry to the flash and read it back the same way. WriteRegistryToOEM() is called whenever RegFlushKey() is called to store the registry on the flash. While booting, a call to ReadRegistryFromOEM() is made and if it is successful the registry is loaded from the flash. That's the backup procedure in the RAM-based registry.

In a hive-based registry, there are two files named boot.hv and system.hv (the names can be changed using registry settings). When using the hive-based registry, we have two boot phases: the first boot phase makes use of boot.hv to bring up the most important components; during the second phase, system.hv is taken from the filesystem and used to complete the boot process. To reach the filesystem and get to system.hv, it is required that the PSM driver be loaded. But, the PSM driver is loaded based on the registry, only. So, the keys that load PSM have to be in the boot hive section (boot.hv). There are a few other keys that need to be loaded before system.hv is loaded. These are also part of boot.hv.

Whatever has to go into boot.hv needs to be mentioned between

;HIVE BOOT SECTION
....
...
...
;END HIVE BOOT SECTION

either in common.reg, platform.reg or project.reg.

Care should be taken to decide which keys become part of boot.hv, and which become part of system.hv.

"Flags"=dword:1000

This setting in the registry flag tells the Device Manager to load the driver in the first boot phase with the boot registry, and not to load it a second time in the second boot phase with the system registry. It prevents the driver from being started twice.

"SYSTEMHIVE"="system.hv"
"Start DevMgr"=dword:1

These keys tell the booting OS to start the device manager in order to reach system.hv (the system hive registry file). The device manager has to be started at this stage because, to get the system.hv file from the filesystem, the necessary drivers need to be loaded -- and only the device manager can do this.

"MountFlags"=dword:2

This says that the filesystem may contain a registry.

The boot process

The booting consists of two phases. Initially, the system boots with boot.hv. In this phase, after Nk.exe, coredll.dll, filesys.exe, fsdmgr.dll, etc. load, the psm driver psmfsd.dll and regenum.dll are loaded. Once this is done, the filesystem becomes accessible and system.hv is taken from the flash.

What happens when booting for the first time?

This interesting situation is handled differently. First, the flash is examined for proper format. Because a fresh flash is not PSM-formatted, PLAT_FormatRecovery() is called, a decision on the format and format options is made, and formatting is done. This formatting may take some time, which is the reason why the boot process might appear to have halted when PSM is enabled for the first time. Since there is no system.hv in the filesystem at this point, the default system.hv is taken from the NK.bin image and stored in the flash.

PSM as the root filesystem

To make IPSM become the root filesystem, the ROM-only filesystem has to be enabled in place of the RAM/ROM filesystem. Also, the mountflags should be . . .

"MountFlags"=dword:6

. . . which means the mounted filesystem may contain root and also the system hive. The remainder of the settings are similar.

In this case, we have the windows directory in ROM, and the rest in the IPSM. But, unfortunately, the program files folder seems to vanish. Well, there is a way to handle this situation -- and that will be the subject of a subsequent article.

To be continued . . .

---

About the Author

---

Maharajan Veerabag is a Technical Lead at e-con Systems in Chennai, India. His software specialities include device drivers and OS internals, and he has hands-on experience in both Windows CE and Windows XP Embedded and in porting embedded OSes. He holds a Bachelor of Engineering, and his hobbies include music, puzzles, and debugging.