System -Start Example

Download

Click on the following link to download -the example: SysStart.zip

Click: browse to view the example code.

Description

This -example demonstrates the use of resource files at the time of System Start-up. -System starter is an architecture designed to provide a consistent, transparent, -easily customisable method of starting components (i.e. servers and applications) -at device boot. It allows an ordering of components according to criticality -and dependency by means of a Static Start-up Configuration (SSC).

Related APIs

egSysStart::E32Main ()

egSysStart::Simple -()

Resource files

In -this example a resource file SSCForStartupMode0.rss is used -at Start-up.

On a target device booting normally, the SSC SSCForStartupMode0.rss is -always used for start-up. This SSC is associated with startup mode zero, which -is defined as EStartupModeUndefined in e32modes.h. The -System Starter architecture provides an ability to select between a number -of static Start-up configurations (rss files) depending on the desired Start-up -Mode, for example: Full, Emergency, Charging, or Test. Each of these modes -may require different sets of components and order of execution.

The -start-up process in the resource file is staged via an ordering of Start-up -States or phases. These states cannot be removed or their values altered. -They appear in the following order:

EStartupStateUndefined – -Value before the system enters its first state/ undefined state.

EStartupStateCriticalStatic – -Within this Start-up State all ROM based (static) components or resources -that are critical to the operation of the phone function are started.

EStartupStateCriticalDynamic – -Within this Start-up State all non-ROM based (dynamic) components or resources -that are critical to the operation of the phone function are started.

EStartupStateNonCritical – -Within this Start-up State all ROM based (static) or non-ROM based (dynamic) -components or resources that are non-critical to the operation of the phone -function are started. All components that have not already been started and -are required at device boot are started in this Start-up State.

This -allows start-up to be split into separate, distinct states with a defined -order. Within each state, a STATE_INFO structure containing -information regarding that state is located. This contains the following information:

- - - -

The id of the state as defined in the custom header file

- - -

Name

A text string describing the state

- - -

Command_list

The name of the Command array in the SSC which contains the list -of Commands to invoke in that state

- - -

The name of the Command array corresponding to the next state

- - - -

Following the STATE_INFO structure in the SSC -is a COMMAND_ARRAY structure. This contains details of all -commands to be executed within that list. Its name matches the command_list -identifier in the STATE_INFO struct and contains one array -entry: Commands. The Command entry contains a list of all commands to be executed. -Each instance in the rss file is headed with the START_PROCESS_INFO identifier -and contains any value needed to override the defaults specified in startup.rh.

- - - -Type -

Set by default. Should not be specified in the SSC.

- - -Path -

The location of the binary e.g. path = "Z:\sys\bin\fbserv.exe"

- - -Args -

Arguments passed to the process.

- - -start_method -

The enum TStartupCommandType is defined in startup.hrh. -Currently it takes one of three values:

EFireAndForget (the -default)
EWaitForStart
EDeferredWaitForStart

Use EFireAndForget if there is no need for the -process to be started serially in other words as soon as the process has been -invoked, the System Starter can continue with starting the next process without -waiting for the process to rendezvous.

Use EWaitForStart if -the process needs to get to a certain stage before starting the next process. -The starter cannot continue with the next Command until a rendezvous has been -made with the first process.

Note that the apparc component must be -started with mode EWaitForStart to allow connection with -the server to take place.

Use EDeferredWaitForStart if -there is no need to start the process serially, but at a later stage there -is a command which cannot be invoked until this process has initialized. Using -this value allows a number of commands to be started and the System Starter -to wait for them all at a later point in the SSC. This ensures later on that -the initializations of all EDeferredWaitForStart commands -have completed.

EWaitForStart and EDeferredWaitForStart depend -upon receiving a rendezvous from the started process. By default this is performed -automatically by EikonEnv. If however, you wish your component to perform -its own rendezvous, then the following function should be overridden in your -AppUi class and return EFalse.

TBool CCoeAppUi::FrameworkCallsRendezvous();

- - -timeout -

This field is for use with start_method EWaitForStart only.

