How to upgrade OS components

The software installer allows the replacement of binaries and data files in ROM, for instance to allow a manufacturer to fix a software issue, by means of eclipsing, but it is strictly controlled.

Eclipsing occurs when some form of path-processing logic is being applied, and a file is installed with the same name and path as an existing file - but to a different drive. Under these circumstances, therefore, the new file is used instead of the original.

The OS loader exhibits this behaviour; when an EXE or DLL is loaded, drives are searched in the order Y: to A: followed by Z:. Therefore, a binary file installed to the C: drive, (or any other drive between A: and Y:) will eclipse one with the same name and path on Z: and will be loaded instead of the original X: file.

In order to eclipse data files in ROM, an application must explicitly support this behaviour, in other words, it should not assume that data files will be located on Z:.

Creating the stub SIS file

Files in ROM can only be eclipsed if the device manufacturer has added a stub SIS file, which claims ownership of these files, to the ROM. The stub SIS file must be located in Z:\system\install\ and its name is not particularly significant.

Without a relevant stub SIS file present, any attempt by the user to install a package that eclipses files in ROM will fail.

In the PKG file used to generate the stub SIS file, the source file entries are irrelevant (because no installable files are included in a stub SIS file), and are therefore specified as empty strings. For instance:

; Example STUB File
&EN
%{"Symbian Software Ltd."}
:"Symbian Software Ltd."
#{"Hello World"},(0x18000091),1,0,0
"" - "z:\sys\bin\HelloWorld.exe"
"" - "z:\resource\apps\HelloWorld.rsc"
"" - "z:\resource\apps\HelloWorld.mbm"
"" - "z:\private\10003a3f\import\apps\HelloWorld_reg.rsc"

The Wildcards * and ? can be used in file names specified in stub SIS files in the ROM, allowing licensees to define multiple files with one definition. Using wildcards means licensees do not need to list every file in the stub, and also licensees only need to create a single stub SIS file to work with all possible language variants. This can help avoid cases such as being unable to upgrade on a phone in the market due to a mismatching stub SIS file in the ROM. For example, the following entry means that all possible language variants of the application's resource files could be eclipsed.

The executables (exes not dlls) should always be explicitly included in the ROM stub, without wildcards. This is necessary to allow files to be installed into private directories of those applications in upgrades and to avoid getting errors due to the SID being eclipsed. This is because, when the ROM stub is processed by the SIS registry at first boot, the SIDs of executables are added to the registry entry enabling upgrades to install files into the private directories corresponding to those SIDs. However, for performance reasons, the SIS registry does not attempt to find the SID for every executable matched by the wildcard. For example if the ROM stub contains "z:\sys\bin\media_*.exe", the SID of z:\sys\bin\media_player.exe won't be added to the registry entry for the ROM stub. Consequently, you would not be able to upgrade z:\sys\bin\media_player.exe or install files into the private directory belonging to media_player.exe. For this reason, when creating installation files, MakeSIS issues a warning if wildcards are used in the \sys directory in ROM stubs.

""-"z:\resource\apps\HelloWorld.r*

To generate the stub SIS file, use:

> makesis – s <PKG_filename>

When creating installation files, MakeSIS issues a warning if wildcards are used in the \sys directory in ROM stubs. This is because, when the ROM stub is processed by the SIS registry at first boot, the SIDs of executables are added to the registry entry enabling upgrades to install files into the private directories corresponding to those SIDs. However, for performance reasons the SIS registry does not attempt to find the SID for every executable matched by the wildcard, for example if the ROM stub contains "z:\sys\bin\media_*.exe", the SID of z:\sys\bin\media_player.exe won't be added to the registry entry for the ROM stub. Consequently, you would not be able to upgrade z:\sys\bin\media_player.exe or install files into the private directory belonging to media_player.exe.

The stub SIS file is not signed, but it must have a package UID from the protected range. In other words, it must be selected from the range allocated to the device manufacturer by Symbian Signed.

Creating the eclipsing package

The files in the eclipsing package must be installed to the same path, and have the same filename as the files in ROM that are being eclipsed (except of course the drive is different). For instance:

;Example eclipsing package
&EN
%{"Symbian Software Ltd."}
:"Symbian Software Ltd."
#{"Hello World"},(0x18000091),1,1,0, TYPE=PU
"HelloWorld.exe"-"$:\sys\bin\HelloWorld.exe"
"HelloWorld.rsc"-"$:\resource\apps\HelloWorld.rsc"
"HelloWorld.mbm" - "$:\resource\apps\HelloWorld.mbm"
"HelloWorld_reg.rsc" - "$:\private\10003a3f\import\apps\HelloWorld_reg.rsc"

Specifying the target drive letter as $: (to denote the system drive) may be preferable to allowing the user to select it, because if the user chose to install the package to a removable drive, which was subsequently removed, the version on Z: would be in use again.

The upgrading package must have the same package UID as the stub SIS file. As this is always from the protected range, the eclipsing (and upgrading) package must have been signed by a signing authority.

The eclipsing package can be of type SA - using the RU flag (full upgrade), PU (partial upgrade) or SP (patch).

The installer prevents a file from being eclipsed by two other files at the same time. For instance, if you install a file to C: that eclipses a ROM file, then an attempt to eclipse the file again, by installing to D:, will fail.

Eclipsing using a full upgrade

The ability to carry out full upgrades using an SA package with the RU flag for eclipsing was introduced in version 9.4. Prior to this, licensees needed to provide a package of type PU to install on phones which had the applications installed in ROM and a separate package of type SA for phones which did not have the application installed in ROM. The introduction of type SA, RU means that licensees can provide one package for both.

