Base +Starter Technology

The purpose of the Base Starter is to:

Define a handset's local +drives
Define what file systems +(.FSY) and file extensions (.FXT) +are to be mounted on those drives
Associate drive letters +with drives
Modify drive start-up +behaviour
Enable fair +scheduling and file caching on a drive by drive basis.

Handset manufacturers need to customise the Base Starter as part of the +process of porting Symbian platform to a new device. Mapping local drives is the most important part of this process, but customisation +using TFSStartup is also possible.

Note that there are some activities +that the Base Starter does not do

Mapping local +drives

There are two ways to do this:

Create local drive mapping files
Use automatic local drive mapping.

Create local drive mapping +files

A local drive mapping file is an ASCII text file that explicitly +defines the drive letter, file system, and file extension to be associated +with a drive. The file contains a set of records, one for each drive, that +specifies this information. Records are also referred to as drive mappings.

The +file is created as part of your hardware variant's source tree, but is copied +into a standard location in your ROM filing system when you build the ROM.

A +drive mapping file has a formal structure; the main rules are:

the file can contain +a maximum of 16 different drive mappings
each drive mapping is +represented by a separate record; each record occupies one line; each line +is separated by the new line character \n
information is represented +by items separated by at least one blank character
comments can occupy +a whole line or can be added onto the end of a record (i.e. at the end of +line). They are marked by a # character that must precede +the start of the comment text.

A record, or drive mapping, has the following items, each separated +by at least one blank character. Each item must appear in the order described:

<drive_letter> <drive_number> <file_system_filename> <file_system> <file_extension_filename> <flags> + + + +

<drive_letter>

A single character between A and Z followed +by a colon.

+ + +

<drive_number>

The local drive number associated with the drive letter .

+ + +

<file_system_filename>

The filename of the file system that is to be mounted on the drive. +This should be the filename without the .FSY extension. +If it is necessary to omit a file system file name for any reason, then this +item should contain the null character: 0.

+ + +

<file_system>

The name of the file system as implemented by <file_system_filename>.

If +the file system name is the same as the file name, as represented by the <file_system_filename> item, +then supply the null character 0. [Internally, the file system +name is sometimes referred to as the object name.]

Symbian platform +supplies the following file systems:

FAT
ROFS - +read/only file system
LFFS - +logging flash file system
COMP - +composite file system (but see the description of the FS_COMPOSITE flag +below)

Handset manufacturers may supply other file systems.

+ + +

<file_extension_filename>

The filename of the file extension that is to be mounted on the +drive. This should be the filename without the .FXT extension. +If it is necessary to omit a file extension file name for any reason, then +this item should contain the null character: 0.

+ + +

<flags>

A set of mount flags that modify the start-up behaviour of +the local drive. More than one flag can be specified, each separated by a +comma, with no intervening blank characters. If no flags apply, then the null +character: 0 must be coded.

+ + + +

FS_FORMAT_ALWAYS

Formats the drive as soon as it has been mounted.

+ + +

FS_FORMAT_COLD

Formats the drive as soon as it has been mounted if the device is +performing a cold boot. This is generally required for internal RAM drives.

+ + +

FS_FORMAT_CORRUPT

Formats the drive, if it is found to be corrupt when mounted.

+ + +

FS_DISMNT_CORRUPT

Dismounts the drive, if it is found to be corrupt when mounted. +The local drive mapping remains unaltered and the associated file system file +is not unloaded.

+ + +

FS_SWAP_CORRUPT-<drv>

Dismounts the drive, if it is found to be corrupt when mounted, +and swaps the mappings for this drive with the alternative drive <drv>, +and remounts both.

The alternative drive <drv> must +be specified, and must follow a '-' character, which follows +the FS_SWAP_CORRUPT symbol.

For example, to swap +with drive Y:, specify:

FS_SWAP_CORRUPT-Y

This +option is commonly used when handling corrupt flash user-data drives on C:. +The corrupt drive is mapped to another drive letter – allowing data to be +extracted from it. The C: drive is replaced by a RAM +disk – providing a temporary work disk for the OS, while the main one is restored. +Note that a mapping file must not specify more than one drive for swapping, +i.e. there can only be one occurrence of FS_SWAP_CORRUPT flag +per mapping file.

Both drives involved in the swap must be internal +drives.

+ + +

FS_SYNC_DRIVE

Mounts this drive as a synchronous drive. This means that requests +are handled in the main file server thread rather than in a dedicated drive +thread. This option is normally only specified for internal RAM drives.

+ + +

FS_SCANDRIVE

Runs Scandrive, once mounted, but only if the +rugged file system is enabled.

+ + +

FS_COMPOSITE

Marks the drive as contributing to the composite file system. The +composite file system allows multiple local drives to be overlaid with each +other, and with the core OS ROM image, and to make them appear as one drive.

