Upgrading OS Components

A device creator can replace data files and binaries in ROM by means of eclipsing. A typical example for this requirement is to fix a software issue.

To eclipse the files in the ROM, the device creators must add a Stub SIS file to the ROM and install a package that supports eclipsing. See Creating and adding a stub SIS file to ROM and Creating SIS files for eclipsing for details.

Creating and adding a stub SIS file to ROM

1. Create a PKG file.

   Ensure the PKG file used to generate the Stub SIS file does not include source file entries and are specified as empty strings.

   For example:

   ; Example STUB File
   &EN
   %{"Nokia Corporation"}
   :"Nokia Corporation"
   #{"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"

   Note: For details about using wildcards, see Wildcard Usage with Stub SIS files.

2. Run the MakeSIS tool at the command-prompt and specify the -s option to create the stub SIS file:

   makesis –s <PKG_filename>

   Note: The package UID must be selcted from the protected range allocated to the device creator by Symbian Signed.

3. Place the generated stub SIS file in the following location Z:\system\install\.

Creating SIS files for eclipsing

1. Create an eclipsing package. The eclipsing package can be of type SA (full upgrade), PU (partial upgrade) or SP (patch upgrade). For details, see Upgrade Types.

   The files in the eclipsing package must have same filename and path as the files in ROM that are eclipsed. However, the drive must be different. For example:

   ;Eclipsing package
   &EN
   %{"Nokia Corporation"}
   :"Nokia Corporation"
   #{"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"

   The upgrading package must have same package UID as the stub SIS file, as this is always from the protected range.

   It is preferable to specify the target drive letter as $: to denote the system drive. This is because if the Symbian device user chooses to install the package to a removable drive, which can subsequently be removed, the files on Z drive can be used again.

   Note: The installer does not allow two different files to eclipse a file at the same time. For example, after eclipsing a ROM file by installing a newer version of the file to C drive, the installer does not allow you to eclipse the ROM file again by installing another version of the file to D drive. The installation fails.

2. Run the MakeSIS and SignSIS tools to create and sign the eclipsing SIS file. Alternatively, you can use the CreateSIS tool.

Important Considerations

Consider the following tips to avoid common problems that can occur when eclipsing ROM files.

• 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\. Else, the application framework picks up the application from z drive.

• The DLLs and EXEs have version numbers. You can set the version (which consists of a major and a minor number) in the MMP file using the VERSION keyword. The default version number is 10.0.

  When eclipsing a DLL available in ROM, the upgrading version number must be higher than the one in ROM, otherwise, any EXEs in ROM (Z drive) that link to this DLL can use the version on Z drive. However, the new version must have the same major version number.

• The application that needs to be upgradable must not hard code any path to Z drive, otherwise files are picked up from z drive.

• If you are upgrading ECOM plugins on Z drive, you must increment the interface implementation version number.

• Verify that the vendor names in the Stub SIS file match with the vendor names of the eclipsing SIS file.

• In an XIP (execute in place) ROM, the linking of executables to DLL s is done at ROM build time. Therefore, to eclipse a DLL in an XIP ROM, the EXE that uses it also needs to be eclipsed.

• To eclipse language specific files, it is recommended to eclipse every language variant that is in the ROM. For example, if the application resource file has .RSC and .R02 in ROM, the eclipsing SIS file must also include .RSC and .R02.