Indicate -if a timer should be started when attempting to start the process by filling -in this timeout value in milliseconds. The value is 0 by default indicating -that no timer will be started.

Note that if the timer expires before -a rendezvous with the component is made, the component will be killed. If -the component is a critical process this will result in a Kern:4 Panic (which -on licensee phones usually initiates in a system restart).

- - -retry_failure_recovery_method -

This specifies the action to take if an error is returned from an -attempt to start the process.

It is set to ERestartOS by -default. This means if the process fails to start the system will restart -in the default start-up mode.

If it is set to EIgnoreOnFailure then -the starter will continue with the next Command. This option is intended for -non-critical components on which nothing critical is dependent.

If -it is set to ERestartOSWithMode the system will be restarted -in a specific start-up mode.

Note: this field has a slightly different -use depending on the start mode: in modes EFireAndForget and EDeferredWaitForStart a -failure will be indicated only if there is an immediate error for example -the initial process creation/invocation fails. In EWaitForStart a -failure will also be indicated if there is no successful rendezvous.

- - -no_of_retries_on_failure -

For use with start_method EWaitForStart only. -Set to 0 by default.

This specifies the maximum number of times the -starter should try to start a failed process. After the process has been retried -the specified number of times, the starter will act according to the value -in the retry_failure_recovery_method field. This is used -in conjunction with the timeout value.

- - -monitor -

Indicates whether the started process should be monitored for failure -by the System Monitor component. The value is 0 by default indicating that -no monitoring will be done.

A value of 1 indicates monitoring should -be performed. The recovery policy set by retry_failure_recovery_method (and -if applicable retry_failure_recovery_startup_mode) will be used by the System -Monitor if a failure occurs to this process during the lifetime of the system.

Note: -if the component being started is a System Critical process, monitoring must -not be enabled.

- - -retry_failure_recovery_startup_mode -

For use with retry_failure_recovery_method ERestartOSWithMode only.

Used -to specify the start-up mode the system should restart with. This is set to EStartupModeUndefined by -default.

- - - -

+ + + + + + System Start Example +

Download

Click on the following link to +download the example: SysStart.zip

Click: browse to view the example code.

Description

This example demonstrates the use of resource files at the time +of System Start-up. System starter is an architecture designed to +provide a consistent, transparent, easily customisable method of starting +components (i.e. servers and applications) at device boot. It allows +an ordering of components according to criticality and dependency +by means of a Static Start-up Configuration (SSC).

Related APIs

egSysStart::E32Main ()
egSysStart::Simple ()

Resource +files

In this example a resource file SSCForStartupMode0.rss is used at Start-up.

On a target device booting normally, +the SSC SSCForStartupMode0.rss is always used for +start-up. This SSC is associated with startup mode zero, which is +defined as EStartupModeUndefined in e32modes.h. +The System Starter architecture provides an ability to select between +a number of static Start-up configurations (rss files) depending on +the desired Start-up Mode, for example: Full, Emergency, Charging, +or Test. Each of these modes may require different sets of components +and order of execution.

The start-up process in the resource +file is staged via an ordering of Start-up States or phases. These +states cannot be removed or their values altered. They appear in the +following order:

TStartupCommandType::EStartupStateUndefined – Value before the system enters its first state/ undefined state.

TStartupCommandType::EStartupStateCriticalStatic – Within this Start-up State all ROM based (static) components or +resources that are critical to the operation of the phone function +are started.

TStartupCommandType::EStartupStateCriticalDynamic – Within this Start-up State all non-ROM based (dynamic) components +or resources that are critical to the operation of the phone function +are started.

TStartupCommandType::EStartupStateNonCritical – Within this Start-up State all ROM based (static) or non-ROM based +(dynamic) components or resources that are non-critical to the operation +of the phone function are started. All components that have not already +been started and are required at device boot are started in this Start-up +State.

This allows start-up to be split into separate, distinct +states with a defined order. Within each state, a STATE_INFO structure containing information regarding that state is located. +This contains the following information:

+ + + +

The id of the state as defined in the custom header file

+ + +

Name

A text string describing the state

+ + +

Command_list

