<?xml version="1.0" encoding="utf-8"?>

<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->

<!-- This component and the accompanying materials are made available under the terms of the License 

"Eclipse Public License v1.0" which accompanies this distribution, 

and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->

<!-- Initial Contributors:

    Nokia Corporation - initial contribution.

Contributors: 

-->

<!DOCTYPE concept

  PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">

<concept id="GUID-89BCF9A5-ABBD-5523-BA76-FDB00B806A30" xml:lang="en"><title>Migration

Tutorial: Fair Scheduling and File Caching</title><prolog><metadata><keywords/></metadata></prolog><conbody>

<p>Describes how to implement and configure the <xref href="GUID-5B24741C-7CE0-58E8-98C9-1D1CACCD476F.dita">fair

scheduling and file caching</xref> features for file systems implementations. </p>

<section id="GUID-450D57A3-928B-5389-B941-595DB20A7CEA"><title>Enabling fair

scheduling</title><p>The <codeph>MExtendedFileInterface</codeph> API enables

fair scheduling. The FAT, FAT32 and LFFS file systems support <codeph>MExtendedFileInterface</codeph>,

this API allows requests to be split into one or more segments with the <codeph>aOffset</codeph> parameter.

Support has been built in for large files by changing the file’s position

parameter (<codeph>aPos</codeph>) from a <xref href="GUID-7A2A43EC-6125-3BFE-834B-23C37F7B40D5.dita"><apiname>TInt</apiname></xref> to a <xref href="GUID-AAE85115-A8AA-3F6C-BA8C-69F5A23B0D90.dita"><apiname>TInt64</apiname></xref>. </p> <p>To

enable fair scheduling, the file system mounted on a particular drive must

support <xref href="GUID-63DF657C-434D-353D-A536-8AF9D97C8260.dita#GUID-63DF657C-434D-353D-A536-8AF9D97C8260/GUID-E57D0ED6-C351-37F4-8E80-5A64144B6655"><apiname>CFileCB::MExtendedFileInterface</apiname></xref>. The object returned

by <xref href="GUID-0012B043-9FC4-3953-928E-CB6107E0486A.dita#GUID-0012B043-9FC4-3953-928E-CB6107E0486A/GUID-EFDD2A6C-1319-30FC-9FC6-9653E0A2F827"><apiname>CFileSystem::NewFileL()</apiname></xref> must be derived from <codeph>CFileCB</codeph> and <codeph>CFileCB::MExtendedFileInterface</codeph>.

The file server determines whether this is the case by calling <xref href="GUID-63DF657C-434D-353D-A536-8AF9D97C8260.dita#GUID-63DF657C-434D-353D-A536-8AF9D97C8260/GUID-D3628A6F-8E6D-39CA-8D36-EB3BC4154DF2"><apiname>CFileCB::GetInterface</apiname></xref>. </p> <p>The <xref href="GUID-63DF657C-434D-353D-A536-8AF9D97C8260.dita#GUID-63DF657C-434D-353D-A536-8AF9D97C8260/GUID-E57D0ED6-C351-37F4-8E80-5A64144B6655"><apiname>CFileCB::MExtendedFileInterface</apiname></xref> interface is as follows: </p><codeblock id="GUID-27EC7D5D-7BB6-5427-9EF0-71561F7AB847" xml:space="preserve">class MExtendedFileInterface

{

public:

    virtual void ReadL(TInt64 aPos, TInt& aLength, TDes8* aDes, const RMessagePtr2& aMessage, TInt aOffset) = 0;

    virtual void WriteL(TInt64 aPos, TInt& aLength, const TDesC8* aDes, const RMessagePtr2& aMessage, TInt aOffset) = 0;

    virtual void SetSizeL(TInt64 aSize) = 0;

};</codeblock> <p>The file system indicates its support for <codeph>MExtendedFileInterface</codeph> by