An eclipsing package of type SA should have the same package name and global vendor name as the package it is eclipsing.

To be able to carry out an installation of a package of type SA, the package must add the ROM Upgrade (RU or ROMUPGRADE) flag as part of the install options of the header section of its PKG file. The RU flag distinguishes a full upgrade to ROM from an ordinary SA installation. The use of the SA, RU flag is shown in the following example.

;Example eclipsing package
&EN
%{"Symbian Software Ltd."}
:"Symbian Software Ltd."
#{"Hello World"},(0x18000091),1,2,4, TYPE=SA, RU

Note: the RU flag applies only to the SA package it is in. It does not apply to any of the embedded packages inside the SA.

After doing an SA, RU upgrade, the SA files eclipse those in ROM. Further upgrades remove the previously installed SA package.

So long as certain restrictions are observed, when you remove the SA package, the ROM files will work as they did before the upgrade. Installing an SA, RU upgrade does not remove or replace the ROM application's private directory (if one exists). The SA, RU upgrade can at runtime overwrite files previously created by the ROM application in its private directory. If it does, it needs to make sure that the new versions of these files are compatible with the ROM application. This is because if the upgrade is uninstalled, the files it created will remain on the device. The upgrade must not remove any private files that it hasn't installed.

An SA, RU installation over ROM removes any previously installed PU upgrades. If the user wants any of those PU files, they need to manually reinstall them. It doesn’t, however, remove previously installed SP packages.

Eclipsing using a partial upgrade

An eclipsing package of type PU should have the same package name and global vendor name as the package it is eclipsing (because the changes made by a partial upgrade are considered to become a part of the original package). Such a package cannot be removed, although it is possible to install multiple partial upgrades with the same package name and UID, for example:

Eclipsing using a patch

Although a patch cannot overwrite files in a base package in RAM, it can eclipse files in ROM. An eclipsing package of type SP must have a different package name from the package it is eclipsing, because it subsequently can be removed separately from it. If two patches with the same package name and UID are installed, the second patch is treated as an upgrade of the first patch and will replace it entirely, for example:

An OS component can be augmented by the installation of a patch. A patch can subsequently be removed separately from the package it is augmenting.

It is possible to re-patch the package to fix any problems which the first patch may introduce. A patch can overwrite an existing patch, if both patches have the same package name.

An OS component does not necessarily need a stub SIS file in order to be patched. However, if the patch attempts to install any files to the component’s private directory, then a stub SIS file is required which specifies the relevant EXE. If the patch installs files to more than one private directory, all relevant EXEs must be specified in the stub file.

A patch (or any package) can install files to a component’s import directory (\private\<SID>\import\) without a stub SIS file present, (the purpose of the import directory is to enable other packages to install files to it). However, the import directory must already exist – the software installer will not create it.

If a stub SIS file is required, the patch must have the same package UID and non-localized vendor name as the package it is patching. The package name should be different in order to distinguish the patch from the existing component. The patch can have its own version number. The PKG file type for a patch is SP. For instance:

; Example patching package
&EN
%{"Symbian Software Ltd."}
:"Symbian Software Ltd."
#{"Hello World patch"},(0x18000091),1,0,0, TYPE=SP
; installs a file to the private directory – a stub SIS is required.
; the private directory is the SID, which in this case is not the same as the package UID
"patch.dat" - "!:\private\e800005a\patch.dat"

Here are some tips to avoid common problems that can occur when using ROM eclipsing.

• Remember that the destination files listed in the stub SIS should be on z:, and the source file names should consist of empty quotes, for instance:

  "" - "z:\sys\bin\HelloWorld.exe"

• If you are eclipsing an application EXE make sure that both the application and the eclipsing SIS file have put the application registration file (*_reg.rsc) in \private\10003a3f\import\apps\ rather than \private\10003a3f\apps\. Otherwise the application framework will still pick up the application from z:

• DLLs and EXEs have version numbers. You can set the version (which consists of a major and a minor number) in the MMP file by using the VERSION keyword. If not specified, the version number defaults to 10.0.

  When eclipsing a DLL in ROM, the upgrading version must have a larger version number than the one in ROM, otherwise any EXEs in ROM (Z:) that link to this DLL may still use the version on Z:. Note though that the new version must have the same major version number. So, assuming a file called bar.dll in ROM, which uses the default version number, an upgrading version of bar.dll installed on a different drive will only be loaded in preference to the one in ROM if its version number is between 10.1 and 10.9.

  Note: eclipsing an entire application does not involve the DLL version number check.

• Remember to build the stub SIS file with the –s option to makesis:

  makesis –s <PKG_filename>

• Remember that the application that needs to be upgradable should not hard code any paths to Z:, otherwise files will still get picked up from z:.

• If you are upgrading ECOM plugins on Z:, remember to increment the interface implementation version number.

• A check on the vendor name in the stub and eclipsing SIS files is performed at install time, so check that these match.

• In an XIP (execute in place) ROM, the linking of executables to the various DLLs is done at ROM build time rather than at run time. Therefore, to eclipse a DLL in an XIP ROM, you must also eclipse the EXE that uses it.

• To eclipse language specific files, it is recommended to eclipse every language variant that is in the ROM. So, for instance, if your application's resource file has .RSC and .R02 in ROM, your eclipsing SIS file should also include a .RSC and a .R02.

• A file cannot be eclipsed by two different files at any one time. For instance, a file installed to c: to eclipse a file in ROM, cannot itself be eclipsed by installing a file to d:.