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 -System Upgrade Packages enables the device creators to overcome the restriction -of using a stub sis file in the ROM drive. For details, see Creating System Upgrade Package.

Creating and -adding a stub SIS file to ROM

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.
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.
Place the generated -stub SIS file in the following location Z:\system\install\.

Creating SIS -files for eclipsing

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.
Run the MakeSIS and SignSIS tools to create -and sign the eclipsing SIS file. Alternatively, you can use the CreateSIS tool.

Creating -system upgrade package

To use system upgrade packages, device creators -must:

Create a PKG file and -include the ROMUpgrade (RU) flag in the package header. For -details about the RU Flag supporting different upgrade types, see System -Upgrades.
Run the MakeSIS and SignSIS tools to create -and sign the SIS file with a SU certificate. 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.

-PKG File -Format - -System Upgrade Packages + + + + + +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 +System Upgrade Packages enables the device creators to overcome the restriction +of using a stub sis file in the ROM drive. For details, see Creating System Upgrade Package.

Creating and +adding a stub SIS file to ROM

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.
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.
Place the generated +stub SIS file in the following location Z:\system\install\.

Creating SIS +files for eclipsing

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.
Run the MakeSIS and SignSIS tools to create +and sign the eclipsing SIS file. Alternatively, you can use the CreateSIS tool.

Creating +system upgrade package

To use system upgrade packages, device creators +must:

Create a PKG file and +include the ROMUpgrade (RU) flag in the package header. For +details about the RU Flag supporting different upgrade types, see System +Upgrades.
Run the MakeSIS and SignSIS tools to create +and sign the SIS file with a SU certificate. 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.

+PKG File +Format + +System Upgrade Packages

\ No newline at end of file