intercepting the <xref href="GUID-63DF657C-434D-353D-A536-8AF9D97C8260.dita#GUID-63DF657C-434D-353D-A536-8AF9D97C8260/GUID-F13F53A3-502A-38E4-B8E3-4099DC44EEC0"><apiname>CFileCB::EExtendedFileInterface</apiname></xref> enumeration

in the <xref href="GUID-63DF657C-434D-353D-A536-8AF9D97C8260.dita#GUID-63DF657C-434D-353D-A536-8AF9D97C8260/GUID-CBCFC605-C942-3D4E-8ABA-2EF454E5A44B"><apiname>CFileCB::GetInterface()</apiname></xref> method as in the following

example: </p><codeblock id="GUID-714AB83B-0A24-5E81-92B8-CB425002B426" xml:space="preserve">TInt CFatFileCB::GetInterface(TInt aInterfaceId, TAny*&amp; aInterface, TAny* aInput)

    {

    switch(aInterfaceId)

        {

        case EExtendedFileInterface:

            ((CFileCB::MExtendedFileInterface*&) aInterface) = this;

            return KErrNone;

        //etc.

        default:

            return CFileCB::GetInterface(aInterfaceId, aInterface, aInput);

        }

    }</codeblock> </section>

<section id="GUID-719C7E0C-790B-5C61-9EA8-E2687397340F"><title>Enabling read

and write caching</title><p>To enable caching, the file system must support

reads and writes to local buffers, which are buffers created and owned by

the file server itself rather by a client of the file server. </p><p>The local

media subsystem already supports local messages, but the file system and any

file system extensions need to be examined carefully to ensure that they do

not call any <xref href="GUID-78E0DEDD-C020-3174-AD0A-E4C18C4C9213.dita"><apiname>RMessagePtr2</apiname></xref> methods, otherwise a panic results. </p> <p>The

file server calls <xref href="GUID-FADDE053-CC1C-39BC-A52D-27093041BE20.dita#GUID-FADDE053-CC1C-39BC-A52D-27093041BE20/GUID-239159E5-1A98-3FE1-9A0D-803BEDB99DCE"><apiname>CMountCB::LocalBufferSupport()</apiname></xref> to find

out whether the file system and all file system extensions mounted on a particular

drive fully support local buffers before it enables caching. The file system

handles the <xref href="GUID-FADDE053-CC1C-39BC-A52D-27093041BE20.dita#GUID-FADDE053-CC1C-39BC-A52D-27093041BE20/GUID-87F36D0F-CAA5-35ED-9E99-BB8F7B9564C2"><apiname>CMountCB::ELocalBufferSupport</apiname></xref> enumeration in

its <xref href="GUID-FADDE053-CC1C-39BC-A52D-27093041BE20.dita#GUID-FADDE053-CC1C-39BC-A52D-27093041BE20/GUID-CABEF8F6-637C-3223-80C6-FBC8B7247030"><apiname>CMountCB::GetInterface()</apiname></xref> method and passes the request

on to the first proxy drive, as in the following example: </p><codeblock id="GUID-969BBBAE-5C1F-5032-831D-3C17E58285AE" xml:space="preserve">TInt CFatMountCB::GetInterface(TInt aInterfaceId, TAny*&amp; aInterface, TAny* /*aInput*/) 

    {

    TInt r= KErrNone;

    switch(aInterfaceId)

        {

        // file caching supported, so pass query on to first proxy drive

        case CMountCB::ELocalBufferSupport:

            r = LocalDrive()->LocalBufferSupport();

            break;

        default:

            r=KErrNotSupported;

        }

    return r;

    }</codeblock> <p>If no file system extensions are loaded, then the query

is eventually handled by <xref href="GUID-F47F56E4-3754-365B-B529-53C1D2A29503.dita#GUID-F47F56E4-3754-365B-B529-53C1D2A29503/GUID-7C0145B1-531A-367C-92DF-61EBB46F01CB"><apiname>CLocalProxyDrive::GetInterface()</apiname></xref>,

