Collapse all Symbian^3 Product Developer Library

Building for an SMP Platform

This document describes the issues raised when building code for an SMP platform.

The only difference between building for an SMP and non-SMP system, is the inclusion of the SMPSAFE keyword in the mmp file.

However, before the SMPSAFE keyword can be used, the ROM compatibility mode should be understood and enabled. It is described below.

ROM compatibility mode

This specifies how the resulting build will execute code that has not been marked as SMP safe, for example, existing applications produced by third party developers. However, ROM compatibility mode does not guarantee that non-SMP code will work. By default, ROM compatibility is turned off. It is expected that code will be tested on a SMP platform to verify that it is SMP safe. Which compatibility mode is to be used will be decided during the ROM integration stage.

The ROM compatibility mode takes the form of two new rombuild parameters (only one can be used at any one time).

There are two parts to using ROM compatibility mode:

Specifying that it is to be turned on and which type of ROM compatibility is to be used. This is done with a new parameter for the rombuild tool.
Adding the appropriate macros in the baseport iby and oby files.

The arguments of rombuild that relate to ROM compatibility are:

rombuild argument	Description
-d SMPCOMPATMODE	Enables regular compatibility mode. This means that all the threads in unsafe processes (non-SMP safe) are restricted, so that only the ready thread with the highest priority can run. In regular compatibility mode, a thread group is created for each process. This thread group will have the same priority as the highest priority thread that it contains. These thread groups can be assigned to any of the available processors, not just CPU 0.
-d SMPCOMPATCPU0	Enables CPU 0 only mode. This means that all threads in unsafe processes (non-SMP safe) can only execute on CPU 0.

rombuild argument

Description

-d SMPCOMPATMODE

Enables regular compatibility mode. This means that all the threads in unsafe processes (non-SMP safe) are restricted, so that only the ready thread with the highest priority can run.

In regular compatibility mode, a thread group is created for each process. This thread group will have the same priority as the highest priority thread that it contains. These thread groups can be assigned to any of the available processors, not just CPU 0.

-d SMPCOMPATCPU0

Enables CPU 0 only mode. This means that all threads in unsafe processes (non-SMP safe) can only execute on CPU 0.

In order for the ROM compatibility mode arguments to work, changes have to be made to the iby and oby files of the baseport being used. This takes the form of setting the appropriate flags:

Flag	Description	Default Value
SMPUNSAFECOMPAT	Sets the state of the regular compatibility mode.	`off`
SMPUNSAFECPU0	Sets the state of the CPU 0 mode.	`off`

The only valid values for these flags are on or off.

The following line has to be added to the baseport iby and oby files:

#include <rom/include/kernel.hby>

An example of the use of above flags is:

#ifdef SMP
#if defined(SMPCOMPATMODE) && defined(SMPCOMPATCPU0)
#error "Can't have SMPCOMPATMODE and SMPCOMPATCPU0 at once!"
#endif
#ifdef SMPCOMPATMODE
SMPUNSAFECOMPAT(on)
#endif
#ifdef SMPCOMPATCPU0
SMPUNSAFECPU0(on)
#endif
#endif //SMP

Note: There is no guarantee that the use of compatibility mode will make SMP unsafe code work correctly. The compatibility mode is only a temporary migration strategy.

Now that the build system has been set up to work with non-SMP safe code, the use of the SMPSAFE can be described.

The SMPSAFE keyword

The SMPSAFE keyword is used to tell the system that the project can work correctly in an SMP environment.

It is indicated by placing the word SMPSAFE on a single line of the project's mmp file.

An example of the use of the SMPSAFE keyword is given below:

capability all

VENDORID 0x70000001

SMPSAFE

The effect of this keyword is as follows:

Is the SMPSAFE keyword present?	State of ROM Compatibility Mode	Resulting Behavior
Yes	N/A	The code is assumed to be SMP safe and will be executed accordingly.
No	Disabled	The code will be executed, but SMP related problems can occur.
No	Enabled	The code will be executed. How it is executed, depends on which ROM compatibility mode has been enabled.

Is the SMPSAFE keyword present?

State of ROM Compatibility Mode

Resulting Behavior

Yes

N/A

The code is assumed to be SMP safe and will be executed accordingly.

Disabled

The code will be executed, but SMP related problems can occur.

Enabled

The code will be executed.

How it is executed, depends on which ROM compatibility mode has been enabled.

The build process for an SMP platform will be described.

The build process for an SMP platform

The build process for an SMP platform is exactly the same as the build process for a non-SMP platform.

Note: The target must be ARMV5SMP. This can be insured if the bld.inf files specify BASE_DEFAULT in the PRJ_PLATFORMS line.

For the description of this process, follow the Build Tool Guide link below.

Parent topic: SMP Concepts

Related concepts

SMP Developer Tips

Related information

Build Tools Guide