Files +in one drive can add to, replace, or hide (i.e. logically remove) files in +another drive

There are number of rules:

the drive letter must +always be Z:
if the file system is +omitted, i.e. both <file_system_filename> and <file_system> are +set to '0', then the the ROFS file system is assumed, and this can be the only drive +marked with FS_COMPOSITE in a mapping file.
if the file system is +explicitly specified, i.e. <file_system_filename> and <file_system> are +set, then more than one drive can be marked with FS_COMPOSITE. +However, adding a drive that uses a file system other than ROFS is strongly +discouraged for performance reasons.
the order of the records +is important, as this defines the search order when Symbian platform is working +out which files will contribute to the final ROM. The core OS ROM file system +(containing the kernel, kernel extensions, media drivers, the file server, +file systems and the Base Starter executable) is searched first, followed +by the last drive in the mapping file marked with FS_COMPOSITE, +followed by the next last drive marked with FS_COMPOSITE etc.

Note: the use of COMP as a <file_system> seems +to contradict the use of this flag. COMP was used to specify +a composite file system that allowed a single drive to be combined +with the ROM file system. For compatibility purposes, and to ensure consistency +of syntax, you can still specify COMP with FS_COMPOSITE on +a drive mapping, but you cannot have any other drive mappings marked as FS_COMPOSITE. +If you specify COMP, then the underlying file system associated +with that drive is assumed to be ROFS.

See Mounting multiple ROM images +as a single ROM drive for more detail.

+ + +

FS_NO_MOUNT

Loads the file specified file system and the specified file extension, +and maps the drive as specified, but does not mount the drive. This is often +used in conjunction with FS_SWAP_CORRUPT. It allows the configuration +for the alternative drive involved in a swap to be specified – but for the +drive not to be mounted and accessible in normal operation. If the drive is +involved in a swap with another, then the FS_NO_MOUNT state +is ignored and the drive is mounted normally.

+ + +

FS_ALLOW_REM_ACC

This is reserved for future use.

+ + +

FS_NOT_RUGGED

Marks the mount as not rugged. Mounting the drive without the rugged +file system means that FS_SCANDRIVE is not supported. If FS_SCANDRIVE is +also defined, it is ignored.

+ + +

FS_SYSTEM_DRIVE

Assigns this drive as the system drive. Applications store user +data on the system drive, and call RFs::GetSystemDriveChar() to +discover the drive letter.

A mapping file can only specify one drive +as the system drive.

See the +system drive.

+ + + +

Use automatic local drive +mapping

If no drive mapping file exists or is unavailable, the +Base Starter decides which file system to mount on each local drive by interrogating +the capabilities of those drives. This is known as auto-detection.

Internally, +the Base Starter holds a table containing entries for every known supported +local drive configuration. This table is known as the auto-configuration table. +The information supplied by each entry in the table resembles that supplied +by a local +drive mapping file, and contains the following information:

The filename of the +file system for this configuration (the .FSY). The filename +corresponds to the <file_system_filename> item in a drive +mapping file entry.
The object name of the +file system for this configuration. The object name corresponds to the <file_system> item +in a drive mapping file entry.
The filename of the +file server extension for this configuration, if applicable. The filename +corresponds to the <file_system> item +in a drive mapping file entry.
The set of mount flags; +these correspond to the <flags> items in a drive mapping +file entry. There is one exception - FS_SWAP_CORRUPT is not +supported, because it is impossible to auto-detect which drive is to be swapped.
A file system identification +function that is used to decide whether the designated file system is really +suitable for this drive. Each function is an internal part of the generic +Base Starter code.

The Base Starter uses the following default mapping of drive letters +to drive numbers:

+ + + +

Local drive number

Drive letter

+ + +

+ + + +

Customisation +using TFSStartup

Most of the functionality provided by the Base +Starter is provided by the class TFSStartup. +This contains a number of virtual functions with default Symbian implementations. +A handset manufacturer can create a customised version of the Base Starter, +which overrides these functions.

Disabling drive auto-detection
Customising for multiple hardware states
Overriding the default drive mapping
Customising mount flags
Customising the drive initialisation sequence
Customising Loadlocale
Customising the restart mode
Customising other behaviour

Disabling drive auto-detection

The +most common customisation is to use the supplied version of the Base Starter +and to create one or more local drive mapping files . In this case, savings +in code space can be made by removing the code that deals with auto-detection. +This is achieved by adding the following line to the MMP file +describing the Base Starter, and then rebuilding it.

MACRO AUTODETECT_DISABLE

Customising for multiple +hardware states

If the state of your hardware varies, and it requires +different mapping files for different states, then it is still possible to +use the local drive mapping scheme. Examples of hardware state variations +might be differences in the state of a switch or jumper setting, or the presence +or absence of a hardware feature. In this situation, the ROM can be built +with more than one mapping file. A custom version of the Base Starter provides +its own version of the virtual function TFSStartUp::LocalDriveMappingFileName(); +this checks the appropriate settings, and returns the name of the appropriate +local drive mapping file. The returned name is the full path name.