which returns <codeph>KErrNone</codeph> to indicate that <xref href="GUID-32659A02-6541-3D15-AB88-B70FBD7DF9B0.dita"><apiname>TBusLocalDrive</apiname></xref> and

the local media sub-system support local buffers. </p> <p>If there are any

file system extensions, they must handle the <xref href="GUID-B0BD0F3D-9081-3DBE-8375-F5000D6D39ED.dita#GUID-B0BD0F3D-9081-3DBE-8375-F5000D6D39ED/GUID-53AC960F-9EE3-3410-9DD6-1BAC08C7B8E8"><apiname>CProxyDrive::ELocalBufferSupport</apiname></xref> enumeration,

as in the following example: </p><codeblock id="GUID-67D3FAA1-9FC3-5653-B21D-73BC13AA36AE" xml:space="preserve">TInt CBitExtProxyDrive::GetInterface(TInt aInterfaceId, TAny*&amp; aInterface, TAny* aInput)

    {

    switch(aInterfaceId)

        {

        // file caching supported, so pass query on to next proxy drive

        case ELocalBufferSupport:

            return CBaseExtProxyDrive::LocalBufferSupport();

        default:

            return CBaseExtProxyDrive::GetInterface(aInterfaceId, aInterface, aInput);

        }       

    }</codeblock> </section>

<section id="GUID-020006B9-1A1E-523B-9CFA-927CDE5D5058"><title>Configuring

caching</title><p>The global and drive-specific cache property defaults are

defined in <filepath>f32\sfile\sf_file_cache_defs.h</filepath>. They may be

overridden for a particular drive by appropriate entries in the Base Starter

component's <filepath>ESTART.TXT</filepath> configuration file. The format

of this file has been enhanced to support the<codeph> .ini</codeph> file style

syntax: </p><codeblock id="GUID-E0DBF04F-8F7E-55E4-8210-D5697A5B3FDB" xml:space="preserve">C: 0  ELOCAL FAT  0       FS_FORMAT_COLD,FS_SYNC_DRIVE     # IRAM

D: 1  ELOCAL FAT  0       FS_SCANDRIVE                     # MMC (textshell)

I: 2  ELOCAL FAT  0       FS_FORMAT_CORRUPT                # NAND - USER DATA

K: 8  ELFFS  LFFS 0       FS_FORMAT_CORRUPT                # LFFS 

[DriveD]

FileCacheSize 256

FairSchedulingLen 128

FileCacheRead ON

FileCacheReadAhead ON

FileCacheWrite ON

ClosedFileKeepAliveTime 3000

DirtyDataFlushTime 3000

FileCacheReadAsync ON

[DriveI]

FileCacheWrite ENABLED

[DriveK]

FileCacheWrite ENABLED

[FileCache]

GlobalCacheEnabled ON

GlobalCacheSize 32768

GlobalCacheMaxLockedSize 1024

LowMemoryThreshold 10</codeblock> <p>In this example, write caching is enabled

on drives I and K and has been turned on by default on drive D.</p><note>Most

of the properties in the example are set to their default values: the definitions

are redundant but are shown for illustrative purposes. </note> <p>For details,

see <xref href="GUID-8BA1EEC2-78A3-54CC-95D9-81BF2659963D.dita">Base Starter Technology</xref>. </p> <p id="GUID-16751410-EFC2-55B8-8BC0-ED5F97F98EBB"><b>Global cache settings</b> </p><p>The

following table holds the global caching properties: </p><table id="GUID-4CBAD2A4-52DE-5BA1-98CC-0B1F6BFC54E1">

<tgroup cols="4"><colspec colname="col0"/><colspec colname="col1"/><colspec colname="col2"/><colspec colname="col3"/>

<tbody>

<row>

<entry><p> <b>Property</b>  </p> </entry>