The name of the Command array in the SSC which contains +the list of Commands to invoke in that state

+ + +

The name of the Command array corresponding to the next +state

+ + + +

Following the STATE_INFO structure in +the SSC is a COMMAND_ARRAY structure. This contains +details of all commands to be executed within that list. Its name +matches the command_list identifier in the STATE_INFO struct and contains one array entry: Commands. The Command entry +contains a list of all commands to be executed. Each instance in the +rss file is headed with the START_PROCESS_INFO identifier +and contains any value needed to override the defaults specified in startup.rh.

+ + + +Type +

Set by default. Should not be specified in the SSC.

+ + +Path +

The location of the binary e.g. path = "Z:\sys\bin\fbserv.exe"

+ + +Args +

Arguments passed to the process.

+ + +start_method +

The enum TStartupCommandType is defined +in startup.hrh. Currently it takes one of three values:

EFireAndForget (the default)
EWaitForStart
EDeferredWaitForStart

Use EFireAndForget if there is no need +for the process to be started serially in other words as soon as the +process has been invoked, the System Starter can continue with starting +the next process without waiting for the process to rendezvous.

Use EWaitForStart if the process needs to +get to a certain stage before starting the next process. The starter +cannot continue with the next Command until a rendezvous has been +made with the first process.

Note that the apparc component +must be started with mode EWaitForStart to allow +connection with the server to take place.

Use EDeferredWaitForStart if there is no need to start the process serially, but at a later +stage there is a command which cannot be invoked until this process +has initialized. Using this value allows a number of commands to be +started and the System Starter to wait for them all at a later point +in the SSC. This ensures later on that the initializations of all EDeferredWaitForStart commands have completed.

EWaitForStart and EDeferredWaitForStart depend upon receiving a rendezvous from the started process. By +default this is performed automatically by EikonEnv. If however, you +wish your component to perform its own rendezvous, then the following +function should be overridden in your AppUi class and return EFalse.

TBool CCoeAppUi::FrameworkCallsRendezvous();

+ + +timeout +

This field is for use with start_method EWaitForStart only.

Indicate if a timer should be started when attempting +to start the process by filling in this timeout value in milliseconds. +The value is 0 by default indicating that no timer will be started.

Note that if the timer expires before a rendezvous with the component +is made, the component will be killed. If the component is a critical +process this will result in a Kern:4 Panic (which on licensee phones +usually initiates in a system restart).

+ + +retry_failure_recovery_method +

This specifies the action to take if an error is returned +from an attempt to start the process.

It is set to ERestartOS by default. This means if the process fails +to start the system will restart in the default start-up mode.

If it is set to EIgnoreOnFailure then the +starter will continue with the next Command. This option is intended +for non-critical components on which nothing critical is dependent.

If it is set to ERestartOSWithMode the system +will be restarted in a specific start-up mode.

Note: this +field has a slightly different use depending on the start mode: in +modes EFireAndForget and EDeferredWaitForStart a failure will be indicated only if there is an immediate error +for example the initial process creation/invocation fails. In EWaitForStart a failure will also be indicated if there +is no successful rendezvous.

+ + +no_of_retries_on_failure +

For use with start_method EWaitForStart only. Set to 0 by default.

This specifies the maximum number +of times the starter should try to start a failed process. After the +process has been retried the specified number of times, the starter +will act according to the value in the retry_failure_recovery_method field. This is used in conjunction with the timeout value.

+ + +monitor +

Indicates whether the started process should be monitored +for failure by the System Monitor component. The value is 0 by default +indicating that no monitoring will be done.

A value of 1 indicates +monitoring should be performed. The recovery policy set by retry_failure_recovery_method (and if applicable retry_failure_recovery_startup_mode) +will be used by the System Monitor if a failure occurs to this process +during the lifetime of the system.

Note: if the component +being started is a System Critical process, monitoring must not be +enabled.

+ + +retry_failure_recovery_startup_mode +

For use with retry_failure_recovery_method ERestartOSWithMode only.

Used to specify the start-up mode the system should +restart with. This is set to EStartupModeUndefined by default.

+ + + +

\ No newline at end of file