Base Starter Technology

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>

FS_SWAP_CORRUPT-Y

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:

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.