<entry><p> <b>Type</b>  </p> </entry>

<entry><p> <b>Comments</b>  </p> </entry>

<entry><p> <b>Default value</b>  </p> </entry>

</row>

<row>

<entry><p> <xref href="GUID-91B81C0D-72F9-3226-BEEF-2E8153104102.dita"><apiname>GlobalCacheEnabled</apiname></xref>  </p></entry>

<entry><p>boolean </p></entry>

<entry><p>on or off</p></entry>

<entry><p>on</p></entry>

</row>

<row>

<entry><p> <xref href="GUID-BAC3ED91-7A3A-3255-B22E-6B6C0CB266E0.dita"><apiname>GlobalCacheSize</apiname></xref>  </p></entry>

<entry><p>integer </p> </entry>

<entry><p>Size of disconnected chunk shared by all files in kilobytes.</p></entry>

<entry><p>32768K (32MB) </p> </entry>

</row>

<row>

<entry><p> <xref href="GUID-BEE48B25-B374-3348-B97C-BA2D634E0330.dita"><apiname>GlobalCacheMaxLockedSize</apiname></xref>  </p></entry>

<entry><p>integer </p> </entry>

<entry><p>Maximum amount of locked RAM for all files in kilobytes.</p></entry>

<entry><p>1024K (1 MB) </p> </entry>

</row>

<row>

<entry><p> <xref href="GUID-36596759-4ABC-3F8E-A09E-97464094A58A.dita"><apiname>LowMemoryThreshold</apiname></xref>  </p></entry>

<entry><p>integer </p></entry>

<entry><p>Low memory threshold expressed as a percentage of total RAM. If

the amount of RAM drops below this value, attempts to allocate memory for

file caching fails.</p></entry>

<entry><p>10% </p> </entry>

</row>

</tbody>

</tgroup>

</table> <p id="GUID-E7F45784-14F2-505C-B21C-0A8010B0B232"><b>File cache settings</b> </p><p>The

properties <xref href="GUID-9278B920-FFEF-3710-8080-B33D028B7A12.dita"><apiname>FileCacheRead</apiname></xref>, <xref href="GUID-33E32FCF-9E02-3254-A9DA-3A6D0B1A52B5.dita"><apiname>FileCacheReadAhead</apiname></xref> and <xref href="GUID-C869ED9F-7F9D-33BC-A1C2-5E21B50A6BFC.dita"><apiname>FileCacheWrite</apiname></xref> may

each be in one of 3 states: </p><ul>

<li id="GUID-71396310-22E1-564A-A094-3EED4721688D"><p> <codeph>OFF</codeph> -

file caching is permanently off and cannot be turned on.</p> </li>

<li id="GUID-032E8EB7-4291-5276-852E-BD910CEC8633"><p> <codeph>ENABLED</codeph> -

file caching is off by default but may be turned on using an appropriate file

open mode, such as <xref href="GUID-4310DC20-300C-3FEB-B1A5-DBA37D5FC940.dita"><apiname>EFileReadBuffered</apiname></xref>  </p> </li>

<li id="GUID-2644023A-855F-5BDE-8A43-57A534E3367A"><p> <codeph>ON</codeph> -

file caching is on by default but may be turned off using an appropriate file

open mode, such as <xref href="GUID-449D6D3A-3F00-35F6-BDFB-DF957F98CA8B.dita"><apiname>EFileReadDirectIO</apiname></xref>. </p> </li>

</ul><p>See <xref href="GUID-3FEEFC4D-19B5-502A-8310-40646B9C34BC.dita">Run time

cache settings</xref>. </p><p>If <xref href="GUID-7F7B7C49-5F60-3B10-A241-98306795A768.dita"><apiname>FileCacheReadAsync</apiname></xref> is

set, media driver reads on this drive are asynchronous. This results in read

ahead requests being issued before completing a client read request. However,

