<?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>Fair Scheduling and File Caching</title><shortdesc>Describes how to implement and configure the fair scheduling

and file caching features for file systems implementations.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>

<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>

</conbody><related-links>

<link href="GUID-5B24741C-7CE0-58E8-98C9-1D1CACCD476F.dita"><linktext>Fair

Scheduling and File Caching Background</linktext></link>

</related-links></concept>