Overriding the default drive +mapping

To override the default mapping of drive letters to drive +numbers on a drive by drive basis, a custom version of the Base Starter provides +its own version of the virtual function TFSStartUp::DefaultLocalDrive().

To +override the auto-configuration table used by the automatic local drive mapping +scheme, for example to add support for a new .FSY, a +custom version of the Base Starter provides its own version of the virtual +function TFSStartUp::GetNextStandardFSInfoEntry().

Customising mount flags

Whether +you use the automatic local drive mapping scheme or an explicit local drive +mapping file, you can provide support for additional mount flags. A custom +version of the Base Starter provides its own version of the virtual functions:

TFSStartUp::ParseCustomMountFlags()
TFSStartUp::HandleCustomMountFlags()

Customising the drive initialisation +sequence

To override the entire local drive initialisation sequence +provided by the generic version of the Base Starter, a custom version of the +Base Starter provides its own version of the virtual function TFSStartUp::LocalDriveInit().

Customising Loadlocale

User::UTCOffset() is called within the LoadLocale() function. Customise TFSStartup::LoadLocale() so +that the offset behaviour is correct for your time zone.

Setting the User::UTCOffset() is required within EStart +to provide backward compatibility and because it provides the system time +to components before the timezone/locale services are initialised.

See setting the universal time +offset.

Customising the restart +mode

TFSStartup::GetStartupMode() and TFSStartup::GetStartupModeFromFile() must be +implemented to get the restart mode at start-up.

Symbian platform +does not define any meaning to restart mode values. It is for the use of the +device manufacturer.

The restart mode is defined by the HAL attribute EPersistStartupM. This is a TAttribute enum +value defined in class HALData in ..\hal\inc\hal_data.h.

To +use this attribute, define it in your variant’s config.hcf file +and set an initial value in your variant’s values.hda file. +The template port defines the attribute as settable using the following definition +in the config.hcf file.

EPersistStartupModeKernel : set = ProcessPersistStartupMode

The value can be changed using HAL::Set(). ProcessPersistStartupMode is +the name of a function internal to Symbian platform. If you choose to make +the attribute settable, you must use this definition.

Calls to HAL::Get() are routed to the function Template::VariantHal() in +your variant's variant.cpp file, and handled by the EVariantHalGetPersistedStartupMode case.

Calls +to HAL::Set() are routed to the function Template::VariantHal() in +your variant's variant.cpp file, and handled by the EVariantHalPersistStartupMode case.

You +need to do the following:

If you choose to make +the custom startup mode settable (in Symbian platform terminology, the attribute +is said to be derived), you need to implement TFSStartup::GetStartupMode(). +Derived attributes are saved when the system is closed down. The function GetStartupMode() is +called before the file server starts.
If you choose to make +the custom startup mode non-settable (in Symbian platform terminology, the +attribute is said to be non-derived), you need to implement TFSStartup::GetStartupModeFromFile(). +Non-derived attributes are read from file, and this function is called after +the file server has started.
You need to provide +an implementation for your Template::VariantHal() function +in your variant.cpp file.

The example below is the OMAP H4 variant implementation of GetStartupModeFromFile() and GetStartupMode() found +in ...\dev1\omap_hrp\h4estart\estartmain.cpp.

TInt TH4FSStartup::GetStartupModeFromFile() + { + if (iStartupMode != EStartupModeUndefined) + { + TInt r = ReadAndReset(); + return r; + } + return KErrNone; + } + +TInt TH4FSStartup::GetStartupMode() + { + TInt r = ReadAndReset(); + return r; + } + +TInt TH4FSStartup::ReadAndReset() + { + TInt value; + TInt r = HAL::Get(HALData::EPersistStartupModeKernel, value); + if (r == KErrNone) + { + iStartupMode = value; + } + r = HAL::Set(HALData::EPersistStartupModeKernel, EStartupModeUndefined); + return r; + }

See User-Side +Hardware Abstraction.

Customising other behaviour

You +can change other default behaviour. For example, to add additional functionality +related to File Server initialisation, or the initialisation of other base +related components, then the following virtual functions can also be customised. +Follow the links to the individual functions for more detail:

TFSStartup::Init()
TFSStartup::Run()
TFSStartup::InitialiseHAL()
TFSStartup::StartSystem()
TFSStartup::Close()

Activities +that the Base Starter does not do

The Base Starter is responsible +for mapping local drives to drive letters and for loading the appropriate +file systems on local drives. It does not install media drivers, and +is not responsible for deciding which local drive a media driver will register +with. This is done by the individual media drivers and peripheral controllers +when they are initialised.

See Registering +the media driver for information about how to register a media driver.

See +also Local +Media Subsystem.