if <codeph>FileCacheReadAsync</codeph> is OFF, then media driver reads on

this drive are synchronous. So, issuing a read ahead is likely to block any

client thread that is normally running at lower priority than the media driver's

thread. In this case read ahead requests only happen during periods of inactivity

to improve latency. </p><table id="GUID-B022918E-9335-5D44-B029-D48B36E45937">

<tgroup cols="4"><colspec colname="col0"/><colspec colname="col1"/><colspec colname="col2"/><colspec colname="col3"/>

<tbody>

<row>

<entry><p> <b>Property</b>  </p> </entry>

<entry><p> <b>Type</b>  </p> </entry>

<entry><p> <b>Comments</b>  </p> </entry>

<entry><p> <b>Default value</b>  </p> </entry>

</row>

<row>

<entry><p> <xref href="GUID-3B777E89-8E4C-3540-958F-C621741895C8.dita"><apiname>FileCacheSize</apiname></xref>  </p> </entry>

<entry><p>integer </p> </entry>

<entry><p>Maximum amount of locked or unlocked RAM per file.</p></entry>

<entry><p>128K </p> </entry>

</row>

<row>

<entry><p> <xref href="GUID-23E2F01D-BD7B-39D3-B7B2-F23E20D273C5.dita"><apiname>FairSchedulingLen</apiname></xref>  </p> </entry>

<entry><p>integer </p> </entry>

<entry><p>Read &amp; write requests greater than this length are split up

into 2 or more requests.</p></entry>

<entry><p>128K </p> </entry>

</row>

<row>

<entry><p> <xref href="GUID-9278B920-FFEF-3710-8080-B33D028B7A12.dita"><apiname>FileCacheRead</apiname></xref>  </p></entry>

<entry><p>string </p></entry>

<entry><p>OFF, ENABLED or ON.</p></entry>

<entry><p>ENABLED </p></entry>

</row>

<row>

<entry><p> <xref href="GUID-33E32FCF-9E02-3254-A9DA-3A6D0B1A52B5.dita"><apiname>FileCacheReadAhead</apiname></xref>  </p></entry>

<entry><p>string </p></entry>

<entry><p>OFF, ENABLED or ON.</p></entry>

<entry><p>ON </p></entry>

</row>

<row>

<entry><p> <xref href="GUID-C869ED9F-7F9D-33BC-A1C2-5E21B50A6BFC.dita"><apiname>FileCacheWrite</apiname></xref>  </p></entry>

<entry><p>string </p></entry>

<entry><p>OFF, ENABLED or ON.</p></entry>

<entry><p>ENABLED </p></entry>

</row>

<row>

<entry><p> <xref href="GUID-7F7B7C49-5F60-3B10-A241-98306795A768.dita"><apiname>FileCacheReadAsync</apiname></xref>  </p> </entry>

<entry><p>boolean </p> </entry>

<entry><p>ON or OFF. If set, media driver reads on this drive are asynchronous.</p></entry>

<entry><p>OFF </p> </entry>

</row>

<row>

<entry><p> <xref href="GUID-A91BE0A1-A79D-3828-9E86-7850839BBFE9.dita"><apiname>ClosedFileKeepAliveTime</apiname></xref>  </p> </entry>

<entry><p>integer </p> </entry>

<entry><p>Time after which a file is removed from the closed file queue, in

milliseconds. </p></entry>

<entry><p>3000ms (3 secs) </p> </entry>

</row>

<row>

<entry><p> <xref href="GUID-78907F25-9D0F-3B76-BDB0-514FC22CAECA.dita"><apiname>DirtyDataFlushTime</apiname></xref>  </p> </entry>

<entry><p>integer </p> </entry>

<entry><p>Time after which a file containing dirty data is flushed, in milliseconds.</p></entry>

<entry><p>3000ms (3 secs) </p> </entry>

</row>

</tbody>

</tgroup>

</table> </section>